wecom_it_smart_desk/docs/08-历史归档/H5-DEPLOY-RUNBOOK-v0.7.1-archived-20260704.md

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

cd frontend-h5
npm install
npm run build
ls -la dist/  # 应有 index.html + assets/

Step 2: 打包 tar.gz(可选,便于堡垒机传输)

# 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 静态目录

# 假设 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 包含:

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;
}

sudo nginx -t  # 检查语法
sudo nginx -s reload  # 重新加载

Step 6: 验证

# 外部访问
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 为可信域名 解决:登录企微管理后台 → 应用 → 自建 → 设置应用可信域名

🔄 回滚

# 备份当前 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 已更新