memind/docs/gadm-local.md

# gadm 由 105 入口转发到 Studio

`gadm.tkmind.cn` 的生产链路和 Plaza 一样，都是 `105 入口 -> Studio 生产机`。
这里的后端服务名是 `memind_adm`，代码入口在本仓库的 `admin-server.mjs`。
根路径 `/` 默认进入 `gadm` 的管理页，也就是 `ops` 前端里的 `/admin` 段。

## 角色拆分

```text
浏览器 / 内部管理人员
    ↓
105 公网入口（gadm.tkmind.cn）
    ↓  nginx / 反代
Studio / 本机生产机
    ├─ ops 前台（/ops/，Vite 开发服务）
    └─ memind_adm :8082（admin-server.mjs）
        ├─ /healthz
        ├─ /admin-api/*
        └─ /api/ops/v1/*
```

`memind_adm` 只负责后端管理 API，不直接托管大部分前台页面。
`ops/` 里的后台 SPA 是独立页面，生产上由 `gadm.tkmind.cn/` 先跳转到 `/ops/admin/`，再由 105 反代回 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 负责把：

- `/` 重定向到 `/ops/admin/`
- `/ops/` 反代到 Studio 上的 ops 页面
- `/admin-api/` 和 `/api/ops/v1/` 反代到 Studio 上的 `memind_adm`

### 0. 本地改动确认

推荐从本地开发目录发布到 Studio：

```bash
cd /Users/john/PycharmProjects/test/test-memind
git status --short
```

如果你改的是 `admin-server.mjs`、`admin-routes.mjs`、`admin-*.mjs` 或 `ops/`，记得先本地自测。

### 1. 本地启动 / 自测

```bash
pnpm dev:adm
```

默认监听 `http://127.0.0.1:8082`，启动后先看：

```bash
curl -s http://127.0.0.1:8082/healthz
```

### 2. 同步到测试机

```bash
bash scripts/deploy-to-test-host.sh --only-adm
```

测试镜像目录是 `/Users/john/PycharmProjects/test/test-memindadm`。

### 3. Studio 生产机启动 / 重启

在 Studio 机器上，`memind_adm` 最终都应该由同一个入口启动：

```bash
cd /Users/john/Project/Memind
node admin-server.mjs
```

如果你们在 Studio 上用了 launchd / pm2 / systemd，就让守护脚最终执行上面这条命令。

常见的生产检查：

```bash
curl -s http://127.0.0.1:8082/healthz
curl -s http://127.0.0.1:8082/admin-api/summary
```

### 4. 105 入口反代

105 上的 nginx 应该把 `gadm.tkmind.cn` 回源到 Studio 的 `memind_adm :8082`。

如果你要确认 nginx 当前配置，优先看：

```bash
ssh ssh105 'nginx -t && systemctl reload nginx'
ssh ssh105 'sed -n "1,220p" /etc/nginx/conf.d/gadm.tkmind.cn.conf'
```

上线后优先验证：

```bash
curl -I https://gadm.tkmind.cn/
curl -I https://gadm.tkmind.cn/ops/admin/
curl -s -D - -o /dev/null https://gadm.tkmind.cn/admin-api/summary
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` 是否限制过严
5. `ops/` 是否还在用正确的 `'/admin-api'` 代理地址

## 相关文件

- [`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)