透過 Cloudflare Tunnel 連到中繼

Cloudflare Tunnel 讓你的中繼擁有公開的 HTTPS 位址，不需要自己的伺服器，也不必在路由器上開放連接埠。OAR 可以替你執行 Cloudflare 的 cloudflared 程式：它會隨中繼一起啟動、在斷線時重新啟動，並在狀態點中顯示它的狀態。如果你在 Cloudflare 上有網域，並想從手機或其他網路連到中繼，或是你需要 HTTPS 來把頁面安裝成 App 和使用推播通知，就選擇這種方式。

cloudflared 會向外連線到 Cloudflare。中繼仍然只在這台機器上監聽（localhostOnly 維持 true），Cloudflare 則把傳給你主機名稱的請求，經由這條連線送到中繼的連接埠。

你需要什麼 #

• 一個啟用 Zero Trust 的 Cloudflare 帳戶，以及帳戶中一個用於公開主機名稱的網域（zone）。
• 在執行中繼的機器上安裝 cloudflared。OAR 不包含它，也不會安裝它。
• 一個你在 Cloudflare 中建立的 tunnel。OAR 會用該 tunnel 的 token 執行它。

中繼會執行 cloudflaredTunnel.binary 中指定的程式，否則就執行它在 PATH 上找到的 cloudflared。安裝方式：

在 Windows 上，.cmd 或 .bat 啟動器無法使用。OAR 只會啟動 .exe 或 .com 檔案。

設定 #

1. 在你的 Cloudflare Zero Trust 帳戶中建立一個 tunnel。複製它的 token。
2. 在你的網域上為這個 tunnel 設定一個公開主機名稱，例如 relay.example.com，並把它指向 http://localhost:3333。如果你變更過 config.json 中的 port，請使用那個連接埠。這項路由設定存放在 Cloudflare，而不是在你的機器上。
3. 把含有 token 的 cloudflaredTunnel 區塊加到 config.json（見設定的 key）。
4. 用 oar restart 重新啟動中繼。

在瀏覽器中開啟 https://relay.example.com/。你像平常一樣用存取 token 登入。

設定區塊 #

{
  "cloudflaredTunnel": {
    "mode": "managed",
    "required": false,
    "token": "<tunnel token>",
    "binary": "cloudflared",
    "extraArgs": []
  }
}

舊的寫法 "enabled": true 仍然等同於 mode: "managed"。有三個環境變數會覆寫檔案中的設定：COPILOT_CLOUDFLARED_MODE、COPILOT_CLOUDFLARED_TOKEN 和 COPILOT_CLOUDFLARED_BINARY。config.json 參考資料會把這些 key 與其他 tunnel 設定一起列出，環境變數頁面則列出這些變數。

中繼會以命令列參數（cloudflared tunnel run --token <token>）把 token 交給 cloudflared，而不是透過環境。因此在有其他使用者的機器上，token 可能會出現在執行中處理程序的清單裡。中繼的記錄則會把它顯示為 <redacted>。

運作方式 #

• 啟動與停止。 中繼啟動時會啟動 cloudflared，關閉時則停止它（傳送終止訊號）。
• 已連線。 當 cloudflared 回報已註冊的連線時，tunnel 就算已連線；如果沒有這種回報，則在它執行滿五秒時算已連線。
• 斷線。 cloudflared 結束時，中繼會在等待大約 5、10、20、40 秒，之後每次 60 秒後再次啟動它，每次等待最多再加上 20%。連線持續超過 30 秒後，這些間隔會從頭開始。
• token 錯誤或 tunnel 已刪除。 如果 cloudflared 連續三次在 10 秒內結束，中繼會回報錯誤 auth-or-config，之後只會大約每分鐘重試一次。
• 沒有 cloudflared。 中繼照常啟動，tunnel 保持關閉。中繼每分鐘重新查找一次，程式出現後就會啟動 tunnel。如果你把它安裝到不在中繼 PATH 上的資料夾，請重新啟動中繼。

必要的 tunnel #

設定 required: true 時，tunnel 未連線期間中繼不會從佇列中取出訊息。這包括第一次連線之前的時間，以及缺少 cloudflared 或 token 的情況。如果只有從外部能連到中繼時它才有用，就使用這個設定。訊息會在佇列中等待，並在 tunnel 連線後執行（見回合與佇列）。

查看狀態 #

因為路由設定存放在 Cloudflare，中繼並不知道你的公開主機名稱，所以以上都不會顯示它。

區分 tunnel 流量 #

Cloudflare 會在它轉送的每個請求中加上 cf-ray 標頭。中繼用它來區分經由 tunnel 傳來的請求和在這台機器上發出的請求。如果你也想讓你自己的邊緣節點加上的標頭被這樣看待，請把它們列在 tunnelMarkerHeaders 中。publicHostnames 列出可連到中繼的主機名稱，trustProxy 則決定中繼相信哪些 proxy 提供的轉送位址。預設值 "loopback" 適合在同一台機器上執行的 cloudflared。這三個都在 config.json 參考資料中。

預覽用的第二個主機名稱 #

預覽需要自己的主機名稱，這樣被預覽的 App 就絕不會和中繼共用登入 cookie。把它加到同一個 tunnel，作為第二個公開主機名稱，並指向預覽監聽程式（預設為 http://127.0.0.1:3334）。預覽頁面有 ingress 範例和 previews 區塊。請把中繼的主機名稱放進 publicHostnames。

中繼前面的 Cloudflare Access #

套用在中繼主機名稱上的 Cloudflare Access 應用程式，會作用於每個訪客，包括分享的對話的觀看者。如果沒有設定例外，他們會被要求登入，連結也就無法使用。請讓 /shared/* 和 /api/shared/* 不需登入即可通過。

不要為 /api/shared/* 加上 Cloudflare 快取規則。分享的頁面會重新載入這個位址來追蹤對話，而快取的回應會一直顯示舊的狀態。中繼會在每個 API 回應中加上 Cache-Control: no-store，並在每個回應中把 CDN-Cache-Control 和 Cloudflare-CDN-Cache-Control 設為 no-store。Cloudflare 會優先遵守這兩個標頭，而不是你網域中的快取規則。

安全性 #

tunnel 會把中繼放到公開的網際網路上。能把其他人擋在外面的是存取 token。見存取 token 與誰能連到中繼和 OAR 會暴露什麼。

中繼的 session worker 透過只在這台機器上運作的 socket 連線。因為公開的 tunnel 會轉送每個路徑，中繼對這些路徑上帶有 cf-ray 或你的任一 tunnelMarkerHeaders 的請求，會回應 403，並在記錄中以 [tunnel-guard] 註明。分享連結雖然不需登入就經由 tunnel 傳來，但不受影響。

疑難排解 #