cnphpbb/deploy.stack
1
0
Fork 0
forked from DevOps/deploy.stack
Code Pull Requests Activity
Files
main
deploy.stack/honcho/share-multi-client.md
T

11 KiB
Raw Permalink Blame History

Honcho 多 Hermes 客户端共享方案

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

1. 场景

客户端 位置 WireGuard IP 网络到 vm61 peer 名
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 关闭（DEV 模式）：vm61 honcho v3.0.10 实例 USE_AUTH=False，JWT_SECRET 留空，peer 不强制鉴权；接入稳后再开
  • ❌ 不共享 LLM 凭据：每个客户端用自己的 hermes LLM key

2. 架构

flowchart LR
    subgraph Clients["3 个 Hermes 客户端"]
        A[mypc03<br/>peer: laodeng-mypc03x]
        B[gov-pc<br/>peer: laodeng-govpcxxxx]
        C[macbook<br/>peer: laodeng-macxxxxxxx]
    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 OFF (v3 DEV)]
        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 关闭（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 已加密 + 认证，没必要再绕公网
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 状态（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"
# 或直接看启动日志
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:18000:18000
  • 6-19 修过的 DB_CONNECTION_URI / CACHE_URL 已稳定，但确认 WireGuard 网卡没被 firewall 拦

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>"}
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 客户端接入步骤：

# 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 对象

未来开 AUTH（USE_AUTH=True）时：每个 peer 创建后用 POST /v3/keys?workspace_id=home&peer_id=<id> 拿 scoped JWT，scp 到客户端 ~/.honcho-keys/<peer>.key，hermes config memory.honcho.api_key 填 JWT。

Phase 3: 3 客户端配置 hermes

每台机器执行（当前 DEV 模式不填 api_key；AUTH 开后填 JWT）：

# 通用（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-mypc03x

# gov-pc
hermes config set memory.honcho.peer      laodeng-govpcxxxx

# macbook
hermes config set memory.honcho.peer      laodeng-macxxxxxxx

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

Step A: 网络 + honcho 响应（3 台机器各跑）

# 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 开启后改用：

curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  -H "Authorization: Bearer $(cat ~/.honcho-keys/xxx.key)" \
  http://10.8.0.9:18000/v3/workspaces/home/peers

Step B: 跨端召回

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

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

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

# 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 容量观察

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

# vm61 看 deriver 进度
docker logs honcho-deriver --since 1h | grep -E "queue|processed|done"

# 队列深度（v3 端点）
ssh yong@10.8.0.9 'curl -s http://127.0.0.1:18000/v3/workspaces/home/queue/status' | 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 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
deriver 队列暴涨 LLM 限流（SiliconFlow） 临时调低 deriver 并发；或加备份 LLM endpoint
honcho-api OOM 写入太频繁 docker stats honcho-api；考虑加 limit

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

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

DEV 模式：直接删 peer（v3 REST）

# 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'

AUTH 开启后：先删 JWT，再删 peer

# 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 的数据）：

-- 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';

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；DEV 模式暂未启用

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 不一致）
  • 评估何时开 AUTH（USE_AUTH=True）+ 配 scoped JWT 体系
View Git Blame Copy Permalink