[Feature] 通过 Cloudflare Tunnel 进行设备间同步

[zerob13]

[Feature] 通过 Cloudflare Tunnel 进行设备间同步

需求

一台 DeepChat（主机，设备 A）通过用户自己的 Cloudflare Tunnel 暴露同步端点，得到一个公网
HTTPS 地址；主机签发配对令牌，其他设备（B、C、D）用这个地址 + 令牌与 A 同步数据。

拓扑是星型：其他设备只和主机通信，设备之间不直连。

为什么需要

• 现在的同步必须依赖 S3 兼容对象存储（R2 / S3 / MinIO / B2）。有些用户不愿把数据放进第三方
  bucket，但自己有域名，而且已经在用 Cloudflare Tunnel 暴露其他自建服务。
• CGNAT 用户（家宽常见）没法做端口映射，局域网直连也不通。
• 现在流程是全手动的：备份 → 上传 → 换设备 → 下载 → 导入。有了主机之后，其他设备可以按需或
  定时拉取。

目标

1. 主机模式 — 通过用户自管的 Cloudflare Tunnel 暴露同步端点，不需要入站端口，不受 CGNAT
   限制。
2. 配对 — 主机展示一个短时效配对码（含二维码），其他设备用配对码换取自己的设备令牌；主机
   可以随时查看、重命名、吊销设备。
3. 同步 — 其他设备可以从主机拉取数据，也可以把自己的数据推给主机，复用现有备份/导入流程，
   语义与现在保持一致。
4. 状态可见 — 隧道状态、上次同步时间、进度、错误提示都放在「设置 → 数据」页。
5. 安全 — 每个请求都要鉴权；Cloudflare 提供 TLS；可选 Cloudflare Access service token；
   可选端到端载荷加密。

非目标

• 不做 DeepChat 官方中继，不做多租户账号体系。
• 主机离线时不排队、不转发（其他设备只能等待或跳过）。
• 不自动操作用户的 Cloudflare 账号。
• 不替代现有的 S3/R2 云备份。
• 第一阶段不做并发编辑合并（见「已知限制」）。

实现思路

      设备 A（主机）                                    Cloudflare 边缘
  ┌───────────────────────┐                        ┌──────────────────────┐
  │ DeepChat              │  cloudflared           │  https://sync.       │
  │  同步端点  ───────────┼──（仅出站连接）────────┼──example.com         │
  │  unix:<sock> 或       │                        │  TLS + 可选          │
  │  127.0.0.1:<port>     │                        │  Access 策略         │
  │  令牌鉴权 + 审计       │                        └──────────┬───────────┘
  └───────────────────────┘                                   │
                              ┌───────────────────────────────┼───────────────────────────────┐
                              │                               │                               │
                        设备 B（从设备）                 设备 C（从设备）                 设备 D（从设备）
                        拉取 / 推送                      拉取 / 推送                      拉取 / 推送

流程：

1. 主机打开「作为同步主机」（默认关闭），填入自己的隧道域名。
2. 主机生成配对码，内容包含域名、主机公钥指纹和一次性密钥。
3. 其他设备通过隧道连接，用配对码换取本机专属令牌；主机只保存令牌哈希。
4. 其他设备本地保存 {hostUrl, deviceId, token}，令牌用 safeStorage 保护。
5. 其他设备拉取主机快照，或把自己的数据推给主机；每个请求都鉴权并记录审计。

建议的接口面（除 handshake 外都需要鉴权）：

接口	用途
GET /sync/v1/handshake	协议/应用/数据库版本、能力、加密方式
POST /sync/v1/pair	配对码换取设备令牌
GET /sync/v1/status	快照 id、大小、哈希、数据库版本
GET /sync/v1/snapshot	流式下载备份包，支持断点续传
POST /sync/v1/push	把本机备份包推给主机导入
GET /sync/v1/events	数据变更通知（SSE / 长轮询）

传输层说明：

• 同步端点本身不需要监听 TCP 端口：cloudflared 支持 service: unix:/path/to.sock
  （文档），
  所以 macOS/Linux 上可以直接复用应用已有的「HTTP over Unix socket」方式。
• Windows 上命名管道不能作为 cloudflared 的 origin，因此 Windows 主机需要一个只绑定回环的
  监听（127.0.0.1:<port>，绝不能是 0.0.0.0）。这一点需要决策，见「待定问题」。

Cloudflare 侧配置（用户操作）

要拿到固定域名，需要一个已接入 Cloudflare 的域名（免费套餐即可）。没有域名只能用 Quick
Tunnel（随机 *.trycloudflare.com、无 SLA、官方定位是试验用途）。

cloudflared tunnel login
cloudflared tunnel create deepchat-sync
cloudflared tunnel route dns deepchat-sync sync.example.com
cloudflared tunnel run deepchat-sync

# ~/.cloudflared/config.yml
tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef
credentials-file: /Users/me/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json
ingress:
  - hostname: sync.example.com
    service: unix:/Users/me/Library/Application Support/DeepChat/sync.sock
  # Windows 主机改用回环监听（端口由实现确定）
  #   service: http://127.0.0.1:<port>
  - service: http_status:404

在应用令牌之外，可以再叠加 Cloudflare Access service token 作为机器间访问控制（Access 策略需
要求携带该令牌）：

CF-Access-Client-Id: <id>.access
CF-Access-Client-Secret: <secret>

本地调试可临时用 Quick Tunnel：cloudflared tunnel --url http://127.0.0.1:<port>。

同步哪些数据（以及哪些不同步）

第一阶段直接复用现有备份流程：agent.db 加 app-settings.json、custom_prompts.json、
system_prompts.json、mcp-settings.json、manifest.json；导入方式仍是 increment（只插入
缺失行）与 overwrite（整库替换）。

现有流程本身的限制，本次需求并不解决：

• 修改和删除不会传播，increment 只插入缺失的行。
• 每次都是整库传输，没有增量。
• 机器本地相关配置（cloudSyncSecret、agentCommandShell）按设计不参与同步。
• 记忆的向量数据不在数据库里，接收端需要重新生成。

所以 tunnel 主要解决的是「不依赖第三方 bucket」。真正让同步又快又不丢数据（增量、删除标记、
冲突处理）是后续工作，需要提前说清楚，避免让人以为加了 tunnel 同步体验就变好了。

安全基线

• 默认关闭，开启需要显式确认并给出风险提示。
• 只绑定 Unix socket、命名管道或 127.0.0.1，绝不监听 0.0.0.0。
• 设备令牌按设备签发：只存哈希、限定作用域、可设置有效期、可即时吊销；配对码一次性、短时效、
  限速。
• 请求体积上限、按设备限速、两端都做路径校验。
• Provider API Key 等凭据默认不参与同步。
• 审计日志记录设备、方法、字节数、结果，不记录令牌和载荷内容。

待定问题

1. Windows 主机：允许仅回环监听，还是第一阶段主机模式只支持 macOS/Linux？
2. cloudflared 由应用托管（启动/监控/升级），还是只做「用户自己跑隧道」？应用托管要处理三个
   平台的打包与签名；cloudflared 本身是 Apache-2.0。
3. 默认同步范围：会话、消息、设置是基本盘；Provider 凭据、Skills、MCP、知识库文件、记忆，哪些
   需要用户显式勾选？
4. 使用公网域名时，Cloudflare Access service token 是强制要求，还是仅在界面上强烈建议？

验收标准

• 两台设备完成配对，能互相拉取与推送，increment 导入不丢数据、不产生重复会话。
• 传输中途断开后可以续传，不损坏数据、不产生半成品导入。
• 令牌被吊销或过期后立即拒绝；任何请求在校验失败时都不会返回 200。
• 关闭该功能后不留监听端口、不留残留的 cloudflared 进程。
• 凭据类数据（Provider Key、隧道凭据、机器本地值）可证明不存在于任何传输内容中。

参考文档

Cloudflare：

• Tunnel 概览 — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/
• 服务类型（unix: / unix+tls:）— https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/protocols/
• Published applications — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/
• 配置文件 — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/local-management/configuration-file/
• 创建隧道（控制台方式，connector token）— https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/
• Quick Tunnel（仅调试）— https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/
• 私有网络（warp-routing，不暴露公网域名）— https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/
• Access service token — https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/
• cloudflared 下载 — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/

相关代码：src/main/sync/、src/shared/contracts/routes/sync.routes.ts、
src/renderer/settings/components/DataSettings.vue、src/main/cli/server.ts、
docs/architecture/local-control-plane/spec.md。

[zerob13]

[Feature] Device-to-device sync over a Cloudflare Tunnel

What I want

One DeepChat instance (host, device A) exposes a sync endpoint through the user's own Cloudflare
Tunnel and gets a public HTTPS address. The host generates a pairing token. Other devices (B, C, D)
use that address plus token to sync their data with A.

Star topology: peers only talk to the host, never to each other.

Why

• Sync today requires an S3-compatible bucket (R2 / S3 / MinIO / B2). Some users don't want their
  data in a third-party bucket, but they do own a domain and already run Cloudflare Tunnel.
• Devices behind CGNAT (common on home broadband) cannot expose a LAN port.
• Sync is manual today: backup → upload → switch device → download → import. With a host, a peer can
  just pull on demand or on a schedule.

Goals

1. Host mode — publish a sync endpoint through a user-managed Cloudflare Tunnel. No inbound
   port, works behind CGNAT.
2. Pairing — the host shows a short-lived code (and QR); a peer exchanges it for its own device
   token. The host can list, rename and revoke devices at any time.
3. Sync — a peer can pull host data and push its own, reusing the existing backup / import
   pipeline so behavior stays consistent with today.
4. Visible state — tunnel status, last sync, progress and clear errors in Settings → Data.
5. Security — authentication on every request, TLS from Cloudflare, optional Cloudflare Access
   service token, optional end-to-end encryption of the payload.

Non-goals

• No DeepChat-hosted relay, no multi-tenant accounts.
• No queueing while the host is offline (peers wait or skip).
• No automatic setup of the user's Cloudflare account.
• Does not replace the existing S3/R2 cloud backup.
• Phase 1 does not merge concurrent edits (see Known limits).

How it works

      Device A (host)                               Cloudflare edge
  ┌───────────────────────┐                     ┌──────────────────────┐
  │ DeepChat              │  cloudflared        │  https://sync.       │
  │  Sync endpoint  ──────┼──(outbound only)────┼──example.com         │
  │  unix:<sock> or       │                     │  TLS + optional      │
  │  127.0.0.1:<port>     │                     │  Access policy       │
  │  token + audit        │                     └──────────┬───────────┘
  └───────────────────────┘                                │
                              ┌────────────────────────────┼────────────────────────────┐
                              │                            │                            │
                        Device B (peer)              Device C (peer)              Device D (peer)
                        pull / push                  pull / push                  pull / push

Flow:

1. Host enables "sync host" (off by default) and points the app at its tunnel hostname.
2. Host generates a pairing code containing hostname, host key fingerprint and a one-time secret.
3. Peer connects over the tunnel, exchanges the code for a per-device token; host stores only a hash.
4. Peer stores {hostUrl, deviceId, token} locally (token protected with safeStorage).
5. Peer pulls the host snapshot and/or pushes its own; every request is authenticated and audited.

Suggested endpoint surface (authenticated except handshake):

Endpoint	Purpose
GET /sync/v1/handshake	protocol / app / schema version, capabilities, encryption mode
POST /sync/v1/pair	pairing code → device token
GET /sync/v1/status	snapshot id, size, hash, schema version
GET /sync/v1/snapshot	stream the backup archive, resumable
POST /sync/v1/push	send this device's archive to the host for import
GET /sync/v1/events	change notifications (SSE / long poll)

Transport notes:

• The origin does not need a TCP port: cloudflared supports service: unix:/path/to.sock
  (docs),
  so on macOS/Linux the app can reuse the same HTTP-over-unix-socket pattern it already uses
  locally.
• Windows: named pipes cannot be a cloudflared origin, so a Windows host needs a loopback-only
  listener (127.0.0.1:<port>, never 0.0.0.0). This needs a decision — see Open questions.

Cloudflare setup (user side)

Requires a domain onboarded to Cloudflare for a stable hostname. Without a domain only Quick
Tunnels exist (random *.trycloudflare.com, no SLA, explicitly for experimentation).

cloudflared tunnel login
cloudflared tunnel create deepchat-sync
cloudflared tunnel route dns deepchat-sync sync.example.com
cloudflared tunnel run deepchat-sync

# ~/.cloudflared/config.yml
tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef
credentials-file: /Users/me/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json
ingress:
  - hostname: sync.example.com
    service: unix:/Users/me/Library/Application Support/DeepChat/sync.sock
  # Windows host: use the loopback listener instead (port TBD by implementation)
  #   service: http://127.0.0.1:<port>
  - service: http_status:404

Machine-to-machine gate with a Cloudflare Access service token (peer sends these headers; the Access
policy must require the token):

CF-Access-Client-Id: <id>.access
CF-Access-Client-Secret: <secret>

Quick tunnel for local testing only: cloudflared tunnel --url http://127.0.0.1:<port>.

What syncs (and what doesn't)

Phase 1 reuses the current backup pipeline unchanged: agent.db plus app-settings.json,
custom_prompts.json, system_prompts.json, mcp-settings.json and manifest.json, with the
existing increment (insert missing rows) and overwrite (replace the whole DB) import modes.

Known limits of the current pipeline, which this request does not fix:

• Edits and deletes do not propagate; increment only inserts missing rows.
• Whole-database transfer each time, no delta.
• Machine-local values (cloudSyncSecret, agentCommandShell) never transfer, by design.
• Memory embeddings live outside the database and must be regenerated on the peer.

So the tunnel mainly removes the third-party bucket dependency. Making sync actually fast and
lossless (deltas, tombstones, conflict handling) is follow-up work — worth calling out so nobody
expects the tunnel alone to fix sync quality.

Security baseline

• Off by default; enabling it is an explicit, warned opt-in.
• Bind to a Unix socket, named pipe, or 127.0.0.1 only — never 0.0.0.0.
• Per-device tokens: hashed at rest, scoped, expiring, revocable; pairing codes single-use with a
  short TTL and rate limiting.
• Size caps, per-device rate limits, and path validation on both ends.
• Provider API keys and other credentials are excluded from sync by default.
• Audit log (device, method, bytes, result) with no tokens or payload contents.

Open questions

1. Windows host: allow the loopback-only listener, or restrict host mode to macOS/Linux in v1?
2. Should the app manage cloudflared (spawn / monitor / update) or stay "bring your own tunnel"?
   The app-managed path needs release and signing work on three platforms; cloudflared itself is
   Apache-2.0.
3. Default sync scope: sessions, messages and settings at minimum. Provider credentials, skills, MCP
   servers, knowledge files, memories — which ones opt-in?
4. Is a Cloudflare Access service token required whenever a public hostname is used, or only
   recommended with a UI warning?

Acceptance criteria

• Two devices complete pairing, then pull and push with increment import; no data loss and no
  duplicate sessions on the receiving side.
• A transfer interrupted mid-way resumes without corruption or partial import.
• A revoked or expired token is rejected immediately; no request returns 200 without auth.
• Disabling the feature leaves no listener and no orphaned cloudflared process behind.
• Secrets (provider keys, tunnel credentials, machine-local values) are provably absent from every
  transferred payload.

References

Cloudflare:

• Tunnel overview — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/
• Service types (unix: / unix+tls:) — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/protocols/
• Published applications — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/
• Configuration file — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/local-management/configuration-file/
• Create a tunnel (dashboard, connector token) — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/
• Quick Tunnels (dev only) — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/
• Private network route (warp-routing, no public hostname) — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/
• Access service tokens — https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/
• cloudflared downloads — https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/

Relevant code: src/main/sync/, src/shared/contracts/routes/sync.routes.ts,
src/renderer/settings/components/DataSettings.vue, src/main/cli/server.ts,
docs/architecture/local-control-plane/spec.md.

[modelpath-dev]

Using Cloudflare Tunnel for device sync sounds like a solid idea, especially for users who want to avoid third-party storage. The star topology approach should simplify communication.