Orca Relay 区域放置机制解析Electron 端如何用延迟探测、24 小时缓存与向后兼容的 preferredRegion 选择最优 Relay 区域【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca本文基于 Orca 仓库中的参考文档 relay-regional-placement.md完整拆解 Orca 桌面端Electron 主进程为 Relay 服务选择部署区域region的整套机制区域目录catalog如何获取与校验、每区域 3 次有界/health延迟探测如何取中位数、24 小时区域偏好缓存何时命中与何时触发切换、preferredRegion字段如何随分配请求发送并在回滚版 Director 上安全降级以及面向本地诊断的ORCA_RELAY_REGION_OVERRIDE环境变量如何使用。读完本文你可以在不阅读全部源码的前提下复述这条链路的关键参数、失败回退行为并定位每个环节对应的实现与测试文件。机制总览主进程在选择分配前先选区域文档给出的核心陈述是Orca 在请求新的 Relay 分配assignment之前由 Electron 主进程先选定一个 Relay 区域。Director 只发布“允许列表式”的区域目录其中仅包含属于该 Director 自身的 HTTPS cell 子域Orca 对每个区域取三次有界/health延迟样本并把稳定选出的结果缓存 24 小时只有在替代区域“显著更快”时缓存的区域才会改变。这条链路在源码中的落点非常清晰。desktop-relay-service.ts 在构造时通过 createRelayRegionPreferenceReader 生成resolvePreferredRegion闭包第 73 行并在打开 Relay 会话时把它注入RelaySessionBroker.connect第 80–92 行。relay-session-broker.ts 中区域解析与授权获取通过Promise.all并行完成第 201 行随后随分配请求一起发出第 219 行。这意味着区域选择不会串行拖慢连接建立解析失败也只是让请求“无偏好”发出。文档还明确了两条安全与网络边界均与源码吻合分配请求只携带preferredRegion不发送延迟数值、IP、国家、配对数据或凭据目录拉取、探测、缓存写入任何一环失败都回退为“无区域偏好的分配请求”而不是让 Relay 连接失败。此外文档指出探测测量的是桌面端本地网络路径。文件夹工作区与 SSH 工作区共享同一个本地 broker探测不会在远程主机上执行手机继续连接桌面端配对载荷pairing payload中那个精确的 cell URL因此手机的地理位置不被独立测量也不需要任何移动端协议更新——这一点从源码结构看得到印证探测与缓存逻辑全部位于src/main/runtime/relay/下的桌面主进程代码中src/relay/与src/renderer/侧没有对应的探测实现。区域目录只允许“Director 自己的 HTTPS 子域”区域目录是整条链路的输入。实现位于 relay-region-preference.ts 的fetchRelayRegionCatalog第 174–205 行先校验 Director 自身是合法来源isCanonicalDirectorOrigin第 308–318 行必须 HTTPS仅回环地址允许 HTTP否则直接抛错请求GET {directorUrl}/v1/regions带cache: no-store、redirect: error和 1.5 秒超时默认PROBE_TIMEOUT_MS响应体受 readFetchResponseJsonWithinLimit 限制在16 KBCATALOG_MAX_BYTES并限制结构 token 数与嵌套深度用 zod 严格模式.strict()解析字段集合固定为{ v: 1, regions: [ { region: us-central1, probeOrigins: [https://us-c1.relay.example.test] }, { region: asia-east2, probeOrigins: [https://asia-c1.relay.example.test, https://asia-c2.relay.example.test] } ] }目录的约束条件对应第 23–61 行的 schema 与 superRefine约束取值含义v固定1目录版本旧版本目录整体拒绝regionus-central1|asia-east2区域枚举即 RELAY_REGIONS第 9 行未知区域名直接拒绝probeOrigins1–2 个规范 HTTPS origin每个区域至多两个探测来源重复的 origin跨区域也算重复被拒绝区域数≤ 2max(RELAY_REGIONS.length)目录规模与枚举一致最关键的一条校验在第 197–203 行每个probeOrigin的 hostname 必须以. director 的 hostname结尾isProbeOriginForDirector第 320–322 行。这正是文档所说“仅包含该 Director 的 HTTPS cell 子域”的实现方式——即使 Director 被攻陷或在网络上被篡改响应探测目标也只能落在 Director 自己的子域内无法把探测流量引向任意外部主机。测试 relay-region-preference.test.ts 第 137–171 行专门验证了四类非法目录未知区域、跨区域重复 origin、非 HTTPS origin、Director 子域之外的 origin以及损坏缓存文件都会导致“无偏好”回退。延迟探测每区域 3 轮样本、中位数、稳定性闸门单次探测函数是导出的 probeRelayOrigin第 207–230 行只请求{origin}/health方法GET不携带任何 header测试第 263–277 行断言headers为 undefined即不泄漏凭据或自定义标识AbortSignal.timeout默认 1500 msPROBE_TIMEOUT_MS任何异常、非 2xx 响应都返回null而不是抛出计时使用performance.now()响应体随后被 cancelUnreadResponseBody 取消避免为一次探测保留 socket。区域级测量在measureRegion第 232–253 行中对应文档中“三个有界/health延迟样本”3 轮采样PROBE_SAMPLES 3。每一轮内若某区域配置了两个 origin则并行探测两者取这一轮中成功样本的最小值作为该轮结果第 244 行——任一 origin 可达即代表该区域可达中位数3 个轮次值排序后取中间值median第 246–247 行对单点抖动天然免疫稳定性闸门spread max(samples) - min(samples)若spread max(20ms, median * 0.5)整个区域的测量被判为“不稳定”并丢弃第 249–251 行。测试用例“unstable probes”第 161–170 行中[10, 20, 200]三个样本因 spread 过大被拒绝最终解析结果为undefined即放弃本次区域选择。任一区域若某一轮所有 origin 都探测失败该区域返回null并被Promise.all后的 filter 剔除第 140–142 行。两个区域都测不出来时selectRegionMeasurement返回null链路自然落入“无偏好”回退。24 小时缓存与“显著更快才切换”探测结果被写入用户数据目录下的orca-relay-region-preference.jsonRELAY_REGION_CACHE_FILENAME第 12 行通过 writeSecureJsonFile 以安全文件权限落盘结构为{ v: 1, directorUrl: https://relay.example.test, region: asia-east2, latencyMs: 35, expiresAt: 1727000000000 }resolve()的优先级顺序第 96–119 行体现了文档中“缓存 24 小时”的行为诊断覆盖diagnosticOverride选项或环境变量ORCA_RELAY_REGION_OVERRIDE通过区域枚举解析成功则直接返回不访问网络、不读写缓存测试第 230–242 行验证了 override 生效时fetch未被调用缓存命中readRelayRegionCache第 278–297 行要求文件存在、大小 ≤ 8 KBCACHE_MAX_BYTES、能通过严格 schema 校验、directorUrl与当前 Director 一致、expiresAt未过期。测试第 205–228 行还验证了expiresAt超出“当前时间 24 小时”上界的缓存会被拒绝防止被篡改出超长 TTL。缓存写入失败如磁盘问题被显式吞掉第 156–158 行注释说明“缓存写入不能阻塞一次本来有效的 Relay 分配”重新探测以上都不满足才走目录拉取 探测流程。this.pending单例把并发resolve()合并为一次探测避免刷新风暴第 109–118 行。“缓存区域仅在替代区域显著更快时才变化”由selectRegionMeasurement第 255–276 行实现两个阈值常量SWITCH_MINIMUM_MS 25候选最优区域必须比当前区域至少快 25 msSWITCH_RATIO 0.8且候选延迟必须不超过当前区域延迟的 80%。两个条件同时满足meaningful第 272–274 行才返回新区域否则维持缓存区域。测试“keeps the cached region unless a stable alternative is meaningfully faster”第 88–135 行给出了直观数字缓存us-central1样本 95/100/105中位 100时asia 中位 85 ms差 15 ms 25 ms不切换asia 中位 60 ms差 40 ms ≥ 25 ms 且 60 ≤ 100×0.8切换。这种迟滞设计避免了网络抖动导致的区域来回漂移——每次漂移都会触发 Relay 重分配。preferredRegion 请求与回滚 Director 的兼容降级选定区域后relay-http-client.ts 的sendRelayAssignment把字段拼进POST {directorUrl}/v1/assign请求体第 185–192 行{ v: 1, relayHostId: base64url 前 16 字符, preferredRegion: asia-east2, reconnect: true }注意两点没有区域偏好时preferredRegion字段整体不出现第 188 行的条件展开而非发送空值reconnect字段声明这是一次“可能的重连”Director 会走有界快速通道而非放置队列。文档中“回滚的 Director 拒绝新字段时只去掉该字段重试一次并保留重连行为”对应第 200–208 行带preferredRegion的请求收到400时用{ ...input, preferredRegion: undefined }原样重试一次reconnect等其余字段保持不变同理带reconnect的请求收到 400 时也会去掉该字段重试一次——两者是平行的兼容降级逻辑注释第 166–167 行解释了为什么降级重试不重新占用限流闸门两次发送在逻辑上是同一尝试重复进入gate.reserve会让兼容回滚路径白白等待约 5 秒。服务端对这一字段的处理可见于 Relay 云应用的测试 relay-region-app.test.tsDirector 会把preferredRegion传入放置逻辑并通过recordRegionRequest/recordRegionSelection记录“请求区域 → 选中区域 → 是否回退”的粗粒度观测同时存在一个regionalPlacementEnabled: false的总开关kill switch关闭时 Director 保持偏好只做观测、按 US 优先放置。目录接口GET /v1/regions的定义在 app.ts 中。区域偏好的两个实际消费点从调用链看preferredRegion在两种场景被发送初始分配RelaySessionBroker建连时并行解析区域relay-session-broker.ts 第 201、219 行并随首次/v1/assign发出迁移/排水恢复当活跃 cell 发出 drain 控制消息或控制连接意外关闭时relay-origin-pool.ts 的resolveDrainTarget第 155–212 行会重新解析区域偏好第 163 行且对解析异常做catch(() undefined)以reconnect: truepreferredRegion请求迁移目标。这样即使 24 小时缓存已过期迁移路径也会触发一次新的探测刷新让恢复目标跟随网络现状。测试 relay-session-broker.test.ts 第 227、254 行验证了偏好会分别出现在初始请求与重连请求中。诊断覆盖ORCA_RELAY_REGION_OVERRIDE文档最后一段描述的确定性诊断手段在源码中是 resolve() 的第一步第 96–102 行ORCA_RELAY_REGION_OVERRIDEasia-east2 orca # 启动 Orca 前设置 ORCA_RELAY_REGION_OVERRIDEus-central1 orca行为要点取值必须精确匹配us-central1或asia-east2非法值被RelayRegionSchema.safeParse拒绝后静默落回正常选择流程而不是报错覆盖值不写入偏好缓存也不发起目录/探测请求测试“uses a valid diagnostic override without network or cache mutation”验证文档强调它不是面向终端用户的设置——diagnosticOverride构造参数第 83 行才是程序化入口环境变量主要用于本地排障与确定性测试。失败模式汇总什么时候“没有偏好”把实现与测试对照以下情形全部收敛为resolve()返回undefined随后分配请求不带preferredRegion发出Relay 功能不受影响失败模式行为依据Director 非规范来源 / 目录请求超时默认 1.5 s抛错被refresh().catch(() undefined)吞掉relay-region-preference.ts 第 113 行、测试第 244–261 行目录非法版本、区域名、origin 校验任一不过无偏好测试第 137–159 行某区域全部 origin 探测失败该区域剔除全失败则无偏好第 241–243 行采样不稳定spread 超阈值该区域剔除第 249–251 行缓存文件损坏 / 超 8 KB / directorUrl 不匹配视为无缓存重新探测第 278–297 行、测试第 137、173–203 行缓存写入失败返回已选区域不落盘第 148–158 行这与文档的表述一致目录、探测、缓存三类失败都回退到“无区域偏好的分配”。延伸阅读路径客户端实现主体relay-region-preference.ts、relay-http-client.ts、relay-origin-pool.ts、relay-session-broker.ts、desktop-relay-service.ts客户端测试relay-region-preference.test.ts、relay-http-client.test.ts、relay-session-broker.test.ts服务端Director行为与观测app.ts、relay-region-app.test.ts原始参考文档relay-regional-placement.md适用前提提示本文描述对应当前仓库中v: 1版本的目录/缓存/分配协议仅覆盖us-central1与asia-east2两个区域枚举若 Director 目录或客户端枚举升级新增区域ORCA_RELAY_REGION_OVERRIDE的合法取值也会随之变化以 RELAY_REGIONS 的实际定义为准。【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考