212 lines
10 KiB
Markdown
212 lines
10 KiB
Markdown
# MessageWeave 部署指南
|
||
|
||
> [English version / 英文版 → deployment.md](deployment.md)
|
||
|
||
使用本指南部署后端、配置邮件传递并验证通知。
|
||
选择任何可以运行后端容器的平台，提供加密环境
|
||
密钥，并连接到外部管理的 Redis 服务。可选的 Cloudflare Worker
|
||
gateway 在一个或多个后端前面添加一个稳定的 URL。特定于平台的设置是
|
||
在[部署平台参考](reference.zh-CN.md#9-部署平台细节)中。
|
||
|
||
## 0. 部署前准备
|
||
|
||
准备启用持久性和公共 HTTPS URL 的外部管理的 Redis 服务
|
||
到达后端。平台或代理终止 TLS； MessageWeave 监听其中一个
|
||
HTTP 端口（“PORT”，默认“8080”）。该过程需要两个加密的启动密钥：
|
||
`REDIS_URL` 和 `CONFIG_ENCRYPTION_KEY` （编码为 64 十六进制的随机 32 字节密钥
|
||
字符）。切勿将真实值放入源代码管理、图像或日志中。业务设置
|
||
通过受保护的配置API保存在Redis中；将它们添加为环境
|
||
变量不配置服务。
|
||
|
||
生产环境没有本地数据库、数据量或内部调度程序。完整的安全边界
|
||
禁止模式位于 [`charter.md`](charter.zh-CN.md) 中。
|
||
|
||
## 1. 部署后端
|
||
|
||
### 容器平台
|
||
|
||
构建根 Dockerfile 并在平台中配置所需的机密。对于本地人来说
|
||
容器冒烟，将 `.env.example` 复制到未跟踪的 `.env`，替换两个占位符，
|
||
然后运行：
|
||
|
||
```sh
|
||
docker build -t messageweave:latest .
|
||
docker run --rm --env-file .env -p 8080:8080 messageweave:latest
|
||
```
|
||
|
||
该镜像使用 Rust 构建器和 Debian slim 运行时，以非 root 用户身份运行，并公开
|
||
仅端口“8080”。不要安装数据或日志卷。完整图像内容位于
|
||
[平台参考](reference.zh-CN.md#91-后端部署方式)。
|
||
|
||
## 2. 首次配置
|
||
|
||
在原点打开后端的配置页面进行初始设置。使用
|
||
`CONFIG_ENCRYPTION_KEY` 建立管理会话，然后完成一次性引导
|
||
表单。Worker 网关不会公开 bootstrap 路由。bootstrap 和管理会话处理器位于
|
||
`src/notify.rs:834` 与 `src/notify.rs:1187`；业务配置保存处理器位于
|
||
`src/notify.rs:694`。后续修改可通过 Worker URL 打开受保护的配置页。
|
||
|
||
至少配置 Telegram 机器人令牌、目标聊天 ID、入站聊天允许列表、Stalwart
|
||
JMAP HTTPS 会话 URL 和应用程序密码、Webhook 机密和工作人员令牌。设置一个
|
||
如果使用计划的协调，则协调令牌。仅当用户
|
||
已明确同意外部处理。秘密值不会由
|
||
配置API；完整的字段语义位于[配置参考](reference.zh-CN.md#5-环境变量)中。
|
||
|
||
### 2.1 可选的远程诊断
|
||
|
||
在生产中保留“DEBUG_ENABLED”和“DEBUG_TOKEN”未设置，除非远程诊断
|
||
刻意需要的。两者都必须配置为挂载诊断路由，并且这些路由
|
||
只能通过后端源访问。诊断表面和响应详细信息
|
||
记录在[参考](reference.zh-CN.md#3-后端路由)中。
|
||
|
||
## 3. 构建并运行 Docker 镜像
|
||
|
||
根 Dockerfile 是容器部署路径。它有独立的 Rust 构建器和
|
||
Debian slim 运行时阶段；有关运行时内容，请参阅 [§8.2](#82-docker-镜像细节)。
|
||
|
||
## 4.1 注册 Telegram 和 Stalwart 回调
|
||
|
||
保存业务配置后，在配置页的“注册 Telegram 和 Stalwart 回调”区域操作。输入接收回调的公开 HTTPS origin：启用 Worker 时填写 Worker 地址，否则填写后端地址。页面会向 Telegram 注册 `/webhook/tg`，并向 Stalwart 注册 `/push/jmap`。凭据保留在后端，浏览器只提交回调 URL。Telegram 和 Stalwart 注册处理器分别位于 `src/notify.rs:1439` 与 `src/notify.rs:1315`。
|
||
|
||
Telegram 使用已保存的 webhook secret 和 `allowed_updates: ["message"]`。注册后，Stalwart 会自动完成验证回调和 verification-code 写回。可以安全地重复注册；更改回调 origin 会更新 Telegram webhook，并为新的 URL 创建 Stalwart subscription。
|
||
|
||
## 5. 运行时配置
|
||
|
||
将启动时进程配置与 Redis 驻留业务配置分开。
|
||
进程启动时仅需要“REDIS_URL”和“CONFIG_ENCRYPTION_KEY”。完整的
|
||
业务字段列表在【配置参考】(reference.md#5-environment-variables)中。
|
||
|
||
## 6. 短请求运行模式与任务调度
|
||
|
||
该服务一次处理一个请求，并且不保留 JMAP 事件流、Telegram
|
||
长轮询，或打开后台计时器。 Telegram/JMAP 推送提供快捷路径；的
|
||
外部调度程序调用下面描述的端点。
|
||
|
||
### 6.3 调度队列排空与状态协调
|
||
|
||
后端没有内部调度程序。外部 cron、计划作业或平台计时器
|
||
必须调用 [`scripts/cron-drain.sh`](../scripts/cron-drain.sh);否则排队的通知
|
||
仍然未交付。当设置“MW_RECONCILE_TOKEN”时，脚本调用“/reconcile”，然后耗尽
|
||
工作队列。
|
||
|
||
提供`MW_APP_URL`和`MW_WORKER_TOKEN`；当对帐时设置“MW_RECONCILE_TOKEN”
|
||
已启用。将令牌存储在调度程序的秘密管理器中。对于单次运行：
|
||
|
||
使用调度程序的秘密管理器注入的令牌，运行：
|
||
|
||
```sh
|
||
MW_APP_URL='https://<PUBLIC_URL>' bash scripts/cron-drain.sh --once
|
||
```
|
||
|
||
调节节奏通常为 5-10 分钟。两个成功的端点都返回“204”
|
||
身体空虚；不要将其视为错误。脚本的“--diagnose”模式有帮助
|
||
将服务配置问题与调度问题分开。其论点和
|
||
操作模式列在[调度程序参考](reference.zh-CN.md#93-回调注册与定时任务)中。
|
||
|
||
### 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](#81-验证部署)。
|
||
|
||
## 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 网关
|
||
|
||
Worker 为多个后端源提供一个公共 HTTPS 入口点。所有后端
|
||
必须共享相同的Redis和业务配置。 Worker 仅转发其固定的
|
||
路由白名单； bootstrap 和 `/debug/*` 仍然仅限原始。详细路线事实在
|
||
[网关路由矩阵](reference.zh-CN.md#4-网关与后端路由对照表)。
|
||
|
||
### 10.1 部署拓扑
|
||
|
||
Telegram webhooks、Stalwart 推送回调和外部调度可以使用稳定的 Worker
|
||
网址。 Worker 转发到后端 HTTPS 源；它不连接到 Redis 或 JMAP。
|
||
|
||
### 10.2 多实例前提
|
||
|
||
多个后端可以共享流量，因为请求状态存储在 Redis 中，重复
|
||
交付已进行重复数据删除，协调修复了错过的推送事件。无粘性会话
|
||
或需要更改应用程序代码。
|
||
|
||
### 10.3 信任模型
|
||
|
||
Worker 传递请求标头和正文。仍需要后端身份验证
|
||
因为后端源可能是直接可达的。每个实例必须使用相同的共享
|
||
业务凭证和 Redis 状态。
|
||
|
||
### 10.4 路由与故障转移
|
||
|
||
HTTP 请求访问 Worker 时，会先收到永久的 `308` 重定向，前往路径和查询参数相同的
|
||
HTTPS URL，之后才进行路由校验或转发。Worker 使用“404”拒绝未注册的路由，并使用“405”拒绝错误的方法。普通
|
||
请求最多尝试“LB_MAX_ATTEMPTS”来源（默认两个），并且只有超时或“5xx”
|
||
触发故障转移。 `/reconcile` 和 `/worker` 是具有较长超时时间的单次尝试路由
|
||
覆盖。使用[参考](reference.zh-CN.md#4-网关与后端路由对照表)中的路由矩阵和调整值。
|
||
|
||
### 10.5 回调地址
|
||
|
||
使用网关时，将Telegram的webhook和Stalwart的push回调设置给Worker
|
||
域。外部调度程序可以对转发路径使用相同的 URL。引导程序和
|
||
诊断端点仍然需要后端源。
|
||
|
||
### 10.6 网关健康状态
|
||
|
||
`GET /healthz-worker` 报告 Worker 版本和后端可用性。两者都使用
|
||
用于验证部署的“可用”和“版本”； `status: no-backends` 可以返回
|
||
当未配置有效源时，HTTP 200。
|
||
|
||
### 10.7 功能边界
|
||
|
||
Worker不是Redis代理，不会使后端无状态；共享外部Redis
|
||
仍然需要。它不添加数据库、长期连接或第二层
|
||
商业认证。
|