wecom_it_smart_desk/docs/DEPLOY-QUICK-v0.7.0.md

v0.7.0 一键部署操作包(给生产运维)

目的:把所有部署命令按顺序排好,生产运维复制粘贴即可完成 v0.7.0 部署。 预计时间:15-20 分钟(含等 docker pull) 回滚:每步都有 rollback 命令,任意一步失败立即回滚。

---

🔴 部署前 必做(用户自己操作)

1. 撤销并重签 Gitea token

1. 浏览器打开 http://100.85.152.112:8418
2. 右上角头像 → Settings → Applications → Manage Access Tokens
3. 找到旧 token(workbuddy-claude),点 Revoke
4. 点 Generate New Token,scope 选 "All",点 Generate
5. 复制新 token(只显示一次),临时存到 ~/Downloads/gitea-new-token.txt

2. 推送代码到 Gitea(用新 token)

# 在本地工作目录(D:\资料\03-项目开发\wecom_it_smart_desk-claude\backend)
cd /d/资料/03-项目开发/wecom_it_smart_desk-claude

# 临时把新 token 加进 remote URL(push 后立刻删除)
git remote set-url origin "http://workbuddy-claude:新TOKEN@100.85.152.112:8418/simon/wecom_it_smart_desk.git"

# 推送 main + tag
git push origin main
git push origin v0.7.0

# push 成功后,立刻从 URL 移除 token
git remote set-url origin "http://workbuddy-claude@100.85.152.112:8418/simon/wecom_it_smart_desk.git"

# 验证 token 已移除
git remote -v
# 期望:没有 token 字样

---

🟢 部署操作(在生产服务器,SSH/PuTTY)

服务器 IP: 10.90.5.110 (内网),115.236.188.3 (公网入口) SSH 用户:堡垒机登录后跳转

步骤 1/6:备份当前生产状态

# 1.1 备份 backend 当前镜像
sudo docker tag wecom_it_backend wecom_it_backend:v0.6.0-backup

# 1.2 备份 4 端 dist
sudo mkdir -p /opt/wecom-it-desk/dist-backup-2026-06-21
sudo cp -r /opt/wecom-it-desk/frontend-admin/dist /opt/wecom-it-desk/dist-backup-2026-06-21/admin
sudo cp -r /opt/wecom-it-desk/frontend-agent/dist /opt/wecom-it-desk/dist-backup-2026-06-21/agent
sudo cp -r /opt/wecom-it-desk/frontend-portal/dist /opt/wecom-it-desk/dist-backup-2026-06-21/portal
sudo cp -r /opt/wecom-it-desk/frontend-h5/dist /opt/wecom-it-desk/dist-backup-2026-06-21/h5
echo "备份完成"

# 1.3 备份 alembic 版本号(用于回滚确认)
sudo docker exec wecom_it_postgres psql -U postgres -d wecom_it -c "SELECT version_num FROM alembic_version;"

步骤 2/6:拉新 backend 镜像并跑 migration

# 2.1 拉新镜像
sudo docker pull wecom_it_backend:v0.7.0

# 2.2 跑 migration(只 PG,SQLite 跳过)
sudo docker exec wecom_it_backend alembic upgrade head
# 期望输出:
#   Running upgrade 024 -> 025, messages.id UUID
#   Running upgrade <old> -> 022, qrcode_login
#   Running upgrade <old> -> 023, mfa_fields

# 2.3 验证 migration head
sudo docker exec wecom_it_postgres psql -U postgres -d wecom_it -c "SELECT version_num FROM alembic_version;"
# 期望:025_messages_id_uuid

# 2.4 验证 messages.id 已改为 UUID
sudo docker exec wecom_it_postgres psql -U postgres -d wecom_it -c "\d messages" | grep "^ id"
# 期望:类型为 uuid

🚨 若 migration 失败:

sudo docker exec wecom_it_backend alembic downgrade -1
# 联系 Claude 排查

步骤 3/6:重启 backend 容器

# 3.1 重启(用 v0.7.0 镜像)
sudo docker restart wecom_it_backend

# 3.2 等 10 秒,检查启动日志
sudo docker logs wecom_it_backend --tail 50

# 期望看到:
#   Application startup complete
#   Uvicorn running on http://0.0.0.0:8000
# 没有 "ModuleNotFoundError" / "relation already exists" / "Restarting" 循环

# 3.3 健康检查
sudo docker ps | grep wecom_it_backend
# 期望:STATUS = Up X minutes (healthy)

🚨 若 backend 启动失败,回滚:

sudo docker tag wecom_it_backend:v0.6.0-backup wecom_it_backend
sudo docker restart wecom_it_backend

步骤 4/6:上传 4 端 dist 到宿主机

# 4.1 在本地(Windows)打包 4 端 dist
cd /d/资料/03-项目开发/wecom_it_smart_desk-claude
tar -czf /tmp/frontend-v0.7.0.tar.gz \
  frontend-admin/dist frontend-agent/dist frontend-portal/dist frontend-h5/dist
ls -la /tmp/frontend-v0.7.0.tar.gz

# 4.2 上传到生产服务器(走堡垒机)
scp /tmp/frontend-v0.7.0.tar.gz <堡垒机用户>@<堡垒机>:/tmp/

# 4.3 在生产服务器解压
ssh <堡垒机>  # 跳到生产
cd /opt/wecom-it-desk
sudo tar -xzf /tmp/frontend-v0.7.0.tar.gz
ls -la frontend-*/dist | head -20
# 期望:每个 dist 都有 index.html + assets/

# 4.4 清理压缩包
sudo rm /tmp/frontend-v0.7.0.tar.gz

🚨 若上传失败,回滚:

# 4 端用备份恢复
sudo cp -r /opt/wecom-it-desk/dist-backup-2026-06-21/admin/* /opt/wecom-it-desk/frontend-admin/dist/
sudo cp -r /opt/wecom-it-desk/dist-backup-2026-06-21/agent/* /opt/wecom-it-desk/frontend-agent/dist/
sudo cp -r /opt/wecom-it-desk/dist-backup-2026-06-21/portal/* /opt/wecom-it-desk/frontend-portal/dist/
sudo cp -r /opt/wecom-it-desk/dist-backup-2026-06-21/h5/* /opt/wecom-it-desk/frontend-h5/dist/

步骤 5/6:应用 nginx access_log 脱敏 + reload

# 5.1 验证当前 nginx 容器名(下划线不是横杠!)
sudo docker ps | grep wecom_it_nginx
# 期望:0.0.0.0:80->80/tcp   wecom_it_nginx

# 5.2 进入容器加 log_format 脱敏配置
sudo docker exec wecom_it_nginx bash -c '
cat > /etc/nginx/conf.d/log-format.conf << "EOF"
log_format secure $remote_addr - $remote_user [$time_local] "$request_method $uri $server_protocol" $status $body_bytes_sent "$http_referer" "$http_user_agent";
access_log /var/log/nginx/access.log secure;
EOF
'
# 验证写入
sudo docker exec wecom_it_nginx cat /etc/nginx/conf.d/log-format.conf

# 5.3 验证配置
sudo docker exec wecom_it_nginx nginx -t
# 期望:nginx: configuration file /etc/nginx/nginx.conf test is successful

# 5.4 reload(不重启容器)
sudo docker exec wecom_it_nginx nginx -s reload

# 5.5 验证 reload 生效
sudo docker exec wecom_it_nginx tail -3 /var/log/nginx/access.log
# 期望:没有 Authorization: Bearer xxx 字样

🚨 若 nginx reload 失败:

# 恢复默认 access_log
sudo docker exec wecom_it_nginx bash -c 'echo "access_log /var/log/nginx/access.log;" > /etc/nginx/conf.d/log-format.conf'
sudo docker exec wecom_it_nginx nginx -t
sudo docker exec wecom_it_nginx nginx -s reload

步骤 6/6:验证域名路由

# 6.1 验证 4 个 location 都返回 200
curl -I https://<生产域名>/itportal/  # 应 200
curl -I https://<生产域名>/itagent/   # 应 200
curl -I https://<生产域名>/itadmin/   # 应 200
curl -I https://<生产域名>/itdesk/    # 应 200

# 6.2 验证 API 端点
curl https://<生产域名>/api/health
# 期望:{"code":0,"data":{"status":"ok"}}

# 6.3 验证扫码登录端点
curl -X POST https://<生产域名>/api/auth_qrcode/create -H "Content-Type: application/json" -d '{}'
# 期望:{"code":0,"data":{"ticket":"...","qrcode_url":"...","expires_in":120}}

# 6.4 验证 MFA 端点(无 token 应 401)
curl https://<生产域名>/api/mfa/status
# 期望:401 Unauthorized

---

🟡 部署后 必做(用户/QA 验收)

按 docs/E2E-CHECKLIST-v0.7.0.md 35 项,逐项打勾。

关键项:

• 浏览器扫码登录全流程(5 子项)
• MFA 绑定 + 30 分钟有效期
• 高危操作守卫(5 类端点)
• WS 推送无 missing argument 错误
• 消息 ID 改为 UUID,无 500
• nginx access_log 无 Authorization/Cookie

---

🔴 部署后 1 周观察(用户拍板)

• 一切正常 → 清理 /opt/wecom-it-desk/dist-backup-2026-06-21/ 和 ~/Downloads/patch1/
• 任何 regression → 用 DEPLOY-LOGIN-MIGRATION-v0.7.0.md 末尾的"回滚预案"恢复

---

📊 部署时间预估

步骤	预计时间	风险
1. 备份	1 min	低
2. migration	1 min	中(若冲突需手动)
3. 重启 backend	2 min(含等健康)	中(若镜像问题需回滚)
4. 上传 4 端	5 min(含上传)	低
5. nginx reload	1 min	低
6. 验证	5 min	低
总计	15 min

---

🆘 紧急联系人

• 部署问题:本会话 + Claude
• backend 代码:Claude session
• 生产服务器:IT 基础设施组