deploy.stack/honcho/share-multi-client.md

Honcho 多 Hermes 客户端共享方案

状态: 📝 草案 (2026-06-20, 06-26 拓扑修正) 适用: vm61 (10.8.0.9, 备用/测试环境) 部署 honcho + 3 个 hermes 客户端共享同一份记忆

---

1. 场景

客户端	位置	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

3 个客户端都是老登本人用，所以希望：

• ✅ 共享 workspace（home）：在 A 上聊的事，B 上能召回
• ✅ peer 独立（带设备后缀）：方便审计"在哪台设备说的"
• ✅ AUTH 开启：每个客户端独立 API key，可单独撤销
• ❌ 不共享 LLM 凭据：每个客户端用自己的 hermes LLM key

---

2. 架构

flowchart LR
    subgraph Clients["3 个 Hermes 客户端"]
        A[mypc03<br/>peer: laodeng-mypc03<br/>key: tok_alpha]
        B[gov-pc<br/>peer: laodeng-govpc<br/>key: tok_beta]
        C[macbook<br/>peer: laodeng-mac<br/>key: tok_gamma]
    end

    subgraph Vm61["vm61 (192.168.10.61 / WG 10.8.0.9, 备用)"]
        WG[WireGuard<br/>10.8.0.9 入口]
        API[honcho-api:8000<br/>AUTH ON]
        DB[(postgres+pgvector)]
        DERIVER[honcho-deriver<br/>~2 done/min]
        REDIS[(redis)]
    end

    A ==wg==> WG
    B ==wg==> WG
    C ==wg==> WG
    WG --> API
    API --> DB
    API --> REDIS
    DERIVER <--> REDIS
    DERIVER <--> DB

    classDef client fill:#e1f5ff,stroke:#0066cc
    classDef svc fill:#fff4e1,stroke:#cc6600
    classDef store fill:#e8f5e9,stroke:#2e7d32
    class A,B,C client
    class WG,API,DERIVER svc
    class DB,REDIS store

网络：3 客户端 (10.8.0.112/143/144) → WireGuard 隧道 (10.8.0.x) → vm61 (10.8.0.9) 8000

---

3. 为什么这样设计

决策	选择	替代方案	理由
AUTH 开	✅ ON	OFF（内网）	可审计 + 可撤销 + 可限流；WireGuard 内网本身已加密
Workspace	home 一个共用	每个 peer 独立 ws	老登本人用，跨设备回忆体验更好
Peer	带设备后缀	统一 laodeng	审计需要知道"哪台设备写的"；peer 概念在 honcho 里是身份，不影响记忆语义
API URL	http://10.8.0.9:18000（vm61 WireGuard IP）	公网 IP / 域名	WireGuard 已加密 + 认证，没必要再绕公网
LLM 凭据	客户端本地保留	共享到 honcho	deriver 已经持有全局 LLM key；客户端 hermes 自己的对话 LLM 不应上送 honcho
deriver 后台	共享 vm61 上现有	每客户端本地跑	honcho deriver 设计就是单实例后台，集中推理更省 API 配额

---

4. 实施步骤

Phase 1: vm61 上 honcho 准备

# 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.3 确认 honcho-api 监听 0.0.0.0（不是 127.0.0.1）
docker inspect honcho-api | grep -A2 -E "HostPort|NetworkMode"
# 或直接看启动日志
docker logs honcho-api 2>&1 | grep -i "listening"

# 1.4 从 WireGuard 网卡验证
curl -s http://10.8.0.9:18000/health
# 期望: {"status":"ok"}

如果 1.3 / 1.4 失败：

• stack.yml 里 ports: 必须暴露 0.0.0.0:8000:8000 或 8000:8000
• 6-19 修过的 DB_CONNECTION_URI / CACHE_URL 已稳定，但确认 WireGuard 网卡没被 firewall 拦

Phase 2: 创建 3 个 API key

# vm61 上跑 create-multi-keys.sh（见同目录）
./create-multi-keys.sh

脚本输出形如：

✅ key_alpha -> /root/.honcho-keys/mypc03.key
✅ key_beta  -> /root/.honcho-keys/govpc.key
✅ key_gamma -> /root/.honcho-keys/mac.key

scp 3 个 key 文件到对应客户端：

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。

Phase 3: 3 客户端配置 hermes

每台机器执行（api_url 都填 WireGuard 内网 IP）：

# 通用（3 台都跑）
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)"

# gov-pc 额外
hermes config set memory.honcho.peer      laodeng-govpc
hermes config set memory.honcho.api_key   "$(cat ~/.honcho-keys/govpc.key)"

# macbook 额外
hermes config set memory.honcho.peer      laodeng-mac
hermes config set memory.honcho.api_key   "$(cat ~/.honcho-keys/mac.key)"

Phase 4: 交叉验证（关键！）

Step A: 网络 + Auth

3 台机器各跑：

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

Step B: 跨端召回

# mypc03 写一条
hermes memory retain "2026-06-20 mypc03 测试 honcho 跨设备共享 v1"

# gov-pc 召回
hermes memory recall "honcho 跨设备共享"
# 期望: 看到 mypc03 写的那条

Step C: 隔离验证（确认 peer 字段）

# honcho 管理 API（vm61 上）
docker exec honcho-database psql -U honcho -d honcho -c \
  "SELECT name, created_at FROM peers WHERE workspace = 'home';"
# 期望: 3 行，name 各不相同

Phase 5: deriver 容量观察

接入第 3 个客户端后，前 2 天重点观察：

# 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

告警阈值：

指标	正常	警告	干预
队列深度	< 500	500-2000	> 2000 持续 1h → 考虑错峰
deriver done/min	2-4	4-8	> 8 持续 → 加 worker
Postgres 连接	< 50	50-100	> 100 → 调大 max_connections

---

5. 故障排查

症状	排查	修复
curl HTTP 401	key 不对 / expired	重新跑 create-multi-keys.sh
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
deriver 队列暴涨	LLM 限流（SiliconFlow）	临时调低 deriver 并发；或加备份 LLM endpoint
honcho-api OOM	写入太频繁	docker stats honcho-api；考虑加 limit

---

6. 撤销 / 隔离某个客户端

需要把 gov-pc 从共享里踢出去（换工作 / 借人）：

# vm61 上
docker exec honcho-database psql -U honcho -d honcho -c \
  "DELETE FROM api_keys WHERE name = 'laodeng-govpc';"

# 立即生效，无需重启 honcho

注意：revoke 后该客户端后续的 retain/recall 会失败；该客户端的 peer 数据不会被删，只是没法继续写。如要删数据：

DELETE FROM messages WHERE peer_id = (SELECT id FROM peers WHERE name = 'laodeng-govpc');
DELETE FROM peers WHERE name = 'laodeng-govpc';

---

7. 关联资源

资源	路径	说明
honcho stack	deploy.stack/honcho/	当前部署
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

---

8. 后续 TODO（可选）

• 把 memory.honcho.api_url 改成 hostname 而非 IP（DNS 友好）
• 给 honcho-api 加 TLS（自签 CA 推 3 客户端）
• deriver 加 Prometheus exporter，接 vm61 VictoriaMetrics
• cron: 每天 pg_dump honcho DB → dufs 备份（参考 hindsight/backup.job）
• 4 个客户端的 hermes 版本统一（避免 protocol 不一致）