backend/docs/deployment-guide.md

SciLit 生产部署指南

前置条件

• 服务器已安装 Docker 24+ + docker compose plugin
• SSH 可连接到服务器（推荐 ~/.ssh/config）
• 代码仓库可被服务器 git pull（Gitee/GitHub/自建 Git）

快速部署

# 1. 服务器上 clone 项目
ssh root@your-server.com
git clone https://gitee.com/your-org/scilit-oncology.git /root/scilit
cd /root/scilit

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，至少填写以下必填项：
#   PG_PASSWORD, REDIS_PASSWORD, JWT_SECRET, PUBLIC_BASE_URL

# 3. 启动
docker compose -f docker-compose.prod.yml --env-file .env up -d

# 检查是否就绪
curl http://localhost:8000/health
curl http://localhost:80

使用 deploy/deploy.sh 自动化部署（生产）

旧根目录 deploy.sh（SSH 直连模型）已废弃，替换为 deploy/ 脚本体系。 完整设计见 16-部署运维方案.md §2。

# 在服务器 /root/scilit（git 仓库 + .env 所在目录）执行

# 0. 前置：基础设施已在跑
docker compose -f docker-compose.prod.yml ps

# 1. 预览将执行的命令（不执行任何变更）
bash deploy/deploy.sh --dry-run

# 2. 正式部署（自动：工作区校验 → git pull → predeploy 快照 →
#    迁移 → 容器切换 → 健康轮询 → versions.log）
bash deploy/deploy.sh

# 3. 回滚到上一成功版本
bash deploy/rollback.sh

PostgreSQL 备份与恢复

备份

# 全量备份（压缩）
docker exec -t scilit-oncology_postgres_1 pg_dump -U scilit scilit | gzip > scilit-backup-$(date +%F).sql.gz

# 仅数据（不含索引，恢复更快）
docker exec -t scilit-oncology_postgres_1 pg_dump -U scilit --data-only --exclude-table=alembic_version scilit | gzip > scilit-data-$(date +%F).sql.gz

恢复

# 先停止后端服务（避免写入冲突）
docker compose -f docker-compose.prod.yml stop backend worker

# 恢复全量备份
gunzip -c scilit-backup-2026-07-08.sql.gz | docker exec -i scilit-oncology_postgres_1 psql -U scilit scilit

# 重启
docker compose -f docker-compose.prod.yml start backend worker

定时自动备份（推荐）

在服务器上配置 cron：

# 每天凌晨 3 点备份，保留 30 天
0 3 * * * cd /root/scilit-oncology && docker exec -t $(docker ps -q -f name=postgres) pg_dump -U scilit scilit | gzip > /backups/scilit-$(date +\%F).sql.gz && find /backups -name 'scilit-*.sql.gz' -mtime +30 -delete

健康检查与运维

# 查看所有服务状态
docker compose -f docker-compose.prod.yml ps

# 查看日志
docker compose -f docker-compose.prod.yml logs -f backend
docker compose -f docker-compose.prod.yml logs -f worker

# 单独重启某个服务
docker compose -f docker-compose.prod.yml restart backend

# 更新到最新代码
git pull origin main
docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d --no-deps --remove-orphans

HTTPS 配置

docker-compose.prod.yml 中的 Nginx 仅提供 HTTP 服务。建议使用上游反向代理：

Caddy（推荐，自动 Let's Encrypt）

your-domain.com {
    reverse_proxy 127.0.0.1:80
}

Nginx

server {
    listen 443 ssl;
    server_name your-domain.com;
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

验证证书可用后更新 PUBLIC_BASE_URL=https://your-domain.com 并重启 backend。