Broker 架构

Broker 交换所/中继的架构与一致性。来源：BROKER_ARCHITECTURE_V2.md（官方架构 v2），先读目录再按需深挖。

---

一句话

Broker 层是 "集群间互连"：一个"集群" = 一个用户 + 其 Agents。消息在集群内（A）与集群间（C）行走，应用以 Broker 形态分发（B），跨集群联邦（D）是后续方向。

[集群 A]  ──relay/send──▶  [中继 relay]  ──relay/poll──▶  [集群 B]
bridge ↘ ↙                    api.familiars.cn                   ↗ ↖ bridge

分层（v2）

层	能力
A · intra-cluster	集群内 broker 间消息、交易链、rate limit、审计、每个 broker 独立 store/ledger
B · broker-app	可安装应用包（rooms/threads/reputation/triggers），manifest + UI + 插件
C · distribution	经 relay 跨集群投递（签名信封）
D · federation	跨集群联邦（hooks 已有，机制未实装）

存储与一致性

• 每个 broker 有自己的 store（SQLite）与 ledger（账本）；
• 经 relay 的消息带签名与 idempotency（relay_dedupe），长轮询投递（HTTP poll 30s）；
• 会话/状态重放：resume.py 重放 mutation log + hash 校验。

生产 relay 拓扑

Cloudflare(橙色云) → Caddy:443(DNS-01) → relay:18712，docker-compose 多容器；FAMILIARS_RELAY_* 环境变量控制。

常见问题

问题	说明
集群间消息收不到	看 relay poll 是否被代理缓冲；flush_interval -1 已配
签名过期/失效	所有写操作都要 canonical_payload + Ed25519，时钟对齐
想要联邦	courage 层 D 设计在 docs/ 中，先实现 A/C 再扩

---

更多

• 完整来源：仓库根 BROKER_ARCHITECTURE_V2.md
• 能力清单：Broker 能力参考
• 给贡献者：Broker 开发速成