wecom_it_smart_desk/DEPLOY-v0.7.1.md

# v0.7.1 部署 runbook (2026-06-22)

## 🎯 一句话

v0.7.1-dev 修复 v0.7.0-hotfix1 的 3 个生产 bug + 新增企微 SSO + RBAC 细粒度权限。**预计 30 分钟**完成部署。

## 📋 v0.7.1 vs v0.7.0 变化

| 类别 | 变化 | 风险 |
|------|------|------|
| 数据库 | 1 个新 migration `026_drop_agent_otp_legacy`(删 `agents.otp_secret`/`otp_enabled` 列) | 🟢 低,生产未正式上线 |
| 数据库 | 重建 `021_rbac` migration(IF NOT EXISTS 兼容,已存在则跳过) | 🟢 低,幂等 |
| 后端 API | 新增 `/api/auth_wecom/sso/{init,callback,verify}` (3 端点) | 🟢 低,新路径 |
| 后端 API | 新增 `/api/admin/roles/permissions/{matrix,check}` (2 端点) | 🟢 低,新路径 |
| 后端服务 | `services/rbac_service.py` 权限矩阵 + `data/seed_rbac.py` 启动种子 | 🟢 低,首次启动建角色 |
| 前端 | `useWeChatWorkSSO.ts` composable + `PortalSelect.vue` 集成 UA 检测 | 🟢 低,默认走 QR 兜底 |
| 配置 | `WECOM_SSO_ENABLED=false` (默认) | 🟢 低,需要手动开 |

## 🚀 部署步骤(基于 v0.7.0-alpha 经验)

### Step 1: 备份(2 分钟)
```bash
# 备份 v0.7.0
cd /opt/wecom-it-desk
docker exec wecom_it_postgres pg_dump -U wecom wecom_it_desk > /tmp/backup-v0.7.0-$(date +%Y%m%d-%H%M).sql
git tag v0.7.0-deployed

# 备份 v0.7.0 容器镜像
docker tag wecom-it-desk-backend:v0.7.0 wecom-it-desk-backend:v0.7.0-deployed
```

### Step 2: 拉 v0.7.1 代码 + alembic 升级(5 分钟)
```bash
# 1. 拉 v0.7.1-dev 分支
cd /opt/wecom-it-desk
git fetch origin
git checkout v0.7.1-dev
git pull

# 2. 重新 build 镜像(仅 backend,前端 dist 单独传)
docker build -t wecom-it-desk-backend:v0.7.1 ./backend

# 3. alembic 升级(包含 026 + 重建 021)
docker exec -it wecom_it_backend alembic upgrade head
# 预期输出:
#   INFO  [alembic.runtime.migration] Running upgrade 025_messages_id_uuid -> 026_drop_agent_otp_legacy
#   INFO  [alembic.runtime.migration] No migrations to apply (021 已存在则跳过)
```

### Step 3: 重启 backend(2 分钟)
```bash
# 1. 停 backend
docker stop wecom_it_backend

# 2. 删容器(保留镜像)
docker rm wecom_it_backend

# 3. 用 v0.7.1 镜像起
docker run -d --name wecom_it_backend \
  --network wecom-it-desk_wecom-net \
  -e DATABASE_URL=postgresql://wecom:wecom_secret@wecom_it_postgres:5432/wecom_it_desk \
  -e REDIS_URL=redis://wecom_it_redis:6379/0 \
  -e WECOM_SSO_ENABLED=false \
  -e WECOM_SSO_CALLBACK_BASE=https://itsupport.servyou.com.cn \
  wecom-it-desk-backend:v0.7.1

# 4. 健康检查
docker ps | grep wecom_it_backend
curl http://127.0.0.1/api/health
curl http://127.0.0.1/api/ready  # v0.7.1 修复
```

### Step 4: 上传前端 4 端 dist(用户手动,10 分钟)
走堡垒机 web 上传到 `/opt/wecom-it-desk/frontend-{portal,admin,agent,h5}/dist/`

```bash
# 上传完后,容器无需重启,nginx 直接 serve 新文件
# 但因为 bind mount,可能要 restart nginx
docker exec wecom_it_nginx nginx -s reload
```

### Step 5: 验证 5 角色种子已建(2 分钟)
```bash
docker exec wecom_it_postgres psql -U wecom wecom_it_desk -c "SELECT name, display_name, jsonb_array_length(permissions) AS perm_count FROM roles ORDER BY name;"
# 预期输出:
#   name      | display_name | perm_count
#   ----------+--------------+------------
#   admin     | 超级管理员   | 1
#   agent     | IT 坐席     | 4
#   auditor   | 审计员      | 4
#   team_lead | 团队主管    | 5
#   user      | 普通员工    | 2
```

### Step 6: SSO 配置(可选,5 分钟)
```bash
# 1. 企微管理后台 → 应用 → 网页授权及 JS-SDK
#    可信域名: itsupport.servyou.com.cn
#    回调域: itsupport.servyou.com.cn

# 2. 启用 SSO(默认 false)
docker stop wecom_it_backend
docker rm wecom_it_backend
docker run -d --name wecom_it_backend \
  --network wecom-it-desk_wecom-net \
  -e WECOM_SSO_ENABLED=true \
  ... wecom-it-desk-backend:v0.7.1

# 3. 测试 SSO 初始化(企微浏览器)
# 打开 https://itsupport.servyou.com.cn/itportal/
# 期望: 企微 UA 检测 → 跳 /api/auth_wecom/sso/init → 企微授权 → 跳回
```

### Step 7: E2E 验证(5 分钟)
```bash
# 1. /api/ready 修复验证
curl http://127.0.0.1/api/ready
# 预期: {"code":0,"data":{"database":"ok","redis":"ok"}}

# 2. SSO 端点注册验证
curl -I http://127.0.0.1/api/auth_wecom/sso/init
# 预期: 422 (缺 next 参数) 而非 404

# 3. 权限矩阵端点
TOKEN=$(curl -s -X POST http://127.0.0.1/api/agents/login \
  -H "Content-Type: application/json" \
  -d '{"user_id":"sxn","name":"宋献","password":"xxx"}' | jq -r .data.token)
curl -s http://127.0.0.1/api/admin/roles/permissions/matrix \
  -H "Authorization: Bearer $TOKEN" | jq '.data.roles | length'
# 预期: 5
```

## ⚠️ 已知坑 & 应对

### 坑 1: pydantic-settings 优先读 .env
**症状**: backend 起来后 aiosqlite ImportError
**应对**:
- `backend/.dockerignore` 已排除 `.env`(v0.7.0 加的)
- `backend/Dockerfile` 已加 `RUN rm -f /app/.env`(v0.7.0 加的)
- 启动时**不要**用宿主机 .env 覆盖容器 .env

### 坑 2: alembic 026 删 otp_secret
**症状**: 如果生产已用 OTP 绑定,会丢失绑定关系
**应对**:
- v0.7.0-hotfix1 期间 IT 支持未正式上线,无用户
- 部署前 `SELECT count(*) FROM agents WHERE otp_secret IS NOT NULL` 应为 0
- 若有用户,先在管理后台解绑,再部署

### 坑 3: SSO 默认未启用
**症状**: 企微浏览器进 /itportal/ 还是走 QR 流程
**应对**:
- 默认 `WECOM_SSO_ENABLED=false`,老用户不受影响
- 想启用需手动配环境变量 + 企微后台可信域名

### 坑 4: 5 角色权限种子在第一次启动写
**症状**: 老数据有 user/agent/admin 3 角色,缺 team_lead/auditor
**应对**:
- `seed_rbac_roles()` 检测到已存在会更新 permissions(不动 is_default)
- 新增的 team_lead/auditor 会自动 INSERT

## 🆘 回滚预案

```bash
# 1. 停 v0.7.1
docker stop wecom_it_backend
docker rm wecom_it_backend

# 2. 起 v0.7.0
docker run -d --name wecom_it_backend ... wecom-it-desk-backend:v0.7.0-deployed

# 3. alembic 不需要回滚(026 是 IF EXISTS,021 是 IF NOT EXISTS,都是安全操作)

# 4. 恢复 DB
psql -U wecom wecom_it_desk < /tmp/backup-v0.7.0-*.sql
```

## ✅ 部署完成 checklist

- [ ] Step 1 备份完成
- [ ] Step 2 alembic 升级无错
- [ ] Step 3 backend 启动 healthy
- [ ] `/api/ready` 返回 OK
- [ ] Step 4 前端 4 端 dist 上传 + nginx reload
- [ ] Step 5 5 角色已建
- [ ] Step 7 3 项 curl 验证通过
- [ ] 浏览器测试 /itportal/ 扫码登录
- [ ] 浏览器测试 /itportal/ 角色选择
- [ ] 浏览器测试 /itdesk/ /itagent/ /itadmin/ 跳转

**部署完成时间**: ~30 分钟 (备份 2 + alembic 5 + 重启 2 + 前端 10 + 验证 5 + 缓冲 6)