oms/frontend/scripts/DEPLOY.md
liufumingren 441659d303 feat(frontend): 新增蓝绿发布脚本与生产 API 地址
发布:
- 新增 scripts/deploy.mjs、rollback.mjs、init-config.mjs 与 scripts/remote/{deploy,rollback}.sh
  · 服务器上按 releases/<版本号> 存放,current 软链原子切换,发布/回滚都不中断服务
  · 切换前校验 index.html 与引用的 /assets 资源完整,并补齐历史版本静态资源(旧 chunk 不 404)
  · 真实配置 scripts/deploy.config.json 已加入忽略清单,模板 deploy.config.example.json 入库
- package.json 增加 deploy / rollback / deploy:init

接口地址:
- 新增 .env.production(VITE_API_BASE_URL=https://api.oms.gztbyc.com/api)与 .env.development
  (/api,继续走 vite 代理到本地 6090)
- request.ts 的 baseURL 改为读 VITE_API_BASE_URL;env.d.ts 声明 ImportMetaEnv
- 新增 utils/media.ts#mediaUrl:跨域部署时把后端返回的相对地址(/api/files/raw/…)
  补全为 API 站点绝对地址,用于 ImageUploader、商品列表图片、主体账号头像渲染

工程:
- tsconfig 去掉已弃用的 baseUrl(TS 7 将移除;paths 自 TS 4.1 起不再依赖它)
- .gitignore 增加 dist.tar.gz 与真实部署配置
2026-09-14 22:14:27 +08:00

4.6 KiB
Raw Blame History

OMS 前端蓝绿发布

发布方式与 WMS 前端一致:服务器上按版本目录存放,current 软链接指向当前线上版本,切换是原子的,因此发布/回滚都不中断服务。

目录结构

frontend/
├─ scripts/
│  ├─ deploy.mjs                  # 本地:构建 → 打包 → 上传 → 触发远程切换
│  ├─ rollback.mjs                # 本地:把 current 切回上一个版本
│  ├─ init-config.mjs             # 生成本地部署配置
│  ├─ deploy.config.example.json  # 配置模板(提交 git)
│  ├─ deploy.config.json          # 真实配置(.gitignore 排除,禁止提交)
│  └─ remote/
│     ├─ deploy.sh                # 服务器端执行:解压 → 校验 → 原子切换 → 清理
│     └─ rollback.sh              # 服务器端执行:原子回滚

服务器上的布局(basePath = /www/wwwroot/oms.gztbyc.com):

/www/wwwroot/oms.gztbyc.com/
├─ releases/
│  ├─ v20260914_153000_12345/     # 各版本静态文件(index.html + assets/…)
│  └─ ...
└─ current -> releases/v2026...   # 软链接,Nginx 站点根目录指向它

服务器前置条件(仅首次)

mkdir -p /www/wwwroot/oms.gztbyc.com/releases

宝塔面板:站点 oms.gztbyc.com 的网站目录要设为 /www/wwwroot/oms.gztbyc.com/current (而不是 .../oms.gztbyc.com),其余 index.html、/api 反向代理到后端等配置保持不变。

不需要 chown 到 www 用户,但站点目录需对 ssh 用户可写(示例用 root)。

使用

cd frontend

# 首次:生成本地部署配置,然后按实际服务器信息修改
npm run deploy:init

# 发布(内部执行 npm run build → 打包 → 上传 → 原子切换)
npm run deploy

# 跳过构建,直接发布现有 dist(调试用)
npm run deploy -- --skip-build

# 回滚到上一个版本(不构建、不上传,秒级)
npm run rollback

配置项(scripts/deploy.config.json)

字段 说明
user ssh 登录用户
ip 服务器 IP
basePath 站点根目录,releases/ 与 current 都在其下
keepReleases 服务器保留的最近版本数(默认 5,超出的自动清理,不会删除 current 指向的版本)
siteHost 发版后健康检查用的域名(本机 curl 带 Host 头访问 https://127.0.0.1/,仅打印状态码,不阻断发布)
sshKey 私钥:绝对路径或 ~/.ssh 下的文件名;留空则用 ssh 默认密钥/agent

发布流程细节(remote/deploy.sh)

  1. 解压到独立的新版本目录,全程不触碰线上目录
  2. 校验 index.html 非空,且 index.html 中引用的 /assets/*.js|css 都存在,否则中止(线上版本不受影响)
  3. 把最近若干个历史版本中、本版本缺失的文件并入新版本 —— 保证切换后仍停留在旧版页面的用户动态加载旧 chunk 不 404(无感切换的关键)
  4. ln -sfn 建临时软链 + mv -Tf 改名,原子切换
  5. 健康检查(仅提示)
  6. 清理超出 keepReleases 的旧版本

注意

  • scripts/deploy.config.json 不要提交 git(已在 frontend/.gitignore 中排除),只提交 deploy.config.example.json 模板。
  • 需要本机具备 ssh、scp、tar(Windows 10 1803+ 自带 OpenSSH 客户端与 bsdtar)。
  • 后端 oms 服务不在本脚本范围内,本脚本只发布前端静态文件。

前后端域名与跨域(CORS)

站点 说明
oms.gztbyc.com 前端静态站点,由本脚本发布(Nginx 根目录指向 current)
api.oms.gztbyc.com 后端 API 站点,Nginx 反代到 egg 后端(端口 6090),接口路由前缀 /api
  • 前端 API 地址由构建期环境变量 VITE_API_BASE_URL 决定:
    • 生产 ${VITE_API_BASE_URL}=http://api.oms.gztbyc.com/api(frontend/.env.production)
    • 开发 VITE_API_BASE_URL=/api(frontend/.env.development,由 vite dev server 代理到 http://localhost:6090)
  • 两个域名不同源,跨域请求由后端 backend/app/middleware/cors.js 按白名单放行 (默认已含 http/https 的 oms.gztbyc.com,可用后端环境变量 CORS_ORIGINS 覆盖)。
  • 后端返回的图片/头像地址是相对路径(/api/files/raw/...),前端渲染时由 frontend/src/utils/media.ts 的 mediaUrl() 补全为 API 站点绝对地址。
  • ⚠️ 若前端站点改用 HTTPS 访问,VITE_API_BASE_URL 必须同步改为 https://api.oms.gztbyc.com/api, 否则浏览器会按「混合内容(Mixed Content)」拦截请求。