上线部署 SOP（Standard Operating Procedure）

本文件是每次部署的唯一依据，执行前必须完整阅读并遵守。

零、核心原则

不影响现有功能 — 改动必须向后兼容，已有的 API、前端行为一个都不能破
增量提交 — 每次只改一个关注点，小步 commit，便于定位和回滚
快速回滚 — 任何时候出问题，3 分钟内回滚到上一个正常版本
部署前自检，部署后观察 — 绝不跳过任何一步

一、部署前 Checklist

在 ./tools/java-deploy.sh deploy 之前，逐项确认：

代码已 push 到 git 仓库
编译通过（本地或 CI）
确认没有新增 AccessDeniedException 或 No thread-bound request 等已知异常
对关键接口心中有数：/health、/api/v1/chat/stream、/api/v1/drug/search
已知回滚路径（见第五节）
如果是数据库变更，已确认向前兼容

二、标准上线步骤

# Step 1: 确认当前状态
./tools/java-deploy.sh status

# Step 2: 一键部署（自动拉代码、编译、备份、重启）
./tools/java-deploy.sh deploy

# Step 3: 确认服务正常
curl -s http://localhost:9000/health | python3 -m json.tool

# Step 4: 检查启动日志无异常
./tools/java-deploy.sh logs 50

# Step 5: 等待 2-3 分钟，观察日志无新的 ERROR
sleep 180
tail -50 /var/log/pharmacopoeia/backend.log | grep -i "error\|exception\|access denied"

三、部署后验证

检查项	命令	预期
健康检查	`curl -s http://localhost:9000/health`	200 OK
药品库搜索	`curl -s 'http://localhost:9000/api/v1/drug/search?keyword=布洛芬'`	返回数据
对话流式	用浏览器访问首页，发送一条问题	SSE 正常走完，无网络异常
品牌推荐	发送含"布洛芬"的问题	SSE 中出现 `brand_recommend` 事件
日志无异常	`tail -100 /var/log/pharmacopoeia/backend.log \\| grep -i "error\\|exception"`	无新增报错

数据库迁移

本次上线涉及新增表和新列，部署前必须执行迁移：

docker exec -i pharmacopoeia-pg psql -U postgres -d pharmacopoeia < database/migrate_brand_recommend.sql

该脚本创建 brands 和 brand_recommend_rules 两张表，以及在 messages 表加 brand_recommendations jsonb 列。使用 IF NOT EXISTS，可重复执行。

四、部署脚本说明

所有操作统一用 ./tools/java-deploy.sh，不手动操作 jar 文件或进程。

命令	用途
`./tools/java-deploy.sh status`	查看运行状态
`./tools/java-deploy.sh deploy`	一键上线（pull → build → backup → restart）
`./tools/java-deploy.sh rollback`	回滚到上一个备份
`./tools/java-deploy.sh rollback <path>`	回滚到指定备份文件
`./tools/java-deploy.sh restart`	重启（不重新编译）
`./tools/java-deploy.sh logs`	最近 100 行日志
`./tools/java-deploy.sh logf`	实时日志跟踪

deploy 命令会自动：

拉取 git 最新代码
编译打包
备份当前 JAR 到 backend-java/backups/ 目录（按时间戳命名）
保留最近 5 个备份，自动清理更早的

五、紧急回滚

# 方式 1: 自动回滚（使用最新备份）
./tools/java-deploy.sh rollback

# 方式 2: 回滚到指定备份
./tools/java-deploy.sh rollback /opt/pharmacopoeia-ai/backend-java/backups/pharmacopoeia-ai-20260724-143000.jar

# 方式 3: 回退 git commit 后重新部署
cd /opt/pharmacopoeia-ai
git revert <坏commit> --no-edit
./tools/java-deploy.sh deploy

回滚决策：

用户反馈功能异常 → 立即回滚
日志 5 分钟内出现 5+ ERROR → 立即回滚
仅 UI 展示问题 → 评估是否需要回滚，优先热修复

六、数据库变更（额外谨慎）

任何表结构或索引变更，必须：

先在 dev 环境验证
使用 IF NOT EXISTS（向前兼容）
不删除列、不重命名列（除非确认无依赖）
变更完成后验证关键查询正常

七、禁止事项

❌ 跳过部署前 Checklist
❌ 手动 kill 进程或直接替换 jar（用脚本）
❌ 生产环境用 -SNAPSHOT 版本
❌ 不做备份就部署
❌ 部署后不观察日志就离开

DEPLOY.md 4.3 KB Историја Датотека