oms/tools/DEPLOY.md
liufumingren 1847e17ba7 feat(auth): 接入微信扫码登录与微信绑定
- 新增网关客户端与通知验签(sha256(appSecret) 派生 HMAC-SHA256,5 分钟防重放),
  扫码会话与一次性结果存 Redis,openid 仅服务端保存
- 新增 user_wechat_binds 表与迁移:openid 唯一(一个微信只绑一个账号)、
  user_id 唯一(重新绑定覆盖旧微信)
- 新增 /api/auth/wechat/* 接口与 /api/wx/notify 网关回调;登录二维码按 IP 限流,
  未配置网关时相关接口返回 400 提示,不影响账号密码 / 邮箱验证码登录
- 前端:「微信登录」tab(二维码 + 倒计时 + 轮询)与「我的」页微信绑定 / 解绑
- 开发与生产各出一份 WX_GATEWAY_* 配置样板,生产权威副本走 shared-config 覆盖
- 同步补充 swagger 契约与请求日志脱敏字段(bind_code / sign)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-01 23:17:11 +08:00

233 lines
11 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 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` 即可停用对应的发布目标。
## 后端共享配置(服务的配置只有一份,本地覆盖它)
服务器上后端的运行配置集中放在 `<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 同站点、同源:根路径出静态文件,`/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/api.oms.gztbyc.com/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`。
### 服务器端 `.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` 保留以便老域名/其他站点访问,
需要收紧时可把后端 `CORS_ORIGINS` 设为空或只留必要来源
- 后端返回的图片/头像地址仍是相对路径(`/api/files/raw/...`),同源下
`frontend/src/utils/media.ts` 的 `mediaUrl()` 原样使用
- 后端切换 v1/v2 端口只需改写 `nginx-upstream.conf` 并 reload,**前端产物无需重新构建**
- `api.oms.gztbyc.com` 现在只作为可选别名(外部回调、调试直连),指向同一后端即可;
若不再使用可下线该站点
- 站点改用 HTTPS 时,反向代理已带 `X-Forwarded-Proto`,前端构建产物无需改动
> 开发环境同理:`VITE_API_BASE_URL=/api` + vite dev server 把 `/api` 代理到 `http://localhost:6090`,
> 与生产保持一致的相对路径。