本頁由英文頁面機器翻譯而成。內容以英文頁面為準。 閱讀英文頁面
在媒體傳送前方加上 CDN
放在伺服器前方的 CDN(Cloudflare、Google Cloud CDN、CloudFront 等)可以負責傳送媒體(/media/ 與 /media/proxy/)。由 CDN 快取回應的請求,完全不會用到伺服器的 CPU 或傳輸量。本指南說明以伺服器作為 CDN 來源(origin pull)的架構。它適用於所有 blob 儲存:使用 blob = s3 或 blob = gcs 時,伺服器會從私有 bucket 讀取檔案,並與 blob = fs 一樣在 /media/ 下提供,因此 bucket 永遠不會成為 CDN 的來源。當整個伺服器都位於 CDN 後方時,還可以拒絕沒有經過 CDN 的請求。
將 media_origin(MY_MEDIA_ORIGIN)設為 CDN 的主機名稱(例如 media.example.org)。
MY_MEDIA_ORIGIN=https://media.example.org- 這個值只能是 origin(
scheme://host[:port]),不能有路徑、查詢字串或結尾斜線。必須使用https,只有localhost這類 loopback 主機才允許http。值無效時,啟動會失敗。 - 未設定時,媒體會從伺服器自己的 origin(
https://{host})提供。 - 以下 URL 使用這個 origin:本地媒體為
{media_origin}/media/...,遠端媒體的代理為{media_origin}/media/proxy/...。用戶端 API、ActivityPub(attachment、icon、image,以及自訂表情符號的icon)和連結預覽(OGP)輸出的所有 URL 都涵蓋在內。 - 網頁用戶端的 Content-Security-Policy 會把這個 origin 加入
img-src和media-src。 - 聯邦 URI(例如 ActivityPub 物件的
id)不論media_origin為何,都維持在https://{host}/之下。改變的只有提供檔案的位置,而不是識別碼。 - URL 是每次讀取時產生的,不會儲存在資料庫中,因此變更
media_origin也會改變既有媒體的 URL。只要舊 origin 上的/media/持續提供服務,遠端伺服器儲存的舊 URL 就仍然有效。
讓 CDN 指向伺服器
Section titled “讓 CDN 指向伺服器”- 將 origin(後端)設為伺服器的公開主機名稱(
https://{host})。CDN 只需要從伺服器取得/media/底下的路徑。 - 伺服器不會依主機名稱限制
/media/和/media/proxy/。CDN 送來任何Host都會提供。 /media/不需要驗證,Authorized Fetch 也不適用。伺服器會直接回應 CDN 送來的未簽章請求。- 遠端媒體(
/media/proxy/{id}/{variant}?sig=...)的sig是 URL 的一部分。請把查詢字串納入快取鍵。否則簽章不同的 URL 會共用同一筆快取。 - 讓 origin 的
Cache-Control決定快取多久(不要在 CDN 端覆寫)。
| 路徑 | Cache-Control |
|---|---|
/media/{...}(本地媒體) |
public, max-age=31536000, immutable(一年) |
/media/proxy/{...}(遠端媒體) |
public, max-age= 加上實例設定 remote_media_cache_ttl_seconds 的秒數 |
兩者回應時都帶有 Cross-Origin-Resource-Policy: cross-origin,因此其他 origin 的頁面也能讀取。
在 Cloud Run 上,ingress-cloudflare-media 會用 OpenTofu 完成這些設定:請參閱在 Cloud Run 上部署。
誰能開啟媒體 URL
Section titled “誰能開啟媒體 URL”媒體 URL 沒有存取控制。任何擁有檔案 URL 的人都能開啟它,不需要登入,也不論附加它的貼文是什麼可見範圍。不論有沒有 CDN 都是如此,包括僅追蹤者貼文和私訊的附件,以及遠端媒體的代理 URL。
- 這些 URL 很難猜到:本地檔案的 URL 包含帶有隨機部分的識別碼,代理 URL 則帶有簽章。知道一個 URL 並不會洩漏其他 URL。
- 任何看過貼文的人都可以把它的媒體 URL 轉給別人,而這些 URL 對別人也同樣有效。
- 回應標示為
public,因此 CDN 以及伺服器和讀者之間的任何共用快取都可能保留副本(保留多久請見上表)。正因如此,CDN 才能不詢問伺服器就提供媒體。
請告訴你的使用者:非公開貼文會限制誰能看到貼文,但無法阻止擁有附件檔案連結的人開啟該檔案。
刪除媒體後,CDN 的快取仍會保留它 max-age 的時間。已刪除的檔案在本地媒體最長可能仍可看到一年,代理則最長為 remote_media_cache_ttl_seconds。伺服器不會清除 CDN 的快取。如果某些內容必須在刪除或審核處置後立刻消失,請在 CDN 的主控台或 API 手動清除。
Service Worker
Section titled “Service Worker”網頁用戶端的 Service Worker 不會快取來自其他 origin 的媒體,而是交給瀏覽器的網路處理,因此只有 CDN 的快取會生效。
拒絕沒有經過 CDN 的請求
Section titled “拒絕沒有經過 CDN 的請求”CDN 只能保護伺服器免受經過它的請求影響。當 origin 也能透過自己的位址存取時(例如在 Cloud Run 上接受網際網路流量的 *.run.app),任何人都可以繞過 WAF 和快取直接呼叫它。如果 CDN 的位址列在 trusted_proxies 中,那麼在 CDN 本身的 serverless 平台上執行的呼叫者(例如他們自己的 Cloudflare Worker)也會從受信任的位址連線,並能自行決定速率限制所看到的用戶端 IP。
以下三個設定可以封住這個漏洞。CDN 會在轉送的每個請求加上一個祕密標頭,伺服器在處理請求的任何其他步驟之前,會對沒有這個標頭的請求回應 403。
- 瀏覽器和應用程式(頁面、用戶端 API、OAuth 和媒體 URL)以及其他伺服器(ActivityPub 的投遞與擷取)會連到位於
host和media_origin主機的 CDN。CDN 會自行回應已快取的/media/檔案,並在轉送給伺服器的每個請求上把origin_secret_header設為origin_secret。 - 平台(健康檢查探測、運作時間監控、Cloud Tasks 和 Cloud Scheduler)以及其他任何人(例如你自己的腳本或 webhook)會不帶標頭,直接連到伺服器自己的位址。
- origin 檢查會在伺服器中最先執行。它會放行只帶一次標頭且值為
origin_secret或origin_secret_previous的請求;沒有標頭時,只放行健康檢查的GET和HEAD,以及送往/_internal/的POST。它會從每個請求中移除這個標頭,其餘請求則以403拒絕。 - 通過檢查的請求會到達網頁用戶端、用戶端 API、OAuth、ActivityPub、健康檢查或
/_internal/,或是/media/和/media/proxy/,後兩者會讀取媒體儲存空間(blob = fs、s3或gcs),或轉送其他伺服器的檔案。被拒絕的請求會收到帶有Cache-Control: no-store的403,並計入my.http.origin_refused。
當伺服器有公開位址,而平台無法將它限制為只允許 CDN 連線時,請使用這個功能。如果防火牆或平台已經限制了誰能連線,例如伺服器只在你的負載平衡器後方的私有網路上監聽,就不需要它。如果負載平衡器本身會檢查 CDN 的標頭,且只接受 CDN 的位址,也不需要它,例如位於 CloudFront 後方的 AWS Application Load Balancer 就能透過 listener rule 和 managed prefix list com.amazonaws.global.cloudfront.origin-facing 做到。這時請在 trusted_proxies 中同時列出負載平衡器和 CDN 的位址,因為兩者都會附加到 X-Forwarded-For。
當流量是由平台本身的功能轉送,且不會加上你能控制的標頭時(例如 Cloud Run 的網域對應),這個功能就幫不上忙。只有能夠加上請求標頭的 CDN 或負載平衡器才可以。
| 設定 | 內容 |
|---|---|
origin_secret(MY_ORIGIN_SECRET) |
值,至少 32 位元組的可見 ASCII 字元。屬於機密,從環境變數或 MY_ORIGIN_SECRET_FILE 讀取 |
origin_secret_header(MY_ORIGIN_SECRET_HEADER) |
標頭名稱,由你自訂。使用 origin_secret 時必須設定。CDN 拒絕設定的名稱,或伺服器、代理會讀取的名稱(例如以 cf- 或 x-cf- 開頭者)都無效 |
origin_secret_previous(MY_ORIGIN_SECRET_PREVIOUS) |
第二個可接受的值,僅在輪替期間使用 |
這些都未設定時,不會進行任何檢查,伺服器的行為就如同這一節不存在。
沒有標頭也能通過的請求
Section titled “沒有標頭也能通過的請求”| 請求 | 原因 |
|---|---|
GET 或 HEAD 對 /healthz、/readyz、/health/live、/health/ready、/api/v1/instance/health |
平台的探測與可用性監控會直接呼叫它們 |
POST 到 /_internal/ 路徑 |
Cloud Tasks 和 Cloud Scheduler 會以伺服器自己的 URL 呼叫它們。它們帶有自己簽署的權杖 |
其他所有請求都需要標頭,維護模式下也一樣:網頁用戶端及其資源、/media/、用戶端 API、OAuth 和 ActivityPub,包括其他伺服器的傳送。
所以任何不經過 CDN、直接以伺服器自己的位址呼叫它的東西都會被拒絕:你自己的 webhook、語音媒體伺服器、腳本。請將它指向 CDN 的主機名稱。
指標埠(metrics_listen)是另一個不公開的監聽器,不會被檢查。
沒有帶著密鑰的請求,即使通過了,對其餘的處理也沒有發言權:它的用戶端 IP 是連線的對端,不論 X-Forwarded-For 怎麼說,而它的 traceparent 和 X-Request-Id 會被忽略。
CDN 轉送到伺服器的每個主機名稱都需要這個標頭:host、media_origin 的主機,以及(如果 CDN 提供服務的話)另外的 account_domain。由同一個 CDN 代理的媒體主機也要設定它,因為 /media/ 和其他所有東西一樣會被拒絕。
-
產生這個值,並選擇一個沒有其他東西使用的名稱:
終端機視窗 openssl rand -hex 32 -
先在 CDN 設定標頭。 伺服器會忽略它不認得的標頭,所以這一步還不會改變任何東西。
- Cloudflare:請求標頭轉換規則(Rules,然後 Transform Rules,然後 Modify Request Header),所有方案都有。比對這個 zone 的所有傳入請求,並選擇 Set static,填入你的名稱與值。它會取代用戶端傳來的值。只涵蓋部分主機名稱的規則,會讓其他主機名稱被鎖在門外。
- Amazon CloudFront:在每個 distribution 的來源上設定來源自訂標頭。它同樣會取代檢視者傳來的值。
- Google Cloud 負載平衡器:在後端服務上設定自訂請求標頭。
- 任何其他 CDN 或代理:必須對每個送到伺服器的請求設定(而不是附加)這個標頭。
-
設定
MY_ORIGIN_SECRET和MY_ORIGIN_SECRET_HEADER並部署。my config check會驗證它們並重述所檢查的內容,但它看不到 CDN。 -
從外部,以來源本身的位址檢查:
終端機視窗 curl -s -o /dev/null -w '%{http_code}\n' https://<host>/ # 200: through the CDNcurl -s -o /dev/null -w '%{http_code}\n' https://<origin address>/ # 403: directlycurl -s -o /dev/null -w '%{http_code}\n' https://<origin address>/health/live # 200: a health check
也請將 CDN 的位址列入 trusted_proxies,否則伺服器只會看到一個用戶端,每個請求都共用 CDN 的速率限制;my config check 會對此發出警告。
被拒絕的請求會得到與其他任何被禁止的請求相同的 403 problem 文件,並帶有 Cache-Control: no-store,不論標頭是哪裡錯了。回應中沒有任何東西指出標頭的名稱。
當所有人都被鎖在門外
Section titled “當所有人都被鎖在門外”錯誤的設定會拒絕每個請求,而健康檢查仍然是 200,所以平台看到的是健康的伺服器,監控 /health/live 的可用性監控也什麼都看不到。徵兆有:
- 透過 CDN 的每個頁面都是
403。 - 指標
my.http.origin_refused上升,而http.server.request.duration的請求停止。 - 日誌中有狀態為
403、且沒有http.route的http request行。日誌與追蹤中從不包含標頭、它的名稱或它的值。被拒絕的請求不會建立追蹤 span。
要復原,請在不做這項檢查的情況下部署:取消設定 MY_ORIGIN_SECRET 和 MY_ORIGIN_SECRET_HEADER。其他伺服器會重試它們的傳送,但這段期間使用者無法連到伺服器。
接著比對 CDN 上的名稱與值和設定,確認規則涵蓋每個主機名稱,然後再次設定它們。
CDN 和伺服器無法在同一瞬間變更,而伺服器的每個副本也會依各自的步調重新啟動,因此如果只接受一個值,變更期間只要兩者不一致,流量就會被拒絕。所以伺服器在輪替期間會接受兩個值:
- 將
MY_ORIGIN_SECRET設為新值,MY_ORIGIN_SECRET_PREVIOUS設為舊值,然後部署。兩個值都會通過。 - 在 CDN 變更值,並等待變更傳遞到它的所有據點。
- 取消設定
MY_ORIGIN_SECRET_PREVIOUS後部署。設定期間my config check會發出警告。
標頭名稱無法用這種方式輪替。要變更名稱,請在暫時關閉伺服器檢查的情況下重複設定步驟,或在部署新名稱之前,先在 CDN 上同時設定新名稱和舊名稱。
供 LLM 與程式設計代理使用:llms.txt,llms-full.txt, llms-small.txt