CheckInApp/docs/deployment.md

部署指南

环境准备

系统要求

• Ubuntu 20.04+ / CentOS 7+ / Windows Server
• Python 3.12+
• uv
• Node.js 20+
• 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

生产部署

方式一：传统部署

1. 后端部署

# 克隆项目
git clone <repository>
cd CheckInApp

# 安装依赖
uv sync

# 生产环境额外依赖
uv sync --extra production

# 配置环境变量
cp .env.example .env
vim .env  # 修改环境变量

2. 前端部署

cd apps/frontend

# 安装依赖
pnpm install --frozen-lockfile

# 构建生产版本
pnpm build

# 输出在 dist/ 目录

使用 Nginx 托管:

示例文件

3. 使用 Systemd 管理

示例文件

方式二：Docker 部署（推荐）

TODO(Maybe never)

配置优化

生产环境变量

示例文件

数据库迁移到 PostgreSQL

# 安装 PostgreSQL
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';"

# 修改 .env
DATABASE_URL=postgresql://checkin_user:password@localhost/checkin

安全加固

1. 防火墙配置

sudo ufw allow 22/tcp   # SSH
sudo ufw allow 80/tcp   # HTTP
sudo ufw allow 443/tcp  # HTTPS
sudo ufw enable

2. SSL 证书（Let's Encrypt）

sudo apt install certbot python3-certbot-nginx

sudo certbot --nginx -d your-domain.com

# 自动续期
sudo systemctl enable certbot.timer

3. 限制访问

• 修改 .env 中的 CORS_ORIGINS 为实际域名
• 在 Nginx 中配置 rate limiting
• 使用 fail2ban 防止暴力破解

监控维护

日志管理

# 查看后端日志
tail -f logs/backend.log

数据库备份

# SQLite 备份
cp data/checkin.db data/checkin.db.backup

# PostgreSQL 备份
pg_dump checkin > backup.sql

# 定时备份（crontab）
0 2 * * * /path/to/backup.sh

性能监控

使用工具：

• Prometheus + Grafana
• New Relic
• Sentry（错误追踪）

扩展部署

负载均衡

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 缓存

# 安装 redis
uv sync --extra redis

# 配置会话存储
REDIS_URL=redis://localhost:6379/0

故障排查

端口占用

sudo lsof -i :8000
sudo kill -9 <PID>

Playwright 问题

# 安装浏览器
uv run playwright install chromium

# 检查系统浏览器（可选）
chromium --version
google-chrome --version

权限问题

# 确保目录权限正确
sudo chown -R www-data:www-data /path/to/CheckInApp
sudo chmod -R 755 /path/to/CheckInApp

回滚策略

# 保存当前版本
git tag -a v2.0.0 -m "Production release"

# 回滚到上一版本
git checkout v1.9.0
docker-compose down
docker-compose up -d --build