14 KiB
MessageWeave 部署指南
使用本指南部署后端、配置邮件传递并验证通知。 选择任何可以运行后端容器的平台，提供加密环境 密钥，并连接到外部管理的 Redis 服务。可选的 Cloudflare Worker gateway 在一个或多个后端前面添加一个稳定的 URL。特定于平台的设置是 在部署平台参考中。
0. 部署前准备
准备启用持久性和公共 HTTPS URL 的外部管理的 Redis 服务
到达后端。平台或代理终止 TLS； MessageWeave 监听其中一个
HTTP 端口（“PORT”，默认“8080”）。该过程需要两个加密的启动密钥：
REDIS_URL 和 CONFIG_ENCRYPTION_KEY （编码为 64 十六进制的随机 32 字节密钥
字符）。切勿将真实值放入源代码管理、图像或日志中。业务设置
通过受保护的配置API保存在Redis中；将它们添加为环境
变量不配置服务。
生产环境没有本地数据库、数据量或内部调度程序。完整的安全边界
禁止模式位于 charter.md 中。
1. 部署后端
容器平台
使用仓库根目录的 Dockerfile 构建镜像，并在部署平台配置必需的密钥。
如需进行本地容器冒烟测试，将 .env.example 复制为未跟踪的 .env，替换两个占位值后运行：
docker build -t messageweave:latest .
docker run --rm --env-file .env -p 8080:8080 messageweave:latest
该镜像使用 Rust 构建器和 Debian slim 运行时，以非 root 用户身份运行，并公开 仅端口“8080”。不要安装数据或日志卷。完整图像内容位于 平台参考。
2. 首次配置
在原点打开后端的配置页面进行初始设置。使用
CONFIG_ENCRYPTION_KEY 建立管理会话，然后完成一次性引导
表单。bootstrap 路由不在网关路由集内，因此只能在后端自己的地址上访问。bootstrap 和管理会话处理器位于
src/notify.rs:834 与 src/notify.rs:1187；业务配置保存处理器位于
src/notify.rs:694。后续修改可通过 Worker URL 打开受保护的配置页。
至少配置 Telegram 机器人令牌、目标聊天 ID、入站聊天允许列表、Stalwart JMAP HTTPS 会话 URL 和应用专用密码、Webhook 密钥和工作令牌。如果启用定时对账，还需设置对账令牌。 只有用户明确同意外部处理时，才配置 LLM。配置 API 不会返回密钥内容；完整字段语义见 配置参考。
2.1 可选的远程诊断
在生产中保留“DEBUG_ENABLED”和“DEBUG_TOKEN”未设置，除非远程诊断 刻意需要的。两者都必须配置为挂载诊断路由，并且这些路由 只能通过后端源访问。诊断表面和响应详细信息 记录在参考中。
3. 构建并运行 Docker 镜像
根 Dockerfile 是容器部署路径。它有独立的 Rust 构建器和 Debian slim 运行时阶段；有关运行时内容，请参阅 §8.2。
4.1 注册 Telegram 和 Stalwart 回调
保存业务配置后，在配置页的“注册 Telegram 和 Stalwart 回调”区域操作。输入接收回调的公开 HTTPS origin：启用 Worker 时填写 Worker 地址，否则填写后端地址。页面会向 Telegram 注册 /webhook/tg，并向 Stalwart 注册 /push/jmap。凭据保留在后端，浏览器只提交回调 URL。Telegram 和 Stalwart 注册处理器分别位于 src/notify.rs:1623 与 src/notify.rs:1468。
Telegram 使用已保存的 webhook secret 和 allowed_updates: ["message"]。注册后，Stalwart 会自动完成验证回调和 verification-code 写回。可以安全地重复注册，重复注册同一 origin 是幂等的。更改回调 origin 会更新 Telegram（原子替换），对 Stalwart 则会在注册锁内先销毁旧订阅、再创建新订阅，因此旧 origin 不再收到推送。
5. 运行时配置
将启动时进程配置与 Redis 驻留业务配置分开。 进程启动时仅需要“REDIS_URL”和“CONFIG_ENCRYPTION_KEY”。完整的 业务字段列表在【配置参考】(reference.md#5-environment-variables)中。
6. 短请求运行模式与任务调度
该服务一次处理一个请求，并且不保留 JMAP 事件流、Telegram 长轮询，或打开后台计时器。 Telegram/JMAP 推送提供快捷路径；的 外部调度程序调用下面描述的端点。
6.3 调度队列排空与状态协调
后端没有内部调度程序。外部 cron、计划任务或平台定时器必须调用
scripts/cron-drain.sh，否则排队的通知会一直无法投递。
设置了 MW_RECONCILE_TOKEN 时，脚本先调用 /reconcile，然后排空 /worker 队列。
提供 MW_APP_URL 和 MW_WORKER_TOKEN；启用增量对账时还要设置 MW_RECONCILE_TOKEN。
将这些令牌存入调度器的密钥管理器。单次运行时，使用调度器注入的令牌：
MW_APP_URL='https://<PUBLIC_URL>' bash scripts/cron-drain.sh --once
增量对账通常每 5–10 分钟运行一次。两个端点成功时都返回 204，且响应正文为空；这是正常结果，不是错误。
脚本的 --diagnose 模式可帮助区分服务配置问题和调度问题。参数与运行模式见
调度器参考。
6.4 可靠性行为
Worker 仅重试超时和后端“5xx”响应；它返回“4xx”响应
直接。 /reconcile 和 /worker 具有更长的每条路由超时，并且不会故障转移到
第二个后端，避免重复工作。后端队列处理至少一次并且依赖
关于 Redis 支持的幂等性。请参阅路线和状态参考以了解完整的行为。
6.5 投递目标
该服务允许短暂的通知延迟，并以至少 99.9% 的通知率为目标 可用性。 Redis 可用性和外部调度间隔超出范围 应用程序的控制；准确的交付保证在“NFR-NOTIFY-SLA”中进行了描述，并且 项目章程中的“NFR-RECONCILE-INTERVAL”。
7. 健康检查
使用 /healthz 检查进程存活（src/notify.rs:118），使用 /ready 检查依赖就绪
（src/notify.rs:193）。验证步骤见§8.1。
8.1 验证部署
首先检查后端：
| 请求 | 预期结果 | 含义 |
|---|---|---|
GET /healthz |
200 |
进程存活。 |
GET /ready |
200 |
配置、Redis、JMAP 和 Telegram 探针均就绪；依赖故障返回 503。 |
GET /api/status |
{"ready":true} |
必需的启动配置已就绪；missing 字段列出缺失变量名。 |
启用 Worker 网关后，还请求“GET /healthz-worker”。要求
available >= 1 并检查 version 是否与部署的 LB_VERSION 匹配；仅 HTTP 200
可能意味着“无后端”。 cloudflare-worker/ 目录的测试和部署命令是
在其自述文件中描述。
将“/help”发送到配置的 Telegram 聊天并确认回复。然后发送一封新电子邮件并 确认外部调度程序耗尽其通知。健康的“/healthz”只能证明 进程活跃度；它并不能证明 Redis 或上游任一者可用。
8.2 Docker 镜像细节
根 Dockerfile 的构建器使用 rust:1-slim-bookworm；运行时间是
debian:bookworm-slim。运行时安装 CA 证书、tini、curl、procps、
iproute2、jq 和 netcat-openbsd 创建 messageweave 系统用户，设置
PORT=8080，并通过 tini 启动二进制文件。它没有“VOLUME”声明并且确实
不启动Redis。这些信息描述仓库提供的 Docker 镜像；其他平台可以使用自己的构建器和运行时镜像。
9. 已确认的部署选择
这些部署决定已经确定；它们不是每次安装的先决条件。
9.1 公共入口与状态存储
后端使用外部 HTTPS 入口和外部 Redis。 Telegram、JMAP 推送和 计划的请求使用选定的公共 URL。当Worker网关启用后，注册 Telegram 和 Stalwart 的稳定 Worker URL；不要在网关处公开凭据。 本节中的稳定 ID 指向项目章程的注册表。
10. 可选的 Cloudflare Worker 网关
网关是可选项，后端没有任何东西依赖它。它为多个后端 origin 提供一个公共 HTTPS 入口。所有后端必须共享同一 Redis 和业务配置。 详细的路由事实在网关路由矩阵中。
它的用途是负载均衡，不是防护。Cloudflare 的 Load Balancer 产品在免费
套餐上不可用，这就是免费套餐账户在多个 origin 前面做负载均衡与故障转移
的办法。没有隐藏后端的意图，也没有加固后端的意图：网关在不在，origin
都同样可以直接访问，边缘上也没有加任何访问控制。固定的路由白名单只是
限定负载均衡器转发哪些路径——bootstrap 和 /debug/* 不在其中，所以发给
网关的请求到不了它们——但它不是防火墙。
10.1 部署拓扑
Telegram webhooks、Stalwart 推送回调和外部调度可以使用稳定的 Worker 网址。 Worker 转发到后端 HTTPS 源；它不连接到 Redis 或 JMAP。
10.2 多实例前提
多个后端可以共享流量，因为请求状态存储在 Redis 中，重复 交付已进行重复数据删除，协调修复了错过的推送事件。无粘性会话 或需要更改应用程序代码。
所有 Redis 键名都是全局命名的，不带实例、主机名或源站后缀。共享同一个 Redis 在这里不是 折中：下列每一项在多源站之间都只有一份。
| 数据 | 键 | 语义 |
|---|---|---|
| 业务配置 | config:business |
单一全局密文块（AES-256-GCM），没有按实例划分的槽位 |
| 配置版本 | config:business:revision |
单一全局单调计数器，与写入在同一次 Lua 事务中提交（CONFIG_STORE_REV_SCRIPT） |
| 启停门 | config:enabled |
一个全局布尔值 |
| 对账游标 | state:jmap:since |
单一全局游标，无账户维度 |
| 投递流 | stalwart:jmap:events / stalwart:telegram:events |
由消费者组共享，组惰性创建，XAUTOCLAIM 回收空闲消息 |
| 对账锁 | lock:reconcile |
单一全局单飞锁，跨实例互斥 |
由此有两条必须知道的推论。
第一，业务配置只有一份，从任何一台源站的 SPA 编辑写进去的都是同一份。不存在“只改其中一台”
的表达方式：没有任何键带实例维度，refresh_business_config 也不接收实例参数。这是预期行为。
如果确实需要两套互不影响的配置（例如生产与预发并行），正确做法是部署第二个实例并指向另一个
Redis，而不是在同一个 Redis 内部做区分。
第二，CONFIG_ENCRYPTION_KEY 必须逐字一致。它是 64 个十六进制字符（32 字节），直接作为
AES-256-GCM 密钥，AAD 固定为 message-weave/config:business/v1；它同时也是 SPA 的管理凭据。
任一台源站持有不同的值，既解不出别的源站写入的配置，也登录不了 SPA，两条路都是 fail closed。
加源站买到的是故障转移，不是吞吐。投递靠共享消费者组分摊，但 /reconcile 受 lock:reconcile
全局串行，游标也只有一份。一台实例在批次中间挂掉，消息会在 XAUTOCLAIM 空闲窗口过后被另一台
接手；代价是可能重复投递（由 dedup:* 键去重），不会丢消息。
10.3 信任模型
Worker 传递请求标头和正文。仍需要后端身份验证 因为后端源可能是直接可达的。每个实例必须使用相同的共享 业务凭证和 Redis 状态。
10.4 路由与故障转移
HTTP 请求访问 Worker 时，会先收到永久的 308 重定向，前往路径和查询参数相同的
HTTPS URL，之后才进行路由校验或转发。Worker 使用“404”拒绝未注册的路由，并使用“405”拒绝错误的方法。普通
请求最多尝试“LB_MAX_ATTEMPTS”来源（默认两个），并且只有超时或“5xx”
触发故障转移。 /reconcile 和 /worker 是具有较长超时时间的单次尝试路由
覆盖。使用参考中的路由矩阵和调整值。
10.5 回调地址
使用网关时，将Telegram的webhook和Stalwart的push回调设置给Worker 域。外部调度程序可以对转发路径使用相同的 URL。引导程序和 诊断端点仍然需要后端源。
10.6 网关健康状态
GET /healthz-worker 报告 Worker 版本和后端可用性。两者都使用
用于验证部署的“可用”和“版本”； status: no-backends 可以返回
当未配置有效源时，HTTP 200。
10.7 功能边界
Worker 不是 Redis 代理，也不会使后端无状态；共享外部 Redis 仍然需要。它不添加数据库、长期连接或第二层 业务认证。
10.8 多源站之间的配置收敛
SPA 的一次编辑只写入 Redis 一次。各源站惰性收敛，发生在请求边界上：每个带请求的入口
（/worker、/reconcile、/healthz、/push/jmap、/api/*）都会调用
refresh_business_config，它先从 Redis 读全局版本，当 remote_revision <= local_revision 时
立即返回。没有轮询循环，也没有 watch，所以一台完全收不到流量的源站会一直保留它原有的配置。
已知行为：重建失败后不会重试，直到下一次版本更新。 上面的版本判断只是一个提前返回，它不是
重试保护。当某台源站的 build_worker 失败——JMAP session URL 不可达，或 llm_api_key /
llm_base_url 缺失或非法——该源站会把内存中的版本推进到远端值，并保留原有运行时。此后提前返回
条件对该源站永久成立，它不会再尝试，直到写入了一个新的版本。同一函数里的其他失败（Redis
不可达、密文块缺失、JSON 解析失败、校验失败）都不推进本地版本，因此会在下一次请求时重试；这些
路径都在构建运行时之前就返回，所以不会重建 worker。
症状是一台源站已运行新配置、另一台还停在旧配置上，而且没有报错也没有日志：失败路径是静默
返回的。排查方法是逐台比对 GET /debug/config 返回的字段值——那些值来自内存里的实时运行时。
不要用它的 revision 字段判断：那个值从 Redis 读取，即使该实例尚未收敛也会显示最新的全局版本。
恢复办法：在 SPA 里再动一次配置让版本前进，卡住的源站就会重新尝试一次。如果这台源站仍在 Worker 的源站列表里，这期间把它从列表中移除，避免请求被分裂到两套配置上。