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 是开发工具层，不是生产服务层。

正确关系：

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

禁止关系：

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

本机已有全局 harness：

/Users/john/Project/harness

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

/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 项目命名空间。

当前生产如何确认

只读检查：

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 指向当前生产进程。

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

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

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

下次开发要预览，怎么做

优先在测试目录进行：

cd /Users/john/Project/test/Memind

启动前先确认生产还在：

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

再用测试端口启动预览：

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：

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 放在：

/Users/john/Project/test/test_tkmind_go

测试 Goose 端口建议固定为：

用途	端口
测试 goosed A	18106
测试 goosed B	18107

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

数据库口径

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

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

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

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

发布前流程

完整步骤、分步发布、105 同步与回滚见 生产更新发布指南。

最小检查：

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 异常，先检查本地主机生产：

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

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

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

恢复后再检查入口反代：

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