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

# 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. 架构

```mermaid
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 准备

```bash
# 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 客户端接入步骤**：

```bash
# 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**）：

```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-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 台机器各跑）

```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/v3/workspaces/home/peers
```

**Step B: 跨端召回**

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

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

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

```bash
# 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 天重点观察：

```bash
# 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）

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

**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
-- 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 体系