wecom_it_smart_desk/docs/08-历史归档/DEPLOY-v0.7.1-archived-20260704.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 分钟)

# 备份 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 分钟)

# 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 分钟)

# 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/

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

Step 5: 验证 5 角色种子已建(2 分钟)

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 分钟)

# 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 分钟)

# 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

🆘 回滚预案

# 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)