Simon
44e77dcb0e
**重构前**（旧编号 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 行
148 lines
4.5 KiB
Markdown
148 lines
4.5 KiB
Markdown
# H5 部署 Runbook v0.7.1
|
|
|
|
> 📅 创建:2026-06-23 | 适用版本:v0.7.0+ | 前端:H5(dist/) + nginx `/itdesk/`
|
|
|
|
## 🎯 目标
|
|
|
|
把 `frontend-h5/dist/` 部署到生产 nginx,让员工可以通过企微 App 访问 `https://itsupport.servyou.com.cn/itdesk/` 并完成 OAuth 授权登录。
|
|
|
|
## ⚠️ 前置条件
|
|
|
|
1. ✅ 后端已部署 v0.7.0+(支持 `/api/auth_wecom/sso/init` + `/api/auth_wecom/sso/verify`)
|
|
2. ✅ 已设置环境变量 `WECOM_SSO_ENABLED=true` + `WECOM_SSO_CALLBACK_BASE=https://itsupport.servyou.com.cn`
|
|
3. ✅ 企微后台已添加 `itsupport.servyou.com.cn` 为应用可信域名
|
|
4. ✅ 已有 `frontend-h5/dist/` 构建产物
|
|
|
|
## 📦 部署步骤
|
|
|
|
### Step 1: 构建 dist
|
|
|
|
```bash
|
|
cd frontend-h5
|
|
npm install
|
|
npm run build
|
|
ls -la dist/ # 应有 index.html + assets/
|
|
```
|
|
|
|
### Step 2: 打包 tar.gz(可选,便于堡垒机传输)
|
|
|
|
```powershell
|
|
# Windows PowerShell
|
|
Compress-Archive -Path dist\* -DestinationPath h5-dist-v0.7.1.zip
|
|
# 或 Git Bash
|
|
cd dist && tar -czf ../h5-dist-v0.7.1.tar.gz . && cd ..
|
|
```
|
|
|
|
### Step 3: 上传到生产 nginx 主机
|
|
|
|
通过堡垒机 → admin 用户 → 上传到 `/tmp/h5-dist/`
|
|
|
|
### Step 4: 解压到 nginx 静态目录
|
|
|
|
```bash
|
|
# 假设 nginx 静态文件目录在 /opt/wecom-it-desk/nginx/html/
|
|
sudo mkdir -p /opt/wecom-it-desk/nginx/html/itdesk
|
|
sudo cp -r /tmp/h5-dist/* /opt/wecom-it-desk/nginx/html/itdesk/
|
|
sudo chown -R nginx:nginx /opt/wecom-it-desk/nginx/html/itdesk/
|
|
```
|
|
|
|
### Step 5: nginx 配置(若未配置)
|
|
|
|
确保 `/etc/nginx/conf.d/wecom-it-desk.conf` 包含:
|
|
|
|
```nginx
|
|
location /itdesk/ {
|
|
alias /opt/wecom-it-desk/nginx/html/itdesk/;
|
|
try_files $uri $uri/ /itdesk/index.html;
|
|
# 注意:不要 proxy_pass,这里是静态文件
|
|
}
|
|
|
|
location /api/ {
|
|
proxy_pass http://wecom_it_backend:8000/api/;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
}
|
|
```
|
|
|
|
```bash
|
|
sudo nginx -t # 检查语法
|
|
sudo nginx -s reload # 重新加载
|
|
```
|
|
|
|
### Step 6: 验证
|
|
|
|
```bash
|
|
# 外部访问
|
|
curl -I https://itsupport.servyou.com.cn/itdesk/
|
|
# 应返回 200 + Content-Type: text/html
|
|
|
|
curl -s https://itsupport.servyou.com.cn/itdesk/ | grep -i 'title'
|
|
# 应看到 <title>IT 智能服务台</title> 类似
|
|
|
|
# OAuth 端点验证
|
|
curl -s -X POST -H "User-Agent: wxwork/3.1.18" \
|
|
https://itsupport.servyou.com.cn/api/auth_wecom/sso/init
|
|
# 应返回 200 + 含 redirect_url: https://open.weixin.qq.com/...
|
|
```
|
|
|
|
### Step 7: 企微 App E2E 测试
|
|
|
|
1. 打开企微 App
|
|
2. 进入自建应用「IT 智能服务台」
|
|
3. 点击进入 → 应跳转到 `https://itsupport.servyou.com.cn/itdesk/?...`
|
|
4. 自动完成 OAuth 静默授权 → 进入会话列表
|
|
5. 发送消息测试 → 坐席端应实时收到
|
|
|
|
## 🐛 常见问题
|
|
|
|
### Q1: 访问 /itdesk/ 404
|
|
|
|
**原因**:nginx 静态目录路径不对,或 try_files 缺失
|
|
**解决**:`sudo ls /opt/wecom-it-desk/nginx/html/itdesk/` 应有 index.html
|
|
|
|
### Q2: /api/ 代理 502 Bad Gateway
|
|
|
|
**原因**:docker network 中找不到 `wecom_it_backend` 容器
|
|
**解决**:`docker network ls` 看 `wecom-it-desk_it-desk-internal` 是否包含 backend 容器
|
|
|
|
### Q3: OAuth 跳转到 `https://open.weixin.qq.com/...` 后报 redirect_uri 错误
|
|
|
|
**原因**:`WECOM_SSO_CALLBACK_BASE` 没设,或 backend 用了相对路径
|
|
**解决**:参考 [[#109-hotfix-二轮修复]] 加 `validation_alias="WECOM_SSO_CALLBACK_BASE"`
|
|
|
|
### Q4: 企微 App 显示「redirect_uri 域名与后台配置不一致」
|
|
|
|
**原因**:企微后台没添加 `itsupport.servyou.com.cn` 为可信域名
|
|
**解决**:登录企微管理后台 → 应用 → 自建 → 设置应用可信域名
|
|
|
|
## 🔄 回滚
|
|
|
|
```bash
|
|
# 备份当前 dist
|
|
sudo mv /opt/wecom-it-desk/nginx/html/itdesk /opt/wecom-it-desk/nginx/html/itdesk.bak.$(date +%Y%m%d)
|
|
|
|
# 回滚到上一版本
|
|
sudo cp -r /opt/wecom-it-desk/nginx/html/itdesk.bak.20260622 /opt/wecom-it-desk/nginx/html/itdesk
|
|
|
|
sudo nginx -s reload
|
|
```
|
|
|
|
## 📚 相关文档
|
|
|
|
- [[DEPLOY-LOGIN-MIGRATION-v0.7.0]] — 旧版扫码登录部署
|
|
- [[E2E-CHECKLIST-v0.7.0]] — 端到端验收清单
|
|
- [[NGINX-DOMAIN-ROUTING]] — nginx 域名分发
|
|
- [[USER-GUIDE-QRCODE-MFA]] — 用户手册
|
|
- [[phase1-progress]] #109 hotfix 修复
|
|
|
|
## ✅ 部署完成检查表
|
|
|
|
- [ ] dist 已上传 + 解压
|
|
- [ ] nginx reload 成功
|
|
- [ ] 外部 curl `/itdesk/` 返回 200
|
|
- [ ] `/api/auth_wecom/sso/init` 返回 200 + 微信 OAuth URL
|
|
- [ ] 企微 App 进入应用成功跳转 + 自动登录
|
|
- [ ] memory/phase1-progress.md 已更新
|