deploy.ts

頁面呈現、上傳、來源驗證、記錄、身分驗證、工作階段、請求速率限制、流量統計和內容目錄。

發布於 2026年9月20日

config/deploy.ts 設定頁面呈現、檔案上傳、請求來源驗證、記錄、電子郵件、介面、使用者身分驗證、工作階段、匿名身分、OAuth 2.0、請求速率限制、流量統計和內容目錄。各項依 websiteDeployCfg 中的順序列出。

`streamRender`

Prop

Type

`upload`

設定檔案大小上限、檔案讀取方式和儲存後端。

Prop

Type

`delivery`

設定透過 Worker 讀取已上傳檔案時，使用的路徑和快取回應標頭。

Prop

Type

`cache`

Prop

Type

`storage`

設定預設儲存後端，以及 KV 和 R2 各自的參數。

Prop

Type

`kv`

Prop

Type

`r2`

Prop

Type

`cors`

依路徑設定跨來源請求可以使用的 HTTP 方法，型別為 Record<Path, HttpMethod[]>。物件的鍵必須是以 / 開頭的站內路徑，方法可以填入 GET、POST、PUT、PATCH、DELETE、OPTIONS 或 HEAD。

範本預設值為空物件。原始碼註解提供下列範例：

cors: {
    // '/test': ['GET', 'POST'],
}

`hosts`

Prop

Type

本機開發環境預設允許 localhost 和 127.0.0.1，正式環境預設允許 VITE_SITE_URL 對應的主機，這裡只需填入額外規則。重複項目會被忽略。

寫法	意義
`saavo.dev`	完全符合主機名稱
`*.saavo.dev`	比對子網域
`localhost:5173`	完全符合主機名稱和連接埠
`localhost*`	比對使用不同連接埠的本機主機
`https://*.example.com`	比對時只取 URL 中的主機部分

`skipOriginCheck`

依路徑前綴和 HTTP 方法，列出不需檢查請求來源的 API，型別為 Record<Path, HttpMethod[]>。

路徑	HTTP 方法	用途
`/api/webhooks/stripe`	`POST`	Stripe Webhook
`/api/auth/oauth2/github`	`GET`	GitHub OAuth 回呼
`/api/auth/oauth2/google`	`GET`	Google OAuth 回呼

`trustedOrigins`

Prop

Type

規則包含 :// 時，會比對完整的 Origin，不包含 :// 時則只比對主機。萬用字元使用 picomatch 規則。

寫法	意義
`saavo.dev`	完全符合主機名稱
`*.staging.example.com`	依主機萬用字元規則比對
`https://partner.example.com`	完全符合 Origin
`https://*.example.com`	依 Origin 萬用字元規則比對
`chrome-extension://`	比對瀏覽器擴充功能的 Origin 前綴
`chrome-extension://*`	比對 Chrome 或 Edge 擴充功能
`moz-extension://*`	比對 Firefox 擴充功能
`chrome-extension://bamaajojgmohmjlnlfeojgibdojjkljk`	完全符合已發布的擴充功能 ID

`logger`

設定系統記錄、稽核記錄和警示記錄的寫入方式與保留時間。

Prop

Type

`system`

Prop

Type

`audit`

Prop

Type

`alert`

Prop

Type

`emailProvider`

Prop

Type

`ui`

設定預設佈景主題、登入方式，以及註冊、登入和登出後的重新導向路徑。

Prop

Type

`redirectTo`

Prop

Type

`oauthRedirectTo`

Prop

Type

`auth`

設定登入、電子郵件驗證、雙重驗證（2FA）和機器人驗證。

Prop

Type

`useTurnstile`

Turnstile 觸發規則。整項設定也可以設為 false，表示不使用 Turnstile。

Prop

Type

`emailVerification`

Prop

Type

`twoFactorAuth`

Prop

Type

`sessions`

各類工作階段的 Cookie 名稱和有效期間。duration 使用 DateIntervalType。

`saasSession`

Prop

Type

`authStepUpSession`

Prop

Type

`emailVerificationSession`

Prop

Type

`passwordResetSession`

Prop

Type

`twoFactorSetupSession`

Prop

Type

`oauthAuthRequestSession`

Prop

Type

`anonymousIdentity`

為尚未登入的瀏覽器分配匿名身分，與登入工作階段互相獨立。身分權杖經過簽署後寫入 Cookie，業務程式碼會從已驗證的請求執行脈絡中讀取。

Prop

Type

`token`

Prop

Type

`networkBucket`

Prop

Type

`fingerprint`

指紋只協助 network-bucket 區分訪客，不能單獨作為身分識別方式。範本內附的前端頁面不會傳送這個請求標頭。

Prop

Type

`oauth2`

設定專案內建的 OAuth 2.0 授權伺服器。

Prop

Type

`spam`

設定全域請求速率、身分驗證 API、郵件寄送、客服案件建立和 OAuth 2.0 API 的呼叫上限。

`globalBlock`

依 IP 和請求路徑計數。達到 freeRetries 後，暫時拒絕請求，lifetimeDuration 到期後重新計數。

Prop

Type

頁面會頻繁呼叫 /api/auth/current-user 更新使用者狀態，也會輪詢 /api/account/profile/email-verification 查詢電子郵件驗證結果，因此範本預設不限制這兩個路徑。

`authBlock`

限制敏感身分驗證頁面和 API 的存取速率，開啟相關頁面也會計入次數。

Prop

Type

`authThrottle`

Prop

Type

`resourceProtection`

`emailSendService`

Prop

Type

`ticketCreate`

系統會先檢查客服案件的建立次數，再上傳圖片並儲存案件。

Prop

Type

`oauth2AuthorizeUserBlock`

Prop

Type

`oauth2AuthorizeIpBlock`

Prop

Type

`oauth2TokenClientBlock`

Prop

Type

`oauth2TokenIpBlock`

Prop

Type

`analytics`

設定專案內建的第一方流量統計。

Prop

Type

`retention`

設定統計資料的保留期間，以及每次排程清理的處理上限。

Prop

Type

`site`

範本內附的 Worker 只統計一個 SaaS 網站。這裡設定網站識別字、啟用狀態、可以回報資料的網域，以及造訪次數的劃分方式。

Prop

Type

`tracker`

控制瀏覽器端的統計指令碼記錄哪些資訊，以及如何處理頁面 URL。

Prop

Type

`collection`

伺服器端依下列規則忽略指定造訪。頁面路徑符合 ignoredPathPrefixes 時，瀏覽器也不會載入 analytics.js。IP 和 Distinct ID 必須完全相符，User-Agent 則依不區分大小寫的片段比對。

Prop

Type

`dashboard`

定義統計面板中顯示的轉換漏斗。修改設定後，需要重新部署。

`funnels`

轉換漏斗陣列。漏斗的 id 不能重複，每個漏斗必須包含 2～8 個步驟。

Prop

Type

每個漏斗步驟包含下列欄位：

Prop

Type

事件步驟可以使用 filters 篩選事件屬性，路徑步驟不能使用。每個步驟最多 20 個篩選條件。

Prop

Type

範本預設漏斗的名稱和說明：

`id`	`name`	`description`
`affiliate-referral-conversion`	Affiliate referral conversion	From a valid Affiliate referral-link click to a newly created account and a subsequent checkout start.
`signup-conversion`	Signup conversion	From viewing the localized signup page to creating a new account; restored accounts are excluded.
`pricing-checkout-start`	Pricing to checkout	From viewing the localized pricing page to creating a Stripe checkout session; this does not claim payment completion.
`checkout-login-recovery`	Checkout login recovery	For signed-out purchase attempts, measures whether modal login is completed and checkout is subsequently started.

範本預設漏斗的時間範圍和步驟順序：

`id`	`window`	`windowMode`	`stepOrder`	步驟數
`affiliate-referral-conversion`	`7d`	`fromFirstStep`	`sequential`	3
`signup-conversion`	`1h`	`fromFirstStep`	`sequential`	2
`pricing-checkout-start`	`1h`	`fromFirstStep`	`sequential`	2
`checkout-login-recovery`	`1h`	`fromFirstStep`	`sequential`	3

affiliate-referral-conversion 的步驟：

`label`	`type`	`match`	`value`	`filters`
Clicked Affiliate link	`event`	`exact`	`affiliate_referral_clicked`	—
Created account	`event`	`exact`	`signup_completed`	`accountAction equals created`
Started checkout	`event`	`exact`	`checkout_session_created`	—

signup-conversion 的步驟：

`label`	`type`	`match`	`value`	`filters`
Viewed signup page	`path`	`endsWith`	`/auth/signup`	—
Created account	`event`	`exact`	`signup_completed`	`accountAction equals created`

pricing-checkout-start 的步驟：

`label`	`type`	`match`	`value`	`filters`
Viewed pricing	`path`	`endsWith`	`/pricing`	—
Started checkout	`event`	`exact`	`checkout_session_created`	`provider equals stripe`

checkout-login-recovery 的步驟：

`label`	`type`	`match`	`value`	`filters`
Purchase required login	`event`	`exact`	`login_modal_opened`	`reason equals checkout`
Completed modal login	`event`	`exact`	`login_completed`	`entryPoint equals modal`
Started checkout	`event`	`exact`	`checkout_session_created`	—

`rateLimit`

限制統計回報 API 的請求速率，計數時同時使用 Website ID 和可信任的用戶端 IP。

Prop

Type