oms/tools/DEPLOY.md
liufumingren 587a39507b fix: run migration cli without altering app dependencies
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-03 21:55:38 +08:00

294 lines
15 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 发布工具(tools)
`tools/` 是前后端**统一的发布入口**:一次 `npm run deploy` 同时更新后端(Egg 双实例蓝绿)与前端
(releases 目录 + `current` 软链接),两条链路都是原子切换,线上不中断。
```
tools/
├─ src/
│ ├─ cli.ts # 命令入口(tsx 直跑,或 tsc 后 node dist/cli.js)
│ ├─ commands/ # deploy(发布)/ rollback(回滚)
│ └─ lib/ # 配置、git 约束、打包、ssh/scp、远端脚本生成
├─ config/
│ ├─ deploy.config.example.cjs # 发布配置模板(提交 git)
│ ├─ deploy.config.local.cjs # 发布配置本地真实值(.gitignore 排除)
│ ├─ env.production.example # 生产环境变量模板(本机权威副本)
│ └─ env.production.local # 生产环境变量本地真实值(.gitignore 排除)
├─ remote/ # 前端服务器端 bash 脚本(deploy.sh / rollback.sh)
├─ temp/ # 本地发布包(.gitignore 排除)
└─ DEPLOY.md
```
## 一次性准备
```bash
cd tools
npm install # tsx / typescript(发布脚本本身零运行时依赖)
npm run init # 生成 config/deploy.config.local.cjs,然后填写 SSH 等信息
```
需要本机具备 `git`、`tar`、`ssh`、`scp`(Windows 10 1803+ 自带 OpenSSH 客户端与 bsdtar)。
## 命令
| 命令 | 说明 |
| --- | --- |
| `npm run dev` | **本地开发**:同时启动后端(6090,egg-bin dev)与前端(5173,vite),日志按 `[backend]` / `[frontend]` 分区,Ctrl+C 一并停止 |
| `npm run dev:backend` | 只启动后端开发环境 |
| `npm run dev:frontend` | 只启动前端开发环境(`/api` 代理到 6090,需后端已启动) |
| `npm run deploy` | **前后端同时发布**:构建前端 → 打包前后端 → 上传 → 一次 SSH 完成切换 |
| `npm run deploy -- --skip-build` | 复用已有 `frontend/dist`,不重新构建 |
| `npm run deploy -- --dry-run` | 只做本地构建与打包,打印远端脚本,不连服务器(同样受 git 约束,可加 `--allow-dirty`) |
| `npm run deploy -- --allow-dirty` | 允许工作区有未提交改动时发布 |
| `npm run deploy:backend` | 只发布后端 |
| `npm run deploy:frontend` | 只发布前端 |
| `npm run rollback` | 前后端一起回滚 |
| `npm run rollback -- --to=v1` | 指定后端回滚到 v1(前端仍回上一个 releases 版本) |
| `npm run rollback -- --dry-run` | 只打印回滚脚本 |
| `npm run cli -- help` | 查看用法 |
在项目目录里也能触发(内部转发到 tools):
```bash
cd backend && npm run deploy # 前后端一起发布
cd backend && npm run deploy:backend # 只发后端
cd frontend && npm run deploy # 前后端一起发布
cd frontend && npm run deploy:frontend # 只发前端
cd frontend && npm run deploy -- --skip-build
```
> 首次在 `backend/` 或 `frontend/` 里调用前,请先在 `tools/` 执行过 `npm install`。
## 发布受限于 git
- 工作区有未提交改动时**默认中止**,并列出改动文件;确认要带改动发布可加 `--allow-dirty`
(或在配置里设 `allowDirtyGit: true`),此时版本记录会标记 `dirty: true`。
- 后端发布包严格按 `git ls-files --cached --others --exclude-standard` 生成,再按
`deployIncludePaths` / `deployExcludePaths` 过滤,天然排除 `.env`、`uploads/`、`logs/` 等未入库内容。
- 远端 `.deploy/state/versions.jsonl` 记录每次发布的 `version / commit / branch / env / dirty /
targets / frontendRelease / operator / time / files / size`,保留最近 `keepVersions` 条。
## 发布配置(独立文件)
发布配置只放在 `tools/config/deploy.config.local.cjs`,不散落在前后端项目里:
```js
module.exports = {
production: {
host, port, username, privateKeyPath, sshOptions, // SSH
allowDirtyGit: false, keepVersions: 30, keepBackups: 5,
backend: {
deployRoot, ports: { v1: 6090, v2: 6091 },
healthCheckPath, healthCheckAttempts, healthCheckInterval,
sharedDirs, deployIncludePaths, deployExcludePaths,
installCommand, startCommand, runMigrations, startTitlePrefix,
sharedConfigDir, envFile, envFileLocalPath, uploadEnvFile, // 服务端共享配置
nginxUpstreamFile, nginxReloadCommand, // Nginx
},
frontend: {
enabled, basePath, distDir, buildCommand, keepReleases, siteHost,
},
},
};
```
`backend` / `frontend` 任一段设为 `false` 即可停用对应的发布目标。
## 后端共享配置(服务的配置只有一份,本地覆盖它)
服务器上后端的运行配置集中放在 `<deployRoot>/shared-config/`:
```
<deployRoot>/shared-config/
├─ .env # 生产环境变量(数据库 / Redis / JWT_SECRET / UPLOAD_DIR …)
└─ config.*.js # 可选:不入库的服务端 Egg 配置
```
发布流程里:
1. **本地覆盖**:若本机 `tools/config/env.production.local` 存在(`envFileLocalPath` 可改),发布前先
`scp` 到 `<deployRoot>/shared-config/.env`,即本地权威副本覆盖服务端共享配置;
本机没有该文件时跳过上传,沿用服务器上现有配置。
2. **下发到实例**:发布时把 `shared-config/.env` 复制为版本目录的 `.env`,
`shared-config/config.*.js` 复制到版本目录的 `config/`,**覆盖**包内同名文件。
3. **首次迁移**:若 `shared-config/.env` 还不存在,而老部署的 `<deployRoot>/.env` 存在,会自动搬过去。
> 实例端口不再写进 `.env`:发布脚本以 `EGG_PORT=<槽位端口>` 启动实例(`dotenv` 不覆盖已存在的环境变量),
> v1/v2 共用同一份 `.env` 也不会串端口。
本地生产环境变量用 `config/env.production.example` 作为模板复制为 `config/env.production.local`,该文件已被 gitignore。
## 后端发布(双实例蓝绿)
前后端统一放在站点目录下,后端发布目录是 `<basePath>/api`(即 `/www/wwwroot/oms.gztbyc.com/api`),
与前端 `releases/`、`current` 并列,互不干扰:
```
/www/wwwroot/oms.gztbyc.com/
├─ current -> releases/<版本>/ # 前端站点根目录(Nginx root 指向它)
├─ releases/ # 前端历史版本(保留 keepReleases 个)
└─ api/ # 后端发布目录(deployRoot)
├─ v1/ v2/ # 两套代码目录,每次发布交替部署另一套
├─ current.md # 当前活跃版本(v1 / v2)
├─ nginx-upstream.conf # proxy_pass http://127.0.0.1:<端口>;
├─ shared-config/ # 共享配置(见上)
├─ uploads/ # 上传文件(版本目录之外,v1/v2 共用)
└─ .deploy/ # incoming 上传包、backups 备份、state 版本记录、logs 启动日志
```
单次远程序列:确定空闲槽位 → 释放端口 → 备份旧槽位 → 清理代码(保留 `sharedDirs`)→ 解压
→ 应用共享配置 → 安装依赖(可选迁移)→ 启动新实例 → 健康检查 → 切 Nginx upstream → 写 `current.md`
→ 停旧实例 → 清理旧备份。
健康检查失败时脚本自己停掉新实例并退出,旧实例继续服务(`current.md` / upstream 都未改动)。
### Nginx 配置(单站点部署,仅首次)
前端静态与后端 API 同站点、同源:根路径出静态文件,`/api/` 反代到 egg。
```nginx
server {
listen 80;
server_name oms.gztbyc.com;
# 前端:站点根目录指向 current 软链(发布脚本原子切换)
root /www/wwwroot/oms.gztbyc.com/current;
index index.html;
# SPA 深链接回退:/order、/export-task 等直接刷新不再 404
location / {
try_files $uri $uri/ /index.html;
}
# 后端:所有接口都在 /api 下;upstream 文件由发布脚本改写(v1/v2 交替),
# 文件内容即 `proxy_pass http://127.0.0.1:<端口>;`
location /api/ {
include /www/wwwroot/oms.gztbyc.com/api/nginx-upstream.conf;
proxy_http_version 1.1;
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;
proxy_read_timeout 300s; # 导出/批量等长请求
client_max_body_size 50m; # 上传上限,按需调整
}
# 外部系统(WMS 等)回推入口:路径与后端 router 的 /openapi 一致,
# OMS_CALLBACK_BASE_URL 应配成本站点域名,拼出来的回调地址即 https://<站点域名>/openapi
location = /openapi {
include /www/wwwroot/oms.gztbyc.com/api/nginx-upstream.conf;
proxy_http_version 1.1;
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;
proxy_read_timeout 300s;
client_max_body_size 50m;
}
}
```
宝塔面板:站点 `oms.gztbyc.com` 的**网站目录**设为 `/www/wwwroot/oms.gztbyc.com/current`,
并删掉指向 `127.0.0.1:6090` 的旧 `/api` 反代,改成上面的 `include`。
> ⚠️ 静态站点默认只有 `location / { try_files $uri $uri/ /index.html; }`,**没有 `/api/` 反代**:
> 前端改成同源 `/api` 后,所有接口都会命中 SPA 回退返回 `index.html`(表现为「配置没生效」、
> 刷新页面正常但任何接口都拿不到数据)。缺这一段时 `curl https://<站点域名>/api/auth/wechat/enabled`
> 会返回 HTML 而不是 JSON。
>
> 宝塔面板改「网站目录 / 伪静态」会重写站点主配置,建议把 `/api/` 反代放进
> 站点 → 设置 → 配置文件 → **扩展配置**(实际落盘 `/www/server/panel/vhost/nginx/extension/<域名>/*.conf`),
> 用 `location ^~ /api/ { include .../nginx-upstream.conf; proxy_set_header ...; }`,面板重写主配置也不会丢。
### `api.oms.gztbyc.com`(已下线,目录已迁移)
后端只经 `https://oms.gztbyc.com/api`(前端)与 `https://oms.gztbyc.com/openapi`(外部系统回调)访问。
该域名的站点配置已移除(原配置备份在 `/www/wwwroot/oms.gztbyc.com/api/.deploy/backup-vhost/`),
发布目录也已从 `/www/wwwroot/api.oms.gztbyc.com/` 迁到 `/www/wwwroot/oms.gztbyc.com/api/`,
`OMS_CALLBACK_BASE_URL` 指向站点域名,域名解析(DNS)可以一并删掉。
- 迁移涉及的三处配置必须一起改,缺一处就会发布失败或 404:
`deploy.config.local.cjs` 的 `deployRoot`、`.env` 的 `UPLOAD_DIR`、站点扩展配置里 `include` 的 upstream 路径;
- 旧目录 `/www/wwwroot/api.oms.gztbyc.com/` 迁完只剩宝塔留下的 `.env`/`releases`/`proxy_cache_dir`,
确认新目录跑通后可以直接删;
- 旧版前端产物(`VITE_API_BASE_URL` 写死 `https://api.oms.gztbyc.com/api` 的版本)在该域名下线后
会整体失效,等用户缓存过期或被强制刷新即可。
### 数据库迁移
发布脚本默认 `runMigrations: false`(见 `config/deploy.config.local.cjs`),不会执行迁移。
新增迁移后有两种做法:
1. 发布前把该配置改成 `true`。部署会通过 `npm exec` 从 npm 缓存运行 `sequelize-cli@6.6.5`
(生产依赖安装不含该开发工具,不会改动应用 `node_modules`),迁移失败会中断本次发布,当前活跃实例继续服务;
2. 发布后到**当前活跃版本目录**手动执行:
```bash
cd /www/wwwroot/oms.gztbyc.com/api/v2 # 版本看 current.md
npm install --no-save sequelize-cli@6.6.5 # 生产依赖是 npm install --production,不含 sequelize-cli
node_modules/.bin/sequelize-cli db:migrate
npm prune --omit=dev --no-audit --no-fund # 跑完清掉临时装的开发依赖
```
迁移前建议先备份:`mysqldump ... --single-transaction | gzip > .deploy/backups/db-<时间>.sql.gz`。
### 服务器端 `.env`(仅首次,之后由 shared-config 管理)
需要包含:`MYSQL_*`、`REDIS_*`、`JWT_SECRET`、`UPLOAD_DIR=<deployRoot>/uploads`(版本目录之外,
v1/v2 共用)、可选 `OMS_CALLBACK_BASE_URL`。
微信扫码登录 / 绑定为可选能力:在网关管理台(https://gateway.gztbyc.com)为生产环境单独创建接入应用,
把 `WX_GATEWAY_APP_KEY` / `WX_GATEWAY_APP_SECRET` 写入 `.env`,并把应用的通知地址配成
`https://{生产域名}/api/wx/notify`。未配置时微信相关接口返回 400 提示,其它登录方式不受影响。
开发环境的同类配置见 `backend/env.development.example`。
## 前端发布(releases + current 软链)
```
<basePath>/
├─ releases/
│ ├─ v20261030_190028_2220/ # 各版本静态文件(index.html + assets/…)
│ └─ ...
└─ current -> releases/v2026... # 软链接,Nginx 站点根目录指向它
```
服务器前置(仅首次):`mkdir -p <basePath>/releases`,并把宝塔站点**网站目录**设为 `<basePath>/current`,
同时按上文「Nginx 配置(单站点部署)」把 `/api/` 反代到后端(`include nginx-upstream.conf`)。
`remote/deploy.sh` 流程:解压到新版本目录(不触碰线上目录)→ 校验 `index.html` 与引用的
`/assets/*.js|css` → 合并历史版本中缺失的文件(旧 chunk 不 404)→ `ln -sfn` + `mv -Tf` 原子切换
→ 健康检查(仅提示)→ 按 `keepReleases` 清理旧版本。失败时脚本会删除未上线的版本目录。
## 前后端同时发布时的顺序
后端先完成(健康检查通过、Nginx 已切到新实例、`current.md` 已更新),再切前端 `current` 软链:
- 后端失败 → 前端完全不执行,线上保持原样;
- 后端成功、前端失败 → 后端已上线(新 API 可用),前端仍是上一版,脚本会清理失败的前端目录。
## 注意
- `tools/config/deploy.config.local.cjs`、`tools/config/env.production.local` **不要提交 git**
(根 `.gitignore` 已排除),只提交 `*.example.*` 模板。
- `tools/temp/` 是本地发布包临时目录,已被忽略(保留最近 3 个包)。
## 单站点部署与同源请求
| 路径 | 处理 |
| --- | --- |
| `/` | 前端静态文件(Nginx `root` = `<basePath>/current`,`try_files` 回退 `index.html`) |
| `/api/` | 反代到 egg(`include nginx-upstream.conf`,发布脚本切换 v1/v2 端口) |
- 前端构建期 `VITE_API_BASE_URL=/api`(`frontend/.env.production`)→ 浏览器请求始终同源
- 同源后**不需要 CORS**:`backend/app/middleware/cors.js` 默认只放行本地开发 `localhost:5173`,
需要时用后端 `CORS_ORIGINS` 覆盖
- 后端返回的图片/头像地址仍是相对路径(`/api/files/raw/...`),同源下
`frontend/src/utils/media.ts` 的 `mediaUrl()` 原样使用
- 后端切换 v1/v2 端口只需改写 `nginx-upstream.conf` 并 reload,**前端产物无需重新构建**
- `api.oms.gztbyc.com` 已下线,前后端都放在 `/www/wwwroot/oms.gztbyc.com/` 下
(前端 `releases/` + `current`,后端 `api/`)
- 站点改用 HTTPS 时,反向代理已带 `X-Forwarded-Proto`,前端构建产物无需改动
> 开发环境同理:`VITE_API_BASE_URL=/api` + vite dev server 把 `/api` 代理到 `http://localhost:6090`,
> 与生产保持一致的相对路径。