CheckInApp/docs/deployment.md

部署指南

推荐方式：Docker Compose

Docker Compose 是当前推荐的生产部署方式。主机只需要 Docker Engine 和 Docker Compose，Python、Node.js、pnpm、Playwright Chromium 都由镜像构建和容器运行时负责。

系统要求

• Linux 服务器，建议 Ubuntu 20.04+ / Debian 11+ / CentOS 7+
• Docker Engine 24+
• Docker Compose v2
• 2GB+ RAM
• 可访问外网以构建镜像和下载依赖

首次部署

git clone <repository>
cd CheckInApp

cp deploy/compose.env.example .env

编辑 .env，至少修改：

• SECRET_KEY: 改成足够长的随机字符串。
• CORS_ORIGINS: 改成浏览器实际访问的站点，例如 https://checkin.example.com。
• FRONTEND_URL: 改成同一个公开站点，用于邮件里的链接。
• CHECKIN_WEB_PORT: 默认 8080，按服务器端口规划调整。
• SMTP 配置：需要邮件通知时填写真实 SMTP 参数。

启动：

docker compose up -d --build

默认访问：

• Web UI: http://localhost:8080
• API 健康检查: http://localhost:8080/health
• API 文档: http://localhost:8080/docs

运行结构

Compose 启动两个服务：

• backend: FastAPI、APScheduler、SQLAlchemy、Playwright Chromium。
• web: nginx，负责前端静态资源、SPA fallback，以及代理 /api、/docs、/redoc、/openapi.json、/health 到 backend。

持久化目录：

• ./data:/app/data: SQLite 数据库，默认 data/checkin.db。
• ./sessions:/app/sessions: Playwright 登录会话状态。
• ./logs:/app/logs: 后端日志文件。

容器重建或镜像更新不会删除这些目录。

创建管理员

先让目标用户完成一次 QQ 扫码注册，然后在容器内运行管理员脚本：

docker compose exec backend uv run python apps/backend/scripts/create_admin.py

脚本会提示输入要升级的用户别名。

常用运维命令

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f backend
docker compose logs -f web

# 重启
docker compose restart

# 停止
docker compose down

更新

git pull
docker compose up -d --build

后端启动时会自动执行待迁移数据库脚本，并在迁移完成后才启动调度器。如果迁移失败，backend 服务会启动失败并在日志中标出失败的迁移 ID。

需要手动执行迁移时：

docker compose exec backend uv run python main.py backend-migrate

不要使用 docker compose down -v，否则会删除 Compose 管理的卷。当前默认使用项目目录 bind mount，仍应避免误删 data/、sessions/、logs/。

备份与恢复

备份 SQLite 和运行时状态：

mkdir -p backups
tar -czf backups/checkin-$(date +%Y%m%d-%H%M%S).tar.gz data sessions logs .env

恢复：

docker compose down
tar -xzf backups/<backup-file>.tar.gz
docker compose up -d

回滚

git checkout <previous-tag-or-commit>
docker compose up -d --build

回滚时复用同一份 .env、data/、sessions/、logs/。回滚到旧版本前，先确认当前版本已经执行的数据库迁移是否可被旧版本兼容读取。

Compose 故障排查

端口占用：

sudo lsof -i :8080

修改 .env 中的 CHECKIN_WEB_PORT 后重新启动：

docker compose up -d

后端健康检查失败：

docker compose logs backend
docker compose exec backend uv run python main.py backend --check

Playwright 问题：

• Compose 部署不需要在主机安装 Chrome/Chromium。
• 如果 QQ 登录或 payload 捕获失败，先查看 docker compose logs backend 和 logs/backend.log。
• 重新构建镜像可刷新 Playwright 浏览器依赖：docker compose build --no-cache backend。

权限问题：

mkdir -p data sessions logs
chmod -R u+rwX data sessions logs
docker compose restart backend

备选方式：传统部署

传统部署适合已经有主机级 Python、Node.js、pnpm、Chromium、nginx 和 systemd 管理经验的环境。

系统要求

• Ubuntu 20.04+ / CentOS 7+ / Windows Server
• Python 3.12+
• uv
• Node.js 24+
• pnpm
• Chrome / Chromium
• 2GB+ RAM

依赖安装

# Ubuntu
sudo apt update
sudo apt install -y python3 nodejs npm chromium-browser
npm install -g pnpm
curl -LsSf https://astral.sh/uv/install.sh | sh

# CentOS
sudo yum install -y python3 nodejs npm chromium
npm install -g pnpm
curl -LsSf https://astral.sh/uv/install.sh | sh

后端部署

git clone <repository>
cd CheckInApp

uv sync
uv sync --extra production

cp .env.example .env
vim .env

uv run playwright install chromium
uv run python main.py backend --no-reload

前端部署

cd apps/frontend
pnpm install --frozen-lockfile
pnpm build

生产静态资源输出在 apps/frontend/dist/。

nginx 示例文件：deploy/nginx/checkin-app.conf.example

systemd 示例文件：deploy/systemd/checkin-app.service.example

配置优化

生产环境变量

Compose 部署参考：deploy/compose.env.example

传统部署参考：.env.example

数据库迁移到 PostgreSQL

当前 Compose baseline 使用 SQLite 单后端部署。需要 PostgreSQL 时，先按传统方式准备数据库并修改 DATABASE_URL：

sudo apt install postgresql postgresql-contrib

sudo -u postgres createdb checkin
sudo -u postgres createuser checkin_user
sudo -u postgres psql -c "ALTER USER checkin_user WITH PASSWORD 'password';"

DATABASE_URL=postgresql://checkin_user:password@localhost/checkin

安全加固

防火墙配置

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

如果直接暴露 Compose web 端口，也需要允许 CHECKIN_WEB_PORT 对应端口。

HTTPS

推荐在 Compose web 服务前放置外部反向代理或云厂商负载均衡来终止 TLS。传统 nginx 部署可以使用 Let's Encrypt：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
sudo systemctl enable certbot.timer

访问限制

• 生产环境必须修改默认 SECRET_KEY。
• 将 CORS_ORIGINS 和 FRONTEND_URL 设置为实际公开域名。
• 在外部反向代理中配置 rate limiting。
• 使用 fail2ban 防止暴力破解。

监控维护

日志

Compose：

docker compose logs -f backend
tail -f logs/backend.log

传统部署：

tail -f logs/backend.log

数据库备份

SQLite：

cp data/checkin.db data/checkin.db.backup

PostgreSQL：

pg_dump checkin > backup.sql

扩展部署

负载均衡

当前应用包含内置调度器，默认 Compose baseline 只运行一个 backend 服务。多 backend 实例需要先设计调度器互斥或外部调度机制。

传统 nginx upstream 示例：

upstream backend {
    server 127.0.0.1:8000;
    server 127.0.0.1:8001;
    server 127.0.0.1:8002;
}

server {
    location /api {
        proxy_pass http://backend;
    }
}

Redis 缓存

uv sync --extra redis

REDIS_URL=redis://localhost:6379/0