部署指南

本章介绍 CSMS 的生产部署方式。CSMS 使用 SQLite 存储，不支持多进程并发写，因此所有方案都保持单进程运行。

部署架构

用户 ──▶ Nginx (:80 / :443) ──▶ Nuxt Server (:3000) ──▶ SQLite (/app/data/*.db)
        HTTPS 终止 / 静态缓存        单进程 (SQLite 限制)      物理隔离的多租户库

选型理由：

• SQLite 免部署数据库，适合中小规模学校场景。
• 因 SQLite 不支持多进程并发写，Nuxt Server 必须单进程运行（ecosystem.config.cjs 固定 instances: 1，禁止改为 cluster）。
• Nginx 负责 HTTPS 终止、静态资源缓存、压缩与安全响应头。

环境变量（所有方案通用）

变量	必填	说明
NUXT_SESSION_PASSWORD	✅	Session 加密密钥，运行期实时生效。生成：openssl rand -hex 32
SESSION_SECRET	⚪	构建期备选密钥，运行期改无效
HOST	⚪	默认 ::
PORT	⚪	默认 3000
NODE_ENV	⚪	部署设为 production

⚠️ NUXT_SESSION_PASSWORD 在 Windows 下即使使用预构建产物也必须设置。

方案一：Docker 部署（推荐）

前置：已安装 Docker 与 Docker Compose。

# 构建并后台启动（应用 + 可选 Nginx）
docker compose up -d --build

# 仅启动应用（不含 Nginx）
docker compose up -d --build csms

# 查看日志
docker compose logs -f csms

• 应用端口 3000，Nginx 端口 80。
• HTTPS 配置位于 deploy/nginx/。
• 数据卷 csms-data 挂载到容器 /app/data，务必持久化该卷。
• 默认管理员在首次启动后的入驻流程中创建。

方案二：PM2 部署（推荐单机）

前置：Node.js 22+，npm i -g pm2。

# 1. 安装依赖并构建
npm install
npm run build

# 2. 用内置 ecosystem 配置启动（已固定单进程）
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup        # 开机自启（按提示执行生成的那条命令）

如需自定义 ecosystem.config.cjs：

module.exports = {
  apps: [{
    name: "csms",
    exec_mode: "fork",          // ❗ 禁止 cluster，SQLite 不支持并发写
    instances: 1,               // ❗ 必须为 1
    script: ".output/server/index.mjs",
    env: { NUXT_SESSION_PASSWORD: "你的密钥" }
  }]
};

Nginx 反向代理（PM2 方式）目标：http://127.0.0.1:3000。

方案三：Windows 部署

# 安装 Node.js 22+ 与 PM2
npm i -g pm2

# 构建
npm install
npm run build

# 设置 Session 密钥（预构建产物也必须在运行环境设置）
$env:NUXT_SESSION_PASSWORD = "你的密钥"

# 注册为 Windows 服务
pm2 startup windows
pm2 start ecosystem.config.cjs
pm2 save

# 放行防火墙
netsh advfirewall firewall add rule name="CSMS" dir=in action=allow protocol=TCP localport=3000

方案四：宝塔面板部署

1. 软件商店安装 PM2 管理器 与 Nginx。
2. 上传项目到 /www/wwwroot/csms，进入目录执行 npm install && npm run build。
3. PM2 启动文件填 .output/server/index.mjs（或 pm2 start ecosystem.config.cjs）。
4. 添加站点，反向代理目标 http://127.0.0.1:3000。
5. 站点 SSL 一键申请 Let's Encrypt。
6. 数据目录 /www/wwwroot/csms/data/ 直接复制即可备份。

HTTPS / SSL 配置

• Docker 方式：在 deploy/nginx/ 中配置证书路径与 443 监听，由 Nginx 终止 TLS。
• PM2 / 宝塔方式：使用 Certbot 或面板申请证书，Nginx 配置 80 → 443 重定向并代理到 127.0.0.1:3000。

PWA「安装到主屏幕」需要 HTTPS 才生效。

数据库备份与恢复

手动备份

# 复制主库与所有分库
cp data/csms.db /backup/csms.db
cp -r data/schools /backup/schools

自动备份（cron，每日凌晨 3 点）

# 0 3 * * *  /usr/bin/rsync -a /app/data/ /backup/csms-data/  (Docker)
# 或 zip 打包后异地同步

恢复时，停止服务 → 用备份文件覆盖 data/ → 重启。

常见问题排查

现象	可能原因	处理
容器启动失败	端口被占 / 数据卷权限	释放端口，检查 csms-data 挂载权限
登录后跳回登录页	NUXT_SESSION_PASSWORD 不一致 / 未设置	确保运行环境密钥与构建一致
database is locked	多进程写 SQLite	确认 instances: 1、未启用 cluster
磁盘不足	审计日志 / 上传文件堆积	清理 data/ 与日志，扩展磁盘
更新后异常	未执行迁移	npm run db:migrate 后重启

部署检查清单

• NUXT_SESSION_PASSWORD 已设置（运行环境）
• SQLite 单进程（instances: 1）
• data/ 已持久化（Docker 卷 / 目录备份）
• 已执行 npm run db:migrate
• 已配置 HTTPS（PWA 与登录安全需要）
• 反向代理 127.0.0.1:3000 正常
• 防火墙放行对应端口

默认管理员

首次启动后通过学校入驻流程创建第一个超级管理员账号；若后续遗忘超管密码，可通过登录页「忘记密码」邮箱验证码自助重置，或由其他超管在「用户管理 → 管理员」中重置。