memind/docs/service-isolation-runbook.md

> **生产环境警示：当前目录 `/Users/john/Project/Memind` 为生产目录与生产环境，禁止重启服务，所有操作必须谨慎并优先避免影响在线流量。**

# 生产 / 测试 / 预览隔离规程

这份文档的目标只有一个：开发预览不能再影响生产。

## 端口边界

| 环境 | 目录 | 用途 | 端口 |
|------|------|------|------|
| 生产 | `/Users/john/Project/Memind` | `g2.tkmind.cn` 当前在线服务（阿里云解析 → 105 → 本地 Mac 1.6） | `8081` |
| 生产 Plaza | `/Users/john/Project/Memind` + Plaza | `plaza.tkmind.cn` 当前在线服务 | `3001` |
| 生产入口 | `/Users/john/Project/Memind/scripts/g2-lb.Caddyfile` | 105 转发入口 / 反代配置 | `8090` |
| 测试 Portal | `/Users/john/Project/test/Memind` | 开发预览 API / Portal | `18081` |
| 测试 Vite | `/Users/john/Project/test/Memind` | 开发预览前端 | `15173` |
| 测试 Admin | `/Users/john/Project/test/Memind` | 开发预览后台 | `18082` |
| 测试 Plaza | `/Users/john/Project/test/Memind` | 开发预览 Plaza | `13001` |
| 测试 Ops | `/Users/john/Project/test/Memind` | 开发预览 Ops | `13002` |

硬规则：

- 不在开发预览中使用 `8081`、`3001`、`8090`。
- 不在生产目录里跑会清理端口的开发脚本。
- 不执行 `scripts/install-prod-services.sh` 来做开发预览；它会释放生产端口。
- 不手动 kill `8081` 上的进程，除非目标就是恢复/重启生产，并且已经确认影响窗口。

## Harness 角色边界

Harness 是开发工具层，不是生产服务层。

正确关系：

```text
Codex / Cursor / Goose 开发过程
        -> harness 记忆、recall、context pack、审计
        -> Memind / tkmind_go 开发
        -> 测试通过后发布到生产
```

禁止关系：

```text
g2.tkmind.cn 生产请求
        -> 必须依赖 harness 才能运行
```

本机已有全局 harness：

```text
/Users/john/Project/harness
```

它应该嵌入 Codex、Cursor 这类开发工具，让项目开发有记忆：

```bash
/Users/john/Project/harness/bin/codex-harness
/Users/john/Project/harness/bin/install_cursor_hooks.sh
/Users/john/Project/harness/bin/start_dashboard.sh
```

开发时按项目目录区分记忆上下文：

| 项目目录 | 记忆含义 |
|----------|----------|
| `/Users/john/Project/Memind` | 生产项目的开发记忆 |
| `/Users/john/Project/test/Memind` | 测试项目的开发记忆 |
| `/Users/john/Project/test/test_tkmind_go` | 测试 Goose 的开发记忆 |

硬规则：

- 生产启动脚本不能依赖 harness 才能启动。
- 生产请求链路不能调用 harness 才能响应。
- 测试开发可以使用 harness，但不能写入或覆盖生产运行数据。
- 如果要做测试专用长期记忆，优先放在 `/Users/john/Project/test/harness` 或明确的 test 项目命名空间。

## 当前生产如何确认

只读检查：

```bash
cd /Users/john/Project/Memind
lsof -nP -iTCP:8081 -sTCP:LISTEN
curl -s http://127.0.0.1:8081/api/status
cat .h5.pid
```

期望：

- `8081` 有 `node server.mjs` 监听。
- `/api/status` 返回 `ok`。
- `.h5.pid` 指向当前生产进程。

不要用下面这些命令做普通预览：

```bash
pnpm dev
pnpm dev:server
pnpm start
pnpm start:plaza
node scripts/dev.mjs
node server.mjs
scripts/install-prod-services.sh
```

这些命令如果没有端口隔离，可能占用或释放生产端口。

## 下次开发要预览，怎么做

优先在测试目录进行：

```bash
cd /Users/john/Project/test/Memind
```

启动前先确认生产还在：

```bash
curl -s http://127.0.0.1:8081/api/status
lsof -nP -iTCP:8081 -sTCP:LISTEN
```

再用测试端口启动预览：

```bash
H5_PORT=18081 \
VITE_PORT=15173 \
ADMIN_PORT=18082 \
PLAZA_PORT=13001 \
OPS_PORT=13002 \
H5_PUBLIC_BASE_URL=http://127.0.0.1:15173 \
VITE_MINDSPACE_BASE=http://127.0.0.1:15173 \
pnpm dev
```

访问地址：

| 页面 | 地址 |
|------|------|
| H5 预览 | `http://127.0.0.1:15173/?preview=mindspace` |
| 测试 Portal | `http://127.0.0.1:18081/api/status` |
| 测试 Admin | `http://127.0.0.1:18082/healthz` |
| 测试 Plaza | `http://127.0.0.1:13001/plaza` |
| 测试 Ops | `http://127.0.0.1:13002/ops/` |

如果只改前端样式，优先只启动 Vite：

```bash
cd /Users/john/Project/test/Memind
VITE_PORT=15173 \
H5_PUBLIC_BASE_URL=http://127.0.0.1:15173 \
VITE_MINDSPACE_BASE=http://127.0.0.1:15173 \
pnpm dev:vite -- --host 127.0.0.1 --port 15173
```

这种方式不会碰 `8081`，适合做 UI 预览。

## Goose 测试服务

生产 Goose 端口当前不要复用。测试 Goose 放在：

```text
/Users/john/Project/test/test_tkmind_go
```

测试 Goose 端口建议固定为：

| 用途 | 端口 |
|------|------|
| 测试 goosed A | `18106` |
| 测试 goosed B | `18107` |

测试 H5 如果要连测试 Goose，必须在测试目录 `.env` 中显式设置对应地址，不能指向生产 Goose。

## 数据库口径

短期如果沿用同一个 RDS 库，只允许做 UI 和非破坏性流程预览。

不能在共用库时做这些事：

- 改表结构。
- 跑迁移脚本。
- 批量清理数据。
- 测试支付回调、发布审核、权限变更等会污染真实用户状态的流程。

涉及数据结构或真实业务状态的开发，先建独立测试库，再预览。

## 发布前流程

完整步骤、分步发布、105 同步与回滚见 **[生产更新发布指南](./release-deploy.md)**。

最小检查：

1. 在测试端口（如 `18081`）完成开发与预览，不要在生产目录跑 `pnpm dev`。
2. `pnpm run build` + `pnpm test`。
3. `curl -s http://127.0.0.1:8081/api/status` 确认生产仍在线。
4. `./rsync_to_server.sh --dry-run` 预览 diff，确认后再执行正式发布。

## 事故恢复最小步骤

如果发现 `g2.tkmind.cn` 异常，先检查本地主机生产：

```bash
cd /Users/john/Project/Memind
lsof -nP -iTCP:8081 -sTCP:LISTEN
curl -s http://127.0.0.1:8081/api/status
```

如果 `8081` 没有监听，再恢复本地主机 Portal：

```bash
cd /Users/john/Project/Memind
nohup /opt/homebrew/opt/node@24/bin/node server.mjs >> h5.log 2>&1 &
echo $! > .h5.pid
sleep 2
curl -s http://127.0.0.1:8081/api/status
```

恢复后再检查入口反代：

```bash
curl -s http://127.0.0.1:8090/api/status
```