Orca Relay 區(qū)域放置機(jī)制解析Electron 端如何用延遲探測(cè)、24 小時(shí)緩存與向后兼容的 preferredRegion 選擇最優(yōu) Relay 區(qū)域【免費(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/orca48/orca本文基于 Orca 倉(cāng)庫(kù)中的參考文檔 relay-regional-placement.md完整拆解 Orca 桌面端Electron 主進(jìn)程為 Relay 服務(wù)選擇部署區(qū)域region的整套機(jī)制區(qū)域目錄catalog如何獲取與校驗(yàn)、每區(qū)域 3 次有界/health延遲探測(cè)如何取中位數(shù)、24 小時(shí)區(qū)域偏好緩存何時(shí)命中與何時(shí)觸發(fā)切換、preferredRegion字段如何隨分配請(qǐng)求發(fā)送并在回滾版 Director 上安全降級(jí)以及面向本地診斷的ORCA_RELAY_REGION_OVERRIDE環(huán)境變量如何使用。讀完本文你可以在不閱讀全部源碼的前提下復(fù)述這條鏈路的關(guān)鍵參數(shù)、失敗回退行為并定位每個(gè)環(huán)節(jié)對(duì)應(yīng)的實(shí)現(xiàn)與測(cè)試文件。機(jī)制總覽主進(jìn)程在選擇分配前先選區(qū)域文檔給出的核心陳述是Orca 在請(qǐng)求新的 Relay 分配assignment之前由 Electron 主進(jìn)程先選定一個(gè) Relay 區(qū)域。Director 只發(fā)布“允許列表式”的區(qū)域目錄其中僅包含屬于該 Director 自身的 HTTPS cell 子域Orca 對(duì)每個(gè)區(qū)域取三次有界/health延遲樣本并把穩(wěn)定選出的結(jié)果緩存 24 小時(shí)只有在替代區(qū)域“顯著更快”時(shí)緩存的區(qū)域才會(huì)改變。這條鏈路在源碼中的落點(diǎn)非常清晰。desktop-relay-service.ts 在構(gòu)造時(shí)通過(guò) createRelayRegionPreferenceReader 生成resolvePreferredRegion閉包第 73 行并在打開(kāi) Relay 會(huì)話時(shí)把它注入RelaySessionBroker.connect第 80–92 行。relay-session-broker.ts 中區(qū)域解析與授權(quán)獲取通過(guò)Promise.all并行完成第 201 行隨后隨分配請(qǐng)求一起發(fā)出第 219 行。這意味著區(qū)域選擇不會(huì)串行拖慢連接建立解析失敗也只是讓請(qǐng)求“無(wú)偏好”發(fā)出。文檔還明確了兩條安全與網(wǎng)絡(luò)邊界均與源碼吻合分配請(qǐng)求只攜帶preferredRegion不發(fā)送延遲數(shù)值、IP、國(guó)家、配對(duì)數(shù)據(jù)或憑據(jù)目錄拉取、探測(cè)、緩存寫入任何一環(huán)失敗都回退為“無(wú)區(qū)域偏好的分配請(qǐng)求”而不是讓 Relay 連接失敗。此外文檔指出探測(cè)測(cè)量的是桌面端本地網(wǎng)絡(luò)路徑。文件夾工作區(qū)與 SSH 工作區(qū)共享同一個(gè)本地 broker探測(cè)不會(huì)在遠(yuǎn)程主機(jī)上執(zhí)行手機(jī)繼續(xù)連接桌面端配對(duì)載荷pairing payload中那個(gè)精確的 cell URL因此手機(jī)的地理位置不被獨(dú)立測(cè)量也不需要任何移動(dòng)端協(xié)議更新——這一點(diǎn)從源碼結(jié)構(gòu)看得到印證探測(cè)與緩存邏輯全部位于src/main/runtime/relay/下的桌面主進(jìn)程代碼中src/relay/與src/renderer/側(cè)沒(méi)有對(duì)應(yīng)的探測(cè)實(shí)現(xiàn)。區(qū)域目錄只允許“Director 自己的 HTTPS 子域”區(qū)域目錄是整條鏈路的輸入。實(shí)現(xiàn)位于 relay-region-preference.ts 的fetchRelayRegionCatalog第 174–205 行先校驗(yàn) Director 自身是合法來(lái)源isCanonicalDirectorOrigin第 308–318 行必須 HTTPS僅回環(huán)地址允許 HTTP否則直接拋錯(cuò)請(qǐng)求GET {directorUrl}/v1/regions帶cache: no-store、redirect: error和 1.5 秒超時(shí)默認(rèn)PROBE_TIMEOUT_MS響應(yīng)體受 readFetchResponseJsonWithinLimit 限制在16 KBCATALOG_MAX_BYTES并限制結(jié)構(gòu) token 數(shù)與嵌套深度用 zod 嚴(yán)格模式.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] } ] }目錄的約束條件對(duì)應(yīng)第 23–61 行的 schema 與 superRefine約束取值含義v固定1目錄版本舊版本目錄整體拒絕regionus-central1|asia-east2區(qū)域枚舉即 RELAY_REGIONS第 9 行未知區(qū)域名直接拒絕probeOrigins1–2 個(gè)規(guī)范 HTTPS origin每個(gè)區(qū)域至多兩個(gè)探測(cè)來(lái)源重復(fù)的 origin跨區(qū)域也算重復(fù)被拒絕區(qū)域數(shù)≤ 2max(RELAY_REGIONS.length)目錄規(guī)模與枚舉一致最關(guān)鍵的一條校驗(yàn)在第 197–203 行每個(gè)probeOrigin的 hostname 必須以. director 的 hostname結(jié)尾isProbeOriginForDirector第 320–322 行。這正是文檔所說(shuō)“僅包含該 Director 的 HTTPS cell 子域”的實(shí)現(xiàn)方式——即使 Director 被攻陷或在網(wǎng)絡(luò)上被篡改響應(yīng)探測(cè)目標(biāo)也只能落在 Director 自己的子域內(nèi)無(wú)法把探測(cè)流量引向任意外部主機(jī)。測(cè)試 relay-region-preference.test.ts 第 137–171 行專門驗(yàn)證了四類非法目錄未知區(qū)域、跨區(qū)域重復(fù) origin、非 HTTPS origin、Director 子域之外的 origin以及損壞緩存文件都會(huì)導(dǎo)致“無(wú)偏好”回退。延遲探測(cè)每區(qū)域 3 輪樣本、中位數(shù)、穩(wěn)定性閘門單次探測(cè)函數(shù)是導(dǎo)出的 probeRelayOrigin第 207–230 行只請(qǐng)求{origin}/health方法GET不攜帶任何 header測(cè)試第 263–277 行斷言headers為 undefined即不泄漏憑據(jù)或自定義標(biāo)識(shí)AbortSignal.timeout默認(rèn) 1500 msPROBE_TIMEOUT_MS任何異常、非 2xx 響應(yīng)都返回null而不是拋出計(jì)時(shí)使用performance.now()響應(yīng)體隨后被 cancelUnreadResponseBody 取消避免為一次探測(cè)保留 socket。區(qū)域級(jí)測(cè)量在measureRegion第 232–253 行中對(duì)應(yīng)文檔中“三個(gè)有界/health延遲樣本”3 輪采樣PROBE_SAMPLES 3。每一輪內(nèi)若某區(qū)域配置了兩個(gè) origin則并行探測(cè)兩者取這一輪中成功樣本的最小值作為該輪結(jié)果第 244 行——任一 origin 可達(dá)即代表該區(qū)域可達(dá)中位數(shù)3 個(gè)輪次值排序后取中間值median第 246–247 行對(duì)單點(diǎn)抖動(dòng)天然免疫穩(wěn)定性閘門spread max(samples) - min(samples)若spread max(20ms, median * 0.5)整個(gè)區(qū)域的測(cè)量被判為“不穩(wěn)定”并丟棄第 249–251 行。測(cè)試用例“unstable probes”第 161–170 行中[10, 20, 200]三個(gè)樣本因 spread 過(guò)大被拒絕最終解析結(jié)果為undefined即放棄本次區(qū)域選擇。任一區(qū)域若某一輪所有 origin 都探測(cè)失敗該區(qū)域返回null并被Promise.all后的 filter 剔除第 140–142 行。兩個(gè)區(qū)域都測(cè)不出來(lái)時(shí)selectRegionMeasurement返回null鏈路自然落入“無(wú)偏好”回退。24 小時(shí)緩存與“顯著更快才切換”探測(cè)結(jié)果被寫入用戶數(shù)據(jù)目錄下的orca-relay-region-preference.jsonRELAY_REGION_CACHE_FILENAME第 12 行通過(guò) writeSecureJsonFile 以安全文件權(quán)限落盤結(jié)構(gòu)為{ v: 1, directorUrl: https://relay.example.test, region: asia-east2, latencyMs: 35, expiresAt: 1727000000000 }resolve()的優(yōu)先級(jí)順序第 96–119 行體現(xiàn)了文檔中“緩存 24 小時(shí)”的行為診斷覆蓋diagnosticOverride選項(xiàng)或環(huán)境變量ORCA_RELAY_REGION_OVERRIDE通過(guò)區(qū)域枚舉解析成功則直接返回不訪問(wèn)網(wǎng)絡(luò)、不讀寫緩存測(cè)試第 230–242 行驗(yàn)證了 override 生效時(shí)fetch未被調(diào)用緩存命中readRelayRegionCache第 278–297 行要求文件存在、大小 ≤ 8 KBCACHE_MAX_BYTES、能通過(guò)嚴(yán)格 schema 校驗(yàn)、directorUrl與當(dāng)前 Director 一致、expiresAt未過(guò)期。測(cè)試第 205–228 行還驗(yàn)證了expiresAt超出“當(dāng)前時(shí)間 24 小時(shí)”上界的緩存會(huì)被拒絕防止被篡改出超長(zhǎng) TTL。緩存寫入失敗如磁盤問(wèn)題被顯式吞掉第 156–158 行注釋說(shuō)明“緩存寫入不能阻塞一次本來(lái)有效的 Relay 分配”重新探測(cè)以上都不滿足才走目錄拉取 探測(cè)流程。this.pending單例把并發(fā)resolve()合并為一次探測(cè)避免刷新風(fēng)暴第 109–118 行?！熬彺鎱^(qū)域僅在替代區(qū)域顯著更快時(shí)才變化”由selectRegionMeasurement第 255–276 行實(shí)現(xiàn)兩個(gè)閾值常量SWITCH_MINIMUM_MS 25候選最優(yōu)區(qū)域必須比當(dāng)前區(qū)域至少快 25 msSWITCH_RATIO 0.8且候選延遲必須不超過(guò)當(dāng)前區(qū)域延遲的 80%。兩個(gè)條件同時(shí)滿足meaningful第 272–274 行才返回新區(qū)域否則維持緩存區(qū)域。測(cè)試“keeps the cached region unless a stable alternative is meaningfully faster”第 88–135 行給出了直觀數(shù)字緩存us-central1樣本 95/100/105中位 100時(shí)asia 中位 85 ms差 15 ms 25 ms不切換asia 中位 60 ms差 40 ms ≥ 25 ms 且 60 ≤ 100×0.8切換。這種遲滯設(shè)計(jì)避免了網(wǎng)絡(luò)抖動(dòng)導(dǎo)致的區(qū)域來(lái)回漂移——每次漂移都會(huì)觸發(fā) Relay 重分配。preferredRegion 請(qǐng)求與回滾 Director 的兼容降級(jí)選定區(qū)域后relay-http-client.ts 的sendRelayAssignment把字段拼進(jìn)POST {directorUrl}/v1/assign請(qǐng)求體第 185–192 行{ v: 1, relayHostId: base64url 前 16 字符, preferredRegion: asia-east2, reconnect: true }注意兩點(diǎn)沒(méi)有區(qū)域偏好時(shí)preferredRegion字段整體不出現(xiàn)第 188 行的條件展開(kāi)而非發(fā)送空值reconnect字段聲明這是一次“可能的重連”Director 會(huì)走有界快速通道而非放置隊(duì)列。文檔中“回滾的 Director 拒絕新字段時(shí)只去掉該字段重試一次并保留重連行為”對(duì)應(yīng)第 200–208 行帶preferredRegion的請(qǐng)求收到400時(shí)用{ ...input, preferredRegion: undefined }原樣重試一次reconnect等其余字段保持不變同理帶reconnect的請(qǐng)求收到 400 時(shí)也會(huì)去掉該字段重試一次——兩者是平行的兼容降級(jí)邏輯注釋第 166–167 行解釋了為什么降級(jí)重試不重新占用限流閘門兩次發(fā)送在邏輯上是同一嘗試重復(fù)進(jìn)入gate.reserve會(huì)讓兼容回滾路徑白白等待約 5 秒。服務(wù)端對(duì)這一字段的處理可見(jiàn)于 Relay 云應(yīng)用的測(cè)試 relay-region-app.test.tsDirector 會(huì)把preferredRegion傳入放置邏輯并通過(guò)recordRegionRequest/recordRegionSelection記錄“請(qǐng)求區(qū)域 → 選中區(qū)域 → 是否回退”的粗粒度觀測(cè)同時(shí)存在一個(gè)regionalPlacementEnabled: false的總開(kāi)關(guān)kill switch關(guān)閉時(shí) Director 保持偏好只做觀測(cè)、按 US 優(yōu)先放置。目錄接口GET /v1/regions的定義在 app.ts 中。區(qū)域偏好的兩個(gè)實(shí)際消費(fèi)點(diǎn)從調(diào)用鏈看preferredRegion在兩種場(chǎng)景被發(fā)送初始分配RelaySessionBroker建連時(shí)并行解析區(qū)域relay-session-broker.ts 第 201、219 行并隨首次/v1/assign發(fā)出遷移/排水恢復(fù)當(dāng)活躍 cell 發(fā)出 drain 控制消息或控制連接意外關(guān)閉時(shí)relay-origin-pool.ts 的resolveDrainTarget第 155–212 行會(huì)重新解析區(qū)域偏好第 163 行且對(duì)解析異常做catch(() undefined)以reconnect: truepreferredRegion請(qǐng)求遷移目標(biāo)。這樣即使 24 小時(shí)緩存已過(guò)期遷移路徑也會(huì)觸發(fā)一次新的探測(cè)刷新讓恢復(fù)目標(biāo)跟隨網(wǎng)絡(luò)現(xiàn)狀。測(cè)試 relay-session-broker.test.ts 第 227、254 行驗(yàn)證了偏好會(huì)分別出現(xiàn)在初始請(qǐng)求與重連請(qǐng)求中。診斷覆蓋ORCA_RELAY_REGION_OVERRIDE文檔最后一段描述的確定性診斷手段在源碼中是 resolve() 的第一步第 96–102 行ORCA_RELAY_REGION_OVERRIDEasia-east2 orca # 啟動(dòng) Orca 前設(shè)置 ORCA_RELAY_REGION_OVERRIDEus-central1 orca行為要點(diǎn)取值必須精確匹配us-central1或asia-east2非法值被RelayRegionSchema.safeParse拒絕后靜默落回正常選擇流程而不是報(bào)錯(cuò)覆蓋值不寫入偏好緩存也不發(fā)起目錄/探測(cè)請(qǐng)求測(cè)試“uses a valid diagnostic override without network or cache mutation”驗(yàn)證文檔強(qiáng)調(diào)它不是面向終端用戶的設(shè)置——diagnosticOverride構(gòu)造參數(shù)第 83 行才是程序化入口環(huán)境變量主要用于本地排障與確定性測(cè)試。失敗模式匯總什么時(shí)候“沒(méi)有偏好”把實(shí)現(xiàn)與測(cè)試對(duì)照以下情形全部收斂為resolve()返回undefined隨后分配請(qǐng)求不帶preferredRegion發(fā)出Relay 功能不受影響失敗模式行為依據(jù)Director 非規(guī)范來(lái)源 / 目錄請(qǐng)求超時(shí)默認(rèn) 1.5 s拋錯(cuò)被refresh().catch(() undefined)吞掉relay-region-preference.ts 第 113 行、測(cè)試第 244–261 行目錄非法版本、區(qū)域名、origin 校驗(yàn)任一不過(guò)無(wú)偏好測(cè)試第 137–159 行某區(qū)域全部 origin 探測(cè)失敗該區(qū)域剔除全失敗則無(wú)偏好第 241–243 行采樣不穩(wěn)定spread 超閾值該區(qū)域剔除第 249–251 行緩存文件損壞 / 超 8 KB / directorUrl 不匹配視為無(wú)緩存重新探測(cè)第 278–297 行、測(cè)試第 137、173–203 行緩存寫入失敗返回已選區(qū)域不落盤第 148–158 行這與文檔的表述一致目錄、探測(cè)、緩存三類失敗都回退到“無(wú)區(qū)域偏好的分配”。延伸閱讀路徑客戶端實(shí)現(xiàn)主體relay-region-preference.ts、relay-http-client.ts、relay-origin-pool.ts、relay-session-broker.ts、desktop-relay-service.ts客戶端測(cè)試relay-region-preference.test.ts、relay-http-client.test.ts、relay-session-broker.test.ts服務(wù)端Director行為與觀測(cè)app.ts、relay-region-app.test.ts原始參考文檔relay-regional-placement.md適用前提提示本文描述對(duì)應(yīng)當(dāng)前倉(cāng)庫(kù)中v: 1版本的目錄/緩存/分配協(xié)議僅覆蓋us-central1與asia-east2兩個(gè)區(qū)域枚舉若 Director 目錄或客戶端枚舉升級(jí)新增區(qū)域ORCA_RELAY_REGION_OVERRIDE的合法取值也會(huì)隨之變化以 RELAY_REGIONS 的實(shí)際定義為準(zhǔn)?！久赓M(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/orca48/orca創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考