Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
自建中转服务:第一期方案
状态:方案 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.mddocs/dev-rules/remote-and-mobile-adaptation.mddocs/dev-rules/credentials-and-local-storage.mddocs/dev-rules/mobile-development.md(冷更边界)docs/dev-rules/architecture-invariants.mddocs/dev-rules/verified-downloads.mddocs/product-rules/input-handoff.md(sudo 密码)docs/design-rules/DESIGN.mddocs/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 自动完成的步骤(每一步在界面上显示进度):
- 探测服务器的系统、架构、是否为 root 或有 sudo 权限、443 端口是否被占用。
- 准备运行环境:复用自带 Node 的安装方式(
bootstrap-script.ts的BUNDLED_NODE_INSTALL_SH, 安装到~/.xdt-server/<ver>/node/)。下载来源见 §13 第 2 条。 - 上传中转程序。同版本重复上传是幂等的,参考
file-service-installer.ts。 - 写入配置:端口、证书方式、域名(可选)、主人设备凭证的哈希。
- 注册为 systemd 服务:开机自启,崩溃自动重启。
以专用的低权限用户运行,只授予绑定低端口的能力(
CAP_NET_BIND_SERVICE)。 - 系统防火墙(ufw、firewalld)开着时,征得用户同意后放行 443。
- 申请证书。
- 从本机检测能否连上。连不上时,按顺序提示:
- 去云服务器控制台的安全组放行 TCP 443。
- 检查服务器上的防火墙。
- 端口被占用时,改用前置代理方式。
- 完成,显示部署结果,不切换线路:是否改用这个中转由用户决定(完成页的「使用这条线路」或线路列表里的切换,都先确认);切换后再添加设备。 可以部署到多台服务器,一台服务器一个中转;部署到已有记录的服务器就是重新部署那一个(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只在自签名方式下出现。
另一台电脑:
- 粘贴链接,或直接点链接让 Cindy 打开。
- 先请求
relay/info,确认地址可达、对方确实是 Cindy 中转;自签名时校验证书指纹。 - 发出加入申请。主人电脑弹出确认框,显示设备名、平台和 4 位核对码。
- 主人同意后,设备拿到凭证,自动切换到该中转。
手机:
- 用系统相机扫二维码,打开 Cindy 的加入页,复用
apps/mobile/app/+native-intent.ts的深链。 链接里的加入码不进路由状态,也不进诊断信息,处理方式与共享任务邀请相同。 - 后续步骤和电脑一样。
App 内不加扫码组件:加一个会改变原生指纹,需要冷更。
核对码:与供应商分享的 Pairing Code 是同一类东西,只用来核对,不参与鉴权。可以沿用这个术语,需要扩充术语表的说明。
5.2 身份与凭证
- 中转凭证:32 字节随机数,只能用来连这一个中转;中转端只存 SHA-256。
- Desktop 存在
safeStorage,参照secrets/providerSecretStore.ts里只在 main 进程读写的键。 - Mobile 存在
expo-secure-store,用WHEN_UNLOCKED_THIS_DEVICE_ONLY。
- Desktop 存在
- 握手与 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 只表示中转凭证失效,界面提示重新加入,或切回官方中转。
- REST 返回 401 时可能登出账号(
证书校验:自签名方式下,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.mdremote-and-mobile-adaptation.mdcredentials-and-local-storage.md路径表- 新增产品规则
docs/product-rules/self-hosted-relay.md,并在AGENTS.md加读取入口 i18n/glossary.json:登记新术语,状态为 proposed
11. 工作拆分(建议的 PR 顺序)
- 内核
packages/device-link-relay:协议、REST、加入与管理、媒体、持久化、三种证书方式。 用scripts/device-link/interop.test.ts(设置CINDY_TEST_RELAY_URL)跑通与现有客户端的互通测试。 - 客户端认证与路由:
@cindy/device-link新增CindyRelay认证方案。- Desktop 的
relayRouting、鉴权失败不影响官方登录、证书指纹校验、跨账号模块暂停。
- 方式 B:Desktop 内置运行与设置界面;同时完成加入流程和主人审批界面。
- 方式 A:SSH 部署器(安装、systemd、证书、防火墙、检测、升级、卸载)。
- Mobile:加入深链与加入页、地址覆盖、凭证存储、设置项。
- 设备签名防冒充:如果确认要做。建议排在方式 A 正式开放之前。
- 文档与术语。
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. 待确认
- 方式 A 正式开放前,是否先做设备签名防冒充? 建议做(§8)。不做的话,第一期在界面上明确提示公网部署的风险。
- 服务器上 Node 从哪里下载? 现有安装器让服务器自己从 nodejs.org 下载,国内服务器可能很慢或下不到。
建议改为 Cindy 在本机按固定版本和哈希下载(
verified-downloads.md),再经 SSH 上传。 - 界面上的名称:用「中转服务」,还是别的叫法?
- 谁可以移除设备:任何已加入的设备(与官方一致),还是只有主人电脑?
- 是否给 Agent 一个只读的中转状态工具?
- 方式 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。 两者都要新增第三方依赖,需要单独评审。
- 明文 HTTP:默认只监听
- 默认端口:独立运行时默认 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-link10 个用例通过。
尚未做:
- 客户端接入(§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。
- device-link 的地址、认证方案与凭证都经零依赖的
- 切换中转复用切换区域时的重连流程(
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-relay11 例,其中新增「共享加入函数 + 真实中转」与「停用时成员收到 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。
- Desktop 与中转用
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)。
- 主人密钥与设备签名密钥按中转 ID 存在
- 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与 DesktopselfHostedRelayDeploy.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 签发和真实云服务器部署仍未验证。
- 证书重试修复随 bundle
- 服务器上已有不属于这台电脑的中转时停下(
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-relay12 例通过,新增两项:- 同意时证书对不上申请(没有证书、证书发给别的公钥)被拒;
- 加入链接里的主人公钥与中转不符时
OWNER_MISMATCH。
@cindy/device-link54 个文件 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、术语表、测试卫生和开发文档检查通过。
体验步骤:
- 使用含本次代码的桌面开发版,在「设置 → 远程」配置自己的 Linux SSH 主机。
- 打开「设置 → 远程连接 → 中转服务 → 部署到我的服务器」,选主机、核对访问地址,开始部署。 主机需支持 systemd,并具备 root 或免密 sudo;80/443 端口需空闲或由原生 Nginx 使用,部署时自动接入 Nginx,云安全组需放行这两个端口。
- 等待部署完成,点「使用这条线路」并确认(2026-10-30 起不再自动切换),再点击「添加设备」。另一台新版电脑粘贴链接,手机用含本次 JS 改动的开发版扫码。 在主人电脑核对配对码并同意,再测试设备列表、远程消息、图片和断线重连。
- 切回官方中转,核对原有连接恢复,服务器中转仍继续运行;可以再点击「改用这个中转」。
真实云服务器部署、生产 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-authpush 通道交换已签名的 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,无需更改已实现的服务端路由。