oms/tools/DEPLOY.md
liufumingren 406e5f3b58 refactor(tools): 发布工具统一到 tools(前后端同时发布 + git 约束 + 共享配置)
- 新增 tools TypeScript 发布 CLI:deploy / deploy:backend / deploy:frontend / rollback / init
- 删除 backend/script 与 frontend/scripts 旧发布脚本,前后端 npm scripts 转发到 tools
- 发布配置独立为 tools/config/deploy.config.local.cjs(模板入库,真实配置与生产 env 不入库)
- 发布受限于 git:工作区有未提交改动默认中止(--allow-dirty 放行),版本记录含 commit/branch
- 后端配置集中到 <deployRoot>/shared-config,本地 env 发布时覆盖共享配置;端口由 EGG_PORT 注入
- 前端服务器端脚本迁至 tools/remote,失败时清理未上线版本目录
- .gitignore 改为忽略 tools 本地配置与临时发布包

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-30 23:04:54 +08:00

9.4 KiB
Raw Blame History

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 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 配置

发布流程里:

  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。

后端发布(双实例蓝绿)

<deployRoot>/
├─ v1/ v2/                # 两套代码目录,每次发布交替部署另一套
├─ current.md             # 当前活跃版本(v1 / v2)
├─ nginx-upstream.conf    # proxy_pass http://127.0.0.1:<端口>;
├─ shared-config/         # 共享配置(见上)
└─ .deploy/               # incoming 上传包、backups 备份、state 版本记录、logs 启动日志

单次远程序列:确定空闲槽位 → 释放端口 → 备份旧槽位 → 清理代码(保留 sharedDirs)→ 解压 → 应用共享配置 → 安装依赖(可选迁移)→ 启动新实例 → 健康检查 → 切 Nginx upstream → 写 current.md → 停旧实例 → 清理旧备份。

健康检查失败时脚本自己停掉新实例并退出,旧实例继续服务(current.md / upstream 都未改动)。

Nginx 前置(仅首次,站点 api.oms.gztbyc.com)

把反向代理 location / 里的 proxy_pass http://127.0.0.1:6090; 换成 include /www/wwwroot/api.oms.gztbyc.com/nginx-upstream.conf;。

服务器端 .env(仅首次,之后由 shared-config 管理)

需要包含:MYSQL_*、REDIS_*、JWT_SECRET、UPLOAD_DIR=<deployRoot>/uploads(版本目录之外, v1/v2 共用)、可选 OMS_CALLBACK_BASE_URL。

前端发布(releases + current 软链)

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

服务器前置(仅首次):mkdir -p <basePath>/releases,并把宝塔站点网站目录设为 <basePath>/current。

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 个包)。

前后端域名与跨域(CORS)

站点 说明
oms.gztbyc.com 前端静态站点,由前端发布流程更新(Nginx 根目录指向 current)
api.oms.gztbyc.com 后端 API 站点,Nginx 反代到 egg 后端(端口由 nginx-upstream.conf 决定),路由前缀 /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)」拦截请求。