配置参考

环境配置具有最终决定权。Warmbly 绝不会允许网页表单覆盖由环境控制的设置，因此无须推断优先级，也不会有文件在后台悄然自行改写。

在查看表格前，需要明确这条规则带来的三个结果：

• 本页所有项目都在运行进程的环境中设置。 Docker Compose 使用 docker-compose.yml 旁的 .env；Kubernetes 使用 Pod 规格或 Secret；直接运行二进制文件时则使用 Shell 环境或 systemd 服务单元。
• 大多数解析后的值可在管理面板中只读查看，位置为 实例 > 配置 > 环境（默认安装中为 http://localhost:5174/configuration?tab=environment）。每行显示变量名、Warmbly 实际解析的值、来源（env、default、derived 或 unset），以及修改后是否需要重启。通过该页面即可确认变量是否真正生效，无须阅读源码。
• 少量设置保存在数据库中，因为它们不受环境变量控制。这些项目列在存储在数据库中的设置中，也是唯一能通过浏览器编辑的设置。

任何 API 都不会返回机密值。配置页面仅显示敏感密钥是否已设置，以及其值的四字符指纹；这足以确认两个服务使用相同的 AUTH_SECRET，而不会向任何人披露实际值。

查看实际生效的配置

实例健康状态中标记的问题都会链接到本页对应的修复说明。

部署

在 Gin release 模式下，访问日志会省略成功的健康探测和内部 GET 查询，包括预期的邮件消息映射缺失。身份验证失败、服务器错误、其他资源缺失以及全部修改操作仍会记录。Gin debug 模式保留每条访问日志。两种模式都会隐藏查询字符串及凭据路径参数；组织审计事件不受影响。

密钥与机密值

五项值保护整个实例。Compose 为每项提供可用默认值，使刚克隆的仓库无须配置即可启动；但这些默认值都已公开在仓库中，因此不提供任何保护。

在允许其他人访问实例前，请生成真正的随机值：

cat >> .env <<EOF
AUTH_SECRET=$(openssl rand -base64 32)
INTERNAL_API_TOKEN=$(openssl rand -hex 24)
SECRET_KEY_BASE=$(openssl rand -base64 64 | tr -d '\n')
KMS_LOCAL_MASTER_KEY=$(openssl rand -base64 32)
CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -hex 32)
APP_ENV=prod
EOF

如果只需要新的 KMS_LOCAL_MASTER_KEY，运行 make gen-key 即可输出一个。

最后设置 APP_ENV=prod。它会将使用公开默认值的行为从日志警告提升为拒绝启动，因此如果其他五项尚未配置就设为 prod，实例将无法启动。

各服务分别读取自身副本，因此以下值必须在服务之间完全一致：

地址

邮件中的所有链接（密码重置、邀请、首次运行认领链接）都由 APP_URL 构建。未设置时，自托管实例会尝试从 CORS_ALLOW_ORIGINS 或 PUBLIC_HOST 推断来源，绝不会回退到托管服务：无人能打开的链接只会带来支持请求，而指向他人控制台的可用链接会将有效重置令牌带出你的部署。请务必设置。

网络与代理

直接暴露后端时，留空是正确选择；使用反向代理时则不适合。如果没有可信 CIDR，Warmbly 会将代理地址记录为客户端地址，按 IP 登录限流、会话记录、审计记录和 API 密钥 IP 允许列表都会使用错误地址。请设置为代理连接所用的 CIDR：

TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12

身份验证

完整行为说明（包括每种注册模式对注册表单的影响）请参见账户与访问。

代理 PostHog 请求

内容拦截器会丢弃发往 posthog.com 的请求，导致相当一部分访客的分析和错误上报悄然停止。为此，后端在 /ingest 提供反向代理。请让各前端指向它：

其他配置不变：密钥保持相同，代理原样转发载荷。代理放在后端，而非三个前端中分别实现，以免三份副本逐渐产生差异。

代理只转发 PostHog 读取请求所需的内容。Cookie 和 Authorization 留在实例这一侧，因此实例会话绝不会交给第三方；调用者地址放入 X-Forwarded-For，以便定位访客位置，而不是服务器位置。

人机验证

CAPTCHA_PROVIDER 没有固定默认值。未设置时，如果 TURNSTILE_SECRET 有值（无论来自环境还是 AWS Secrets Manager），则解析为 turnstile，否则为 none。因此配置密钥会开启人机验证，清除密钥则关闭。面板将解析值的来源显示为 derived。

唯一会出问题的组合，是在 TURNSTILE_SECRET 为空时显式设置 CAPTCHA_PROVIDER=turnstile：所有验证都会失败，导致无人能登录。请设置密钥，或将提供方改回 none。

原生 iOS 应用从不显示 Turnstile。它使用 Apple App Attest 证明自己是真实应用副本，在登录、注册和密码重置时替代人机验证。CAPTCHA_PROVIDER=none 时应用不发送任何证明。开启 Turnstile 后，只有 APP_ATTEST_APP_IDS 包含应用的 App ID 时，应用才提供邮箱地址和密码登录；否则只提供 Apple 登录、Google 登录和通行密钥，这些方式从不需要人机验证。自托管实例如果启用 Turnstile 且希望 iOS 应用支持密码登录，需将 APP_ATTEST_APP_IDS 设置为 iOS 应用的 App ID。验证不需要 Apple 账户，也不发起外部调用：使用二进制文件内置的 Apple App Attest 根证书检查。每次安装的密钥保存在 app_attest_keys 表中，属于实例，不包含在工作区导出中。iOS 模拟器不支持 App Attest，因此本地开发继续使用 TURNSTILE_BYPASS_TOKEN。

平台邮件

平台邮件是产品自身发送的邮件：注册验证码、密码重置、团队邀请、通知摘要，以及启用时的登录验证码。它与营销活动邮件相互独立，后者通过你连接的邮箱发送。

自托管实例绝不会自动填入我们的信息。Warmbly 自身的公司信息和网站属于托管服务，不属于你，因此未设置的 EMAIL_BRAND_* 不显示任何内容，避免给你的用户发送带有无关公司名称的页脚。如果所在司法辖区要求商业邮件包含身份说明，请设置为你自己的信息。

虽然带有邮件前缀，这些配置不只用于邮件。GET /v1/auth/config 提供其中可公开的内容（名称、网站、条款、隐私政策、支持地址），原先硬编码 warmbly.com 的各处都改为读取它：登录页的文字标志和条款、隐私链接，API 密钥页面中可复制的 API 示例，共享统计卡片，以及托管表单页面底部的“技术支持”说明。未设置对应值时均不显示，确保填写你的表单的人不会被引向与其无关的网站。

log 是有效的传输方式，并非故障状态：它将每封邮件写入后端日志，不实际投递。这样新安装在没有中继时也能完成首次登录。缺少的功能是密码重置邮件、邀请投递和摘要通知；其替代操作见账户与访问。

从日志中读取验证码：

docker compose -p warmbly logs backend | grep -B2 -A12 "MAIL_TRANSPORT=log"

发送前验证

营销活动向某地址发送前，后端可以先检查地址：检查语法，再检查 MX，最后对收件人邮件服务器执行 SMTP RCPT 探测。返回 invalid 的地址会被跳过，不会发送，从而将可能的硬退信转为静默跳过。探测由后端发起，绝不从工作节点发起，因为工作节点使用你的发信 IP。

明确判定在 90 天后复查，不确定判定在 30 天后复查；每分钟分批处理 200 位联系人，有积压时持续运行。在集成中连接了 MillionVerifier 的工作区始终使用自身额度，无论是否设置实例级密钥。

EMAIL_VERIFY_HELO_HOST 与 SMTP_EHLO_NAME 不同。SMTP_EHLO_NAME 是平台邮件中平台邮件中继看到的问候；本项是收件人服务器从验证器看到的问候。

加密

CREDENTIALS_ENCRYPTION_KEY 为空不会导致启动失败，而会禁用加密，使邮箱密码以未加密形式存储。连接任何邮箱前，请先设置并备份。

存储

使用 filesystem 时，远程工作节点会将 Blob 写入自身磁盘，而非后端可读的卷。工作节点在其他主机运行时，请使用 s3，并配置双方可访问的存储桶。

事件总线

Kafka 事件发布会等待消息代理的交付报告，以及所有同步副本确认，受调用方截止时间和 EVENTBUS_HANDLER_TIMEOUT 限制。进入本地队列不代表已经发布。结果被拒绝或超时时，原命令保持未确认，以便重放；超时不能证明事件从未交付，因此消费者仍需对重放结果去重。通用生产者事件在关闭期间单独排空，不会消耗某次发布独立的交付报告。

json 无须额外组件，是默认值。avro 根据 SCHEMA_REGISTRY_URL 解析每个事件，只包含在 -kafka 镜像中。生产者和消费者必须采用同一种编解码器：消息内没有格式标记，使用另一种编解码器的消费者无法读取总线中已有消息。切换前应排空总线，不能原地更改。封装消息主题需要 BACKWARD 兼容性，因为新事件类型会增加联合类型分支；发布器遇到 FORWARD 或 FULL 时，会自行将主题设为 BACKWARD。后端、消费者和实时服务的 PUBSUB_ENABLED 必须一致。

Go 服务将每个解码后的 Avro 数组或映射限制为 65,536 项，跨数据块累计；每个字符串或字节字段限制为 1 MiB。超限载荷会被拒绝。当前维护的编码器使用现有模式和 Confluent 封装。符合这些限制的队列消息仍可读取，无须排空总线或重新注册主题。升级期间请保持相同编解码配置。

数据库

迁移已嵌入后端二进制文件，并在启动时应用。无须单独执行迁移；如有需要，镜像中也提供独立的 /app/migrate 二进制文件。

实时服务升级兼容性

仍支持以主机、/socket 或 /socket/websocket 结尾的现有 WEBSOCKET_URL 值，包括自定义路径前缀、端口和查询参数。HTTP(S) 形式会转换为 WS(S)。发现响应和票据响应使用相同的规范化处理。

控制台可通过 API 来源上的 /v1/realtime/socket/websocket 连接。无须新增环境变量、CSP 允许列表条目或数据迁移。API 只转发到已配置的实时网关，并保留浏览器 Origin。旧 Docker 安装若声明的是回环网关，而 API 容器无法访问自身回环地址，可回退到相同端口上的现有 realtime 服务。

请将后端、实时服务和控制台镜像一起升级到同一版本；实时服务更新会为经过 API 代理的连接保留按客户端 IP 的限制。现有直连客户端和较旧的控制台／后端组合继续使用直连 URL。自定义反向代理应同时允许 API 路由和直接实时路由上的 WebSocket 升级；直连仍作为重试后备。请保持 CHECK_ORIGIN_HOSTS 和共享的 AUTH_SECRET／JWT_SECRET 一致。重试标签不代表已恢复：实时连接表示套接字已打开，正在重连表示仍在重试。

缓存

Redis 保存限流计数器、组织密钥缓存、实时消息桥接状态和首次运行设置令牌。在尚未认领的实例上清空 Redis，会同时销毁认领链接和全部待完成身份验证会话。

GeoIP

后端在所有环境中都必须设置 GEODB_PATH。文件本身可选：路径下没有文件时，会话和审计记录不包含城市信息，其他行为不变。消费者也可选读取同一变量，为每次邮件打开和点击补充国家与城市；未配置时，这些记录只有客户端和设备信息。

这是两种不同数据库和两个不同文件。GeoLite2-City 回答地址位于何处；GeoLite2-ASN 回答由哪个网络宣告该地址，用于匹配跟踪服务的 asn: 扫描器条目。两者不包含对方数据，因此读取器指向错误文件时不会得到结果。同一个 MaxMind 账户可免费获取 GeoLite2-City 和 GeoLite2-ASN 两个版本，geoipupdate 可下载任意一种。

GEODB_PATH 应配置在后端和消费者上，TRACKING_SCANNER_ASN_DB 应配置在跟踪服务上；对应文件缺失时都会被忽略。缺少城市数据库会失去位置标签，缺少 ASN 数据库会失去 asn: 匹配。如果将 TRACKING_SCANNER_ASN_DB 指向 City 数据库，启动时会拒绝并记录实际发现的类型，而非悄然不匹配任何内容。

导入地理位置数据库

能够挂载文件是最简单的方式，不需要下列任何变量。大多数容器托管环境没有可挂载来源，此时设置相应的 _URL 变量，服务会在启动时下载自己的副本。

# MaxMind's download endpoint, which always serves the current build of an
# edition, so a restart is how an instance picks up a newer one. Both halves of
# the credential come from the same page of your MaxMind account: the account
# id is the username and the licence key is the password.
GEODB_URL=https://ACCOUNT_ID:[email protected]/geoip/databases/GeoLite2-City/download?suffix=tar.gz
TRACKING_SCANNER_ASN_DB_URL=https://ACCOUNT_ID:[email protected]/geoip/databases/GeoLite2-ASN/download?suffix=tar.gz

任何提供 MaxMind 格式数据库的 URL 都可使用；文件形式根据内容而非文件名识别，因此 .tar.gz、.mmdb.gz 和未压缩的 .mmdb 均受支持。如上例，URL 用户信息部分中的凭据以 HTTP Basic 认证发送。DB-IP 免费的 Lite 数据库 完全不需要账户，以 dbip-city-lite 和 dbip-asn-lite 名称发布相同格式；其国家数据质量相当，城市数据较弱。

需要了解两点：

• 其他组件不会等待下载。 服务启动时位置查询先返回 Unknown，数据库下载完成后再加载。因此镜像源缓慢或不可用只会影响城市标签，不会导致部署健康检查失败。
• 已有文件会保留使用，直到过期。 不满七天的数据库直接使用，不发送任何请求，因此挂载副本、重启后保留的卷及手动放入的副本均优先。超过七天后通过 If-Modified-Since 重新验证，通常返回 304 Not Modified，不产生费用，也不计入 MaxMind 每日额度；只有确有更新数据库时才下载。未设置 URL 时绝不会发起请求，文件完全由你管理。
• 下载被拒绝时会重试。 最多尝试四次，逐次增加等待时间，并遵守服务器返回的 Retry-After。此前下载只在启动时执行一次且不再重试，因此镜像源限流或短暂不可达会导致容器整个生命周期都没有地理数据。对于必然重复的拒绝，如许可证密钥无效或名称无法解析，不会重试。
• 下载内容不是数据库时会被丢弃，不会安装。 过期许可证密钥可能返回错误页面；若将其保存，下次启动会因文件已存在而不再重试，导致位置查询永久失效。因此内容会在放到目标位置前尝试打开；失败时路径保持为空，并记录一行日志。
• 携带凭据的 URL 不允许使用明文 http，无论凭据位于查询参数还是用户信息部分，因为这会在网络上传输明文许可证密钥。URL 中不含任何机密的 http 镜像源可以使用；但无论如何，从 https 降级重定向到 http 都会被拒绝。

跟踪服务的路径处理有所不同：ASN 数据库保存在内存中，从不写入磁盘，因此单独设置 TRACKING_SCANNER_ASN_DB_URL 即可，TRACKING_SCANNER_ASN_DB 可以不设。

使用数据库镜像，而非直接从 MaxMind 拉取

GeoLite2 账户每 24 小时允许直接下载 30 次，超限返回 429；付费 GeoIP 账户允许 2,000 次。每次消费者启动会下载 GeoLite2-City，每次跟踪服务启动会下载 GeoLite2-ASN，因此一次发布消耗两次下载，重启循环每次重启消耗一次。繁忙时很容易达到上限，而且后果不只是下载失败：启动时遇到 429 的容器，在被替换前都没有地理数据。

可以将 URL 指向你自己的副本。.github/workflows/geoip-mirror.yml 按 MaxMind 自身发布节奏，在周二和周五运行，每次分别下载两个版本一次，并上传到私有存储桶。之后整个集群都从该处读取，无论部署多频繁，MaxMind 每周只看到两次请求。同区域拉取 60 MB 文件通常也只需一两秒，无须等待 MaxMind 响应。

该任务需要以下仓库设置；未设置 MAXMIND_ACCOUNT_ID 时会自行跳过，因此分叉仓库不会因此失败：

然后将 GEODB_URL 和 TRACKING_SCANNER_ASN_DB_URL 指向镜像对象。两者都接受位于用户信息或查询参数中的凭据，因此可使用预签名 URL，或使用无法猜测对象键下的对象，而无须让服务持有存储桶凭据。只有镜像任务持有 MaxMind 许可证密钥，这也是推荐此方式的另一原因：密钥从多个服务的部署配置，变为单个仓库机密。

请保持副本私有。GeoLite2 不允许再分发，因此发布镜像中也从不内置数据库。如果希望完全不使用账户，DB-IP Lite 数据库采用 CC-BY 4.0 许可，无须账户。

工作节点

工作节点按设计不持有数据库连接。它们需要的所有关系数据均通过后端内部 HTTP API 获取。

节点加入时会获得哪些配置

warmbly join 根据后端自身环境生成 /etc/warmbly/node.env，因此本页多数配置会自动传递给节点，无须设置两次。有三项采用转换或判断，而非直接复制：

• 加密和 Blob 提供方会进行转换。 使用 KMS_PROVIDER=aws 的实例向节点下发 brokered，使用 BLOB_PROVIDER=s3 的实例也向节点下发 brokered，使集群机器无须持有云凭据。不需要凭据的提供方原样传递。
• 工作节点绝不会收到 PRIMARY_DB。 消费者会收到，因为它直接访问 Postgres。如果实例将 DSN 保存在机密管理器而非环境中，就没有可下发的值，加入脚本会明确提示。
• 地址按原样继承。 NATS_URL、REDIS 和 ENCRYPTED_KEYS_BACKEND_URL 完全沿用后端的值。如果地址只能在容器网络内解析，节点虽然能顺利注册，却无法访问任何服务。

控制平面无法获知的设置

每次加入都会重写 node.env。旁边的 /etc/warmbly/node.local.env 只创建一次，之后绝不重写；容器在第二步读取它，因此其中重复的变量名会覆盖前者。

每台机器特有的值应写在此处，例如当前实例没有的 DSN、自有基础设施凭据，或有意覆盖回直接访问提供方的配置。

printf 'PRIMARY_DB=%s\n' "postgres://..." >> /etc/warmbly/node.local.env
systemctl restart warmbly-consumer

邮箱连接

后端以及每个工作节点都需要配置：后端发起 OAuth 流程，各工作节点在令牌到期时刷新令牌。

普通 SMTP 和 IMAP 邮箱无须这些配置。如果工作节点缺少这些值，邮箱初次连接会正常，但约一小时后首个访问令牌到期时会悄然停止。

为各控制台部署配置 Google 登录

控制台有独立的显示开关，只影响连接对话框和邮箱导入中的逐邮箱 Google 登录，不影响 Microsoft 登录、Google 控制台登录或 Workspace 整域授权。

两个控制台部署可以共享同一后端，并为此开关设置不同值。例如：

# Public dashboard environment
WARMBLY_GMAIL_OAUTH_CONNECT=false

# Assessment dashboard environment (a separate deployment)
WARMBLY_GMAIL_OAUTH_CONNECT=true

两个控制台都将 WARMBLY_API_URL 指向同一 API，并将 WARMBLY_APP_URL 设为各自的控制台 URL。容器在启动时生成 /config.js，因此不需要第二份镜像。Cloudflare Pages 在 build:pages 期间生成配置；请在目标 Pages 项目上设置变量并重新部署。

客户控制台也会根据相同部署设置生成内容安全策略。静态引导脚本和样式使用构建生成的哈希；通常不允许作为标记注入的脚本和样式。API、Sentry 和 PostHog 来源从各自配置的 URL 派生。nginx 启动前，控制台会访问已配置 API URL 的公开 /v1/auth/config 端点，只允许准确的 websocket_url 来源。因此，已有后端 WEBSOCKET_URL 配置无须再重复设置 CSP。如果 Web 容器也接收到 WEBSOCKET_URL，则直接使用它提供的来源，无须 HTTP 请求。

pnpm build:pages 在构建时执行相同发现，使用构建主机上的 curl 和 jq（控制台容器已包含两者）。发现过程采用有界重试；后端不可达或返回无效配置时，绝不会放宽 CSP。后端不可用会产生启动或构建警告；待其就绪后，请重启控制台或重新构建 Pages。离线或自定义部署可通过 WARMBLY_CSP_CONNECT_ORIGINS 显式允许实时服务来源，例如 wss://realtime.example.com。请将其传入 Web 服务环境，而不只是写入 Compose 的 .env。更改来源需要重启容器或重新构建 Pages。Pages 仍完全静态，无须 Function。

Pages 控制台会从静态响应中移除 Cloudflare 默认的 Access-Control-Allow-Origin: * 标头。控制台资源不是跨来源公共 API。这不会更改后端的 CORS_ALLOW_ORIGINS，也不会更改客户邮件使用的公开图片 URL。

邮件正文在独立的静态沙盒中呈现，脚本被禁用。该文档允许邮件样式和读者选择的远程内容，但不会放宽控制台策略。控制台图片可从自身来源、已配置 API、data URL 或临时 Blob URL 加载。外部界面图片和编辑器预览使用后端图片预览端点；该端点只允许 HTTPS 公网目标，检查每次连接和重定向，并将图片限制为 5 MiB、请求限制为十秒。自有公开图片通过已配置 Blob 存储读取，因此文件系统存储和私有 MinIO 端点不需要公网限制例外。开发用不安全 Webhook 开关不会放宽图片抓取限制。

此代理仅用于显示。已有记录无须迁移，保存和发送的邮件 HTML 保留原有图片 URL、链接和样式。收件人不使用控制台代理，也不需要会话即可加载邮件图片。来信继续使用独立的远程内容同意机制，不使用此代理。为支持编辑器生成的邮件设计，控制台仍允许内联 style 属性，但不允许内联脚本或任意样式块。开发环境为 Vite 注入的脚本和样式表使用每次响应新生成的随机数。

共享后端应保持 APP_URL 指向主控制台，并将两个准确的控制台来源都加入 CORS_ALLOW_ORIGINS，例如 https://app.example.com,https://assessment.example.com。Google 和 Microsoft 邮箱连接、重新授权、整域管理员授权、集成 OAuth 以及 Slack 身份验证，都会将发起浏览器的来源绑定到服务端 OAuth 状态。回调只向该允许来源发送消息；没有 opener 的弹出窗口返回其 /oauth-return 页面。路由状态缺失、过期或已使用时，显示重试提示，不会将授权码转发给另一个控制台。不含来源的有效旧状态仍使用主控制台。OAuth 返回来源不接受通配符。服务商注册的回调 URI 仍位于同一 API。

邮箱地址和密码登录、OTP／2FA、注册、退出以及普通控制台导航都使用本地路由。从允许列表中的控制台发起的密码重置和邀请邮件，会链接回该控制台。Stripe 结账、积分充值、账单门户和预热套餐返回均使用发起控制台，并保留安全的同来源路径。推荐分享链接也使用该控制台的注册页。没有可信浏览器来源的请求使用主控制台。

对于 Warmbly 托管的评估控制台，共享后端需要同时允许以下两个来源：

APP_URL=https://app.warmbly.com
CORS_ALLOW_ORIGINS=https://app.warmbly.com,https://tac-security-assessment.warmbly.com

这只是环境配置示例，不是内置允许列表。请保留管理控制台等其他已有来源：将 https://tac-security-assessment.warmbly.com 追加到当前 CORS_ALLOW_ORIGINS，而不是替换整个列表。在 Railway 上，修改后端服务变量并重新部署；修改前端变量或合并代码不会更新线上后端环境。APP_URL 和 APP_ORIGIN 应继续指向主控制台，而非评估控制台。评估前端设置 WARMBLY_APP_URL=https://tac-security-assessment.warmbly.com 和 WARMBLY_GMAIL_OAUTH_CONNECT=true。

向评估人员开放访问前：

• 将评估前端的 WARMBLY_API_URL 指向共享 API，并使用不带末尾斜杠的准确 WARMBLY_APP_URL 来源。
• 在现有 Cloudflare Turnstile 小组件中允许评估主机名。仅允许 app.warmbly.com 的组件不会覆盖同级评估主机名。请保持人机验证开启。
• 将评估来源追加到实时服务的 CHECK_ORIGIN_HOSTS，保留已有来源。API 来源允许列表不会配置 WebSocket 来源检查。
• 对于仅使用密码的评估账户，可使用 管理 > 测试人员，或在用户下的现有账户页面启用跳过邮件登录验证码。这些账户免于邮件登录验证码步骤，但仍使用人机验证和现有权限检查。已启用 2FA 的账户仍需要第二因素。
• 请保持现有 WEBAUTHN_RP_ID 不变。app.warmbly.com 的通行密钥 RP ID 无法用于同级评估主机名，更改它会使已有凭据失效。评审人员可使用邮箱地址和密码；跨两个主机支持通行密钥需另行决定迁移方案。

这不会全局改写所有主控制台链接。控制台的 Google、Apple 和 OIDC 登录仍路由到主控制台；评估人员应使用邮箱地址和密码。服务器生成的通知、从 Slack 打开的链接、CLI 或引导链接，以及自托管 Cloud 代理返回仍使用实例的规范路由。Cloud 代理返回来源继续绑定已注册实例，而非托管评估控制台。

即使前端开关关闭，已有 Google OAuth 邮箱仍可重新授权。应用密码和 SMTP／IMAP 选项继续可用。关联 Warmbly Cloud 时，Google 同意流程由 Cloud 而非本地后端代理，但仍需启用前端选项。

整域连接

工作区可以通过一次管理员授权，连接Google Workspace 域名或 Microsoft 365 组织中的所有邮箱（添加账户 > Google > 整个 Workspace 域名、添加账户 > Microsoft > 整个组织）。以下配置仅由后端读取：后端自行签发这些邮箱的所有令牌，并在每次需要时交给工作节点，因此工作节点无须此处配置。完整分步设置见整域邮箱连接。

Google，每个实例配置一次：

1. 在 Google Cloud 控制台 中创建项目，或选择将长期使用的项目。项目 ID 无法更改。
2. 在 API 和服务 > 库 下启用 Gmail API 和 Admin SDK API。
3. 在 IAM 和管理 > 服务账户 下创建服务账户，例如 warmbly-workspace。不要授予它任何项目角色。
4. 在其密钥选项卡中选择 添加密钥 > 创建新密钥 > JSON。新的 Google Cloud 组织默认通过禁用服务账户密钥创建策略阻止此操作，组织策略管理员可以为此项目解除限制。
5. 将密钥文件路径写入 GOOGLE_WORKSPACE_DELEGATION_KEY_FILE（只读挂载），或将 JSON 写入 GOOGLE_WORKSPACE_DELEGATION_KEY，然后重启后端。

每位客户的授权都绑定服务账户的客户端 ID，因此服务账户只创建一次，后续轮换密钥，不要更换账户：重新创建会生成新的客户端 ID，所有域名都必须再次授权。该密钥可为任何已授权域名中的任意地址签发令牌，因此请像保护 CREDENTIALS_ENCRYPTION_KEY 一样保护它；它是所有此类邮箱背后的统一凭据。

只有工作区证明自己控制该域名，且目录将管理员地址列为超级管理员时，才会为该工作区记录 Google 授权。可采用以下任一证明方式：

• 管理员的 Google 登录通过控制台自身的登录客户端（GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET）及现有重定向 URI（GOOGLE_REDIRECT_URI，或 API_PUBLIC_URL 加 /v1/auth/google/callback）进行，仅请求 openid 和 email 范围。回调识别证明流程后，会交回控制台窗口，而不是让任何人登录，因此无须注册新重定向 URI。未配置该客户端时，以相同方式使用 BOX_GOOGLE_* 邮箱客户端。两者均不依赖 BOX_GOOGLE_OAUTH_CONNECT。
• 在 _warmbly.<domain> 发布 TXT 记录 ，内容为工作区和域名独有的 warmbly-verify= 值。此方式始终可用；两种客户端均未设置时，这是唯一证明方式。该值使用 AUTH_SECRET 作为生成密钥。

Microsoft 365 组织复用 Outlook 应用的 BOX_OUTLOOK_CLIENT_ID 和 BOX_OUTLOOK_CLIENT_SECRET，设置两者后即启用。应用注册需要增加三项配置：

• 支持的账户类型：任何组织目录中的账户（多租户），以便其他组织同意该应用。
• 重定向 URI：使用已有地址，即 API 基础地址加 /addresses/outlook/callback。管理员同意也返回此处。
• API 权限：在单邮箱登录已有的委托权限之外，添加 Microsoft Graph 应用权限 Mail.ReadWrite、Mail.Send 和 User.Read.All。

除非使用自己的租户测试，否则不要在自身租户授予这些权限的管理员同意。每个客户组织由其全局管理员通过控制台分别同意。授权对应的组织是管理员实际登录的组织，从同意登录流程本身读取，绝不从请求读取。发布者验证可选。

应用权限能够访问已同意组织中的每个邮箱。建议各组织通过 Exchange Online ApplicationAccessPolicy 或 RBAC for Applications，将应用限制到 Warmbly 应访问的邮箱；策略范围之外的邮箱连接时会被拒绝。客户操作步骤见连接整个 Microsoft 365 组织。

GET /emails/grants/config 通过 google_missing 和 microsoft_missing 报告仍缺少的配置：列出上述未设置项目的名称；提供方就绪后返回空列表。

集成

三个 Slack 值均来自 Slack 应用的基本信息页面。请在后端和消费者上设置，并重启两者；随附的 docker-compose.yml 会将三个值传递给两个服务。请求 URL 优先基于 BACKEND_PUBLIC_URL，未设置时使用 API_PUBLIC_URL。从清单创建应用的方式见 Slack 应用。

Google Sheets 应用

Google Sheets 从 联系人 > 同步源 连接，而非集成目录。按需同步只在你主动运行时读取选定工作表并导入联系人。

仅仅权限不同，并不要求独立 Google Cloud 项目，但同一项目中的 OAuth 客户端共享同意配置和验证。若希望 Sheets 的同意和验证与现有 Google 登录或 Gmail 配置分离，请使用具有独立同意配置和 Web 应用客户端的专用项目。同一项目中的第二个客户端不能提供这种隔离。Google 也建议在为已批准应用评估新权限范围时使用独立测试项目。独立项目仍需完成所请求权限范围要求的验证。

1. 在 Google Cloud 项目 中启用 Google Sheets API。
2. 配置项目的 Google Auth Platform 品牌和受众。处于测试状态的外部应用，应将要连接的 Google 账户添加为测试用户。公开发布时，请遵循Google 敏感权限范围验证要求。
3. 创建类型为Web 应用的 OAuth 客户端，或复用该项目中已有的 Web 应用客户端。在其授权重定向 URI中添加准确的后端回调：优先使用 INTEGRATIONS_OAUTH_REDIRECT_URL；未设置时为 BACKEND_PUBLIC_URL（否则 API_PUBLIC_URL）加 /integrations/oauth/callback。例如 https://api.example.com/integrations/oauth/callback。这不是控制台 URL、Google 登录回调或 Gmail 邮箱回调。
4. 当前客户端请求 https://www.googleapis.com/auth/spreadsheets 和 https://www.googleapis.com/auth/userinfo.email，请在同意配置中包含这些范围。Sheets 范围属于敏感权限，授予读写访问，即使联系人同步并不会回写。它不是受限的 Gmail 权限范围；已有 Google 登录或 Gmail 批准不会自动批准 Sheets 访问。
5. 在后端进程环境中，将客户端 ID 和密钥分别设为 GOOGLE_SHEETS_OAUTH_CLIENT_ID 和 GOOGLE_SHEETS_OAUTH_CLIENT_SECRET，然后重启或重新部署后端。容器部署必须显式将两个变量传入服务；只写入 Compose 的 .env 不会自动转发。不要将密钥放入控制台构建变量。更改这些设置需要重启，无须数据库迁移。

不会回退到 GOOGLE_CLIENT_ID／GOOGLE_CLIENT_SECRET，也不会回退到 BOX_GOOGLE_CLIENT_ID／BOX_GOOGLE_CLIENT_SECRET。缺少任意一项 Sheets 凭据时，通过 Google 连接会在联系 Google 前返回 501，提示 OAuth 尚未配置。Warmbly Cloud 由服务运维方为所有工作区统一配置客户端一次，工作区成员只需授权自己的 Google 账户。

配置后，连接同步源：授权能够访问电子表格的账户，粘贴表格 ID，选择工作表，映射列（包括邮箱）并保存。需要导入新行时运行立即同步。第一行应为列标题，之后每行对应一位联系人。

HubSpot 应用

自托管实例中的 HubSpot 模式 使用你在自己 HubSpot 开发者账户中创建的 HubSpot 应用：

• 重定向 URL：使用 INTEGRATIONS_OAUTH_REDIRECT_URL 的值；未设置时为 BACKEND_PUBLIC_URL（否则 API_PUBLIC_URL）加 /integrations/oauth/callback
• 必需权限范围: oauth, crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.companies.read, crm.objects.companies.write, crm.objects.deals.read, crm.objects.deals.write, crm.objects.owners.read, crm.schemas.contacts.read, crm.schemas.contacts.write
• 可选权限范围：crm.lists.read（从 HubSpot 列表导入）和 sales-email-read。无法授予这些权限的账户仍可连接
• Webhook（可选）：目标 URL 为 <backend>/api/v1/integrations/hubspot/webhooks，订阅 contact.creation、contact.propertyChange、contact.deletion、deal.creation、deal.propertyChange 和 deal.deletion。每个 HubSpot 请求都根据公开 URL 上的 X-HubSpot-Signature-v3 签名验证；该 URL 为 BACKEND_PUBLIC_URL（否则 API_PUBLIC_URL）加路径，因此必须与 HubSpot 实际调用的地址一致。没有 Webhook 时，消费者每分钟拉取一次以保持数据最新

HubSpot 联系人的 warmbly_link 属性也链接到 APP_URL。通过 warmbly join 加入集群的消费者会连同其余环境一起收到 HubSpot 变量和 APP_URL；工作节点不会收到。

仓库的 hubspot-app/ 目录包含同一应用的 HubSpot 开发者项目：应用定义、联系人记录上的 Warmbly 卡片、“添加到 Warmbly 营销活动”工作流操作及 Webhook 订阅。将其 *-hsmeta.json 文件和 src/app/cards/WarmblyCard.tsx 中的 https://api.warmbly.com 替换为你的后端 URL，再通过 HubSpot CLI 上传（在该目录执行 hs project upload）。CLI 会忽略隐藏目录中的文件，因此上传路径不能包含点开头的目录，否则卡片构建会报告入口文件缺失。卡片只允许请求 <backend>/api/v1/integrations/hubspot/app/（配置于 app-hsmeta.json 的 permittedUrls.fetch）。卡片和工作流操作调用以下公开路由，每个请求都使用应用客户端密钥验证。卡片路由从 HubSpot 附加到查询参数的值读取门户和用户；Webhook 和工作流操作路由从请求体读取门户，并拒绝携带这些查询值的请求：

Pipedrive 应用

自托管实例中的 Pipedrive 模式 使用你在 Pipedrive Developer Hub 中创建的 Pipedrive 应用：

• 回调 URL：使用 INTEGRATIONS_OAUTH_REDIRECT_URL 的值；未设置时为 BACKEND_PUBLIC_URL（否则 API_PUBLIC_URL）加 /integrations/oauth/callback

• 权限范围：商机、联系人和活动的完全访问权限，以及用户读取权限。授予后还会使用潜在客户完全访问权限（有兴趣的回复会添加潜在客户）、联系人字段完全访问权限（Warmbly 人员字段）和 Webhook 完全访问权限（即时更新）；未授予时跳过相应步骤。Pipedrive 从应用配置而非请求中获取权限范围

• Webhook：无须预先配置。工作区切换到此模式时，Warmbly 为每个连接在 <backend>/api/v1/integrations/pipedrive/webhooks/<connection id> 自动注册，切换离开时移除。它们要求 BACKEND_PUBLIC_URL（否则 API_PUBLIC_URL）为 Pipedrive 可访问的 https 地址；否则消费者改为每五分钟检查 Pipedrive

• 应用扩展（可选）：人员和商机页面上的 Warmbly 面板。在应用扩展下添加 JSON 面板，API 端点为 <backend>/api/v1/integrations/pipedrive/app/panel，JSON 数据结构来自 pipedrive-app/panel.schema.json，展示位置为人员详情和商机详情。再添加两个具有相同展示位置的 JSON 弹窗：“添加到 Warmbly 营销活动”（<backend>/api/v1/integrations/pipedrive/app/enroll，模式 pipedrive-app/enroll-modal.schema.json）和“在 Warmbly 中暂停”（<backend>/api/v1/integrations/pipedrive/app/pause，模式 pipedrive-app/pause-modal.schema.json），并将两者添加为面板操作。所有 JWT 密钥留空，使 Pipedrive 使用应用客户端密钥签署每次调用；后端会验证该密钥，以及令牌指定的用户和公司。Pipedrive 要求后端使用 https，并配备公共证书颁发机构签发的证书

人员字段 Open in Warmbly（在 Warmbly 中打开） 也链接到 APP_URL。通过 warmbly join 加入集群的消费者会连同其余环境收到 Pipedrive 变量、APP_URL 和 BACKEND_PUBLIC_URL（或 API_PUBLIC_URL），因为消费者负责注册 Webhook；工作节点不会收到。

Salesforce 读取 SALESFORCE_OAUTH_CLIENT_ID 和 SALESFORCE_OAUTH_CLIENT_SECRET，它们来自你组织中的 External Client App 或 Connected App，需强制 PKCE，并配置 api、refresh_token 和 id 权限范围。一个应用可支持生产、沙盒和 My Domain 登录，各成员连接时自行选择。参见Salesforce 自托管配置。

AI 与搜索

模型兼容性无须配置。不同后端要求的请求格式不同：较新的 OpenAI 模型使用 max_completion_tokens 而非 max_tokens，拒绝默认值以外的温度，部分模型还要求关闭推理后才能使用函数工具；多数兼容 OpenAI 的后端只支持旧格式。提供方会从每个参数首次被拒绝的响应中学习并记忆，因此首次调用会逐步调整到可用格式，后续调用直接使用该格式。

兼容 OpenAI 的智能体循环也会自动处理超过 128 个工具的目录。它提供只读工具发现，每次加载最多 20 个匹配工具，而不是在一个请求中发送整个目录。所有获准的内置和已连接 MCP 工具仍可被发现，原有权限及批准规则继续适用。升级后已有对话可以继续，无须数据库迁移或更改 AI 配置。

请在后端和消费者上设置这些变量。

自动收件箱标签配置由后端、消费者和 warmblyctl 读取。两个收件箱标签变量都必须设置；仅有密钥不会启动分类。参见自动收件箱标签。

任务与计费

无论使用哪种队列提供方，预热回复都使用同一个持久化 SQL 任务身份。它们在准确对应的父邮件回执之后至少等待 45 分钟，并在原生调度前重新检查邮箱时间窗口、角色、同意状态、健康状态、禁止发送状态和剩余额度。队列回调不授予发送权限。参见诊断内容生成与上线。

每邮箱的 test_mode、test_send_enabled 和 test_receive_enabled 将诊断发送与接收分开；新邮箱默认关闭，旧版 NULL 值保留原有行为。为正值的 shared_daily_limit 和 rolling_recipient_limit 可在独立的冷邮件／诊断额度之上，对全部出站通道施加共同限制。这些是存储在数据库中的邮箱 PATCH 字段，不是环境变量或全局管理员设置。协议 2 执行器会重新检查当前参与状态、日历、禁止发送规则、服务商暂停状态和持久化预留。参见默认值、修复证据与上线。

本地任务分发器最多同时运行八个处理器，并按后端有效 Postgres 连接池上限的三分之一进一步下调，最少为一个，为 API 请求和协调工作预留容量。超出限制的任务继续在 Postgres 中等待，不尝试分发，也不标记失败。该上限跨轮询轮次生效，而非每批单独计算，不改变发送权限或未知结果保护。

Stripe Tax 还需在账户侧配置。在 税务 > 设置 中确认总部地址，将商用 SaaS 产品税码（txcd_10103001）设为默认，并选择价格是否含税，或在结账时另加税费。对每个订阅和积分包的产品及价格应用相同税码，并显式指定税务行为。价格一旦设为含税或不含税，之后不可更改；要改变选择，需创建新 Price，并更新对应套餐或 STRIPE_CREDIT_PACK_*_PRICE_ID 值。

企业完成向相应税务机关登记后，才应添加税务登记。对于没有适用有效登记的司法辖区，自动税务返回零税额及 not_collecting 原因。启用 Stripe Tax 不能代替税务登记或申报。

Stripe Checkout 始终请求计算税费所需的账单地址，并允许企业买家提供法定名称和企业税号。当前默认账单门户配置必须允许更新付款方式、账单邮箱、账单地址、名称和税号，并显示发票历史，以便客户在续费前更正税务所在地或登记信息。

将 Webhook 端点指向 /webhook/stripe，使用与 stripe-go v86 匹配的 API 版本 2026-08-26.dahlia。订阅 checkout.session.completed、checkout.session.async_payment_succeeded、checkout.session.expired、customer.subscription.created、customer.subscription.updated、customer.subscription.deleted、invoice.paid、invoice.payment_failed、invoice.finalization_failed、payment_intent.succeeded 和 charge.refunded。更换端点时，先将 STRIPE_WEBHOOK_SECRET 更新为新端点的签名密钥，再禁用旧端点。处理器在端点升级期间接受旧 Webhook 格式，但新端点应使用匹配版本。

开启 Stripe Tax 不会更新已有订阅。设置价格税务行为后，请在 税务 > 迁移 中检查并迁移。Stripe 从下个账单周期开始应用税务变更，不进行按比例调整。控制台迁移不适用于沙盒订阅，测试时需逐个更新。

延迟发送通过本地轮询程序执行，因此后端必须保持运行，计划任务才会触发。

可观测性

错误报告

Warmbly 的各运行时均可上报错误，但只有你指定目标后才会上报。目标由运维人员选择，并非软件要求，因此默认安装不向任何地方报告，也不联系任何主机。

支持两种后端，可以任选一种、两者都用或都不用：

• PostHog 是默认方案。一个项目密钥即可承载全部服务的错误跟踪，以及下述少量产品事件，因此只需一个账户，无须分别配置两个。
• Sentry 仍获完整支持。已向 Sentry 上报的实例可保持配置不变；设置 POSTHOG_ERROR_TRACKING=false 后，可保留 PostHog 密钥用于分析，同时不向其发送异常。

同时设置两者时，每个错误都会发送到两处。每个变量由单个进程读取，因此为后端配置项目并不会自动让控制台也上报。

两种后端均未配置时，数据不会离开进程，也不会联系任何主机。控制台、管理面板和表单页面甚至完全不加载 SDK，因此连脚本都不存在；Go、Rust 和 Elixir 服务仍在自身日志中记录错误。

PostHog 密钥可对应 PostHog Cloud（美国或欧洲），也可通过 POSTHOG_HOST 对应你自己的 PostHog。Sentry DSN 可指向 Sentry Cloud、自托管 Sentry 或 GlitchTip 等兼容 Sentry 的服务器；Warmbly 不假设目标一定是 sentry.io。

服务端 PostHog 异常的 distinct ID 标识触发它的进程（warmbly-backend、warmbly-worker），每个事件都关闭个人档案，并禁用 IP 地理定位，因为地址属于服务器。浏览器异常则归属于应用已识别的登录用户，因此与该用户的会话回放关联显示。

异常仍会携带可搜索的上下文属性，便于排查：

浏览器异常还包含操作轨迹：此前访问的路由和失败的 API 调用，以及各自的方法、路径、状态和请求 ID。在控制台及管理面板中，开启 WARMBLY_POSTHOG_SESSION_REPLAY 时，异常还会关联到发生异常的会话回放；这两处录制内容见下述分析一节。

admin 面板和控制台还会为事件标注实际提供页面的构建版本。该值在镜像构建时固定，因为必须与上传源映射时的发布版本一致，之后无法通过容器变量更改。

源码映射（Source map）

没有源映射时，浏览器堆栈跟踪显示的是压缩代码。上传可选，只有构建获得凭据时才开启；因此分叉仓库、自托管构建和本地 pnpm build 均不生成源映射，发布的资源包保持相同。

本仓库的发布工作流将两个项目 ID 保存为仓库变量，将两把密钥保存为仓库机密，并以构建机密形式传入镜像构建。应用中无须匹配发布名称：PostHog 通过 CLI 注入实际资源文件的代码块 ID，将堆栈帧与源映射配对，因此只要对应构建的源映射已上传，任何构建的事件都能解析。

静态托管使用 pnpm build:pages 而非镜像构建；在托管平台构建环境中设置相同两个变量后，会执行相同上传。此配置很关键：未上传源映射时，PostHog 会尝试从网站自身获取 <bundle>.js.map，静态主机却返回 SPA 后备页面，导致每个问题的所有堆栈帧都在压缩函数名旁显示 Invalid source map: bad json。

产品分析与会话回放

这里使用与上述错误跟踪相同的两把密钥，它们是为托管服务提供的。自托管实例未设置密钥时，不加载分析代码，也不发送使用数据：安装程序从不询问这些值，未设置任何密钥的构建也不包含需要拦截的分析脚本。设置密钥的实例会启用以下内容。

设置密钥后，各界面发送以下内容：

控制台用户与服务端事件中的用户使用同一账户 ID，因此后端记录的注册、促成注册的会话，以及后续 Stripe Webhook 报告的订阅属于同一漏斗。营销网站带入注册链接的获客参数在注册时一次性写入该用户。国家信息由 PostHog 根据事件来源地址执行自身 GeoIP 解析；上述 /ingest 代理正是为此转发访客地址，服务端事件也会附带注册请求的地址。

会话回放会在发送前，先在浏览器内遮蔽密码字段输入。其他输入和全部屏幕都会录制，这使回放能准确还原发生的事情，也是托管服务隐私页面明确如此描述的原因。

推送通知

更新

更新器自身变量（UPDATER_MODE、UPDATER_COMMAND、UPDATER_REPO_DIR 等）见更新；它是独立进程，其环境不会显示在配置页面。

表单服务

托管表单的公开服务（cmd/forms）：在独立端口提供从 forms/ 构建的 React（TanStack）表单应用、各表单页面外壳、嵌入加载器及公开提交，使表单流量不接触 API 来源。它读取自身环境；以下项目除 FORM_IP_RATE_LIMIT 外均不显示在管理面板。

跟踪服务

这是 Rust 打开和点击跟踪服务。它读取自己的环境，因此必须在该容器上设置这些变量；它们均不显示在管理面板。

请只运行一个副本。事件去重、按来源限流及点击票据缓存都保存在各进程内存中，没有共享存储。因此第二个副本不会将工作减半，而会让洪泛来源获得双倍额度，并允许同一次打开发布两次。一个容器即可轻松处理大型实例的像素与点击负载；应扩容工作节点。如果必须运行多个副本，请在前方按来源地址做粘性哈希，将同一来源固定到一个进程，以恢复去重和限流特性。

目录条目格式为 <source> <scope> <certainty> <label>。权限范围决定可判断哪些请求：all 用于从不承载真实用户请求的网络；clicks 用于也代理邮件客户端图片抓取的网络，其像素抓取属于真实打开。确定性决定匹配能得出多强的结论，默认为 certain：该来源只执行邮件过滤，因此一旦匹配即可确定结果。probable 表示来源也可能承载用户操作；邮件安全厂商的浏览器隔离会产生这种情况，因此匹配只会扩大消费者的机器行为判定窗口（tracking.machine_window_probable_seconds），而不直接定论。这两列相互独立。probable 条目只会将事件从按人工计数改为按自动行为计数，绝不会让扫描计入互动；窗口外则与未知来源完全相同地判断。代价是：收件人在窗口内真实点击也会被归为自动行为；另外，来自any已识别网络的点击都会在重定向时移除识别票据，因为边缘层没有调度时间，无法像消费者那样区分投递时扫描和隔离环境中的人工点击。因此，即使消费者后来将某次隔离点击计为人工，该联系人仍不会获得网站访问归因。

asn: 条目需要来源 ASN，可通过两种方式获取。TRACKING_SCANNER_ASN_DB 直接根据地址解析，无须 ASN 标头或转换规则，适用于 nginx、Caddy、云负载均衡器后方或直接公开的实例。TRACKING_SCANNER_ASN_HEADER 从边缘代理写入的标头读取，Cloudflare 上只需一条转换规则。两者均配置时，只要请求携带标头，就优先使用标头，因此添加数据库不会改变边缘已给出的判断；标头未覆盖的请求才回退到数据库。

在反向代理后方，两种方式都不能替代 TRACKING_TRUSTED_PROXIES，原因不同：标头只从其中列出的对端读取，因此变量为空时，标头不会解析出任何结果；数据库读取客户端地址，变量为空时该地址是代理地址，因此查到的是代理网络而非请求者网络。如果完全没有可用来源，目录的 ASN 部分就不生效，跟踪服务会在启动时明确提示，并列出两种来源。

默认启用哪些条目及采用何种方式，由上述区别决定。Microsoft 365 Exchange Online Protection 网段和 Barracuda Email Gateway Defense 地址块属于邮件过滤层本身，收件人不会在那里阅读邮件，因此标为 certain，匹配即可直接判定。Proofpoint、Mimecast 和 Cisco Secure Email 按 ASN 匹配并标为 probable：它们虽是专用邮件安全网络，但 Proofpoint Isolation 和 Mimecast Browser Isolation 会在厂商云端渲染点击页面并流式传给收件人，因此该来源的点击可能来自真实用户。隔离通常适用于尚未分类的 URL，而新的开发邮件域名正属于此类。较可能为机器行为的窗口使这些条目可以安全地默认启用：扫描发生在发送后几分钟内，隔离点击则发生在用户实际查看邮件时。

Microsoft 和 Google 的其余网络即使标为 probable 也保持注释，因为它们是整体云地址分配，不是专用邮件安全网络。Windows 365、Azure Virtual Desktop 或企业 NAT 网关后的收件人可能全天都使用这些网络，因此匹配几乎不能说明请求者身份。tracking/scanner-networks.txt 记录每个条目，也是修改条目的位置。

实时服务

这是 Elixir WebSocket 服务。只有发布版本以 prod 启动时才读取运行时配置，随附镜像正是以此方式运行。与跟踪服务一样，它读取自身环境，不会显示在管理面板中。

存储在数据库中的设置

以下是唯一能通过浏览器修改的设置，均不受环境变量控制。它们位于管理面板的 实例 > 配置 > 设置（/configuration?tab=settings）。各进程会缓存读取结果 30 秒，因此修改会在此时间窗口内于所有位置生效。

四项 sync.* 值由后端在将邮箱加载到工作节点时读取，包括连接、重新分配，以及协调器定期重新发布。因此更改后无须重启，30 分钟内会覆盖所有邮箱（每个邮箱每 30 分钟重新发布一次，错开执行，避免工作节点同时收到全部邮箱）。相关固定节奏值（每五分钟突发量、每小时限额、历史回填速率、洪泛阈值和长期超额规则）是编译常量，列在 实例 > 配置 > 有效限制 下；额度行为见邮箱。四项 sync.* 还在 运维 > 同步 提供配套查看页面，展示各邮箱的历史回填进度及公平使用限流状态，并可清除限流或重新开始回填。

五项 retention.* 值在每轮清理时读取，因此缩短期限会在下次清理生效，无须等到重启。删除永久生效，没有宽限期；已超出新期限的数据会在该轮删除。预热邮件期限还会作用于客户邮箱：消费者终止各封邮件的保留状态，持有邮箱的工作节点在邮箱中删除。因此缩短期限后，整个实例的预热文件夹会在数小时内清理至新窗口。各日志内容及缩短期限的影响见数据控制。

无人值守安装可在任何人登录前，通过 WARMBLY_SETTINGS_BOOTSTRAP 初始化整份配置文档，其值为与管理 API 接受形式相同的部分 JSON：

WARMBLY_SETTINGS_BOOTSTRAP={"sync":{"backfill_days":30},"retention":{"audit_log_days":30}}

只有设置记录从未写入过时才会应用，因此从第一次在面板保存开始，以面板为准，此变量不再产生效果。回答保留期限问题后，install.sh --wizard 就会写入该变量。

两项 deliverability.* 值在每轮调度和每次预热发送时读取，因此关闭阻断会在 30 秒缓存窗口内释放被阻止的邮箱。重新开启不会追溯性地立即停止发送：域名仍需先持续失败整个宽限期。只有持续失败才会阻断，因此状态为 unknown 的域名（从未检查、DNS 无响应，或无法解析的特殊用途域名）始终可发送。手动发送和统一收件箱回复从不受此阻断，详见域名身份验证。

placement.* 的额度、种子数量和间隔值在测试开始时读取，因此更改只影响下一次测试，不影响已开始发送的测试。四项 placement.batch_* 值在批次执行器每轮运行时读取，约每 30 秒一次，因此修改一分钟内影响运行中的批次；降低并发不会停止已经发送的邮箱，只延迟下一个邮箱启动。零或负值会解析为默认值，超出范围的值会限制到上限。哪些邮箱组成实例种子面板并非配置项，而由管理员在管理面板中标记。

更改会写入审计记录；每个值在服务端写入和读取时都会验证并限制范围，因此旧版本写入的记录仍能正确解析。

名称与实际作用不完全一致的变量

另请参阅

• 安装：通过一个命令安装，并自动写入这些配置
• 数据控制：各存储位置及各保留期限控制的内容
• 首次运行：认领全新实例。
• 账户与访问权限：谁可以登录，以及如何邀请他人
• 实例健康状态：读取并检查这些值的健康检查
• 故障排查：这些设置可能产生的错误