simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 扫码登录+OTP 用户手册 + Phase 1+2 部署手册 (task #21 初稿)

Browse Source 
- docs/USER-GUIDE-QRCODE-MFA.md — 员工/坐席/管理员三端用户指南
  - 扫码登录流程
  - OTP 绑定步骤
  - 高危操作 OTP 弹窗
  - 蜂鸟 SMS 备用通道
  - 丢手机兜底(管理员后台重置)
  - 常见问题 FAQ

- docs/DEPLOY-LOGIN-MIGRATION-v0.7.0.md — 运维部署手册
  - 部署前检查(依赖/migration/配置/域名)
  - 部署步骤(后端→前端 4 端→nginx→migration→验收)
  - RO bind mount 陷阱提示
  - 容器名坑(nginx 用 wecom_it_nginx)
  - 回滚方案
  - 已知风险与缓解

后续:task #21 E2E 验收 + 集成测试会在代码合入后补充
This commit is contained in:
Simon
2026-06-21 01:14:59 +08:00
parent c3899594d0
commit c1ac9b936c
2 changed files with 385 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEPLOY-LOGIN-MIGRATION-v0.7.0.md
+220
View File
@@ -0,0 +1,220 @@
# 部署手册:扫码登录 + OTP 二次认证(Phase 1+2)
> 创建:2026-06-21
> 适用版本:v0.7.0+ (Phase 1+2)
> 部署顺序:后端 → 前端 4 端 → nginx → 数据库 migration → 验收
---
## 🎯 部署目标
从 v0.6.x 的"企微 OAuth + SMS 2FA"升级到 v0.7.0 的"扫码登录 + OTP TOTP + SMS 备用"。
涉及后端变更:
- 新增 `/api/auth_qrcode/*` 4 个端点(扫码登录)
- 新增 `/api/mfa/*` 6 个端点(OTP 二次认证)
- 新增 `/api/admin/mfa/reset/{employee_id}`(管理员重置)
- 新增 `/api/admin/high-risk/*` 演示端点 + require_high_risk_otp 守卫
- 新增 2 个数据库字段: `users.mfa_secret`, `users.mfa_enabled`, `users.mfa_bound_at`, `users.mfa_last_verified_at`
涉及前端变更:
- frontend-agent:Login.vue 重写(扫码 UI)+ 新增 MfaBind.vue + useHighRiskOtp
- frontend-portal:新增 QrcodeLogin.vue + 默认路由
- frontend-admin:新增 MfaManage.vue(管理员 MFA 重置 UI)
- frontend-h5:**不变**(仍走企微 OAuth)
涉及 nginx 变更:
- `/itportal/` 新增 location(扫码入口)
- 其余 4 个 location 已有,配置按 docs/NGINX-DOMAIN-ROUTING.md
---
## 📋 部署前检查
### 1. 后端镜像依赖
`backend/requirements.txt` 必须包含:
```
pyotp==2.9.0 # TOTP 生成
qrcode[pil]==7.4.2 # 二维码生成
redis==5.0.7 # 已存在
```
### 2. 数据库迁移文件
确认以下 migration 已存在:
- `backend/alembic/versions/023_mfa_fields.py`(加 4 个 MFA 字段)
- `backend/alembic/versions/024_*.py`(可选:其他变更)
### 3. 配置文件
`backend/.env` 确认:
```bash
# 新增(扫码登录)
WECOM_OAUTH_REDIRECT_URI=https://itsupport.servyou.com.cn/itportal/qrcode-callback
WECOM_CORP_ID=ww1234567890abcdef
WECOM_AGENT_ID=1000002
# 已有(OTP)
SMS_2FA_ENABLED=true # 蜂鸟 SMS 备用通道
```
### 4. 域名 / DNS
- `itsupport.servyou.com.cn`(主域名,已有)
- 子路径:`/itportal/` `/itagent/` `/itadmin/` `/itdesk/`(同一域名,nginx 分发)
- 证书:`itsupport.servyou.com.cn.crt`(公司统一管理)
---
## 🚀 部署步骤
### 步骤 1:部署后端(注意 RO bind mount)
```bash
# 1. 上传新 backend 包到堡垒机
scp backend-v070-p1.tar.gz user@bastion:/tmp/
# 2. 通过堡垒机 PuTTY(不用 ssh -J)登录生产服务器
# 参考:feedback-putty-not-openssh.md
# 3. 解压并复制到 backend 目录(走宿主机路径,避开 RO bind mount 陷阱)
cd /opt/wecom-it-desk/
tar -xzf /tmp/backend-v070-p1.tar.gz
# 注意:用 cp -r 不是 docker cp(避开 RO bind mount 假成功陷阱)
sudo cp -r backend-v070-p1/* backend/
# 4. 数据库 migration
cd /opt/wecom-it-desk/backend
sudo docker exec wecom_it_backend alembic upgrade head
# 验证:
sudo docker exec wecom_it_backend alembic current
# 期望:023_mfa_fields (head)
# 5. 重启 backend(注意:backend 不在 compose 里,直接 docker restart)
sudo docker restart wecom_it_backend
# 验证:等待 ~30s,看健康检查
curl http://localhost:8000/health
# 期望:{"status":"ok",...}
```
### 步骤 2:部署前端 4 端
```bash
# 1. 各前端 build(本地)
cd frontend-agent && npm run build
cd frontend-portal && npm run build
cd frontend-admin && npm run build
# frontend-h5 不变,不用 build
# 2. 上传 dist 到生产服务器
scp -r frontend-agent/dist user@bastion:/tmp/agent-dist/
scp -r frontend-portal/dist user@bastion:/tmp/portal-dist/
scp -r frontend-admin/dist user@bastion:/tmp/admin-dist/
# 3. 通过堡垒机,复制到 nginx 容器挂载的目录
# 路径可能是 /opt/wecom-it-desk/frontend-*/
sudo cp -r /tmp/agent-dist/* /opt/wecom-it-desk/frontend-agent/dist/
sudo cp -r /tmp/portal-dist/* /opt/wecom-it-desk/frontend-portal/dist/
sudo cp -r /tmp/admin-dist/* /opt/wecom-it-desk/frontend-admin/dist/
# 4. 验证:curl HTML 文件
curl -I https://itsupport.servyou.com.cn/itportal/
# 期望:200 OK,content-type: text/html
```
### 步骤 3:更新 nginx 配置
```bash
# 1. 上传新 nginx 配置
# 新增 /itportal/ location,更新其他 location
# 参考:docs/NGINX-DOMAIN-ROUTING.md
# 2. 验证配置(在 nginx 容器里)
sudo docker exec wecom_it_nginx nginx -t
# 注意容器名是 wecom_it_nginx 不是 wecom-nginx
# 期望:nginx: configuration file /etc/nginx/nginx.conf test is successful
# 3. reload(不重启容器)
sudo docker exec wecom_it_nginx nginx -s reload
```
### 步骤 4:验收测试
按 docs/NGINX-DOMAIN-ROUTING.md 末"验证清单"逐条测试。
---
## 🔄 回滚方案
### 后端回滚
```bash
# 1. 用上次 patch1 备份
sudo cp -r /opt/wecom-it-desk/backend-v070-patch1/* /opt/wecom-it-desk/backend/
sudo docker restart wecom_it_backend
# 2. 数据库回滚(谨慎!)
sudo docker exec wecom_it_backend alembic downgrade -1
# 注意:只能降 1 个版本,如果已经升到 023,降到 022
```
### 前端回滚
```bash
# 直接覆盖 dist
sudo cp -r /opt/wecom-it-desk/frontend-*-bak/* /opt/wecom-it-desk/frontend-*/dist/
```
### nginx 回滚
```bash
# 容器内 sed -i 改回旧配置(避开 RO bind mount 假成功陷阱)
sudo docker exec wecom_it_nginx cp /etc/nginx/nginx.conf.bak /etc/nginx/nginx.conf
sudo docker exec wecom_it_nginx nginx -s reload
```
---
## ⚠️ 已知风险
| 风险 | 影响 | 缓解 |
|---|---|---|
| OTP 二维码渲染失败(后端 base64 生成出错) | 用户绑不上 OTP | 前端降级显示 qrcode_url 让用户手动复制 |
| pyotp 库版本升级导致不兼容 | OTP 验证失败 | 锁版本 pyotp==2.9.0,生产前跑 pytest |
| Admin MFA 重置端点被未授权访问 | 安全 | require_admin + 后续可加 IP 白名单 |
| 蜂鸟 SMS API 未上线 | 备用通道不可用 | 不影响 OTP 主通道,先上线 OTP,后接 SMS |
| nginx IP 白名单临时全开 | 安全 | v1.0 前必须收窄(task #48) |
---
## 📊 部署后验证
### 业务指标
- [ ] 扫码登录成功率 > 95%
- [ ] OTP 验证成功率 > 99%
- [ ] 高危操作 OTP 触发率 100%
- [ ] 蜂鸟 SMS fallback 触发 < 5%(绝大多数人用 OTP)
### 技术指标
- [ ] 扫码登录端到端 < 5s(从扫码到进入工作台)
- [ ] OTP 验证 < 500ms
- [ ] 高危操作 OTP 弹窗响应 < 200ms
---
## 📚 相关文档
- [USER-GUIDE-QRCODE-MFA.md](./USER-GUIDE-QRCODE-MFA.md) — 用户手册
- [NGINX-DOMAIN-ROUTING.md](./NGINX-DOMAIN-ROUTING.md) — nginx 域名分发
- [v070-alpha-deploy-runbook.md](../memory/v070-alpha-deploy-runbook.md) — v0.7.0-alpha 总览
- [docker-cp-readonly-bind-mount-fake-success.md](../memory/docker-cp-readonly-bind-mount-fake-success.md) — RO bind mount 陷阱
- [nginx-container-name-wecom-it-nginx.md](../memory/nginx-container-name-wecom-it-nginx.md) — 容器名坑
- [feedback-putty-not-openssh.md](../memory/feedback-putty-not-openssh.md) — 堡垒机 PuTTY
---
**变更历史**:
- 2026-06-21 创建(Phase 1+2 部署手册)
docs/USER-GUIDE-QRCODE-MFA.md
+165
View File
@@ -0,0 +1,165 @@
# 用户手册:扫码登录 + OTP 二次认证(Phase 1+2)
> 创建:2026-06-21
> 适用版本:v0.7.0+ (Phase 1+2 上线后)
> 读者:全体员工、坐席、管理员
---
## 📖 这是什么?
从 v0.7.0 开始,登录方式升级为**扫码登录 + OTP 二次认证**:
- ✅ 不再依赖企业微信应用入口,任意浏览器都能打开
- ✅ 多角色用户(坐席+管理员)可在 Portal 选角色自动跳转
- ✅ 管理员每次登录强制 OTP,高危操作也强制 OTP
- ✅ 备用通道:蜂鸟短信(手机丢/没装 Authenticator 时用)
---
## 🧑‍💼 员工端(H5)
### 入口
- 仍在企微内打开"IT智能服务台"应用
- 不需要扫码登录,沿用企微 OAuth
### 使用场景
- 提工单
- 看历史会话
- 查知识库
---
## 🧑‍🔧 坐席端(Agent)
### 首次登录(扫码)
```
步骤 1:浏览器访问 https://itsupport.servyou.com.cn/itportal/
步骤 2:页面显示二维码(120 秒有效)
步骤 3:用企业微信扫 → 确认登录
步骤 4:自动跳到 /itagent/workspace
```
### 日常登录
- 浏览器直接打开 `https://itsupport.servyou.com.cn/itagent/`
- 没登录 → 自动跳到 Portal 扫码
- 第二次扫码可免重复(浏览器记住 localStorage)
### 高危操作时 OTP
如果你是**坐席+管理员**(双角色),触发以下操作前会弹 OTP 输入框:
- 改权限
- 改系统配置
- 导出数据
- 封号
- 新增账号/MFA 重置
弹框出现 → 输入 Authenticator 6 位码 → 验证通过(30 分钟内免重输)
---
## 🛡️ 管理员端(Admin)
### 入口
- 浏览器直接打开 `https://itsupport.servyou.com.cn/itadmin/`
- 没登录 → 自动跳到 Portal 扫码
### 强制 OTP
管理员**每次登录都需要 OTP**:
- 扫码登录成功后,会跳到 MFA 绑定页(首次)或 OTP 验证页
- 输入 Authenticator 6 位码 → 进入管理后台
- 高危操作前还要再验一次(30 分钟内免重输)
### 首次绑定 OTP(强制)
```
步骤 1:登录后 → 自动跳 /mfa-bind
步骤 2:用 Google Authenticator / 微软 Authenticator / Authy 扫描二维码
步骤 3:输入 Authenticator 显示的 6 位码 → 点"启用 OTP"
步骤 4:绑定成功,后续登录用 OTP 验证
```
### 丢手机兜底(管理员后台重置)
如果你手机丢了/坏了,**找其他管理员重置**:
```
步骤 1:其他管理员登录 /itadmin/
步骤 2:进入"用户管理" → "MFA 管理"
步骤 3:搜索你的姓名 → 点"重置 MFA"
步骤 4:你下次登录时重新绑定 OTP
```
---
## 🆘 备用通道:蜂鸟 SMS
什么情况下用:
- 📱 手机丢了/坏了
- 🆕 刚入职,还没装 Authenticator
- 🔧 Authenticator 客户端不兼容
怎么用:
- 在 OTP 输入页点"收不到验证码?短信验证"
- 输入手机号(企微已绑定)→ 收短信码 → 验证
---
## 📱 推荐 OTP 客户端
| 客户端 | 平台 | 推荐度 |
|---|---|---|
| Google Authenticator | iOS / Android | ⭐⭐⭐⭐⭐ |
| 微软 Authenticator | iOS / Android | ⭐⭐⭐⭐ |
| Authy | iOS / Android / 桌面 | ⭐⭐⭐⭐⭐ |
| 1Password | 全平台 | ⭐⭐⭐ |
公司偏好:**Google Authenticator**(零依赖,离线可用)
---
## ❓ 常见问题
### Q1:扫码登录过期了怎么办?
A:二维码有效期 120 秒,过期后点"刷新二维码"按钮。
### Q2:扫码登录失败?
A:
- 确认用的是企业微信(不是普通微信)
- 确认企微里能看到"IT智能服务台"应用
- 刷新页面重新生成二维码
### Q3:OTP 输入错误?
A:连续 5 次错误会被锁定 5 分钟,等 5 分钟后再试。
### Q4:换手机了怎么办?
A:登录前在旧手机上导出 OTP(Google Authenticator 支持),或者找管理员后台重置。
### Q5:多角色用户(admin + agent)怎么登录?
A:扫码登录成功后,Portal 自动跳到角色选择页,选你要进入的工作台。
### Q6:H5 员工端也需要扫码吗?
A:不需要。H5 员工端仍在企微内,沿用企微 OAuth。
### Q7:扫码登录安全吗?
A:扫码登录比企微 OAuth 还安全:
- 员工必须用企微扫(企微已经做了员工身份认证)
- 二维码 120 秒过期
- Token 8 小时过期
- 高危操作还要再 OTP 一次
---
## 📞 技术支持
- 内部: 信息技术部 服务台
- 紧急: 群里 @ IT 主管
- 反馈: https://itsupport.servyou.com.cn/itdesk/feedback
---
**变更历史**:
- 2026-06-21 创建(Phase 1+2 培训)