forked from DevOps/deploy.stack
cnphpbb
258 lines
8.4 KiB
Markdown
258 lines
8.4 KiB
Markdown
# 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. 架构
|
||
|
||
```mermaid
|
||
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 准备
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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 文件到对应客户端**：
|
||
|
||
```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`。
|
||
|
||
### Phase 3: 3 客户端配置 hermes
|
||
|
||
每台机器执行（**api_url 都填 WireGuard 内网 IP**）：
|
||
|
||
```bash
|
||
# 通用（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 台机器各跑：
|
||
|
||
```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
|
||
```
|
||
|
||
**Step B: 跨端召回**
|
||
|
||
```bash
|
||
# mypc03 写一条
|
||
hermes memory retain "2026-06-20 mypc03 测试 honcho 跨设备共享 v1"
|
||
|
||
# gov-pc 召回
|
||
hermes memory recall "honcho 跨设备共享"
|
||
# 期望: 看到 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 各不相同
|
||
```
|
||
|
||
### Phase 5: deriver 容量观察
|
||
|
||
接入第 3 个客户端后，前 2 天重点观察：
|
||
|
||
```bash
|
||
# 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 从共享里踢出去（换工作 / 借人）：
|
||
|
||
```bash
|
||
# vm61 上
|
||
docker exec honcho-database psql -U honcho -d honcho -c \
|
||
"DELETE FROM api_keys WHERE name = 'laodeng-govpc';"
|
||
|
||
# 立即生效，无需重启 honcho
|
||
```
|
||
|
||
**注意**：revoke 后该客户端后续的 retain/recall 会失败；该客户端的 peer 数据**不会被删**，只是没法继续写。如要删数据：
|
||
|
||
```sql
|
||
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 不一致） |