feat: add streaming runtime router

This commit is contained in:
John
2026-07-02 06:55:26 +08:00
parent 4fc59729ee
commit 04e308e582
14 changed files with 1925 additions and 285 deletions
@@ -0,0 +1,439 @@
# Memind 2.0 Streaming Agent Runtime 改造计划
更新时间: 2026-07-02
执行状态:
- P0 StreamController v1: 已完成代码落地、语法检查、Portal kickstart 和基础健康验证。
- P1 Gateway SSE 配置: 已完成,`mm.tkmind.cn` 接入 PortalSSE route 已禁缓冲。
- P2 Redis Runtime State + Router v1: 已完成可回退版本并启用 Redis。
- P3 Observability: 已完成第一版,只读 runtime 状态接口已上线。
- P4 Tool Gateway v1: 已完成第一步,普通用户默认不再暴露 Aider/OpenHands,显式用户白名单保留。
- P5 Worker Pool 运维化: 已完成第一步,Redis Router 支持 worker drain。
- 生产同步分支: 已从远程 `origin/main` 新建干净副本和分支 `memind-streaming-runtime-20260702`,用于远程开发机后续直接拉取。
## 目标
把当前 Memind H5 + multi-goosed 架构升级为 streaming-first agent runtime:
- 易扩展: goosed worker pool 横向扩展,调度层按压力分配新会话。
- 低延迟: SSE 首 token 优先,代理层禁缓冲、及时 flush、处理 backpressure。
- 高稳定: 流式链路、工具执行、worker 状态、持久化状态分层隔离。
## 当前基线
- Memind Portal: `/Users/john/Project/Memind/server.mjs`,本机 `:8081`
- H5 public base: `https://mm.tkmind.cn``m.tkmind.cn` 暂时不再作为 H5 public base。
- goosed worker pool: Docker/Colima 内 `goosed-prod-1..4`,宿主机 `18006..18009`,当前健康。
- H5 上游配置: `TKMIND_API_TARGETS=https://127.0.0.1:18006,...,18009`
- 当前已有 session affinity: start 时分配 worker,后续 reply/events 回到同一 worker。
- imgproxy: 原生 `127.0.0.1:20082`,兼容代理 `10.10.0.2:20081`
- 风险点: SSE 代理尚未完整处理 `flushHeaders``X-Accel-Buffering`、客户端断开 abort、写入 backpressure 和统一 pipeline 收尾。
## 目标架构
```mermaid
flowchart LR
U["H5 / WeChat / Web"] --> E["Edge Gateway (Nginx / Envoy)"]
E --> S["Stream Controller (Memind Portal v2)"]
S --> R["Router / Scheduler"]
R <--> Redis["Redis Runtime State"]
S <--> Redis
R --> G1["goosed-prod-1"]
R --> G2["goosed-prod-2"]
R --> G3["goosed-prod-3"]
R --> G4["goosed-prod-4"]
G1 --> T["Tool Gateway"]
G2 --> T
G3 --> T
G4 --> T
T --> A["Aider Service"]
T --> O["OpenHands Service"]
S --> PG["PostgreSQL / MySQL Persistence"]
```
## 分层原则
1. Control Plane: Redis + Router,负责 worker 心跳、active stream、错误率、首 token 延迟、session worker pointer。
2. Stream Data Plane: Memind Portal StreamController + goosed worker,负责低延迟流式传输。
3. Persistence: 现有数据库只保存最终状态、会话历史、计费、发布记录,不保存高频 runtime state。
4. Worker Affinity: goosed 尽量业务无状态,但 session 运行期必须 worker-affine;已存在 session 优先回原 worker。
5. Tool Isolation: Aider/OpenHands 从默认全开逐步改为按任务启用、队列化、限流、超时和熔断。
## 阶段计划
### P0: StreamController v1 加固
目标: 不引入新基础设施,先把现有 H5 SSE 链路做稳。
任务:
-`/api/sessions/:sessionId/events` 增加 SSE 专用响应头:
- `Content-Type: text/event-stream; charset=utf-8`
- `Cache-Control: no-cache, no-transform`
- `Connection: keep-alive`
- `X-Accel-Buffering: no`
- 在响应开始后调用 `flushHeaders()`
- 使用 `AbortController` 将客户端断开传递到 goosed upstream fetch。
- 用 backpressure-aware writable sink 替代裸 `res.write()`
-`pipeline()` 统一处理 source、sanitizer、billing、client sink 的关闭和错误。
- 保留 keepalive 和 billing balance event。
验收:
- `node --check /Users/john/Project/Memind/server.mjs` 通过。
- 本机 `http://127.0.0.1:8081/api/status` 仍返回 `ok`
- 四个 `https://127.0.0.1:18006..18009/status` 仍返回 `ok`
### P1: Gateway SSE 配置
目标: `mm.tkmind.cn` 新入口和本机入口不缓冲 SSE;后续 H5 不再走 105 nginx 反向隧道转发。
任务:
-`/api/sessions/*/events``/api/agent/runs/*/events` 配置:
- `proxy_buffering off`
- `proxy_cache off`
- `gzip off`
- `proxy_read_timeout 3600`
- `proxy_send_timeout 3600`
- `add_header X-Accel-Buffering no always`
- 确认 `mm.tkmind.cn/api/status` 返回真实 H5 API,而不是维护页 HTML。
-`m.tkmind.cn -> 105 nginx -> 127.0.0.1:19081 -> reverse SSH tunnel -> Portal :8081` 标记为 legacy/rollback-only。
验收:
- `mm.tkmind.cn/api/status` 返回后端 `ok` 或明确 JSON health,而不是维护页 HTML。
- SSE 响应头包含 `X-Accel-Buffering: no`
### P2: Redis Runtime State + Router v1
目标: 从 round-robin 升级为 pressure-aware routing。
Redis key:
```text
worker:{id}:heartbeat
worker:{id}:active_streams
worker:{id}:active_sessions
worker:{id}:ewma_first_token_ms
worker:{id}:error_rate
worker:{id}:memory_pressure
worker:{id}:drain
session:{session_id}:worker
stream:{stream_id}:status
stream:{stream_id}:started_at
```
调度分数:
```text
score =
active_streams * 3
+ active_sessions * 1
+ ewma_first_token_ms * 0.01
+ error_rate * 5
+ memory_pressure * 2
```
原则:
- 已存在 session 优先使用 `session:{id}:worker`
- 新 session 选择最低 score 的健康 worker。
- heartbeat 过期 worker 不接新 session。
- 不做无损中途迁移,除非 goose 支持完整 session restore。
### P3: Observability
目标: 调度不靠感觉。
指标:
- stream open/close/abort count
- active_streams gauge
- first_token_latency_ms
- stream_duration_ms
- worker fetch error rate
- billing finish count/error count
先写日志和内存聚合,后续接 Prometheus 或 Redis。
### P4: Tool Gateway v1
目标: Aider/OpenHands 工具隔离。
任务:
- 普通聊天默认不暴露 Aider/OpenHands。
- 代码任务按策略启用 Aider 或 OpenHands。
- Tool Gateway 提供 queue、timeout、retry、并发上限、失败熔断。
- stream 中输出 tool progress event,避免用户界面无反馈。
第一阶段实际落地:
- 普通用户默认不暴露 Aider/OpenHands。
- 保留显式 user capability override,作为白名单。
- 后续再将 Aider/OpenHands 从 goosed platform extension 进一步拆成 queue-based Tool Gateway。
### P5: Worker Pool 运维化
目标: 多 goosed 的发布、回滚、扩缩容可控。
任务:
- 固化 `goosed-prod-1..N` compose/启动配置。
- 每个 worker 独立日志、健康检查、资源上限。
- drain 模式: 不接新 session,等 active stream 清零后升级。
- 保留一键回滚镜像 tag。
Drain 操作:
```bash
docker exec memind-runtime-redis redis-cli SET memind:runtime:worker:goosed-3:drain 1
curl -sk https://mm.tkmind.cn/api/runtime/status
docker exec memind-runtime-redis redis-cli DEL memind:runtime:worker:goosed-3:drain
```
说明:
- `drain=1` 后 Router 不再给该 worker 分配新 session。
- 已存在 session 仍保持 worker affinity,不做中途迁移。
-`activeStreams=0` 后再重启或升级该 worker。
## 执行顺序
1. P0 立即执行,低风险高收益。
2. P1 基于 `mm.tkmind.cn` 新入口执行;除非明确回滚,不再改造 105 H5 转发链路。
3. P2/P3 一起推进,先观测再调度。
4. P4/P5 在流式链路稳定后推进。
## 执行记录
### 2026-07-02 P0 StreamController v1
变更文件:
- `/Users/john/Project/Memind/server.mjs`
备份:
- `/Users/john/Project/Memind/server.mjs.bak-streamcontroller-20260702-0628`
已完成:
- `proxySessionEvents` 增加 upstream `AbortController`,客户端断开时主动 abort goosed SSE fetch。
- SSE 响应头升级为 `text/event-stream; charset=utf-8``no-cache, no-transform``X-Accel-Buffering: no`
- 响应开始后调用 `flushHeaders()`
-`Writable` sink 处理 `res.write()` backpressure,并保留 billing balance event 注入。
-`pipeline(source, sanitizer, billing, sink)` 统一管理 SSE 管道收尾。
- 通过 `launchctl kickstart -k gui/$(id -u)/cn.tkmind.memind-portal` 让变更生效。
验证:
- `/opt/homebrew/opt/node@24/bin/node --check /Users/john/Project/Memind/server.mjs` 通过。
- Portal 新 PID: `89465`,监听 `*:8081`
- `http://127.0.0.1:8081/api/status` 返回 `ok`
- `https://127.0.0.1:18006/status` 返回 `ok`
- `https://127.0.0.1:18007/status` 返回 `ok`
- `https://127.0.0.1:18008/status` 返回 `ok`
- `https://127.0.0.1:18009/status` 返回 `ok`
### 2026-07-02 H5 public base 临时切换
决策:
- H5 public base 从 `https://m.tkmind.cn` 临时切换为 `https://mm.tkmind.cn`
- 后续 H5 公网访问不再走 105 转发链路。
- 旧链路 `m.tkmind.cn -> 105 nginx -> 127.0.0.1:19081 -> reverse SSH tunnel -> Portal :8081` 仅保留为 legacy/rollback-only 说明,不作为 Memind 2.0 改造目标。
变更文件:
- `/Users/john/Project/Memind/.env`
- `/Users/john/Project/Memind/scripts/run-memind-portal-prod.sh`
- `/Users/john/Project/Memind/RUNBOOK.txt`
- `/Users/john/Project/memind_architecture/memind-2-streaming-agent-runtime-plan.md`
已执行:
-`H5_PUBLIC_BASE_URL` 改为 `https://mm.tkmind.cn`
-`VITE_MINDSPACE_BASE` 改为 `https://mm.tkmind.cn`
- 将 Portal 启动脚本默认 `H5_PUBLIC_BASE_URL` 改为 `https://mm.tkmind.cn`
- 更新 `RUNBOOK.txt`,明确 105 转发链路不再作为后续 H5 公网路径。
- 通过 `launchctl kickstart -k gui/$(id -u)/cn.tkmind.memind-portal` 重启 Portal。
验证:
- Portal 新 PID: `94324`,监听 `*:8081`
- 运行环境确认: `H5_PUBLIC_BASE_URL=https://mm.tkmind.cn``VITE_MINDSPACE_BASE=https://mm.tkmind.cn`
- 本机 `http://127.0.0.1:8081/api/status` 返回 `ok`
- 四个 goosed worker `18006..18009` 均返回 `ok`
- 公网 `https://mm.tkmind.cn/api/status` 当前返回 nginx `502 Bad Gateway`,说明域名侧入口尚未接到当前 Portal;该问题纳入 P1 新入口修复,不再回到 105 转发链路处理。
### 2026-07-02 P1 Gateway SSE 配置
变更文件:
- `/opt/homebrew/etc/nginx/servers/mm.tkmind.cn.conf`
- `/Users/john/Project/Memind/scripts/wechat-mp-menu.mjs`
- `/Users/john/Project/Memind/server.mjs`
- `/Users/john/Project/Memind/dist/dev/wechat-share-demo.html`
- `/Users/john/Project/Memind/public/dev/wechat-share-demo.html`
备份:
- `/opt/homebrew/etc/nginx/backups/mm.tkmind.cn.conf.bak-streaming-20260702-0635`
已完成:
- `mm.tkmind.cn` 通过本机 nginx 反向代理到 Portal `127.0.0.1:8081`
-`/api/sessions/<id>/events``/api/agent/runs/<id>/events` 增加 SSE 专用 nginx location:
- `proxy_buffering off`
- `proxy_cache off`
- `gzip off`
- `proxy_read_timeout 3600s`
- `proxy_send_timeout 3600s`
- `add_header X-Accel-Buffering no always`
- 通用 `location /` 增加 `proxy_read_timeout 300s``proxy_send_timeout 300s`
- 微信菜单脚本默认入口改为 `https://mm.tkmind.cn``https://mm.tkmind.cn/space`
- `server.mjs``H5_PUBLIC_BASE_URL` 缺省值改为 `https://mm.tkmind.cn`
验证:
- `nginx -t` 通过。
- `nginx -s reload` 已执行。
- `https://mm.tkmind.cn/api/status` 返回 `ok`
- 未登录访问 `https://mm.tkmind.cn/api/sessions/test-session/events` 返回 `401`,且响应头包含 `x-accel-buffering: no`
- 未登录访问 `https://mm.tkmind.cn/api/agent/runs/test-run/events` 返回 `401`,且响应头包含 `x-accel-buffering: no`
### 2026-07-02 P2 Redis Runtime State + Router v1
变更文件:
- `/Users/john/Project/Memind/server.mjs`
- `/Users/john/Project/Memind/.env`
新增运行组件:
- Docker 容器: `memind-runtime-redis`
- 镜像: `redis:7-alpine`
- 绑定: `127.0.0.1:6379->6379`
- 持久化卷: `memind-runtime-redis-data`
- 启动参数: `redis-server --appendonly yes`
- 重启策略: `unless-stopped`
已完成:
- 新增可选 `createRuntimeRouter`
- `MEMIND_RUNTIME_REDIS_URL` 未配置时自动回退到原 round-robin。
- `MEMIND_RUNTIME_REDIS_URL` 配置后启用 Redis scheduler。
- 新 session 选择最低 score 的健康 worker;同分时仍按轮转顺序打散,避免全部压到第一个 worker。
- session pointer 写入 Redis:
- `memind:runtime:session:<id>:worker`
- `memind:runtime:session:<id>:target`
- SSE 打开/关闭维护 Redis active stream:
- `memind:runtime:worker:<id>:active_streams`
- `memind:runtime:worker:<id>:heartbeat`
- `memind:runtime:stream:<id>:status`
验证:
- `docker exec memind-runtime-redis redis-cli PING` 返回 `PONG`
- Redis AOF 已开启。
- Portal 运行环境包含 `MEMIND_RUNTIME_REDIS_URL=redis://127.0.0.1:6379/0`
- Portal 日志出现 `[RuntimeRouter] Redis scheduler enabled`
- Redis 当前可见 key 示例:
- `memind:runtime:worker:goosed-3:active_streams=1`
- `memind:runtime:worker:goosed-3:heartbeat=<timestamp>`
- `memind:runtime:stream:20260701_24:status=active`
- `https://mm.tkmind.cn/api/status` 返回 `ok`
- 四个 goosed worker `18006..18009` 均返回 `ok`
### 2026-07-02 P3 Observability v1
变更文件:
- `/Users/john/Project/Memind/server.mjs`
已完成:
- 新增只读接口 `GET /api/runtime/status`
- 接口返回:
- `publicBaseUrl`
- Redis Router 是否启用
- Redis namespace
- 每个 worker 的 `target``activeStreams``activeSessions``ewmaFirstTokenMs``errorRate``memoryPressure``heartbeat`
- 每个 `TKMIND_API_TARGETS` 上游的 `/status` 健康状态
- 该接口与 `/api/status` 一样作为运维健康读接口,不要求登录;不返回任何密钥。
验证:
- `/opt/homebrew/opt/node@24/bin/node --check /Users/john/Project/Memind/server.mjs` 通过。
- `https://mm.tkmind.cn/api/runtime/status` 返回 `ok: true`
- 返回中 `router.enabled=true`namespace 为 `memind:runtime`
- 返回中四个目标 `18006..18009``healthy: true`
- `https://mm.tkmind.cn/api/status` 返回 `ok`
- 未登录访问 `https://mm.tkmind.cn/api/sessions/test-session/events` 返回 `401`,且响应头包含 `x-accel-buffering: no`
### 2026-07-02 P4 Tool Gateway v1 第一阶段
已完成:
- 只读验证发现数据库中 `role=user` 曾将 `aider``openhands` 覆盖为 `allowed=1`
- 已将 `h5_capability_grants``subject_type='role' AND subject_id='user'``aider``openhands` 改为 `allowed=0`
- 保留两个显式 user override:
- `a6fb1e97-2b0f-447b-b138-4561d8e5c53e`
- `a70ff537-8908-486e-9b6c-042e07cc25db`
效果:
- 普通用户新建/恢复 session 时,Portal policy 不再把 Aider/OpenHands 放入 `extension_overrides`
- 已授权用户仍可继续使用。
- goosed 全局 config 仍保留 Aider/OpenHands enabled,避免破坏显式授权用户和既有会话;后续 Tool Gateway 阶段再拆 queue/timeout/retry。
### 2026-07-02 P5 Worker Pool Drain v1
变更文件:
- `/Users/john/Project/Memind/server.mjs`
已完成:
- Redis Router scoring 支持读取 `memind:runtime:worker:<id>:drain`
- 当 drain 值为 `1` / `true` / `yes` 时,该 worker 对新 session 的 score 为不可选。
- `/api/runtime/status` 返回每个 worker 的 `drain` 字段。
验证:
- `/opt/homebrew/opt/node@24/bin/node --check /Users/john/Project/Memind/server.mjs` 通过。
- `https://mm.tkmind.cn/api/runtime/status` 返回四个 worker `healthy=true`
- `https://mm.tkmind.cn/api/runtime/status` 返回四个 worker `drain=false`
- `https://mm.tkmind.cn/api/status` 返回 `ok`
- 未登录访问 `https://mm.tkmind.cn/api/sessions/test-session/events` 返回 `401`,且响应头包含 `x-accel-buffering: no`
### 2026-07-02 生产同步分支
决策:
- 当前是生产环境,改造过程中不随意删除数据、不清理持久化目录、不覆盖旧本地脏改动。
- `/Users/john/Project/Memind` 是生产运行产物目录,不是 git 工作树。
- 生产 release manifest 指向 `git_head=4fc59729ee222734628dca001e172c127c84488f`
- 远端 `https://git.tkmind.cn/tkmind/memind.git``origin/main` 当前正是该提交。
已执行:
- 新建干净源码目录 `/Users/john/Project/memind-clean-main-20260702`
-`origin/main` 创建分支 `memind-streaming-runtime-20260702`
- 迁入本次已在生产验证的 StreamController、Redis Router、runtime status、`mm.tkmind.cn` 和 nginx SSE 配置样例。
- 新增远程开发机同步说明 `docs/architecture/remote-dev-sync.md`
限制:
- 不提交生产 `.env`、数据库、`MindSpace/``data/``users/``.tailscale/``logs/`、证书和密钥。
- 只提交代码、配置模板、部署样例和架构/运维文档。
## 回滚策略
- P0: 修改前保留 `server.mjs` 备份;如启动失败,恢复备份并 `launchctl kickstart` Portal。
- P1: 修改 nginx 前备份 conf`nginx -t` 成功后再 reload。
- P2: Redis Router 默认可通过 env 开关退回当前 `pickTarget()` round-robin。
- P4: Tool Gateway 默认关闭,通过用户策略逐步放量。
+82
View File
@@ -0,0 +1,82 @@
# Remote Dev Sync Runbook
更新时间: 2026-07-02
## 目标
让远程开发电脑和当前生产主机的 Memind 代码版本保持一致,同时避免覆盖生产数据、密钥、用户文件和本机脏改动。
## 当前基线
- 生产运行目录: `/Users/john/Project/Memind`
- 生产 release manifest: `release_id=20260701-220548-4fc5972`
- 生产来源提交: `4fc59729ee222734628dca001e172c127c84488f`
- 干净同步分支: `memind-streaming-runtime-20260702`
- 干净分支目录: `/Users/john/Project/memind-clean-main-20260702`
- 远端仓库: `https://git.tkmind.cn/tkmind/memind.git`
## 硬约束
- 不在生产运行目录执行 `git reset --hard``git clean -fdx``rm -rf`、数据库清理或数据目录同步删除。
- 不提交生产 `.env`、数据库、`MindSpace/``data/``users/``.tailscale/``logs/`、证书、密钥和运行缓存。
- 本次 H5 public base 临时切到 `https://mm.tkmind.cn`
- 后续公网 H5 不再依赖 105 转发链路;105 只保留 legacy/rollback 说明。
## 远程开发机拉取方式
```bash
git clone https://git.tkmind.cn/tkmind/memind.git memind
cd memind
git fetch origin
git switch memind-streaming-runtime-20260702
```
如果远程开发机已有仓库:
```bash
cd /path/to/memind
git fetch origin
git switch memind-streaming-runtime-20260702
git pull --ff-only
```
## 配置方式
`.env.example` 复制生成本机 `.env`,然后只在本机填入密钥和数据库连接:
```bash
cp .env.example .env
```
生产关键项:
```text
H5_PUBLIC_BASE_URL=https://mm.tkmind.cn
VITE_MINDSPACE_BASE=https://mm.tkmind.cn
MEMIND_RUNTIME_REDIS_URL=redis://127.0.0.1:6379/0
MEMIND_RUNTIME_REDIS_NAMESPACE=memind:runtime
```
## 本分支包含的改造
- StreamController v1: SSE headers、flush、abort propagation、backpressure-aware pipeline。
- Redis Runtime Router v1: session pointer、worker score、active stream、drain。
- Runtime status: `/api/runtime/status`
- Gateway SSE 示例: `deploy/nginx/mm.tkmind.cn.conf`
- H5 public base: `mm.tkmind.cn`
- 普通用户默认不暴露 Aider/OpenHands,显式白名单保留。
## 验证命令
```bash
node --check server.mjs
node --check scripts/wechat-mp-menu.mjs
curl -sk https://mm.tkmind.cn/api/status
curl -sk https://mm.tkmind.cn/api/runtime/status
```
## 回滚思路
- 代码回滚: 切回 `origin/main` 对应提交 `4fc59729ee222734628dca001e172c127c84488f`
- 配置回滚: 恢复生产主机 `/Users/john/Project/Memind/.env.bak-mm-domain-20260702-0633`
- Worker drain 回滚: 删除 Redis drain key,例如 `DEL memind:runtime:worker:goosed-3:drain`