Tunly 系统设计

一句话架构

Tunly 以 Namespace 为唯一归属边界，以 Link 为长期分享对象，以 Route 提供稳定地址，以 Revision 表达每次发布版本；所有公开请求都按 Route → Link → Access → Revision 的顺序确定性解析。

系统上下文与信任边界

Agent / Human CLI                              Browser Reviewer
       │ API key / attach grant                       │ HTTPS / session
       ▼                                              ▼
┌──────────────────────────────────────────────────────────────┐
│                    Caddy · TLS edge                          │
│  control paths ───────────────┐  public paths ────────────┐  │
└───────────────────────────────┼────────────────────────────┼──┘
                                ▼                            ▼
                    ┌────────────────────┐       ┌────────────────────┐
                    │ tunlyctl           │       │ tunlyd             │
                    │ control plane      │       │ edge + live proxy  │
                    │ publish / review   │       │ PublicResolver     │
                    └──────┬─────┬───────┘       └──────┬─────┬───────┘
                           │     │                      │     │
                     ┌─────▼─┐ ┌─▼───────────┐   ┌─────▼─┐ ┌─▼───────────┐
                     │Redis  │ │Postgres     │   │Redis  │ │ArtifactStore│
                     │runtime│ │product facts│   │leases │ │manifests   │
                     └───────┘ └─────────────┘   └───────┘ └─────────────┘
                                ▲
                                │ same durable repository contract
                                └─────────────────────────────────────────

核心请求流程

A. Artifact 发布与原子提升

B. 公共请求解析

HTTP request
  │
  ├─ 1. normalize Host + Path
  ├─ 2. resolve the most specific active Route
  ├─ 3. load active Link inside the same Namespace
  ├─ 4. evaluate Link access policy (fail closed)
  ├─ 5. choose exact Version or Link.current_revision_id
  ├─ 6. require a servable Revision
  │
  ├─ live ─────► validate active Redis lease/generation ─► proxy local origin
  └─ artifact ─► read manifest + file from ArtifactStore ─► apply profile headers

Latest 响应使用可重新验证的 cache 语义；Version artifact 可使用 immutable cache。私有内容、Review rendition 和访问挑战必须使用 private/no-store，避免代理缓存跨用户泄露。

C. Live attach 与 Latest

1. CLI 先通过控制面用 API Key 请求一次性、短 TTL、精确 Namespace/Link scope 的 attach grant。
2. CLI 与 edge 建立 WebTransport/QUIC；edge 消费 attach grant，并检查 API Key 所有者仍是活跃成员。
3. edge 建立带 generation 的 Redis live lease，旧连接不能覆盖新 generation。
4. 生产环境从 edge 往本地 origin 做真实 readiness round trip。
5. 只有探针通过才原子提升 live Revision；失败则清理 lease，Latest 保持不动。

HTML Review：Revision 上的协作层

Review 不修改原始 artifact，也不创建新的文档模型。它是 Link 开启的策略，并把每条 annotation 固定在一个 Namespace + Link + Revision 元组上。

Rendition 与隔离

锚点定位策略

根评论同时保存 W3C 风格的 TextQuoteSelector 与 TextPositionSelector。渲染时先用位置快速验证，再用 exact + prefix + suffix 回退；匹配不唯一或找不到时显示 orphan，而不是猜测错误位置。

{
  "type": "Text",
  "refinedBy": [
    { "type": "TextQuoteSelector", "exact": "selected text", "prefix": "before ", "suffix": " after" },
    { "type": "TextPositionSelector", "start": 120, "end": 133 }
  ]
}

读写权限与实时更新

当前部署与扩展路径

当前单节点生产拓扑

Internet :80/:443 TCP ──► Caddy LoadBalancer
                              │
                              ├─ /api, /app, /login, /review/sidebar ─► tunlyctl:8080
                              ├─ /wt (h2c fallback) ──────────────────► tunlyd-control:8081
                              └─ all public Link paths ───────────────► tunlyd:80

Internet :443 UDP ───────────────────────────────────────────────────► tunlyd:443 QUIC

tunlyctl + tunlyd ─► Postgres service
                  ├► dedicated Tunly Redis
                  ├► shared ArtifactStore provider
                  └► OTLP logs collector

Persistent volumes: artifact bytes, Postgres data, Redis data, Caddy state

横向扩展目标

关键决策记录

本轮建议重点评审

1. Link 是否足以成为 live、static、evidence、design doc 的统一产品对象？
2. 访问策略只挂 Link，是否需要近期支持 revision-specific audience？
3. 两阶段 publish/promote 对 Agent 高频发布是否需要 cancel 或 manual promote？
4. 新 Revision 不复制评论，只显示 prior unresolved count，是否符合设计评审习惯？
5. 从 LocalStore 切换对象存储前，哪些 SLO、容量或恢复指标应作为硬触发器？