- 新增 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>
190 lines
9.4 KiB
Markdown
190 lines
9.4 KiB
Markdown
# 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)」拦截请求。
|