进阶玩法

团队 Vault 协议

Pro 版才有 — 多人协作、分片同步、冲突解决、权限分级。

架构概览

团队 Vault 不走 Dropbox / iCloud 这类“同步整个目录”的路子 — 而是自架一个 CRDT hub，客户端订阅它感兴趣的分片。这样既能保证不冲突地多人编辑同一段文字，又能让大 Vault（10GB+）只同步活跃部分。

Hub 是个无状态的协调层：它转发 op、持久化历史、做 ACL。真正的数据格式还是 Markdown + 附件 + .kitable 数据表 — 即使 hub 挂了，客户端的 Vault 仍是完整、可读的本地文件。

这是一份典型的 local-first 设计：网络是优化项，不是依赖项。断网时所有人继续工作，重连之后自动 reconcile。

中心节点 = 你自架（CRDT 同步服务，Go 实现）
客户端 = 标准 Kition 桌面 / Headless
分片：按目录划分，高频改动单独同步管道
冲突：CRDT 自动合并；元数据冲突按时间戳 + 三方合并
离线：客户端持续可写，上线后自动 reconcile

权限模型

权限粒度到目录 + 角色。Role 是预定义的（owner / editor / commenter / viewer），也可以自定义。Hub 在 op 层校验 — 没权限的写入会被拒，不会污染其他客户端。

角色之间是继承的：自定义 role 可以 inherits: editor，再 override 具体路径。SSO 集成（OIDC / SAML）会把外部 group 自动映射到 role。

# /etc/kition-hub/acl.yaml
roles:
  engineer:
    inherits: editor
    paths:
      - "engineering/**": editor
      - "finance/**": viewer
  finance:
    inherits: editor
    paths:
      - "finance/**": editor
      - "engineering/**": none

users:
  - email: [email protected]
    role: engineer
  - email: [email protected]
    role: finance
  - email: [email protected]
    role: owner

groups:
  - oidc_claim: "groups"
    mapping:
      "eng-team": engineer
      "fin-team": finance
      "leads": owner

部署 hub

Hub 以 Docker compose 一键起。生产建议放在 VPC 内网，配合 reverse proxy（Caddy / nginx）做 TLS 与 SSO 拦截。Postgres 存历史，对象存储（S3 / R2 / MinIO）存大附件。

最小生产部署：1 个 hub 实例（2 vCPU / 4GB）+ 1 个 Postgres（managed 即可）+ 1 个 S3 兼容桶。50 人团队完全够用。

services:
  hub:
    image: ghcr.io/kition-ai/vault-hub:latest
    environment:
      DATABASE_URL: postgres://hub:secret@db/hub
      OBJECT_STORE: s3
      S3_BUCKET: kition-vault-prod
      S3_REGION: us-east-1
      ACL_PATH: /etc/kition-hub/acl.yaml
      OIDC_ISSUER: https://auth.acme.com
    volumes:
      - ./acl.yaml:/etc/kition-hub/acl.yaml:ro
    ports: ["7000:7000"]
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_USER: hub
      POSTGRES_DB: hub
    volumes: ["db:/var/lib/postgresql/data"]
volumes: { db: {} }

客户端连接

# Pair a desktop client to a hub vault
kition vault join \
  --hub https://vault.acme.com \
  --vault team-eng \
  --as [email protected]

# Force a full resync
kition vault sync --vault team-eng --full

# Inspect sync state
kition vault status --vault team-eng

# List shards the client is subscribed to
kition vault shards --vault team-eng

# Subscribe to an additional shard
kition vault shards add --vault team-eng "design/**"

同步协议细节

协议是 WebSocket 之上的二进制帧 — 帧分四类：ops（CRDT 操作，含向量时钟）、presence（在线状态、光标位置）、request（拉历史 / 快照）、ack（持久化确认）。文本走 RGA CRDT，元数据走 LWW map，附件走内容寻址 blob 引用。

客户端断网时所有写入会进入本地 outbox；重连后按 op 序号回放。Hub 会按 user × shard 维护 vector clock，所以 reconcile 是增量的，不是“拉全量”。

运维要点

Postgres 每日逻辑备份 + 对象存储跨区复制
/metrics 暴露 op rate、活跃 client 数、合并失败计数
Hub 升级是滚动的 — 客户端会自动重连
审计日志：每个 op 含 user + 时间戳 + 路径，导出到 SIEM
禁用某个用户：改 acl.yaml 后 hub 自动 reload；现有连接立即降级
快照导出：kition-hub snapshot --vault team-eng --out /backup/
断开 hub 后客户端仍可读写本地 Vault — 这是 local-first 的保险

← 返回帮助中心更多进阶玩法 →