chore(docs): docs/ 目录全面重新编号 + 重组
**重构前**（旧编号 02-11）： - docs/02-产品需求/ → 00 产品规划/PRD - docs/03-技术架构/ → 01-05 子目录散落 - docs/04-原型设计/ → 01-02 产品设计（HTML 原型） - docs/05-原型设计/ → screens/ - docs/06-测试素材/ → 02-E2E / 03-功能 / 04-版本测试 - docs/07-项目管理/ → 任务说明书/日报/计划 - docs/08-安全审计/ → 审计报告 - docs/09-堡垒运维/ → toolbox / deploy - docs/10-项目管理/ → 任务说明书（重复） - docs/11-历史归档/ → deploy-nas-archived **重构后**（新编号 00-07，语义化）： - docs/00-产品开发流程与文档管理规范.md - docs/00-版本迭代总览.md - docs/01-产品文档/ （PRD/原型/认证/会话/AI 服务/坐席/集成） - docs/02-技术文档/ （技术方案/架构图/重构记录/前端改造/实现配置） - docs/03-测试文档/ （E2E/功能用例/版本报告/缺陷单） - docs/04-运维文档/ （部署运维/运维指南） - docs/05-运营文档/ （品牌推广/用户手册） - docs/06-安全审计/ （审计报告） - docs/07-项目管理/ （任务说明书/日报/计划/看板） **净收益**： - 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号） - 消除 02-产品需求 与 10-项目管理 的编号重叠 - 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录） - 把运维/安全/项目管理从 0X 散落改为 04/06/07 合计 494 文件 + 78495 行 / - 14076 行
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