feat(v0.7.1): P0 修复 + 企微 SSO + RBAC 细粒度 + audit_log
P0 修复: - /api/ready import 错误 (_get_engine + settings.create_redis_client) - 删 agent.otp_secret/otp_enabled 双字段 (migration 026) - 重建 021_rbac migration (IF NOT EXISTS 兼容) P1 新增: - 企微 SSO (auth_wecom_sso.py, useWeChatWorkSSO composable, PortalSelect UA 检测) - RBAC 5 角色 × 4 资源 × 4 操作 × 3 范围 (rbac_service + seed_rbac + require_permission) - audit_log 模型 + migration 027 + 服务 + API - 管理后台 RBAC 权限矩阵 UI (PermissionsMatrix.vue) 质量: - pytest 405 passed / 33 pre-existing failed / 4 xfailed (v0.7.1 引入失败 = 0) - conftest GBK patch 强制 UTF-8 读 .env - .gitignore 排除 *.b64 (含 admin token 凭据) - DEPLOY-v0.7.1.md 7 步 runbook + 4 坑 + 回滚预案
This commit is contained in:
Simon
@@ -0,0 +1,190 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user