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

101 lines
4.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 站点根目录指向它
```
## 服务器前置条件(仅首次)
```bash
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`)。
## 使用
```bash
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)」拦截请求。