VMax / 设计档案

外观

VMax 服务端部署模式 ​

1. 适用范围 ​

本文给出官方实例、普通私有实例和完全主权部署的参考拓扑与操作边界。Go、Docker Compose、PostgreSQL、Redis 任务队列和 S3 兼容对象存储已被选为总体架构，但当前仍无可运行实现。

1.1 状态说明 ​

  • 来源 MUST：Docker Compose 是首版必须交付；全新 Linux 主机从空机到健康状态目标不超过 10 分钟。
  • 来源 MUST：生产只允许 HTTPS/WSS，实例发现配置签名且客户端固定指纹。
  • 来源 MUST：普通私有实例依赖官方 Push Gateway 时不能称为完全主权。
  • 来源 MUST：完全主权模式使用独立 Bundle ID、自有 APNs 凭据和自有 Gateway，不共享官方私钥。
  • 已选架构：Caddy + Go vmax-api + Go vmax-worker + PostgreSQL + Redis 队列；S3 兼容对象存储作为 P1 附件组件。
  • MVP 启用范围：启动 API、Worker、PostgreSQL、Redis 与入口代理；不启动对象存储，不启用图片、视频或文件接口。
  • 管理边界：不提供 Web 管理后台；只提供受控配置和一次性 vmax-cli 运维命令。
  • 已验证事实：当前仓库没有 Compose、镜像或部署脚本，以下步骤与 SLO 尚未实测。

官方实例、普通私有实例和完全主权部署的 App、Gateway 与 APNs 关系

图中的“完全主权”仅指独立 App/实例/网关凭据的部署模式，仍受 Apple APNs 平台约束；详细差异见下表。查看图示说明。

2. 三种模式 ​

能力官方实例普通私有实例完全主权部署
消息 API/数据库官方运营用户运营用户运营
Push官方 Gateway官方 Gateway 或关闭自有 Gateway
App Bundle ID官方官方独立
APNs 凭据官方官方持有用户持有
Redis 队列核心部署组件核心部署组件核心部署组件
S3 兼容存储P1 附件启用时P1 附件启用时P1 附件启用时
主权表述托管服务私有消息实例，不是完全主权可称完全主权部署，但仍依赖 Apple/APNs 平台

表中的“完全主权”是部署模式名称，不是“无第三方依赖”或生产安全声明；只有满足独立 Bundle ID、凭据、Gateway、构建与运营边界后才可使用该名称。

3. Compose 参考服务 ​

text
edge          TLS termination, request size/rate limits
vmax-api      stateless REST/WSS and auth verification
vmax-worker   Redis queue consumer, expiry, ACK cleanup, wake retries
postgres      authoritative durable state
redis         task queue and ephemeral acceleration; rebuilt from PG outbox
object-store  selected P1 architecture; disabled in MVP
vmax-cli      one-shot init, migration, signed policy and recovery checks

要求：

  • vmax-api 和 vmax-worker 使用同一发布版本与 schema 兼容矩阵，但最小权限数据库账号分离。
  • PostgreSQL 使用持久卷、校验过的备份和磁盘容量告警；不得暴露到公网。
  • Redis 队列是 MVP 部署组件，但不是权威存储。短时故障时核心事务写入 PostgreSQL outbox；达到受控积压阈值后 API readiness 失败并返回可重试错误，避免无限堆积。Redis 清空后由 outbox 重建，不能丢消息或永久漏清理。
  • 对象存储在 MVP 关闭，API 在实例能力中声明 attachments=false；附件端点返回稳定的未启用错误，不创建上传会话。
  • 不部署常驻 vmax-admin 或 Web 管理服务；vmax-cli 以一次性 Compose run 执行，使用单独最小权限凭据。
  • edge 只转发必要 headers，不记录 query、Authorization、token 或请求正文。

4. 网络与权限 ​

  • 公网入口只开放 443；80 仅用于受控跳转或证书挑战。
  • API、Worker、PostgreSQL、Redis、对象存储分别使用最小权限网络和账号。
  • 管理端口不与用户 API 共用公网监听；首版优先本机 CLI/受控运维网络。
  • Redis 只在内部网络监听，启用认证和连接加密（跨主机时），按环境隔离 key namespace；不得从公网访问。
  • 容器以非 root、只读根文件系统、最少 Linux capabilities 运行；临时目录与持久卷明确列出。
  • liveness 仅证明进程活着；readiness 判断能否接流；dependency 健康单独暴露且不泄露连接串、版本细节或 secret。

5. 配置与 secret ​

环境配置至少分为公开策略、运行配置和 secret：

  • 公开策略：实例名、注册模式、TTL/配额、API/协议能力、Push 模式。
  • 运行配置：监听地址、连接池、超时、日志级别、Worker 并发。
  • 队列配置：Redis 地址/凭据、任务 namespace、并发、租约、退避、最大尝试和 outbox 积压阈值。
  • 对象配置：S3 endpoint、region、bucket、path-style/virtual-host 模式和凭据；MVP 不提供真实值且能力关闭。
  • secret：实例签名私钥、数据库凭据、Redis 凭据、游标签名/加密密钥、Gateway 认证材料、APNs 凭据，以及 P1 启用后的 S3 凭据。

secret 不得进入 Git、镜像层、Compose 示例、日志、诊断导出或普通数据库备份。.gitignore 不是 secret 管理方案。生产可选 Docker secrets、文件挂载或云 KMS/Secret Manager；具体供应商不写死。

6. 模式配置 ​

6.1 官方实例 ​

官方运营消息实例与 Gateway，仍需保持两者数据域和访问权限分离。Gateway 不得通过内部权限反查消息实例。上线前需要容量压测、备份恢复、APNs 凭据轮换和事故响应演练。

6.2 普通私有实例 ​

默认推荐两种明确选择：

  1. official_gateway：实例向官方 Gateway 提交无内容 wake；后台收信体验较好，但官方可观察随机路由与唤醒时间。
  2. disabled：不使用官方 Gateway；前台 WSS 正常，后台只按 iOS 允许的最佳努力拉取，可能延迟。

部署 UI/文档必须展示该取舍，不得把关闭 Gateway 描述为后台实时可靠。

6.3 完全主权 ​

除自托管消息实例外，还需独立 App 构建、Bundle ID、签名、APNs entitlement/凭据、自有 Gateway 与发布/分发流程。不能复制或请求官方 APNs 私钥。其密码协议、许可、App Store/企业分发与合规仍需各自评估。

7. 上线流程 ​

  1. 固定镜像 digest，校验 SBOM/签名；许可证与发布批准仍为独立门槛。
  2. 生成并外置 secret；确认备份不包含不应复制的 APNs/签名私钥。
  3. 启动 PostgreSQL，执行版本化迁移并检查锁、磁盘与回滚条件。
  4. 启动 API/Worker，验证 liveness、readiness、dependency。
  5. 验证实例配置签名、TLS、指纹和客户端能力交集。
  6. 执行提交、超时重试、拉取、ACK、Redis 任务重放、过期与 Push 失败冒烟测试。
  7. 验证日志/指标/追踪无敏感字段并启用容量、错误和备份告警。
  8. MVP 明确检查 attachments=false、没有对象存储容器/凭据，文本流程不访问 S3。

8. 升级与回滚 ​

  • 升级遵循 docs/architecture/兼容性与迁移.md 的 expand-contract。
  • 发布前创建并验证备份；“备份成功”必须包含实际恢复与校验。
  • 旧 API/Worker 与新 schema 的混合窗口先在测试环境演练。
  • 不可逆迁移不得承诺二进制回滚；明确 forward-fix 或恢复窗口。
  • 回滚后检查信封数量/字节、幂等键、ACK 清理、outbox 和 Push 重试是否连续。

9. 待总控决策 ​

事项选项与取舍建议验证
边缘代理Caddy 简单自动 TLS；Nginx/Traefik 更适合既有平台Compose 默认 Caddy，保持可替换TLS 扫描、限流、正文上限、日志检查
Redis 队列实现Go 队列库减少自研；Streams 更透明；自建风险最高以许可证、维护状态和故障语义选择，PG outbox 保底清空、断连、重复、毒任务、滚动升级
S3 兼容实现内置 MinIO 易自托管；云 S3 运维成熟；兼容差异存在总体架构保持 S3 兼容，MVP 关闭，P1 建兼容矩阵超时、分片、孤儿对象、TTL 对账
Gateway 认证mTLS、短期签名 token、私网选择可轮换且不携带用户身份的机制重放、伪造、轮换与泄漏演练
开源发布多种许可证/分发策略跟随 ADR-001/ADR-010，不在本文冻结法务与依赖许可证审查

10. 验收 ​

  • 全新 Linux 主机按文档一次部署成功，10 分钟目标需用发布产物实测。
  • Redis、Gateway 或 APNs 不可用不破坏已持久化文本消息的最终拉取；MVP 无对象存储依赖。
  • Redis 清空后 PostgreSQL outbox 可重建全部未完成后台任务，重复执行不改变最终业务结果。
  • 数据库迁移中断、磁盘满、容器重启和 secret 轮换有可重复演练记录。
  • 镜像、历史、示例、日志、备份和诊断扫描无私钥、token、APNs token 或消息明文。
  • 在完成上述验证前，只能称“参考部署设计”，不得称“生产就绪”。

系统初步设计 · 待决事项不代表批准 · 安全方案尚未完成独立审计

VMax 文档站仅发布 docs/ 范围内的评审材料