Files

T

Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交）

本提交为 .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-*/

2026-08-07 22:31:32 +08:00

4.5 KiB

Raw Permalink Blame History

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 授权登录。

⚠️ 前置条件

✅ 后端已部署 v0.7.0+(支持 /api/auth_wecom/sso/init + /api/auth_wecom/sso/verify)
✅ 已设置环境变量 WECOM_SSO_ENABLED=true + WECOM_SSO_CALLBACK_BASE=https://itsupport.servyou.com.cn
✅ 企微后台已添加 itsupport.servyou.com.cn 为应用可信域名
✅ 已有 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 测试

打开企微 App
进入自建应用「IT 智能服务台」
点击进入 → 应跳转到 https://itsupport.servyou.com.cn/itdesk/?...
自动完成 OAuth 静默授权 → 进入会话列表
发送消息测试 → 坐席端应实时收到

🐛 常见问题

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

4.5 KiB Raw Permalink Blame History