Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

57.3 KB
Raw Blame

自建中转服务:第一期方案

状态:方案 v2(2026-10-28)。§11 第 1 步「内核」已实现(packages/device-link-relay,见 §15 实施记录), 其余步骤未开始。§13 第 1、2 条按建议执行:方式 A 正式开放前先做设备签名防冒充;服务器上的 Node 由 Cindy 本机校验后上传。 v1 以 Tailscale 为主路径,已废弃:Tailscale 的 iOS App 不在中国大陆 App Store (tailscale/tailscale#19625),注册还需要海外账号。 范围:本仓(Desktop、Mobile、共享 packages)。不改 cindy-server,官方中转的行为不变。 代码位置基于本仓 main(2026-10-28)调研,实施前以当时代码为准。 动手前按 AGENTS.md 读以下文档:

  • docs/dev-rules/protocol-compatibility.md
  • docs/dev-rules/remote-and-mobile-adaptation.md
  • docs/dev-rules/credentials-and-local-storage.md
  • docs/dev-rules/mobile-development.md(冷更边界)
  • docs/dev-rules/architecture-invariants.md
  • docs/dev-rules/verified-downloads.md
  • docs/product-rules/input-handoff.md(sudo 密码)
  • docs/design-rules/DESIGN.md
  • docs/dev-rules/engineering-conventions.md §3.2

0. 一句话

中转服务只有一个内核(packages/device-link-relay),有两种运行方式:

A. 部署到公网服务器 B. 在这台 Cindy 上直接开启
适合 设备分布在不同网络,需要从公网访问 设备之间网络本来就通,或用户自己能打通
用户提供 一台服务器的 SSH 配置,并在云控制台放行端口 让其他设备能访问这台电脑的网络条件
Cindy 负责 安装、配置、申请证书、注册为系统服务、升级、卸载 启动内核、显示地址、检测连通、提醒保持唤醒
内核运行方式 服务器上用 Node 运行,由 systemd 托管 Cindy 内的独立进程(utilityProcess)

两种方式共用:

  • 同一份中转程序和协议。
  • 同一套加入流程:二维码或链接发起,主人确认,设备拿到中转专用凭证。
  • 同一个设置页,同一套客户端切换逻辑。

1. 原则与边界

  • 一个内核。 A 和 B 只在三件事上不同:怎么启动、证书从哪里来、谁来管理。 协议、认证、加入、设备管理、媒体全部由内核实现,两种方式不能各写一份。
  • 网络连通的责任。
    • A:由服务器的公网地址保证。
    • B:由用户自己保证。同一局域网、路由器端口映射、内网穿透、组网工具都可以。 Cindy 只做检测和提示,不安装、不配置任何网络软件。
  • 手机只能用受信任的 https/wss 连接。 Android 正式包只允许明文访问 127.0.0.1,放开要改原生配置,也就是冷更。 所以手机加入时,中转必须有受信任的证书(见 §2.2)。电脑之间不受这个限制。
  • 不碰 Cindy 账号凭证。 Cindy 账号 token 不会发给自建中转;中转返回 401 也不会让 Cindy 账号登出(§5.3)。
  • 官方服务不变。 官方中转和服务端都不改。自建模式只替换设备之间的中转,登录、模型等服务照旧走官方。

2. 内核:packages/device-link-relay

2.1 功能

起点是 scripts/device-link/relayFixture.ts(142 行的测试用中转)。它已经具备握手、presence 广播、按目标转发、 DEVICE_OFFLINE/REMOTE_DISABLED、覆写 src、4409 顶替。在此基础上需要补:

  • 设备协议(§6.1):
    • 凭证认证。
    • 帧校验:单帧上限 2 MiB,超出回 PAYLOAD_TOO_LARGE,不断开连接。
    • 检查目标设备的 remoteControlEnabled。
    • 跨账号的 sharedTask/providerShare 帧一律拒绝。
    • 出站缓冲上限,以及 1013 拥塞关闭。
  • REST(§6.2):设备列表、改名、移除;媒体上传与下载。
  • 加入与管理(§6.3):一次性加入码、加入申请、主人审批、移除设备、状态查询。
  • 持久化:
    • 设备档案(只存凭证哈希)。
    • 加入申请。
    • 媒体文件(24 小时后清理,有总量上限)。
    • 证书与 ACME 账号。
    • 配置。
  • 证书:见 §2.2。
  • hello-ack 的 capabilities 为空,即不声明 notify、shared-task-v2、provider-share-v1。
  • 单实例内存路由,不需要 Redis。

依赖只有 @cindy/device-link-protocol、ws 和一个 ACME 客户端,不依赖 Desktop(architecture-invariants.md §1)。 最终打成一个单文件 bundle:

  • 方式 A:服务器上运行 node relay.mjs --data <目录>。
  • 方式 B:Desktop 用 utilityProcess 运行同一个文件。参考 localDb/dbSlimmingWorkerClient.ts 等现有用法;进程崩溃不影响 Cindy 主进程。

2.2 证书:三种方式

方式 做法 手机能否加入 典型场景
自动证书 内核用 ACME 向 Let's Encrypt 申请并自动续期。
有域名时用域名证书。
没有域名时用 IP 地址证书:2026-01-15 正式提供,有效期约 6 天,需要自动续期(公告)。
实际实现使用 http-01,公网 80 提供验证,443 提供 HTTPS
能 A 的默认方式;B 中有公网 IP 的电脑
前置代理提供 内核只在 127.0.0.1 上明文监听。
TLS 由用户自己的 nginx、Caddy、frp、内网穿透服务或 Tailscale serve 等提供
取决于前置代理的证书是否受信任 B 的常见情况;服务器上 443 已被别的网站占用时
自签名 + 指纹固定 内核生成自签名证书,加入链接里附带证书指纹,电脑端按指纹校验 不能(需要原生改动),界面直接说明 B,只连自己的几台电脑

不提供在网络上明文监听(ws:// 对外)的方式:否则加入码和凭证会被同一网段的人截获。

IP 证书的注意点:

  • 有效期只有约 6 天,内核大约每 3 天续期一次。续期失败时,管理状态里显示证书剩余时间,并提醒主人。
  • 申请 IP 证书使用 ACME profile(shortlived)与 http-01,实现见 packages/device-link-relay/src/acme.ts。

2.3 管理:主人凭证

  • 开启中转(B)或部署中转(A)的那台电脑就是主人电脑。
    • 主人电脑在本机生成自己的设备凭证,交给内核的只有它的哈希;这份凭证同时带管理权限,不另发管理凭证。
    • A 方式下,这个哈希由 SSH 安装时写进服务器配置(relay init --owner-credential-hash)。
    • 所以两种方式的管理方式完全一样:主人电脑带着自己的凭证调用 §6.3 的管理接口。
  • 加入审批、移除设备、查看状态,都在主人电脑的设置页完成。
  • 主人电脑在显示加入二维码期间轮询待审批的申请,不需要新增协议帧。
  • 第一期只有一台主人电脑。以后要加第二台管理设备,再单独设计。

3. 方式 A:部署到公网服务器

入口:设置 → 远程连接 → 中转服务 → 部署到我的服务器。选择一台已配置的 SSH 主机,复用现有 SSH 主机配置与认证 (packages/maker-remote-ssh);没有就先添加。

支持范围:Linux x64 / arm64,与现有远程安装一致。

Cindy 自动完成的步骤(每一步在界面上显示进度):

  1. 探测服务器的系统、架构、是否为 root 或有 sudo 权限、443 端口是否被占用。
  2. 准备运行环境:复用自带 Node 的安装方式(bootstrap-script.ts 的 BUNDLED_NODE_INSTALL_SH, 安装到 ~/.xdt-server/<ver>/node/)。下载来源见 §13 第 2 条。
  3. 上传中转程序。同版本重复上传是幂等的,参考 file-service-installer.ts。
  4. 写入配置:端口、证书方式、域名(可选)、主人设备凭证的哈希。
  5. 注册为 systemd 服务:开机自启,崩溃自动重启。 以专用的低权限用户运行,只授予绑定低端口的能力(CAP_NET_BIND_SERVICE)。
  6. 系统防火墙(ufw、firewalld)开着时,征得用户同意后放行 443。
  7. 申请证书。
  8. 从本机检测能否连上。连不上时,按顺序提示:
    1. 去云服务器控制台的安全组放行 TCP 443。
    2. 检查服务器上的防火墙。
    3. 端口被占用时,改用前置代理方式。
  9. 完成,显示部署结果,不切换线路:是否改用这个中转由用户决定(完成页的「使用这条线路」或线路列表里的切换,都先确认);切换后再添加设备。 可以部署到多台服务器,一台服务器一个中转;部署到已有记录的服务器就是重新部署那一个(2026-10-30,见 §15.5)。

权限:

  • 安装 systemd 服务和放行防火墙需要 root 或 sudo。
  • SSH 用户是 root,或者有免密 sudo,就能全自动完成。
  • 需要输入 sudo 密码时,走代输入:密码只交给执行命令的那个进程,不进模型、记录和日志(input-handoff.md)。
  • 没有 sudo 权限时,退回用户级运行:使用高位端口,证书只能用前置代理方式,并明确提示这些限制。

域名:

  • 可选。有域名就填,内核申请域名证书。
  • 服务器在中国大陆时,用域名访问 80/443 需要 ICP 备案。
  • 不填域名就用 IP 证书,不涉及域名备案。各家云厂商会不会拦截按 IP 访问,需要实测(§12)。

升级与卸载:

  • 主人电脑连接中转时会读到中转版本;版本落后时提示「更新中转」,重新上传并重启。
  • 卸载:停止服务,删除程序。中转数据(设备档案、媒体)可选保留或一并删除。

4. 方式 B:在这台 Cindy 上直接开启

入口:设置 → 远程连接 → 中转服务 → 在这台电脑上开启。

用户需要设置的:

  • 监听端口。
  • 监听范围:仅本机(配合前置代理)或所有网络。
  • 证书方式(§2.2)。
  • 对外地址:其他设备用来连接的地址,会写进加入链接。

Cindy 负责的:

  • 用 utilityProcess 启动内核。崩溃后自动重启,次数有上限。
  • 本机作为一台设备连接自己的中转(127.0.0.1)。
  • 列出本机的局域网地址,方便用户填写对外地址。
  • 从本机检测对外地址能否访问。受网络环境限制(比如很多路由器不支持从内网访问自己的公网地址),结果只作参考。
  • 提醒保持唤醒,并自动打开现有的「保持唤醒」设置;笔记本合盖仍会休眠,要写清楚。
  • 监听范围选「所有网络」时,macOS 和 Windows 会弹出系统防火墙确认框;Cindy 先说明原因,再触发。

用户自己负责的:其他设备能访问对外地址。界面用一句话说明,并举例:

  • 同一局域网。
  • 路由器端口映射。
  • 内网穿透。
  • 组网工具(如 Tailscale、ZeroTier)。

Cindy 不安装、不配置这些工具。

手机:只有在「自动证书」或「受信任的前置代理证书」下才能加入;选了自签名时,加入页直接说明手机不支持。

5. 加入与切换(A、B 共用)

5.1 加入

加入链接:<scheme>://relay/join?u=<对外地址>&c=<加入码>[&k=<证书指纹>]

  • scheme 跟随构建区域:cindy、cindycn 或 cindydev。
  • k 只在自签名方式下出现。

另一台电脑:

  1. 粘贴链接,或直接点链接让 Cindy 打开。
  2. 先请求 relay/info,确认地址可达、对方确实是 Cindy 中转;自签名时校验证书指纹。
  3. 发出加入申请。主人电脑弹出确认框,显示设备名、平台和 4 位核对码。
  4. 主人同意后,设备拿到凭证,自动切换到该中转。

手机:

  1. 用系统相机扫二维码,打开 Cindy 的加入页,复用 apps/mobile/app/+native-intent.ts 的深链。 链接里的加入码不进路由状态,也不进诊断信息,处理方式与共享任务邀请相同。
  2. 后续步骤和电脑一样。

App 内不加扫码组件:加一个会改变原生指纹,需要冷更。

核对码:与供应商分享的 Pairing Code 是同一类东西,只用来核对,不参与鉴权。可以沿用这个术语,需要扩充术语表的说明。

5.2 身份与凭证

  • 中转凭证:32 字节随机数,只能用来连这一个中转;中转端只存 SHA-256。
    • Desktop 存在 safeStorage,参照 secrets/providerSecretStore.ts 里只在 main 进程读写的键。
    • Mobile 存在 expo-secure-store,用 WHEN_UNLOCKED_THIS_DEVICE_ONLY。
  • 握手与 REST 请求头:Authorization: CindyRelay <凭证>。DeviceLinkClient 已有 authorizationScheme (packages/device-link/src/client.ts:262),只需新增一种。
  • deviceId:上报与官方登录相同的设备 ID,hello-ack.deviceId 原样返回。 这样本机按设备 ID 保存的状态在切换后依然有效,包括撤销记录、设备名、远程任务绑定。
  • userId:中转属于主人电脑登录的 Cindy 账号。账号不一致的设备直接拒绝,跨账号场景走共享任务或供应商分享。 这只防误操作,真正的准入关口是主人确认。

5.3 客户端切换

设置按账号保存:{mode:'official'} | {mode:'self-hosted', relayId, name, baseUrl, role:'owner'|'member', certPin?}, 凭证另存安全存储。

Desktop:

  • 地址与凭证统一经新增的 device-link/relayRouting.ts:

    • deviceLinkApiBase()、wsUrl()、getToken(main/device-link/index.ts:203-206、681-684、715)改走它。
    • remote-desktop/iceConfig.ts 也改走它。
    • 不在 getClientEndpoint 做全局覆盖:它还负责区域切换和更新链,影响范围太大。
  • 自建模式下暂停跨账号模块:sharedTaskApi.ts、providerShareApi.ts、providerShareGuest.ts、providerShareHost.ts 不发请求; 对应入口显示「使用自建中转时不可用」。

  • 鉴权失败不能影响官方登录。 现有两条路径会碰官方登录:

    • REST 返回 401 时可能登出账号(main/serverApiClient.ts:142-171)。
    • WS 握手 401 会强制刷新官方 token(index.ts:618-654)。

    自建模式下这两条路径都不能碰官方登录。此时 401 或 4410 只表示中转凭证失效,界面提示重新加入,或切回官方中转。

  • 证书校验:自签名方式下,WebSocket 和 REST 都按指纹校验,不信任系统根证书以外的任何证书。

  • 代理:设置了代理时,device-link 的 WebSocket 会走代理(见 dnsFallbackLookup.ts 顶注)。 自建中转的地址是私有网段或组网地址时,要绕开代理,实测确认。

Mobile:

  • DEVICE_LINK_API_BASE_URL(src/config/env.ts:272)会被三个区域函数改写;新增覆盖值,在它们之后重新应用。
  • src/device-link/DeviceLinkContext.tsx:1005 的 getWsUrl / getToken 改走新的 relayRouting。
  • apiFetch(src/auth/AuthContext.tsx:3309)会给任何 baseUrl 附上 Cindy token。 自建模式下改用中转凭证,确保官方 token 不会发到自建中转。
  • 推送注册(src/notifications/pushNotifications.ts:190)在自建模式下跳过。

状态与退出:

  • 中转离线时提示,并提供「切回官方中转」。不会自动切回官方。
  • 主人可以移除设备:凭证立即失效,对方收到 4410 断开,并看到提示。
  • 主人停用中转(B)或卸载中转(A)前,先用 4410 断开所有设备;各设备提示「中转已停用」,可一键切回官方中转。

6. 接口

6.1 WebSocket /api/device-link/ws

只实现现有客户端已经在用的行为(依据:packages/device-link-protocol/src/protocol.ts 与 packages/device-link/src/client.ts):

  • 握手:hello 必须是第一帧。中转在 15 秒内回 hello-ack:{serverProtocolVersion:1, deviceId, userId, capabilities:[]}。
  • 心跳:收到 ping 回 pong,pong 不带 payload。
  • presence:收到 presence-set 后更新状态,并广播完整的 PresenceSnapshot。 初始设备列表靠 /devices 获取,与官方行为一致。
  • 转发:转发 ROUTED_KINDS 并回填 src。
    • 目标设备不在线,回 DEVICE_OFFLINE。
    • CONTROL_KINDS 的目标关闭了「允许被控」,回 REMOTE_DISABLED。
    • relay-error 带回原帧的 id 和 dst。
  • 关闭码:
关闭码 含义
4409 同一设备有新连接,顶替旧连接
4429 连接数超限
4400 版本不符
4410 设备被移除,或中转已停用;客户端停止重连
1013 拥塞

6.2 REST

所有接口以 /api/device-link 为前缀,请求头为 Authorization: CindyRelay。

接口 第一期
GET /devices、PATCH /devices/:id、DELETE /devices/:id 实现。删除设备等于吊销凭证,并用 4410 断开该设备
POST /media/presign-put、POST /media/presign-get、DELETE /media 实现。上传和下载地址都指向中转自身,带签名、短期有效;单文件与总量的上限,实现时对齐客户端现有的上传限制
GET /ice-servers 不实现,返回 404。远程桌面退回公共 STUN(remoteDesktopIceConfig.ts:99-136)
PUT /push-token、DELETE /push-token 返回 204,不保存
/provider-shares* 返回空列表,只作兜底
/shared-tasks*、/identities* 不实现

6.3 加入与管理(只在自建中转上存在)

公开接口(不需要凭证):

  • GET /api/device-link/relay/info → {relayId, name, protocolVersion:1, relayVersion, features:['pairing-v1']}。不返回任何账号信息。
  • POST /api/device-link/relay/pair → 请求 {code, deviceId, deviceName, platform, appVersion, accountUserId}, 返回 {requestId, pollToken, verifyCode}。
  • GET /api/device-link/relay/pair/:requestId?wait=<秒,≤25>:长轮询,请求头 X-Cindy-Relay-Poll-Token 带提交时拿到的轮询口令。 结果为 pending、approved {credential, deviceId}、rejected 或 expired;凭证只返回一次,设备在取回凭证时才写入档案。

管理接口(需要主人设备的凭证):

  • POST /relay/admin/join-codes:生成加入码。一次性、10 分钟有效,用后作废。
  • GET /relay/admin/pair-requests:查看待审批申请。
  • POST /relay/admin/pair-requests/:id/approve、.../reject:同意或拒绝。
  • GET /relay/admin/status:版本、证书到期时间、在线设备、媒体占用。

限制:

  • 同时待处理的申请最多 5 个。
  • 按来源限速。
  • 加入码、凭证、签名地址都不写进日志。

7. 自建模式下的功能边界

功能 第一期
远程查看和控制任务、实时输出、审批 可用
设备列表、改名、移除 可用
远程文件、图片、语音 可用
直连(direct-link-v1) 可用,信令经中转透传;只用本机地址候选,能否直连取决于网络环境
远程桌面 可用。没有 TURN,退回公共 STUN
手机系统推送 不可用:推送凭据绑定在官方 App 上
供应商分享、共享任务 不可用:它们跨账号,界面上明确说明
登录、模型、插件市场等 不受影响,仍然使用官方服务

8. 安全

  • 最大风险:冒充。
    • 方式 A 天然在公网上;方式 B 也可能被用户映射到公网。
    • 中转负责回填 src,中转所在机器一旦被入侵,攻击者就能冒充控制端,让被控电脑执行远程指令。
    • 建议在方式 A 正式开放前,先做设备签名防冒充(§13 第 1 条):
      • 主人电脑作为信任根,给每台通过审批的设备签发设备证书。
      • 主人公钥随加入二维码带到新设备,不经过中转。
      • 设备对每条消息签名,接收方验证签名并检查消息是否新鲜。
      • 内容加密可以放在下一期。
  • 凭证:只对这一个中转有效;客户端存在安全存储,中转只存哈希;设备被移除后立即失效。
  • 准入:三道关:加入码(能看到主人屏幕的人才拿得到)、主人确认、核对码。
  • 账号 token 不外发:Cindy 账号 token 不发往自建中转。Desktop 的 WS 与 REST、Mobile 的 apiFetch 都要覆盖,并补回归测试。
  • 服务器上的运行身份:专用低权限用户,只授予绑定低端口的能力;数据目录只有该用户可读写。
  • SSH 凭证与 sudo 密码:沿用现有 SSH 主机的凭证存储;sudo 密码只走代输入。
  • 媒体:用带签名的短期地址,过期清理。Desktop 侧的落盘目录登记到 credentials-and-local-storage.md 的路径表。
  • 日志:新增的日志行按 log-upload-and-redaction.md 的白名单规则评审。

9. 故障半径

按 remote-and-mobile-adaptation.md 的故障半径三问:

  • 中转不可达(服务器宕机、电脑休眠、网络断开):
    • 所有设备按现有退避重连同一个中转;不自动切回官方,界面提示并提供手动切回。
    • 方式 B 中转进程崩溃时,只重启中转进程,不影响 Cindy 主进程和本机任务。
  • 单台设备被移除:只影响这一台(4410),其他设备不受影响。
  • 证书过期(续期失败):所有设备连不上。主人电脑提前提醒,证书剩余时间显示在管理状态里。
  • 切换中转:只重建本机的 device-link 连接,被远程控制的任务继续运行。
  • 多设备回归用例:两台控制端加一台被控端,移除其中一台控制端,断言另一台的在途请求与连接不受影响。

10. 兼容与发布

  • 协议:中转帧协议不变,仍是 v1。新增内容只存在于自建中转上:CindyRelay 认证方案、加入接口、管理接口。官方中转与服务端零改动。
  • 旧客户端:没有入口,不受影响;旧版手机无法加入,加入页提示升级。
  • 手机:深链、设置、地址覆盖、安全存储都是 JS 改动,可以热更。 不加相机扫码组件、ATS 或明文例外、本地网络权限文案;用 @expo/fingerprint 确认指纹不变。
  • Desktop:内核的 bundle 要随 Desktop 打包,供方式 B 使用;方式 A 上传的也是这个文件,两边版本天然一致。
  • 需要更新的规则文档:
    • protocol-compatibility.md
    • remote-and-mobile-adaptation.md
    • credentials-and-local-storage.md 路径表
    • 新增产品规则 docs/product-rules/self-hosted-relay.md,并在 AGENTS.md 加读取入口
    • i18n/glossary.json:登记新术语,状态为 proposed

11. 工作拆分(建议的 PR 顺序)

  1. 内核 packages/device-link-relay:协议、REST、加入与管理、媒体、持久化、三种证书方式。 用 scripts/device-link/interop.test.ts(设置 CINDY_TEST_RELAY_URL)跑通与现有客户端的互通测试。
  2. 客户端认证与路由:
    • @cindy/device-link 新增 CindyRelay 认证方案。
    • Desktop 的 relayRouting、鉴权失败不影响官方登录、证书指纹校验、跨账号模块暂停。
  3. 方式 B:Desktop 内置运行与设置界面;同时完成加入流程和主人审批界面。
  4. 方式 A:SSH 部署器(安装、systemd、证书、防火墙、检测、升级、卸载)。
  5. Mobile:加入深链与加入页、地址覆盖、凭证存储、设置项。
  6. 设备签名防冒充:如果确认要做。建议排在方式 A 正式开放之前。
  7. 文档与术语。

12. 验证

自动测试:

  • 内核单测:
    • 认证、路由、错误码。
    • 加入码:一次性、过期、限速。
    • 管理权限(只有主人设备)。
    • 媒体:签名与过期。
    • 证书:用本地 ACME 测试服务器(如 Pebble)验证申请与续期。
  • 用客户端互通测试跑通新内核。
  • 回归:官方 token 不会发往自建中转。
  • 回归:中转返回 401 不会让官方账号登出。
  • 回归:自签名指纹不匹配时拒绝连接。
  • 多设备故障半径用例(§9)。

测试遵守 engineering-conventions.md §3.2 的价值门槛与性能预算。

真机手动验证:

  • 方式 A:
    • 中国大陆云服务器(如阿里云、腾讯云),按 IP 访问并使用 IP 证书:确认按 IP 访问会不会被拦截,证书能否申请、续期。
    • 中国香港或海外服务器。
    • 有域名的服务器。
    • root 用户、需要输入 sudo 密码的用户、没有 sudo 权限的用户,各测一遍。
  • 方式 B:
    • 局域网 + 自签名,只连电脑。
    • 路由器端口映射 + 自动证书。
    • 前置代理(frp、nginx 各一种)。
  • 手机:iPhone、Android 通过 IP 证书和域名证书加入,验证远程任务、发图片、远程桌面。
  • 设置了代理的电脑能否连上中转。
  • 界面:Light 与 Dark 两种模式都要目检。

13. 待确认

  1. 方式 A 正式开放前,是否先做设备签名防冒充? 建议做(§8)。不做的话,第一期在界面上明确提示公网部署的风险。
  2. 服务器上 Node 从哪里下载? 现有安装器让服务器自己从 nodejs.org 下载,国内服务器可能很慢或下不到。 建议改为 Cindy 在本机按固定版本和哈希下载(verified-downloads.md),再经 SSH 上传。
  3. 界面上的名称:用「中转服务」,还是别的叫法?
  4. 谁可以移除设备:任何已加入的设备(与官方一致),还是只有主人电脑?
  5. 是否给 Agent 一个只读的中转状态工具?
  6. 方式 B 是否保留「检测到 Tailscale 时一键发布」? 建议第一期不做,只在说明文案里把它列为连通方式之一。

14. 后续阶段

  • 设备间内容加密(端到端),在设备签名的基础上加密钥协商。可参考插件授权 v3 的设备密钥,以及通讯录同步的加密中转。
  • 多台主人电脑。
  • 中转自带 TURN。
  • 可选的官方推送转发。
  • 自建模式下的供应商分享与共享任务(用户 2026-10-30 提出):卡住它们的不是官方证书,而是它们跨账号,成员关系和转发校验都在官方 device-link 服务端(provider-sharing-contract.md §2、§3),受邀者也连在官方中转上。可行做法是自建模式下这台电脑另外保持一条到官方的连接,只走带 providerShare / sharedTask 范围的帧,自己设备之间仍走自建中转;要改 device-link 的连接管理,单独设计。手机系统推送需要官方 App 的推送凭据,不在此列。
  • 公司内网场景:内网服务器 + 公司自己签发的证书。

15. 实施记录

15.1 第 1 步:内核(2026-10-28)

已完成:packages/device-link-relay

  • 线协议:与官方 relay 对齐的 v1 线协议(§6.1)。
  • REST:与官方同形的 REST(§6.2)。
  • 加入与管理:加入与管理接口(§6.3)。
  • 媒体:中转自带的媒体存储。
  • 持久化:设备档案的持久化。
  • 命令行:relay init / relay serve / relay --version。

与上文的差异(以此为准):

  • 主人凭证:主人设备的凭证同时带管理权限,不另发管理凭证(§2.3 已同步)。
  • 移除设备:主人可以移除任何成员,成员只能让自己退出,主人设备不能被移除。这一项回答了 §13 第 4 条。
  • 加入轮询:用提交申请时返回的轮询口令,不再复用加入码。
  • 凭证失效的错误码:REST 返回 401 RELAY_CREDENTIAL_INVALID,不用会触发 Desktop 刷新或登出官方账号的错误码。
  • 证书:本步只提供两种方式。
    • 明文 HTTP:默认只监听 127.0.0.1,用于本机自连、测试,以及由前置代理负责 TLS 的场景。
    • 用户自带证书文件:--tls-cert / --tls-key。
    • 自动证书(ACME / IP 证书)与自签名生成放到下一步内核 PR。 两者都要新增第三方依赖,需要单独评审。
  • 默认端口:独立运行时默认 47820。
  • 数据目录:relay-state.json 文件权限 0600,原子写入;媒体放在 media/ 下。

验证:

  • 单测:pnpm --filter @cindy/device-link-relay test,9 个用例,单文件约 1.5 秒。
    • 故意改坏「覆写 src」和「加入码作废」两处,对应用例都会失败。
  • 互通:pnpm --filter @cindy/device-link-relay run interop。
    • 正式 DeviceLinkClient 加上 Mobile 恢复核心,通过 CindyRelay 凭证连上中转。
    • 握手、补订阅、断线后自动重连都通过。
    • 控制端凭证由真实的加入流程取得。
  • 回归:pnpm test:device-link 10 个用例通过。

尚未做:

  • 客户端接入(§11 第 2 步起)。
  • 自动证书与自签名证书。
  • 打包成单文件 bundle:随方式 A / B 接入时一起做。

15.2 第 2 步:方式 B 与加入流程接入客户端(2026-10-28)

Desktop:

  • 设置 → 远程连接 → 「中转服务」:显示当前使用的中转,可以在这台电脑上开启中转,也可以加入别的中转或切回官方中转。
    • 开启中转时可以设置端口、允许谁连接(仅本机 / 所有网络)和对外地址。
    • 开启后可以「添加设备」:生成二维码和加入链接,在同一处审批申请(显示配对码)。
  • 中转由 Cindy 主进程运行(device-link/selfHostedRelayRuntime.ts)。
    • 开启后本机以主人身份连接 http://127.0.0.1:<端口>,并自动打开「保持电脑唤醒」。
    • 应用启动、登录后,按设置自动拉起中转;登出时停掉。
  • 路由:
    • device-link 的地址、认证方案与凭证都经零依赖的 selfHostedRelayRouting.ts 读取。
    • REST 统一走 deviceLinkApi.ts,覆盖设备列表、媒体预签名和远程桌面 ICE。
    • 自建中转返回 401 时不会刷新或登出 Cindy 账号,也不会轮换账号 token。
  • 切换中转复用切换区域时的重连流程(restartDeviceLinkForRelayChange)。

Mobile(纯 JS,不改原生配置):

  • 扫码打开 relay/join 深链,进入加入页:显示配对码,等待电脑那边同意,然后保存凭证并切换。
  • 设置里可以查看当前中转,并切回官方中转。
  • REST 发往自建中转时只带中转凭证,不带账号 token;推送注册跳过官方 device-link。

与上文的差异:

  • 方式 B 的中转目前运行在 Electron 主进程里,不是 utilityProcess:它是纯 Node 网络服务、负载很小,先保证可用;崩溃隔离留给后续步骤。
  • 4 位数字统一沿用术语表的「配对码 / Pairing code」,§2.2 与 §5.1 里写的「核对码」都按此理解。
  • 手机端的共享任务入口在自建模式下没有隐藏,打开会因中转不提供 /shared-tasks 而报错,后续再处理。

验证:

  • Desktop typecheck、Mobile typecheck 通过。
  • 以下测试通过:
    • @cindy/device-link-relay 11 例,其中新增「共享加入函数 + 真实中转」与「停用时成员收到 4410」。
    • @cindy/device-link 加入链接解析 8 例。
    • Desktop deviceLinkApi.test.ts:账号 token 不外发,中转 401 不登出。
    • mediaTransfer.test.ts、remoteControlDevicesDeepLink.test.tsx。
    • Mobile 相关 13 个文件。
  • 互通测试已改用与客户端相同的加入函数,通过。

未在真机或界面上走通:两台电脑加一部手机的完整体验需要用户实测,步骤见交付说明。

15.3 第 3 步:设备签名、一键部署到服务器、远程管理(2026-10-28)

设备签名(见 §16):

  • 共享协议:packages/device-link/src/selfHostedRelayAuth.ts,加密实现由宿主注入。
    • Desktop 与中转用 @cindy/device-link/node-relay-crypto(node:crypto)。
    • Mobile 用 @noble/curves / @noble/hashes 与 expo-crypto。
  • DeviceLinkClient 新增 frameAuth 选项,只有两处钩子:
    • sendEnvelope 给经中转转发的对端帧附上 auth;
    • handleMessage 在任何解码与分发之前核对签名。
    • 官方中转返回 null,wire 行为与旧版完全相同。
  • 中转:
    • relay-state.json 升到 schema 2,保存主人公钥与每台设备的证书;
    • 新增 GET /api/device-link/relay/certs;
    • 加入申请必须带公钥与配对证明,同意必须附主人签发、发给申请里那把公钥的证书;
    • 帧里的 auth 原样转发。
  • Desktop:
    • 主人密钥与设备签名密钥按中转 ID 存在 secrets/<中转ID>.enc(safeStorage 加密);
    • 审批时用加入链接里的配对秘密核对证明,对不上只能拒绝;
    • 电脑核对所有对端消息(selfHostedRelayFrameAuth.ts)。
  • Mobile:加入时生成签名密钥并核对证书;发出的对端消息都签名,收到的对端消息也在分发前核对(见 §16.4)。

一键部署到服务器(方式 A 的落地形态):

  • 内核新增自动证书(acme.ts、csr.ts、certificates.ts)。
    • 自己实现了最小 ACME 客户端(http-01)与 CSR 编码,没有引入第三方库。
    • 填 IP 时用 Let's Encrypt shortlived 配置申请 6 天有效的 IP 证书;填域名时用常规证书。
    • 剩余有效期不足 1/3 时自动续期,续期后热替换证书,不断开现有连接。
    • 证书状态写进数据目录的 status.json,部署方据此报告进度与失败原因。
  • relay serve --acme-identifier <IP或域名>:先在 80 端口提供验证,拿到证书后才开始提供 443。
    • 首次申请失败按 1 / 5 / 15 / 30 / 60 分钟退避重试(Let's Encrypt 对失败验证有限额)。
  • 单文件:packages/device-link-relay/build.mjs 打出 dist/relay.mjs(约 210 KB)。
    • 由 apps/desktop/scripts/build-remote-bundles.mjs 放进 resources/device-link-relay/,随安装包分发。
  • 部署器 apps/desktop/src/main/device-link/selfHostedRelayDeploy.ts:走「远程」里已配置的 SSH 主机。
    • 需要 root 或免密 sudo;没有就停下来提示,不索要密码。
    • 步骤:连接 → 检查系统和 80/443 端口 → 安装 Node → 上传并核对 SHA-256 → 建系统用户、初始化、写 systemd 服务、开放 ufw / firewalld → 等证书 → 从这台电脑访问 https://<地址>/api/device-link/relay/info 核对中转 ID。
    • Node 24.22.1 的 SHA-256 写死在代码里。国内区域先试 npmmirror,其他区域先试 nodejs.org;校验不符视为下载失败。
    • 服务器有 IPv6 时监听 ::(双栈),否则 0.0.0.0。Let's Encrypt 会优先通过 IPv6 验证有 AAAA 记录的域名。
    • systemd 服务以 cindy-relay 用户运行,只放行绑定低端口的权限;ProtectSystem=strict,只能写数据目录。
    • 主人身份(中转 ID、主人凭证、主人密钥)只在这台电脑生成;服务器只拿到凭证哈希、主人公钥和主人证书。
    • 身份在动服务器之前就记进部署记录:中途失败重试,用的还是同一份身份,不会和服务器上已初始化的数据冲突。 记录在检查通过、第一次改动服务器前才写入(2026-10-29):只在连接或检查阶段停下的部署不留记录,界面也不会出现从未装上的中转。
  • 部署界面(2026-10-29 用户反馈后重做):
    • 表单不预选服务器,用户选中后才做只读检查(check-server:只跑探测与检查脚本),说明能否部署、走直连还是已有 Nginx、服务器上已有的中转是不是这台电脑的;不通过时「开始部署」不可点,可直接换服务器或重新检查。下拉显示 账号@地址;探测脚本一行都没输出时报 SHELL_UNAVAILABLE(例如 Git 服务的 git 账号),不误报为系统不支持。
    • 证书机构连不上(断网、超时、连接重置、CA 5xx)与 CA 拒绝验证分开:中转的 ACME 请求先短暂重试,仍失败时在 status.json 标 transient 并按 15 秒起的退避重试;部署方遇到 transient 继续等待并显示「正在自动重试」,等待期满仍连不上才报 CA_UNREACHABLE。起因是 2026-10-29 国内服务器首次申请 IP 证书时一次 fetch failed 就被当作最终失败并回滚。
    • 端口由 Docker 容器发布时报 PORT_BUSY_CONTAINER 并写出容器名:容器里的 Nginx 由它自己的部署配置管理,Cindy 不改。其他程序占用报 PORT_BUSY 并写出程序名。
    • 「连接线路」直接展示在「远程连接」页的「我的设备」下面,不另设入口行或子页(用户 2026-10-29 要求);原独立的「中转服务」折叠分区取消,设置搜索沿用旧别名。
    • 线路是一个单选列表(官方 / 我的服务器(每台服务器一行,2026-10-30 起)/ 这台电脑当中转 / 已加入的中转):选中的那一行就是正在用的;其他行给切换图标,切换一律先弹确认,说明原线路会怎样(从官方切到自己的中转时说明手机系统推送、供应商分享和共享任务暂不可用)。部署中、未完成、移除中的状态显示在服务器那一行上。右侧只放同样大小的图标并贴右对齐:切换在前,这条线路自己的操作(服务器中转的删除、这台电脑当中转的设置)在后,没有的不占位,只有一个图标时它就在最右边;正在用的线路在名字旁边显示一个绿点(悬停与读屏为「正在使用」),不进图标列(文字和图标混在一列对不齐,用户 2026-10-29 反馈)。「加入别的中转」和这台电脑当中转的设置都用小窗口,不在列表下面展开;这台电脑当中转要先填设置,切换到它就是打开设置窗口。
    • 部署是三步窗口(选择服务器 → 部署 → 完成,2026-10-30 起第 3 步不再是添加设备):关窗口不中断部署;失败的一步下面写原因(技术细节折叠),失败后不再列出没执行的步骤,可重试、修改设置(回第 1 步,可换服务器)或放弃部署(清理服务器后删除记录)。完成页只显示结果和「使用这条线路」,不自动切换、不生成加入链接;换到另一台服务器部署时,原服务器上没完成的那条记录保留,可以继续或放弃(见 §15.5)。
    • 服务器中转的详情并入服务器那一行,且只在正在使用这条线路时显示(没在用时设备数、证书等没有意义,也不去请求):在线状态、已加入/在线设备数、证书剩余天数与版本来自 deployment-status(用部署记录里的主人凭证读 admin/status,中转 ID 不符按连不上处理),添加设备与升级在详情里,检查连接是状态旁的刷新图标。移除是行尾的图标按钮,先确认;服务器连不上或中转不归这台电脑时才提供「只在本机移除」。
  • 已有 Nginx 的自动接入(2026-10-29,服务器 bundle 0.3.0):
    • 证书重试修复随 bundle 0.3.1 提供;已部署 0.3.0 的用户通过现有升级入口上传新程序,设备档案与主人身份继续沿用,不改变线协议。
    • 沿用同一个部署入口,自动判断 80/443 的占用者;原生 Nginx 自动接入,其他程序不停止、不接管。
    • 上传暂存程序保留 .mjs 后缀(relay.new.mjs),Nginx 准备阶段可在正式安装前由 Node 执行;旧的 relay.mjs.new 会被 Node 拒绝(ERR_UNKNOWN_FILE_EXTENSION)。启动时尚无 CLI JSON 的错误也保留 Node 错误码,避免只显示笼统失败。回归通过 Desktop 部署入口指定的真实文件名调用原生 Node loader,防止 SSH fake 掩盖后缀错误。
    • 从运行中的 master 与 nginx -T 找到实际配置,不要求用户选安装目录或复制配置。
    • 访问地址已有可信 HTTPS 时沿用原证书管理,中转仅在回环地址提供 HTTP;否则中转在回环地址申请、续期证书,Nginx 转发 HTTP-01 验证并提供公网 HTTPS。
    • 自动探测空闲回环端口,代理 REST、WebSocket 与媒体流;按访问地址及域名解析结果匹配实际监听 socket,保留无关 IP、原默认网站与域名证书。常见 ACME webroot 的其他验证文件在中转验证服务返回 404 或掉线时均可回退访问。
    • 公网 IP 经 NAT 映射、目标端口尚无同族监听时使用通配地址;不把公网地址直接当作本机网卡地址绑定。原站点跨多个 socket 或同时提供 HTTP 时保留其名字,由前置托管站点接管目标 TLS。
    • root Nginx 的省略 listen 与只写 IPv4/括号 IPv6 地址的配置,统一按默认 80 端口识别并在原站点接入验证,不新增 HTTP 站点抢走原默认页面。
    • 两种 Nginx 后端均启用代理模式,Nginx 覆盖客户端来源头;中转仅对回环代理传来的单个合法 IP 按来源限流。API 单独关闭访问与错误日志,并隔离原站点的自定义/递归错误页,避免后端掉线时将签名媒体地址写入原网站日志;原网站的错误页和日志照常保留。
    • 配置、备份与导出的证书仅存在服务器的 /etc/cindy-relay/nginx 私有目录;nginx -t 通过后平滑重载。证书按代写入私有目录,systemd timer 每 5 分钟检查并原子切换引用。
    • 验证成功才提交事务;每次配置或服务单元写入前记录前后指纹,失败或任意写入点中断后,重新部署或卸载可恢复未完成事务。恢复检测到管理员并发修改时保留备份并停止,不能覆盖新修改。卸载撤销本次补丁,不停止 Nginx。
    • 不支持安全解析的配置(例如没有精确地址的正则站点名、复杂的自定义 ACME 处理器或多个 master)明确失败,不猜测、不覆盖。
    • 实现:packages/device-link-relay/src/nginx.ts;回归:同目录 __tests__/nginx.test.ts 与 Desktop selfHostedRelayDeploy.test.ts;真实 Nginx 验证:pnpm --filter @cindy/device-link-relay run interop:nginx(Docker 内运行,不访问用户服务器)。
    • 已验证:中转内核 44 例、Desktop 部署与运行时 22 例及两包类型检查通过。真实 Nginx 容器覆盖仅 HTTP、仅 HTTPS、默认 HTTP 监听、NAT 公网 DNS、具体 IP 监听、域名的隐式默认网站、共享块的其他 IP/HTTP 名字、无关 IP 网站保留、其他 ACME 客户端(含中转掉线)、REST、WebSocket、大于 1 MB 的上传、伪造来源头与限流隔离、正常及后端掉线时的签名地址日志保护、证书轮换、升级回滚、已有 HTTPS 复用和卸载恢复。缺陷回归已先复现后修复;默认监听的真实 Nginx 回归复现原站从 200 变为 404,修复后保留原页面。测试使用容器内临时证书,生产 CA 签发和真实云服务器部署仍未验证。
  • 服务器上已有不属于这台电脑的中转时停下(RELAY_MISMATCH),由用户选择清掉重新部署。

远程管理(设置 → 远程连接 → 中转服务):

  • 部署表单:选择 SSH 主机,访问地址默认取 SSH 主机地址(IP 或域名),可以修改。
  • 部署进度逐步显示,当前步骤使用标准加载动画并显示耗时;下载、切换下载源、校验、解压和等待证书时显示实时进展。 可展开带相对时间的部署日志,失败后保留步骤、日志和最终耗时,标题明确显示未完成。 重试前重新检查服务器,自己的未完成部署保留身份继续;仍需清除别人的中转时重新确认,取消不继续部署。部署、添加设备等命令的失败原因显示在当前部署弹窗内。 只展示受控的本地化事件,SSH 原始输出和凭证不进入进度日志;应用日志记录操作、步骤和失败码,便于排查。 状态与日志仅在当前账号的内存中保存,日志最多 100 条;账号切换后的迟到进展不能覆盖新账号。 进度事件只用于本机部署界面,不改变中转通信协议,也不要求已部署的中转内核更新。 实现与回归见 selfHostedRelayDeploy.ts、selfHostedRelayRuntime.ts 及其同名单测;界面场景见 scripts/fixtures/relay-service/(均相对 Desktop)。
  • 失败时给出原因与处理办法,例如安全组没放行 80 / 443、端口被占、没有 root。
  • 可以重试,也可以清掉旧中转重新部署。
  • 「我的服务器中转」:
    • 版本;
    • 升级(Cindy 带的中转版本不同时);
    • 从服务器卸载(连同设备档案);
    • 只在本机移除;
    • 改名(只改本机显示的名字,服务器和已加入的设备看到的仍是部署时的名字);
    • 改用这个中转。
  • 作为服务器中转的主人时,「添加设备」与审批直接对 https://<地址> 调管理接口,与本机中转共用同一套界面。
  • 切回官方中转时,服务器上的中转继续运行,可以随时改回来。

与上文的差异:

  • §2.2 原计划的自签名证书不再需要:手机只信任公开 CA 的证书,IP 证书已覆盖「没有域名」的场景。
  • §3 原计划由用户自己执行安装命令,现在由 Cindy 经 SSH 一键完成;不支持 SSH 的服务器仍可手动运行同一个 relay.mjs。
  • 中转版本升到 0.2.0(加入签名与证书,wire 行为变化);第 2 步留下的本机中转数据(schema 1)不能使用,开启时会自动重建,已加入的设备需要重新加入。

验证:

  • @cindy/device-link-relay 12 例通过,新增两项:
    • 同意时证书对不上申请(没有证书、证书发给别的公钥)被拒;
    • 加入链接里的主人公钥与中转不符时 OWNER_MISMATCH。
  • @cindy/device-link 54 个文件 1081 例通过,新增两项:
    • 客户端签名用例:未签名、他人密钥、签名后改内容、原样重放的帧都在分发前被丢弃,本机发出的帧带有效签名;
    • 加入链接缺主人公钥或配对秘密时拒绝。
  • 互通:pnpm --filter @cindy/device-link-relay run interop 全程开启设备签名,主机核对每一条对端消息,通过。
    • 故意把控制端换成错误的签名密钥,主机丢帧、测试失败,说明签名确实在生效。
  • ACME:用 Let's Encrypt 官方测试 CA Pebble 在本机实测内核单文件。
    • IP 证书(6 天)与域名证书(90 天)都签发成功,HTTPS 正常提供;
    • 重启后复用已保存证书,不重复申请;
    • 失败原因(80 端口连不上)原样写进状态文件。
    • Pebble 需要单独下载,没有放进 CI。
  • Desktop:typecheck 通过;src/main/device-link/__tests__ 88 个文件 1811 例通过。

尚未验证:

  • 真实云服务器上的部署:Let's Encrypt 生产环境、云厂商安全组、不同发行版的 sudo / useradd / ufw。
  • 界面实机操作与手机真机。

15.4 收尾验证与体验入口(2026-10-28)

部署等待期间换账号时,旧工作不能继续取新账号的 SSH 主机、写入新账号的配置或覆盖新部署进度。 部署、升级、卸载及切换中转的异步步骤核对发起时的账号代次;旧账号的本机中转迟到启动成功时立即关闭。 已送到服务器的命令不能撤回,但旧任务不再继续后续 SSH 步骤;切回原账号后可用原部署记录重试。 实现见 selfHostedRelayRuntime.ts、selfHostedRelayDeploy.ts,回归从实际注册的 IPC 入口验证。

本次补验:

  • Desktop、Mobile 与中转内核类型检查通过;中转单文件构建通过。
  • 共享通信库 54 个文件、1081 例通过;真实 WebSocket 断线恢复 10 例通过。
  • 中转内核 12 例及开启设备签名的互通测试通过。
  • 手机签名、加入深链、API 路由、账号隔离与通知的定向测试 6 个文件、101 例通过。
  • Desktop 部署器 7 例、运行时账号切换 6 例、账号 token 隔离 2 例通过。
  • 部署表单、部署进度、部署完成三个真实组件场景,Light/Dark × 中文/英文/日文共 18 个截图场景通过并目检。 SSH 列表和部署状态为模拟数据,不代表真实服务器已部署。 ui:check --changed --theme all 因公共语言资源选入大量无关页面,已主动中止,不计作通过;上述结果来自部署页定向验证。
  • i18n、术语表、测试卫生和开发文档检查通过。

体验步骤:

  1. 使用含本次代码的桌面开发版,在「设置 → 远程」配置自己的 Linux SSH 主机。
  2. 打开「设置 → 远程连接 → 中转服务 → 部署到我的服务器」,选主机、核对访问地址,开始部署。 主机需支持 systemd,并具备 root 或免密 sudo;80/443 端口需空闲或由原生 Nginx 使用,部署时自动接入 Nginx,云安全组需放行这两个端口。
  3. 等待部署完成,点「使用这条线路」并确认(2026-10-30 起不再自动切换),再点击「添加设备」。另一台新版电脑粘贴链接,手机用含本次 JS 改动的开发版扫码。 在主人电脑核对配对码并同意,再测试设备列表、远程消息、图片和断线重连。
  4. 切回官方中转,核对原有连接恢复,服务器中转仍继续运行;可以再点击「改用这个中转」。

真实云服务器部署、生产 CA 签发与续期、手机真机仍待体验验证;本轮未操作用户的云服务器,也未提交或发布。

15.5 多台服务器、部署后手动切换、改名与部署窗口高度(2026-10-30)

用户反馈:部署过程中窗口高度来回跳;部署了一台就不能再部署;部署完不该马上切换;部署完要能改名。

  • 窗口高度:部署窗口三步共用固定高度 min(560px, 88vh),内容在中间区域滚动,底部按钮不动;服务器检查卡片在未选、检查中、检查通过时都先占两行说明的高度;部署中的实时进展固定在进度条下面的一行,不再插在当前步骤下面推动列表。
  • 多台服务器:本机配置 config.json 的部署记录从单个 deployment 改为 deployments 列表,一台服务器(SSH 主机)一条,中转 ID 不重复;配置版本仍是 2。读取时没有 deployments 就把旧字段 deployment 读成一条;写入时同时把正在用的(或第一条)写进旧字段,装回旧版本仍能看到它(旧版本再写回会丢掉其余几条的本机记录,服务器上的中转与秘密文件不受影响)。
  • 命令:upgrade-deployment、uninstall-deployment、forget-deployment、use-deployment、deployment-status 都带 relayId;新增 rename-deployment。部署任务带 relayId,界面据此把进度显示在对应那一行;同时仍只允许一个部署任务。IPC 只在本机窗口与主进程之间,随同一版本发布,不涉及手机或中转协议。
  • 不自动切换:部署完成只保存记录;正在用的就是这个中转时(升级、重新部署)才按新记录重连。完成页给「使用这条线路」,与列表里的切换一样先确认。
  • 不再清理其他服务器:原先换服务器部署前会先清理上一台没完成的部署(cleanup 步骤),现在那条记录留在列表里,由用户继续或放弃。
  • 改名:只改本机记录与正在用的线路名,不连服务器;部署或升级进行中改名,完成时不被覆盖。服务器上没有改名接口,新设备加入时等待页显示的仍是部署时的名字。
  • 实现:apps/desktop/src/shared/selfHostedRelay.ts、src/main/device-link/selfHostedRelayConfig.ts、selfHostedRelayRuntime.ts、src/renderer/components/settings/RelayServicePanel.tsx。
  • 回归:selfHostedRelayRuntime.test.ts(部署不切换、两台服务器并存、改名、没完成的记录保留)、selfHostedRelayConfig.test.ts(旧格式读取与旧字段写回);单页场景 relay-service 新增 deploy-steady(每一步窗口位置与大小、表单输入框和步骤列表都不动)、multi(两台服务器、改名)与 retry-existing(完整旧记录重新部署在改动服务器前失败时,仍可查看原因和重试)。

16. 设备签名:中转无法冒充你的设备

16.1 要防什么

中转部署在云服务器上之后,服务器被入侵(或云厂商、托管方能动它)就等于中转被人控制。没有签名时,控制了中转的人可以:

  • 冒充手机给电脑发 invoke / link-open,让电脑执行任务、读写文件;
  • 冒充电脑给其他电脑推送插件同步、词典、通讯录等会写入状态的消息;
  • 重放之前的消息。

签名之后,中转仍然能看到经它转发的内容,也能断开、丢弃消息(它本来就能),但不能让任何一台电脑执行没有经过你自己设备签名的请求。端到端加密不在本期范围。

16.2 密钥与证书

  • 主人密钥:开启或部署中转的那台电脑生成(Ed25519),私钥只在它的 safeStorage 里。主人电脑自己的设备签名也用这把密钥。
  • 设备证书:主人密钥对「中转 ID + 设备 ID + 设备公钥 + 角色 + 签发时间」的签名。
    • 中转保存证书并提供给所有设备,但伪造不了。
    • 每台设备用主人公钥逐个核对证书。
  • 主人公钥从哪来:
    • 主人电脑自己知道;
    • 其他设备从加入链接 o= 参数取得。链接经二维码或复制粘贴交给新设备,不经中转。
  • 新设备的公钥怎么不被中转替换:
    • 加入链接里还有一次性配对秘密 s=,同样不经中转。
    • 新设备生成签名密钥,用 HMAC-SHA256(s, [中转ID, 设备ID, 公钥]) 证明这把公钥是拿着链接的设备生成的。
    • 主人电脑审批时核对证明,对不上只能拒绝。
    • 4 位配对码仍保留,给人眼再核对一次。
  • 加入时核对证书:新设备拿到中转转交的证书后,必须核对它出自链接里的主人、发给自己这把公钥。否则视为中转被替换,停止加入(OWNER_MISMATCH)。

16.3 每条消息的签名

经中转转发的对端帧(ROUTED_KINDS)都带 auth: { t, b, r, c, s }:

  • t:发送时刻(毫秒),收到时与本机时钟相差超过 10 分钟即拒绝。
  • b:本次启动的随机标识;c:本次启动内严格递增的计数。收到方按「发送设备 + 启动标识」记下最大计数,不大于它的一律视为重放。启动标识的最后一条消息也过期后清理记录,内存不随消息量增长。
  • r:收件设备本次启动的随机挑战,签名必须绑定它。重启后挑战变化,即使计数窗口已经清空,旧建链或写请求也不能再次执行。 双方先在保留的 device-link:relay-auth push 通道交换已签名的 request / response;仅完整的认证 request 允许空挑战, 接收端验签后直接消费认证消息,不进入业务 handler、不建立远控链路,也不改变开关、订阅或权限。 因而关闭远控的手机仍能接收插件同步;未建链的允许查询沿用原有权限边界。 首次业务消息在客户端按设备有界排队,认证重试不重连共享 socket;超时、断线或签名身份变化后不再发送旧请求。 电脑重启且证书尚未加载时,只允许有界的无业务认证探测;未验签消息仍丢弃。对端新挑战验签通过后, 发送端可重签仍在等待的原 link-open,沿用原请求 ID、签名身份和超时期限;不重发任意旧写请求,已取消的建链不会恢复。
  • s:Ed25519 签名。签名对象是以下内容的 SHA-256:
    • JSON.stringify(["cindy-relay-frame/2", 中转ID, 发送设备, 收件设备, kind, id, t, b, r, c]);
    • 换行;
    • JSON.stringify(payload)。
    • 中转转发时会重新序列化帧,JSON 解析再序列化在 V8 与 Hermes 上都保持不变。
  • 收件设备还核对 dst 就是自己:签给别的设备的消息不能转投给它。
  • 可靠传输重发、分片都会重新签名(签名发生在每次真正写入 WebSocket 时)。
  • 直连通道上的帧不签名:直连的 DTLS 指纹经已签名的信令交换,电脑只接受签名有效的信令,因此直连的对端身份同样可信。
  • 遇到证书列表里还没有的设备,先丢弃这条消息并刷新证书(5 秒节流);可靠传输的重发会在刷新后送达。

16.4 手机收发均核对设备身份

  • 手机签名发出的每条对端消息,收到的对端消息也必须通过设备证书、帧签名和重放检查才分发。 权限请求的展示内容同样受保护,不能让中转保留真实请求 ID、替换文案后诱导主人签出允许决定。
  • 复用已有的纯 JS @noble 和共享 RelayFrameAuthenticator,不新增原生依赖或冷更输入。
  • 首次使用时拉取主人签发的设备证书;通信活跃时每十分钟刷新,未知设备或签名不符时按五秒节流刷新。 证书尚未取得、刷新失败或签名无效时丢弃当前帧,可靠传输可在证书就绪后重发,不放行未经认证的内容。
  • 账号、中转、凭证或签名身份变化会使旧请求失效,迟到证书不能写入新路由。官方中转不受影响。
  • Hermes 上的持续推送吞吐与耗电仍需真机验收,不能以未实测的性能判断跳过验签。

16.5 兼容

  • 官方中转完全不受影响:frameAuth 返回 null,不签名、不核对,wire 与旧版逐字节一致。
  • 自建中转从 0.2.0 起要求签名。
    • 旧格式的加入链接(没有 o / s)会被拒绝;
    • 不支持 device-signatures-v1 的中转不能加入。
  • 自建中转从未发布过,不存在需要迁移的用户数据。第 2 步开发期间留下的本机配置会被忽略并清掉旧凭证文件。
  • 开发期间不含接收端挑战的旧签名客户端不兼容本次签名格式,需同步更新 Desktop / Mobile; 中转仅原样转发 auth 与已有 push,无需更改已实现的服务端路由。