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

```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 已更新