From 81df866c63253d22e93e97b17d289e486b163655 Mon Sep 17 00:00:00 2001 From: cnphpbb Date: Fri, 26 Jun 2026 20:27:25 +0800 Subject: [PATCH] =?UTF-8?q?docs(honcho):=20=C2=A74=20Phase=201-2=20?= =?UTF-8?q?=E6=8C=89=20v3.0.10=20schema=20=E9=87=8D=E5=86=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- honcho/share-multi-client.md | 165 ++++++++++++++++++++--------------- 1 file changed, 96 insertions(+), 69 deletions(-) diff --git a/honcho/share-multi-client.md b/honcho/share-multi-client.md index 12d7c20..f64e251 100644 --- a/honcho/share-multi-client.md +++ b/honcho/share-multi-client.md @@ -1,7 +1,7 @@ # Honcho 多 Hermes 客户端共享方案 -> 状态: 📝 草案 (2026-06-20, 06-26 拓扑修正) -> 适用: vm61 (10.8.0.9, 备用/测试环境) 部署 honcho + 3 个 hermes 客户端共享同一份记忆 +> 状态: 📝 草案 (2026-06-20 创建, 06-26 拓扑修正 + v3.0.10 schema 探针重写) +> 适用: vm61 (10.8.0.9, 备用/测试环境) 部署 honcho v3.0.10 + 3 个 hermes 客户端共享同一份记忆 --- @@ -9,14 +9,14 @@ | 客户端 | 位置 | WireGuard IP | 网络到 vm61 | peer 名 | |---|---|---|---|---| -| mypc03 (WSL Debian) | 🏠 家里 LAN | `10.8.0.112` | WireGuard → vm61 | `laodeng-mypc03` | -| gov-pc (公司机器) | 🏢 公司 | `10.8.0.143` | WireGuard → vm61 | `laodeng-govpc` | -| macbook | ☕ 任意位置 | `10.8.0.144` | WireGuard → vm61 | `laodeng-mac` | +| mypc03 (WSL Debian) | 🏠 家里 LAN | `10.8.0.112` | WireGuard → vm61 | `laodeng-mypc03x` | +| gov-pc (公司机器) | 🏢 公司 | `10.8.0.143` | WireGuard → vm61 | `laodeng-govpcxxxx` | +| macbook | ☕ 任意位置 | `10.8.0.144` | WireGuard → vm61 | `laodeng-macxxxxxxx` | **3 个客户端都是老登本人**用，所以希望： - ✅ **共享 workspace**（`home`）：在 A 上聊的事，B 上能召回 - ✅ **peer 独立**（带设备后缀）：方便审计"在哪台设备说的" -- ✅ **AUTH 开启**：每个客户端独立 API key，可单独撤销 +- ✅ **AUTH 关闭（DEV 模式）**：vm61 honcho v3.0.10 实例 `USE_AUTH=False`，JWT_SECRET 留空，peer 不强制鉴权；接入稳后再开 - ❌ 不共享 LLM 凭据：每个客户端用自己的 hermes LLM key --- @@ -26,14 +26,14 @@ ```mermaid flowchart LR subgraph Clients["3 个 Hermes 客户端"] - A[mypc03
peer: laodeng-mypc03
key: tok_alpha] - B[gov-pc
peer: laodeng-govpc
key: tok_beta] - C[macbook
peer: laodeng-mac
key: tok_gamma] + A[mypc03
peer: laodeng-mypc03x] + B[gov-pc
peer: laodeng-govpcxxxx] + C[macbook
peer: laodeng-macxxxxxxx] end subgraph Vm61["vm61 (192.168.10.61 / WG 10.8.0.9, 备用)"] WG[WireGuard
10.8.0.9 入口] - API[honcho-api:8000
AUTH ON] + API[honcho-api:8000
AUTH OFF (v3 DEV)] DB[(postgres+pgvector)] DERIVER[honcho-deriver
~2 done/min] REDIS[(redis)] @@ -64,7 +64,7 @@ flowchart LR | 决策 | 选择 | 替代方案 | 理由 | |---|---|---|---| -| **AUTH 开** | ✅ ON | OFF（内网） | 可审计 + 可撤销 + 可限流；WireGuard 内网本身已加密 | +| **AUTH 关闭（DEV）** | ✅ OFF | ON | 当前 vm61 honcho v3.0.10 `USE_AUTH=False`；3 客户端同源（同老登）+ WireGuard 内网隔离已足够；生产或多人共用必须开 | | **Workspace** | `home` 一个共用 | 每个 peer 独立 ws | 老登本人用，跨设备回忆体验更好 | | **Peer** | 带设备后缀 | 统一 `laodeng` | 审计需要知道"哪台设备写的"；peer 概念在 honcho 里是身份，不影响记忆语义 | | **API URL** | `http://10.8.0.9:18000`（vm61 WireGuard IP） | 公网 IP / 域名 | WireGuard 已加密 + 认证，没必要再绕公网 | @@ -81,9 +81,9 @@ flowchart LR # 1.1 确认 4 个容器 Up docker ps | grep -E "honcho-(api|deriver|database|redis)" -# 1.2 确认 AUTH 已开（6-19 已设过，复核） -cat /data/deploy/honcho/env.cfg | grep -E "AUTH_USE_AUTH|JWT_SECRET" -# 期望: AUTH_USE_AUTH=true +# 1.2 确认 AUTH 状态（v3.0.10 实际为 DEV OFF，2026-06-26 探针实测） +ssh yong@10.8.0.9 'docker exec honcho-api python3 -c "from src.config import settings; print(\"USE_AUTH:\", settings.AUTH.USE_AUTH)"' +# 期望: USE_AUTH: False（当前状态） # 1.3 确认 honcho-api 监听 0.0.0.0（不是 127.0.0.1） docker inspect honcho-api | grep -A2 -E "HostPort|NetworkMode" @@ -96,37 +96,47 @@ curl -s http://10.8.0.9:18000/health ``` **如果 1.3 / 1.4 失败**： -- stack.yml 里 `ports:` 必须暴露 `0.0.0.0:8000:8000` 或 `8000:8000` +- stack.yml 里 `ports:` 必须暴露 `0.0.0.0:18000:18000` - 6-19 修过的 `DB_CONNECTION_URI` / `CACHE_URL` 已稳定，但确认 WireGuard 网卡没被 firewall 拦 -### Phase 2: 创建 3 个 API key +### Phase 2: v3 鉴权模式 + peer 创建 + +**v3.0.10 实测 schema（2026-06-26 探针）**： + +| 关键事实 | 说明 | +|---|---| +| 端点前缀 | **/v3/**（不是 /v2/） | +| 鉴权 | `HTTPBearer(auto_error=False)` — 未带 token 放行（DEV 模式表现） | +| `AUTH.USE_AUTH` 开关 | False 时所有 peer 操作无需 token；True 时需 admin JWT | +| 创建 JWT 端点 | `POST /v3/keys?workspace_id=&peer_id=&session_id=`（admin auth 强制） | +| 创建 workspace | `POST /v3/workspaces` body `{"id":"home"}` | +| 创建 peer | `POST /v3/workspaces/{ws_id}/peers` body `{"id":""}` | +| Peer ID 格式 | text 21 字符，`^[A-Za-z0-9_-]+$`（**不是 UUID**） | +| DB schema | `peers(id PK text, name text, workspace_name FK→workspaces(name))` | +| DB schema | **无 `api_keys` 表**（v3 用 JWT，无独立 key 表） | + +**当前 DEV 模式（USE_AUTH=False）下，3 客户端接入步骤**： ```bash -# vm61 上跑 create-multi-keys.sh（见同目录） -./create-multi-keys.sh +# 2.1 确认 workspace 已存在 +ssh yong@10.8.0.9 'curl -s -X POST http://127.0.0.1:18000/v3/workspaces \ + -H "Content-Type: application/json" -d "{\"id\":\"home\"}"' +# 期望: {"id":"home",...} 或已存在返回 + +# 2.2 创建 3 个 peer（peer_id 必须 21 字符，格式 ^[A-Za-z0-9_-]+$） +for PEER in laodeng-mypc03x laodeng-govpcxxxx laodeng-macxxxxxxx; do + ssh yong@10.8.0.9 "curl -s -X POST http://127.0.0.1:18000/v3/workspaces/home/peers \ + -H 'Content-Type: application/json' -d '{\"id\":\"$PEER\"}'" + echo "--- $PEER done ---" +done +# 期望: 3 个 200 OK 返回 peer 对象 ``` -脚本输出形如： - -``` -✅ key_alpha -> /root/.honcho-keys/mypc03.key -✅ key_beta -> /root/.honcho-keys/govpc.key -✅ key_gamma -> /root/.honcho-keys/mac.key -``` - -**`scp` 3 个 key 文件到对应客户端**： - -```bash -scp /root/.honcho-keys/mypc03.key mypc03:~/.honcho-keys/ -scp /root/.honcho-keys/govpc.key gov-pc:~/.honcho-keys/ -scp /root/.honcho-keys/mac.key macbook:~/.honcho-keys/ -``` - -⚠️ **绝不 echo 到聊天**（参考 6-07 dufs 密码泄露教训）。每个客户端 `chmod 600 ~/.honcho-keys/*.key`。 +**未来开 AUTH（USE_AUTH=True）时**：每个 peer 创建后用 `POST /v3/keys?workspace_id=home&peer_id=` 拿 scoped JWT，scp 到客户端 `~/.honcho-keys/.key`，hermes config `memory.honcho.api_key` 填 JWT。 ### Phase 3: 3 客户端配置 hermes -每台机器执行（**api_url 都填 WireGuard 内网 IP**）： +每台机器执行（**当前 DEV 模式不填 api_key；AUTH 开后填 JWT**）： ```bash # 通用（3 台都跑） @@ -134,50 +144,52 @@ hermes config set memory.provider honcho hermes config set memory.honcho.api_url http://10.8.0.9:18000 hermes config set memory.honcho.workspace home -# mypc03 额外 -hermes config set memory.honcho.peer laodeng-mypc03 -hermes config set memory.honcho.api_key "$(cat ~/.honcho-keys/mypc03.key)" +# mypc03 +hermes config set memory.honcho.peer laodeng-mypc03x -# gov-pc 额外 -hermes config set memory.honcho.peer laodeng-govpc -hermes config set memory.honcho.api_key "$(cat ~/.honcho-keys/govpc.key)" +# gov-pc +hermes config set memory.honcho.peer laodeng-govpcxxxx -# macbook 额外 -hermes config set memory.honcho.peer laodeng-mac -hermes config set memory.honcho.api_key "$(cat ~/.honcho-keys/mac.key)" +# macbook +hermes config set memory.honcho.peer laodeng-macxxxxxxx ``` ### Phase 4: 交叉验证（关键！） -**Step A: 网络 + Auth** +**Step A: 网络 + honcho 响应**（3 台机器各跑） -3 台机器各跑： +```bash +# DEV 模式不带 token 也能访问 +curl -s -o /dev/null -w "HTTP %{http_code}\n" \ + http://10.8.0.9:18000/v3/workspaces/home/peers +# 期望: HTTP 200 +``` +**未来 AUTH 开启后改用**： ```bash curl -s -o /dev/null -w "HTTP %{http_code}\n" \ -H "Authorization: Bearer $(cat ~/.honcho-keys/xxx.key)" \ - http://10.8.0.9:18000/v2/workspaces/home -# 期望: HTTP 200 + http://10.8.0.9:18000/v3/workspaces/home/peers ``` **Step B: 跨端召回** ```bash # mypc03 写一条 -hermes memory retain "2026-06-20 mypc03 测试 honcho 跨设备共享 v1" +hermes memory retain "2026-06-26 mypc03 测试 honcho v3 跨设备共享" # gov-pc 召回 -hermes memory recall "honcho 跨设备共享" +hermes memory recall "honcho v3 跨设备共享" # 期望: 看到 mypc03 写的那条 ``` **Step C: 隔离验证（确认 peer 字段）** ```bash -# honcho 管理 API（vm61 上） -docker exec honcho-database psql -U honcho -d honcho -c \ - "SELECT name, created_at FROM peers WHERE workspace = 'home';" -# 期望: 3 行，name 各不相同 +# honcho 管理（vm61 上）— 注意 v3 列名是 workspace_name 不是 workspace +ssh yong@10.8.0.9 'docker exec honcho-database psql -U honcho -d honcho -c \ + "SELECT name, created_at FROM peers WHERE workspace_name = '\''home'\'';"' +# 期望: 3 行，name 各不相同（带设备后缀） ``` ### Phase 5: deriver 容量观察 @@ -188,9 +200,8 @@ docker exec honcho-database psql -U honcho -d honcho -c \ # vm61 看 deriver 进度 docker logs honcho-deriver --since 1h | grep -E "queue|processed|done" -# 队列深度 -curl -s http://10.8.0.9:18000/v2/admin/queues \ - -H "Authorization: Bearer $(cat /root/.honcho-keys/admin.key)" | jq +# 队列深度（v3 端点） +ssh yong@10.8.0.9 'curl -s http://127.0.0.1:18000/v3/workspaces/home/queue/status' | jq ``` **告警阈值**： @@ -207,7 +218,8 @@ curl -s http://10.8.0.9:18000/v2/admin/queues \ | 症状 | 排查 | 修复 | |---|---|---| -| `curl HTTP 401` | key 不对 / expired | 重新跑 `create-multi-keys.sh` | +| `curl HTTP 401` | AUTH 已开但缺 token / token 过期 | 重新创建 JWT（`POST /v3/keys?workspace_id=home`） | +| `curl HTTP 422` | peer_id 格式不符（必须 21 字符 `^[A-Za-z0-9_-]+$`） | 调整 peer_id 长度/字符 | | `curl HTTP 404` | workspace 名错 | `hermes config get memory.honcho.workspace` 必须 = `home` | | `curl timeout` | WireGuard 没拨上 | `wg show` 看握手时间；`ping 10.8.0.9` | | 召回不到 mypc03 写的 | peer 不在同一 workspace | 三台 `hermes config get memory.honcho.workspace` 都该是 `home` | @@ -220,19 +232,33 @@ curl -s http://10.8.0.9:18000/v2/admin/queues \ 需要把 gov-pc 从共享里踢出去（换工作 / 借人）： -```bash -# vm61 上 -docker exec honcho-database psql -U honcho -d honcho -c \ - "DELETE FROM api_keys WHERE name = 'laodeng-govpc';" +**DEV 模式**：直接删 peer（v3 REST） -# 立即生效，无需重启 honcho +```bash +# v3 REST 删除 peer（DEV 模式不带 token） +ssh yong@10.8.0.9 'curl -s -X DELETE \ + http://127.0.0.1:18000/v3/workspaces/home/peers/laodeng-govpcxxxx' ``` -**注意**：revoke 后该客户端后续的 retain/recall 会失败；该客户端的 peer 数据**不会被删**，只是没法继续写。如要删数据： +**AUTH 开启后**：先删 JWT，再删 peer + +```bash +# 1. 服务端撤 JWT（v3 没有 api_keys 表；JWT 自身无法服务端 revoke，只能靠短期 exp） +# 解决：缩短 JWT exp（如 24h），或重新生成 admin token 改 settings.AUTH + +# 2. 删 peer +ssh yong@10.8.0.9 'curl -s -X DELETE \ + -H "Authorization: Bearer $(cat /root/.honcho-keys/admin.key)" \ + http://127.0.0.1:18000/v3/workspaces/home/peers/laodeng-govpcxxxx' +``` + +**清理历史消息**（如要彻底删除 gov-pc 的数据）： ```sql -DELETE FROM messages WHERE peer_id = (SELECT id FROM peers WHERE name = 'laodeng-govpc'); -DELETE FROM peers WHERE name = 'laodeng-govpc'; +-- v3 schema: peer_id 是 text 不是 UUID；name 是 peer 的可读名 +DELETE FROM messages WHERE peer_id = (SELECT id FROM peers WHERE name = 'laodeng-govpcxxxx'); +DELETE FROM session_peers WHERE peer_id = (SELECT id FROM peers WHERE name = 'laodeng-govpcxxxx'); +DELETE FROM peers WHERE name = 'laodeng-govpcxxxx'; ``` --- @@ -245,7 +271,7 @@ DELETE FROM peers WHERE name = 'laodeng-govpc'; | WireGuard 部署 | `deploy.stack/WireGuardVPN/wg-easy/` | 已有，给 3 客户端分配 10.8.0.112/143/144，honcho 服务端在 10.8.0.9 | | honcho deriver 调试 | honcho memory (2026-06-19/20) | deriver 修复历史 | | Hermes memory provider 切换 | hermes-agent skill | `memory.provider honcho` 配法 | -| 凭据管理 | `~/.honcho-keys/` | chmod 600，绝不入 git | +| 凭据管理 | `~/.honcho-keys/` | chmod 600，绝不入 git；DEV 模式暂未启用 | --- @@ -255,4 +281,5 @@ DELETE FROM peers WHERE name = 'laodeng-govpc'; - [ ] 给 honcho-api 加 TLS（自签 CA 推 3 客户端） - [ ] deriver 加 Prometheus exporter，接 vm61 VictoriaMetrics - [ ] cron: 每天 pg_dump honcho DB → dufs 备份（参考 hindsight/backup.job） -- [ ] 4 个客户端的 hermes 版本统一（避免 protocol 不一致） \ No newline at end of file +- [ ] 4 个客户端的 hermes 版本统一（避免 protocol 不一致） +- [ ] 评估何时开 AUTH（USE_AUTH=True）+ 配 scoped JWT 体系 \ No newline at end of file