Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
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 已更新
|