# 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 <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 失败**:
```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 基础设施组