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

190 lines
9.4 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 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。
## 后端发布(双实例蓝绿)
```
<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)」拦截请求。