18 · 运维、可观测性与质量体系

Buzz 的工程化与产品体量匹配：Hermit 固定工具链，Just 统一本地入口，CI 按 Rust/Desktop/Web/Mobile 路径分流，部署覆盖 Compose 与 Helm，安全关键协议还有 property/conformance、TLA+、Tamarin 和 Python 状态模型。代价是 CI 图很大，部分关键测试需要真实 Postgres/Redis/S3/平台凭证。

1. 本地开发入口

text

Hermit pinned tools
       │
       ▼
Justfile
  ├─ bootstrap / setup / dev
  ├─ fmt / clippy / typecheck / lint
  ├─ unit / integration / e2e
  ├─ desktop/web/mobile builds
  ├─ relay + Docker dependencies
  └─ release / mesh / maintenance helpers

just ci 聚合 Rust checks、核心 unit、Desktop test/build/Tauri check、Web build 和 Mobile test。项目要求 Rust 生产代码避免 unsafe、unwrap/expect 等，并用 -D warnings 提升 lint 为门禁。

2. 测试分层

层	例子	捕获问题
单元	core/filter/kind、auth、DB helpers、workflow schema	局部不变量、边界输入
Property/conformance	`buzz-conformance` + proptest	多租户/协议实现对独立模型的偏差
数据库集成	Postgres/Redis、migration、replica fence	SQL 与真实事务/约束
Relay E2E	`buzz-test-client`	EVENT/REQ/auth/interop 与服务接线
Desktop browser smoke	Playwright	React UI 和路由，不依赖完整 Relay 的基础路径
Desktop relay-backed E2E	shard Playwright + 预建 Relay	UI 到真实服务全链路
Web/Mobile	Playwright / Flutter tests	各端协议和交互
Release contract	shell tests	tag/ref/artifact/工作流规则

仓库中至少有数十个独立 Rust integration test 文件，另有大量 #[cfg(test)] 内联测试。

3. 多租户 conformance gate

buzz-conformance 不直接复用生产权限实现，而是以独立 checker/model 对照候选事件与可见性。独立性很重要：如果测试 helper 只是调用生产 event_visible_to_reader，两者会一起犯错。

Property test 生成社区、频道、成员、事件/过滤器组合，寻找：

跨社区泄露。
global/channel scope 混淆。
author/p/shared/result gate 偏差。
边界前缀/tag 匹配错误。

4. 形式化资产

文件	工具/主题
`MultiTenantRelay.tla`	TLA+；租户隔离、事件流与状态转移
`MultiTenantAuth.spthy`	Tamarin；认证协议与攻击者模型
`GitOnObjectStore.tla`	TLA+；pack/manifest/CAS 并发正确性
`formal/nip-pl/*.py`	Python exhaustive/mutation；Push lease acceptance/delivery

形式化模型证明的是模型在假设下的性质，不自动证明 Rust/SQL/云服务实现。但它能迫使设计明确状态、原子点、攻击者能力与公平性假设，并可派生 conformance fixtures。

5. CI 图

.github/workflows/ci.yml 先做 path detection，再按需执行：

Rust fmt/clippy/unit。
Desktop React、Tauri Rust 与编译 flag 双态验证。
Desktop smoke E2E 四 shard。
预建 Relay artifact + relay-backed Desktop E2E shards。
backend/relay E2E。
Web/Mobile checks。
cargo-deny 依赖许可证/漏洞策略。
Windows 特定 dev-mcp test。

push 到 main/release 会跑更广矩阵；PR path filter 缩短反馈。Artifact job 让多个 E2E shard 复用同一 Relay build，减少重复编译。

6. 发布供应链

独立 workflow 覆盖：

multi-arch Relay/Push Gateway container。
Helm chart 发布。
Desktop macOS/Windows/Linux canary 与签名/公证。
Mobile release candidate。
Sprig artifact。
release PR merge 后自动 tag。

Docker workflow 使用 provenance attestation；CI action 多数 pin 到 commit SHA，降低 tag 被篡改的供应链风险。发布 contract shell tests 验证 ref/tag/版本约束，避免工作流 YAML 改坏后直到 release 才发现。

7. 部署层

方式	用途
`deploy/compose`	单机/开发/小规模，自带 Caddy 与服务依赖示例
`deploy/charts/buzz`	Kubernetes Relay、Postgres/Redis/S3 配置与 probes
`deploy/charts/buzz-push-gateway`	Push gateway 独立网络、密钥与数据库
`deploy/local`	本地 HA/快速验证脚本

Push Gateway 分离 chart 与 values 是安全边界体现，不应为了“部署简单”把 APNs secrets 塞回普通 Relay chart。

8. 健康与优雅退出

Relay AppState 有 shutting-down 标志：收到 SIGTERM 后 readiness 先返回不健康，负载均衡停止新流量，再取消连接/后台任务并 drain 审计队列。liveness 只判断进程是否活，readiness 还应检查数据库/Redis/迁移等接流前置条件。

Push Gateway 把 public router 与 private health router 分开，私有端口提供 /_liveness、/_readiness 和可选 /metrics，不在公网业务端口暴露 Prometheus。

9. 可观测性

Relay 使用 structured tracing 与 metrics：

WS 活跃连接、auth timeout、backpressure disconnect。
subscription gauge、fan-out、ingest/query latency。
membership/access cache hit/miss。
audit error/latency。
COUNT fallback rejection。
Git hydrate/cache bytes/hit/eviction。
storage physical/logical/orphan sweep。
workflow、Push、moderation/reconciliation。

指标 label 必须 bounded-cardinality。Push Gateway metrics.rs 明确用枚举归一错误类别；不要把 event ID/pubkey/任意 URL 填进 Prometheus label。

10. 背压与降级可观测

慢 WS 客户端会先经历有界 grace，持续 send buffer full 后断开，并记录 counter。Redis broadcast lag、audit worker panic、storage sweep age 等也要显式指标，否则“最终一致”会退化成“永久丢失而无人知道”。

11. 运维风险清单

新库与 brownfield FTS expression 可能不同，升级后需维护脚本/验证。
S3 provider 必须满足 Git CAS 文档的 conditional write 假设。
Redis 故障策略要按 rate/replay/fan-out 不同风险配置。
多 pod 需要验证 cache invalidation、connection control 与 dynamic subscriptions。
Desktop release 同时打包多个 sidecar，版本矩阵必须保持一致。
Push Gateway 的 DB、APNs key、App Attest 和 private metrics 网络需独立备份/轮换。

12. 源码入口

Justfile：统一开发/测试命令。
.github/workflows/ci.yml：CI DAG。
deploy/：Compose 与 Helm。
crates/buzz-conformance/：独立模型与 property tests。
docs/spec/MultiTenantRelay.tla：Relay TLA+ 模型。
docs/spec/MultiTenantAuth.spthy：认证 Tamarin 模型。
crates/buzz-relay/src/telemetry.rs：Relay telemetry。
crates/buzz-push-gateway/src/metrics.rs：私有 Prometheus 与 bounded labels。

18 · 运维、可观测性与质量体系 ​

1. 本地开发入口 ​

2. 测试分层 ​

3. 多租户 conformance gate ​

4. 形式化资产 ​

5. CI 图 ​

6. 发布供应链 ​

7. 部署层 ​

8. 健康与优雅退出 ​

9. 可观测性 ​

10. 背压与降级可观测 ​

11. 运维风险清单 ​

12. 源码入口 ​