deploy.ts

渲染、上传、来源校验、日志、认证、会话、请求频率限制、访问统计和内容目录。

发布于 2026年8月25日更新于 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 方法列出无需检查请求来源的接口，类型为 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`

设置全局请求频率、认证接口、邮件发送、工单创建和 OAuth 2.0 接口的调用上限。

`globalBlock`

按 IP 和请求路径计数。达到 freeRetries 后暂时拒绝请求，lifetimeDuration 到期后重新计数。

Prop

Type

页面会频繁调用 /api/auth/current-user 刷新用户状态，也会轮询 /api/account/profile/email-verification 查询邮箱验证结果，因此模板默认不限制这两个路径。

`authBlock`

限制敏感认证页面和接口的访问频率，打开相关页面也会计入次数。

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`

限制统计上报接口的请求频率，计数时同时使用 Website ID 和可信客户端 IP。

Prop

Type