From cb51b94f2c0385ffb131a4ad0441eea413bdbd3d Mon Sep 17 00:00:00 2001 From: john Date: Sat, 20 Jun 2026 15:41:22 +0800 Subject: [PATCH] Document gadm release flow --- README.md | 9 ++++ docs/gadm-local.md | 110 +++++++++++++++++++++++++++++++++++++++++ docs/release-deploy.md | 30 ++++++++++- 3 files changed, 148 insertions(+), 1 deletion(-) create mode 100644 docs/gadm-local.md diff --git a/README.md b/README.md index 6c7113d..5599d48 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,15 @@ pnpm open:plaza # 浏览器打开 https://plaza.tkmind.cn/plaza 公网 `https://plaza.tkmind.cn` 经 Cloudflare Tunnel 回源本机 `:3001`，需保持 `pnpm start:plaza` 运行。 +## gadm / memind_adm + +管理后台和运维接口说明见 **[docs/gadm-local.md](docs/gadm-local.md)**。 + +| 服务 | 地址 | +|------|------| +| memind_adm | http://127.0.0.1:8082 | +| ops 审核后台 | http://127.0.0.1:3002/ops/ | + ## 常用脚本 | 命令 | 说明 | diff --git a/docs/gadm-local.md b/docs/gadm-local.md new file mode 100644 index 0000000..8243fa1 --- /dev/null +++ b/docs/gadm-local.md @@ -0,0 +1,110 @@ +# gadm 由 105 入口转发到 Studio + +`gadm.tkmind.cn` 的生产链路和 Plaza 一样，都是 `105 入口 -> Studio 生产机`。 +这里的后台服务名是 `memind_adm`，代码入口在本仓库的 `admin-server.mjs`。 + +## 角色拆分 + +```text +浏览器 / 内部管理人员 + ↓ +105 公网入口（gadm.tkmind.cn） + ↓ nginx / 反代 +Studio / 本机生产机 + └─ memind_adm :8082（admin-server.mjs） + ├─ /healthz + ├─ /admin-api/* + └─ /api/ops/v1/* +``` + +`memind_adm` 只负责后端管理 API，不直接托管大部分前台页面。 +开发时，`ops/` 里的后台 SPA 会把请求代理到它；生产上则由 `gadm.tkmind.cn` 入口把请求转给 Studio。 + +## 本地开发 + +```bash +pnpm dev:adm +``` + +默认监听 `http://127.0.0.1:8082`。 + +常见本地访问地址： + +| 服务 | 地址 | +|------|------| +| memind_adm | http://127.0.0.1:8082 | +| ops 后台 | http://127.0.0.1:3002/ops/ | + +## 测试机同步 + +如果要同步到测试目录，`memind_adm` 对应的是： + +- 源码目录：`/Users/john/PycharmProjects/test/test-memind` +- 测试镜像目录：`/Users/john/PycharmProjects/test/test-memindadm` + +同步脚本： + +```bash +bash scripts/deploy-to-test-host.sh --only-adm +``` + +如果你要同步三套目录，也可以直接： + +```bash +bash scripts/deploy-to-test-host.sh +``` + +## 生产发布流程 + +生产上，`gadm.tkmind.cn` 解析到 105，105 只做反代，最终回源到 Studio 上的 `memind_adm`。 + +### 1. 在 Studio 上更新代码 + +推荐从本地开发目录发布到 Studio： + +```bash +cd /Users/john/PycharmProjects/test/test-memind +git status --short +``` + +如果你改的是 `admin-server.mjs`、`admin-routes.mjs`、`admin-*.mjs` 或 `ops/`，记得先本地自测。 + +### 2. 启动 / 重启 `memind_adm` + +```bash +cd /Users/john/Project/Memind +pnpm dev:adm +``` + +如果你们的生产环境是 launchd、pm2、systemd 或别的守护方式，就让它最终执行同一个入口： + +```bash +node admin-server.mjs +``` + +### 3. 105 入口反代 + +105 上的 nginx 应该把 `gadm.tkmind.cn` 回源到 Studio 的 `memind_adm :8082`。 + +上线后优先验证： + +```bash +curl -I https://gadm.tkmind.cn/healthz +curl -s https://gadm.tkmind.cn/healthz +``` + +## 故障排查顺序 + +如果 `gadm.tkmind.cn` 挂了，按这个顺序查： + +1. Studio 上 `http://127.0.0.1:8082/healthz` 是否正常 +2. Studio 上 `memind_adm` 是否还在运行 +3. 105 上 nginx 是否把 `gadm.tkmind.cn` 转发到了 Studio +4. `ADMIN_CONSOLES`、`ADMIN_API_ALLOWED_HOSTS`、`OPS_API_ALLOWED_HOSTS` 是否限制过严 + +## 相关文件 + +- [`admin-server.mjs`](/Users/john/PycharmProjects/test/test-memind/admin-server.mjs) +- [`scripts/deploy-to-test-host.sh`](/Users/john/PycharmProjects/test/test-memind/scripts/deploy-to-test-host.sh) +- [`scripts/local-test-proxy.mjs`](/Users/john/PycharmProjects/test/test-memind/scripts/local-test-proxy.mjs) + diff --git a/docs/release-deploy.md b/docs/release-deploy.md index 30487fd..92b3139 100644 --- a/docs/release-deploy.md +++ b/docs/release-deploy.md @@ -254,7 +254,35 @@ pnpm deploy:plaza-105 依赖 goose-h5 已部署（`pnpm deploy:105` 或全量 rsync）。详见 [Plaza 本机部署](./plaza-local.md)。 -### 10.3 已废弃 / 不可用 +### 10.3 gadm / memind_adm + +`gadm.tkmind.cn` 是 `memind_adm` 的生产入口，当前流程和 Plaza 一样也是： + +```text +本地开发目录 -> Studio 生产机 -> 105 入口反代 -> 公网域名 +``` + +开发入口： + +```bash +pnpm dev:adm +``` + +测试机同步： + +```bash +bash scripts/deploy-to-test-host.sh --only-adm +``` + +生产发布时优先检查： + +1. Studio 上 `http://127.0.0.1:8082/healthz` +2. 105 上 `gadm.tkmind.cn` 反代是否指向 Studio +3. `ADMIN_CONSOLES` / `ADMIN_API_ALLOWED_HOSTS` / `OPS_API_ALLOWED_HOSTS` + +详细说明见 [gadm 入口与发布](./gadm-local.md)。 + +### 10.4 已废弃 / 不可用 | 命令 | 状态 | |------|------|