Document gadm release flow

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/ |
+
 ## 常用脚本
 
 | 命令 | 说明 |

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)
+

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 已废弃 / 不可用
 
 | 命令 | 状态 |
 |------|------|