# 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` 即可停用对应的发布目标。 ## 后端共享配置(服务的配置只有一份,本地覆盖它) 服务器上后端的运行配置集中放在 `/shared-config/`: ``` /shared-config/ ├─ .env # 生产环境变量(数据库 / Redis / JWT_SECRET / UPLOAD_DIR …) └─ config.*.js # 可选:不入库的服务端 Egg 配置 ``` 发布流程里: 1. **本地覆盖**:若本机 `tools/config/env.production.local` 存在(`envFileLocalPath` 可改),发布前先 `scp` 到 `/shared-config/.env`,即本地权威副本覆盖服务端共享配置; 本机没有该文件时跳过上传,沿用服务器上现有配置。 2. **下发到实例**:发布时把 `shared-config/.env` 复制为版本目录的 `.env`, `shared-config/config.*.js` 复制到版本目录的 `config/`,**覆盖**包内同名文件。 3. **首次迁移**:若 `shared-config/.env` 还不存在,而老部署的 `/.env` 存在,会自动搬过去。 > 实例端口不再写进 `.env`:发布脚本以 `EGG_PORT=<槽位端口>` 启动实例(`dotenv` 不覆盖已存在的环境变量), > v1/v2 共用同一份 `.env` 也不会串端口。 本地生产环境变量用 `config/env.production.example` 作为模板复制为 `config/env.production.local`,该文件已被 gitignore。 ## 后端发布(双实例蓝绿) 前后端统一放在站点目录下,后端发布目录是 `/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=/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 软链) ``` / ├─ releases/ │ ├─ v20261030_190028_2220/ # 各版本静态文件(index.html + assets/…) │ └─ ... └─ current -> releases/v2026... # 软链接,Nginx 站点根目录指向它 ``` 服务器前置(仅首次):`mkdir -p /releases`,并把宝塔站点**网站目录**设为 `/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` = `/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`, > 与生产保持一致的相对路径。