From 1255e95a73fdad2f43373515afa8e1e7ce0bd890 Mon Sep 17 00:00:00 2001 From: Simon Date: Sun, 21 Jun 2026 06:19:05 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20v0.7.0=20=E4=B8=80=E9=94=AE=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E6=93=8D=E4=BD=9C=E5=8C=85(=E5=88=86=E6=AD=A5?= =?UTF-8?q?=E5=91=BD=E4=BB=A4+=E5=9B=9E=E6=BB=9A+=E9=A2=84=E8=AE=A1?= =?UTF-8?q?=E6=97=B6=E9=97=B4)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 给生产运维一站到底的部署指南: - 步骤 1-6 顺序:备份 → migration → 重启 → 上传 4 端 → nginx → 验证 - 每步带回滚命令(任意一步失败立即回滚) - 预计时间 15 分钟 - 容器名纠错:wecom_it_nginx(下划线不是横杠) - RO bind mount 陷阱提醒 - Gitea token 撤销+重签+push+立刻删除流程 Co-Authored-By: Claude --- docs/DEPLOY-QUICK-v0.7.0.md | 252 ++++++++++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 docs/DEPLOY-QUICK-v0.7.0.md diff --git a/docs/DEPLOY-QUICK-v0.7.0.md b/docs/DEPLOY-QUICK-v0.7.0.md new file mode 100644 index 0000000..ef75078 --- /dev/null +++ b/docs/DEPLOY-QUICK-v0.7.0.md @@ -0,0 +1,252 @@ +# 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) + +```bash +# 在本地工作目录(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:备份当前生产状态 + +```bash +# 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 + +```bash +# 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 -> 022, qrcode_login +# Running upgrade -> 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 失败**: +```bash +sudo docker exec wecom_it_backend alembic downgrade -1 +# 联系 Claude 排查 +``` + +### 步骤 3/6:重启 backend 容器 + +```bash +# 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 启动失败,回滚**: +```bash +sudo docker tag wecom_it_backend:v0.6.0-backup wecom_it_backend +sudo docker restart wecom_it_backend +``` + +### 步骤 4/6:上传 4 端 dist 到宿主机 + +```bash +# 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 +``` + +**🚨 若上传失败,回滚**: +```bash +# 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 + +```bash +# 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 失败**: +```bash +# 恢复默认 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:验证域名路由 + +```bash +# 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 基础设施组