15 KiB
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
一次性准备
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):
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,不散落在前后端项目里:
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 配置
发布流程里:
- 本地覆盖:若本机
tools/config/env.production.local存在(envFileLocalPath可改),发布前先scp到<deployRoot>/shared-config/.env,即本地权威副本覆盖服务端共享配置; 本机没有该文件时跳过上传,沿用服务器上现有配置。 - 下发到实例:发布时把
shared-config/.env复制为版本目录的.env,shared-config/config.*.js复制到版本目录的config/,覆盖包内同名文件。 - 首次迁移:若
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。
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),不会执行迁移。
新增迁移后有两种做法:
- 发布前把该配置改成
true。部署会通过npm exec从 npm 缓存运行sequelize-cli@6.6.5(生产依赖安装不含该开发工具,不会改动应用node_modules),迁移失败会中断本次发布,当前活跃实例继续服务; - 发布后到当前活跃版本目录手动执行:
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, 与生产保持一致的相对路径。