AIclinicalresearch/docs/05-部署文档/01-日常更新操作手册.md

日常更新操作手册

版本: v2.1（补充 0228 部署经验）
更新日期: 2026-02-28
适用: 日常代码更新、功能迭代、配置变更

---

0. 部署前检查

□ 打开 03-待部署变更清单.md，确认本次要部署哪些变更
□ 打开 00-阿里云SAE最新真实状态记录.md，确认当前版本号
□ 确认新版本号（当前版本 +1）
□ 如有数据库变更，先执行数据库迁移

---

1. ACR 登录（首次 / 过期后）

docker login --username=gofeng117@163.com --password=fengzhibo117 crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com

---

2. Node.js 后端更新（~25 分钟）

当前版本: v2.3 → 下个版本: v2.4

2.1 构建

cd D:\MyCursor\AIclinicalresearch\backend

# TypeScript 编译（有类型错误时用 --noCheck）
npm run build
# 或: npx tsc --noCheck

# 构建 Docker 镜像
docker build -t backend-service:v2.4 .

0227 经验: tsc 不会拷贝 .json 配置文件，Dockerfile 中已有 COPY src/modules/ssa/config/*.json 等补丁步骤。如新模块有 JSON 配置文件需要确认 Dockerfile 覆盖到。

2.2 推送

docker tag backend-service:v2.4 crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v2.4

docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v2.4

推送约 10 分钟（~840MB），看到 digest: sha256:... 表示成功。

2.3 SAE 部署

1. SAE 控制台 → nodejs-backend-test → 部署应用
2. 选择镜像 backend-service:v2.4（与上方构建版本一致）
3. 确认部署，等待 5-8 分钟

2.4 验证

□ SAE 实例状态为 Running
□ 日志中出现启动成功信息
□ 健康检查: curl http://<新IP>:3001/health
□ 前端功能测试

重要: 部署后 IP 会变更！需同步更新 frontend-nginx-service 的 BACKEND_SERVICE_HOST 环境变量。

---

3. 前端 Nginx 更新（~15 分钟）

当前版本: v1.9 → 下个版本: v2.0

3.1 构建

cd D:\MyCursor\AIclinicalresearch\frontend-v2

docker build -t ai-clinical_frontend-nginx:v2.0 .

构建约 5 分钟（含 React 编译）。

3.2 推送

docker tag ai-clinical_frontend-nginx:v2.0 crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v2.0

docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v2.0

推送约 2 分钟（~50MB）。

3.3 SAE 部署

1. SAE 控制台 → frontend-nginx-service → 部署应用
2. 选择镜像版本 v2.0（与上方构建版本一致）
3. 检查环境变量: BACKEND_SERVICE_HOST 指向最新后端 IP

3.4 验证

□ 访问 https://iit.xunzhengyixue.com/ 页面正常
□ 登录功能正常（排除 504 超时）
□ 测试核心功能

---

4. Python 微服务更新（~30 分钟）

当前版本: v1.2 → 下个版本: v1.3

4.1 构建

cd D:\MyCursor\AIclinicalresearch\extraction_service

docker build -t python-extraction:v1.3 .

构建约 15 分钟（镜像 ~1.1GB）。

4.2 推送

docker tag python-extraction:v1.3 crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.3

docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.3

4.3 SAE 部署

1. SAE 控制台 → python-extraction-test → 部署应用
2. 选择新版本

4.4 验证

□ 健康检查: curl http://<新IP>:8000/api/health
□ 如 IP 变更，更新后端的 EXTRACTION_SERVICE_URL

---

5. R 统计引擎更新（~40 分钟）

当前版本: v1.0.1 → 下个版本: v1.0.2

5.1 构建

cd D:\MyCursor\AIclinicalresearch\r-statistics-service

docker build -t ssa-r-statistics:v1.0.2 .

构建约 20 分钟（镜像 ~1.8GB，R 包编译耗时）。

5.2 推送

docker tag ssa-r-statistics:v1.0.2 crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ssa-r-statistics:v1.0.2

docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ssa-r-statistics:v1.0.2

5.3 SAE 部署

1. SAE 控制台 → r-statistics-test → 部署应用
2. 选择新版本

5.4 验证

□ 健康检查: curl http://<新IP>:8080/health
□ 如 IP 变更，更新后端的 R_STATISTICS_SERVICE_URL

---

6. 数据库迁移

6.1 标准迁移（Prisma migration 文件）

# 通过后端 SAE Webshell 执行（推荐）
npx prisma migrate deploy

# 或手动执行 SQL
# 将 migration.sql 内容粘贴到 Webshell psql 中

6.2 手动 SQL 补丁

# 在 SAE nodejs-backend-test 的 Webshell 中
node -e "
const { execSync } = require('child_process');
execSync('PGPASSWORD=Xibahe@fengzhibo117 psql -h pgm-2zex1m2y3r23hdn5so.pg.rds.aliyuncs.com -U airesearch -d ai_clinical_research_test -c \"你的SQL\"', {stdio:'inherit'});
"

6.3 标记手动迁移

npx prisma migrate resolve --applied <migration_name>

---

7. 环境变量修改（5 分钟）

核心规则: 只改环境变量时用「重启应用」，不要「部署应用」！

操作	用途	IP 是否变
重启应用	改配置/环境变量	不变
部署应用	更新镜像版本	会变

步骤: SAE 控制台 → 应用 → 应用配置 → 环境变量 → 编辑 → 保存 → 重启应用

---

8. 部署后收尾

□ 更新 00-阿里云SAE最新真实状态记录.md（新IP/版本）
□ 清零 03-待部署变更清单.md（已部署项移到历史区域）
□ 如果是大版本部署，创建 MMDD部署/ 文件夹记录过程
□ 如有服务 IP 变更，检查相互依赖的环境变量是否已更新
□ CLB 负载均衡器无需手动更新（阿里云自动处理）

---

9. 常见问题速查

现象	原因	解决
前端 504 Gateway Timeout	后端 IP 变更但前端环境变量未更新	更新 BACKEND_SERVICE_HOST 并重启
column does not exist	数据库迁移遗漏	检查 03-待部署变更清单.md 中是否有未执行的 DB 变更
ENOENT .json 文件	tsc 不拷贝非 .ts 文件	在 Dockerfile 中添加 COPY 指令
健康检查失败 404	健康检查路径配置错误	确认 HTTP 路径为 /health
镜像推送超时	网络问题	重试，或换网络环境
prisma db push 遗留 drift	开发时绕过了迁移系统	创建 patch migration + resolve --applied

---

10. 部署顺序参考

如果多个服务同时更新：

1. 数据库迁移（先行，确保表结构就绪）
2. R 统计引擎（独立服务，不影响其他）
3. Python 微服务（独立服务）
4. Node.js 后端（依赖上游服务 IP，需更新环境变量）
5. 前端 Nginx（最后部署，需要最新的后端 IP）