安装

curl -fsSL https://warmbly.com/install.sh | sh

无需克隆仓库、编译器或工具链。脚本检查 Docker，创建一个目录，生成所有秘密值，拉取固定版本的发布镜像，启动服务栈，并打印用于认领实例的链接。在已安装 Docker 的干净机器上，两分钟内即可完成。

加上 --wizard，安装向导就会询问那些配置参考无法替你决定的问题。

curl -fsSL https://warmbly.com/install.sh | sh -s -- --wizard

不必记住这个参数。首次安装时，如果有可用终端且未指定主机名，脚本会在写入任何内容前询问是否进行配置。否则实例只能使用 localhost：控制台、跟踪主机和退订地址都只能在该机器上访问，却会出现在营销活动邮件中。选择否时，脚本会明确说明这一点并继续。--assume-yes、--host、WARMBLY_HOST，以及对已有安装重新运行，都会跳过此问题，因为这些情况已经给出了答案。

安装哪些组件

机器上不会进行任何构建。克隆并构建的路径仍然存在且受支持；需要时参见自托管。

运行前的准备

对把脚本直接通过管道交给 shell 执行有所顾虑是合理的。脚本只有具备版本管理、可检查和校验和，才有依据回应这一顾虑。这里三者都具备：

curl -fsSLO https://warmbly.com/install.sh
curl -fsSLO https://warmbly.com/install.sh.sha256
sha256sum -c install.sh.sha256
less install.sh
sh install.sh

脚本本身也按这一要求编写：使用 set -eu，所有代码行都放在函数内，最后一行才执行 main "$@"，因此下载中途截断时不会执行任何操作。它不会要求你把脚本通过管道交给 sudo；只在确实需要提权的具体步骤请求权限，并说明步骤名称。

无需真正运行安装，也能查看它准备做什么：

sh install.sh --dry-run

这会打印准备写入的完整 .env 和 Compose 文件，不修改任何内容。

运行完成后

每个发布都提供 images.json 资源，列出其中每个镜像的清单摘要。拉取完成后，安装器会将机器实际获得的镜像与该文件比较；不一致时，在启动任何服务前停止。你也可以随时自行检查：

docker image inspect ghcr.io/warmbly/warmbly/backend:v1.4.2 --format '{{index .RepoDigests 0}}'

通过 --registry 指向自有镜像仓库的安装，没有可用于比较的清单；安装器会明确说明，不会假装已经验证。

环境要求

最容易冲突的是端口 3000，许多自托管软件都默认使用它。安装器会在写入任何内容前检查所有端口，并告诉你哪个已被占用。

安装向导

--wizard 包含九个步骤。每个答案都有与快速安装一致的默认值，因此一路按回车，会得到与单行命令完全相同的安装。

菜单支持常用按键：

最后的确认页面按 enter 安装，按 e 返回某个部分，按 q 退出。

各步骤会追加显示，而不是相互覆盖，因此整个过程可滚动回看，也不会影响安装器上方的终端内容。如果更喜欢每一步重绘屏幕，可使用 --clear。

app.example.com     admin.example.com    api.example.com
ws.example.com      track.example.com    forms.example.com

先预览安装过程

curl -fsSL https://warmbly.com/install.sh | sh -s -- --demo

展示真实向导和确认页面，但拉取、容器创建和健康等待只是演示，不实际执行。它不写文件、不拉镜像、不创建容器，也不需要 Docker，因此无需准备服务器，就能了解“实际会做什么”。

演示约半分钟，速度经过安排，方便阅读每个阶段；真实安装需要几分钟，主要花在拉取镜像和首次启动迁移。WARMBLY_DEMO_FAST=1 可缩短到十秒内。在源码检出目录中可运行 make installer-demo。

供智能体使用

智能体不应操作向导，因为它读取原始按键并需要终端。每个答案都有对应参数，因此使用 --yes 配合参数，可以安静、确定且幂等地执行；--print-env 和 --dry-run 可展示运行结果，而不真正生成它们。

仓库提供 warmbly-install 技能，位于 skills/ 下，专门覆盖这套流程，以及备份和实例迁移。按智能体要求安装即可，例如 cp -r skills/warmbly-install ~/.claude/skills/。

无人值守安装

每个答案都有对应参数和 WARMBLY_* 环境变量，因此同一脚本也可用于 Ansible 或 cloud-init 配置：

curl -fsSL https://warmbly.com/install.sh | sh -s -- --yes \
  --dir /opt/warmbly \
  --host warmbly.acme.com \
  --tls caddy \
  --data-root /mnt/data/warmbly \
  --blobs s3 \
  --retention-preset minimal \
  --backup-dir /mnt/backups/warmbly \
  --version v1.4.2

--print-env 输出 .env 后退出。--dry-run 打印准备写入的所有文件后退出。--demo 演示完整流程，但不安装任何内容。

再次运行安装程序

安装器是幂等的。第二次运行会：

• 沿用现有 .env，绝不重新生成秘密值，因为新的 AUTH_SECRET 会让所有人退出登录，新的 CREDENTIALS_ENCRYPTION_KEY 则会造成永久数据丢失。
• 保留现有数据根目录，因为把安装指向新路径不是迁移，而是在有数据的实例旁边另建一个空实例。
• 保留你自行加入 .env 的键，并放在末尾明确标注的区块中。
• 重新生成 docker-compose.yml，将旧文件保留为 docker-compose.yml.bak。
• 拒绝使用不是由它创建的目录，除非传入 --force。

请将自己的 Compose 改动放在 docker-compose.override.yml 中；Compose 会叠加合并，安装器也不会触碰该文件。

更新

先升级后端，并确认数据库迁移完成，再升级消费者。消费者开始依赖数据库的工作前，最多等待两分钟，确认数据库达到其嵌入代码要求的干净迁移版本。如果后端仍旧或迁移失败，消费者会退出并给出可操作的 Schema 就绪错误，可由容器重启策略再次尝试。消费者不会执行迁移，也不会忽略缺失表。

统一收件箱转发功能的升级顺序

在所有处理提交、排队发送回调和工作节点/控制平面授权的后端升级完成、旧请求处理完毕、旧副本停用之前，不要使用向禁止发送收件人转发的功能。混合后端发布期间，应暂停统一收件箱提交和排队发送派发，因为旧后端仍会拒绝这些转发。现有客户端已经可以提交转发，因此仅安排前端顺序不够。应明确验证旧副本已停用，不要仅凭发布完成或某个后端健康判断。无需工作节点 Schema 变更或重新连接邮箱。参见发送安全。

邮箱同步功能的升级顺序

邮箱查找优化为归一化的发送 Message-ID 和精确 IMAP 文件夹代际添加并发索引，不改写现有记录。索引构建需要临时磁盘空间和 I/O，因此升级繁忙实例前，应确认数据库余量并等待迁移完成。新的批量邮件映射端点无需配置：旧工作节点仍使用逐邮件读取；旧后端不支持批量时，新工作节点也回退到原路径。先升级后端以获得性能收益，再升级工作节点。同步频率、草稿删除核对和持久来信要求保持不变。

要启用持久邮箱来信，应先升级后端并等待迁移完成，再升级并启动消费者，最后升级工作节点。后端在同一个数据库事务中接纳新的服务商映射和组织加密的来信载荷；消费者重启后继续处理待完成阶段。工作节点继续使用内部 HTTP 端点，无需数据库访问。应将实例的组织密钥和正文存储与数据库一起保留，详见数据控制。

旧工作节点配合新后端，仍只写入旧版映射记录。新工作节点配合旧后端，仅在持久内部端点不存在，即 HTTP 404 或 405 时回退。两种混合版本路径都不具备新的持久接纳保证。后端失败或缺少持久标记的确认，不会被视为成功。冲突映射没有保留的待处理载荷时，后端会保守拒绝，不会声称已持久接纳；这也包括待处理行已经投递并移除之后的重试。普通映射查找仍会对该邮件去重。

已完成导入和现有映射都保留。升级前映射没有重放载荷，因此不能仅凭映射重建旧的丢失来信。有界服务商恢复仅覆盖支持的近期历史，不提供无限历史修复。邮箱同步说明了各服务商限制。

降级前，应保持更新后的消费者运行，直到所有待处理来信完成。只要还存在任何待处理行，迁移就会拒绝移除来信表。不要删除队列行或强制迁移版本来绕过拒绝。旧消费者无法处理此队列。待处理来信仅属于当前实例，不随工作区导出迁移。

节点集群自动更新只选择不晚于当前后端的版本。响应心跳时，会再次检查现有集群和节点固定版本，因此不兼容的已存储目标不会发给节点；新设置的不兼容固定版本会被拒绝。新加入机器回退到后端的精确发布版本，而不是不断变化的 prod 标签。主分支构建使用其已发布的提交 SHA 镜像标签。没有版本标记的自定义构建，必须将 WARMBLY_VERSION 设置为其已发布镜像标签；未知版本无法安全排序。将节点集群迁移到新版本前，应先升级后端。这项保护只有安装兼容版本后才生效，无法改变正在运行的旧后端行为。

控制台在容器启动或静态构建时，从后端现有公开配置发现独立的实时服务来源。应先启动后端；如果发现过程警告不可用，在后端就绪后重启控制台，或重新构建静态部署。参见配置。

点击管理面板的版本标记，再选择更新并重启。这种安装方式下，更新器以镜像模式运行：将新标签写入 .env，拉取镜像，并重新创建镜像发生变化的容器，不进行构建。参见更新。

也可以在安装目录手动执行：

docker compose -p warmbly pull && docker compose -p warmbly up -d

更新不会立即切断正在进行的工作。生成的服务栈为每个应用容器提供 60 秒停止时间，由 stop_grace_period 控制；期间后端会完成已开始的邮箱连接及正在连接的导入行，工作节点会完成当前发送。此后仍未完成的工作由新容器继续：工作节点在第一次心跳时重新接手原先加载中的邮箱，导入行则在两分钟租约到期后接手。参见更新时不丢失工作。

卸载

sh install.sh --uninstall

这会停止并移除容器，所有数据原样保留。添加 --purge-data 还会删除数据根目录和安装目录，操作前要求输入确认短语，因为这也会毁掉唯一能够解开备份的密钥。

出现问题时

更多说明见故障排查和实例健康状态。

与邮件服务共用一台主机

自托管实例可以连接只存在于其所在机器上的邮箱。Proton Bridge 是典型场景：它在本地登录 Proton Mail，并通过 127.0.0.1:1143 的普通 IMAP 和 127.0.0.1:1025 的 SMTP 重新提供该账户。因为它从不监听网络接口，所以不提供客户端可验证的 TLS。

连接时，在表单中选择无安全模式。Warmbly 仅在主机是回环字面值，即 localhost、127.0.0.0/8 或 ::1，且实例为自托管时提供此模式。允许它的全部理由，就是凭据不会离开机器；工作节点也会检查实际连接的对端，避免后续修改已存储主机扩大范围。托管 Warmbly 的工作节点运行在我们的基础设施上，绝不提供此模式。

工作节点必须位于同一台机器。docker compose 安装默认如此；其他主机上的专用工作节点无法访问 Bridge。完整说明见邮箱指南。

下一步

• 首次运行：认领实例、首位所有者和演示数据。
• 数据控制：各存储位置、保留窗口范围、备份和实例迁移。
• 配置：所有环境变量和数据库支持的设置。
• 整域邮箱连接：让工作区连接整个 Google Workspace 域或 Microsoft 365 组织所需的 Google 服务账户和 Microsoft 应用。
• 自托管：完整指南，包括从源码构建。