[Owlbay]

变更摘要 / Summary

• deploy/saas/compose.yml 加可选服务 push-relay（profile push，缺省的 docker compose up -d 不起）：镜像 ghcr.io/ama-link/armadra-push-relay，标签跟 ARMADRA_CLOUD_VERSION（版本线分开走时可设 PUSH_RELAY_VERSION）；只进 edge 网络（要出网访问 APNs / FCM，够不到 postgres 与 redis）；只读根文件系统、cap_drop: ALL、no-new-privileges；健康检查用镜像自带的。
• 独立的 secrets 与变量：push_relay_secret（init-secrets.sh 生成，封中继令牌）必填；APNs .p8 与 FCM 服务账号是占位的空文件，对应变量缺省为空，不填也能启动（/health 报空平台列表，登记与推送答 platformUnavailable；此行为由 Armadra 同批 PR 提供）。
• 参考 nginx 加 push.<域> 站点，只转 /v1/register、/v1/push、/health，登记按 IP 限流。
• .env.example、deploy/README.md（deploy/saas 的说明与变量表）、运维手册新节「推送中继（可选）」、CHANGELOG Unreleased（中英）同步。

镜像要到 Armadra v0.12.0 打标签后才第一次存在（AMA-Link/Armadra#698，标签发布时由 push-relay-image.yml 推送）。在那之前启用 --profile push 会拉取失败；不启用则对现有部署没有任何影响。合并本 PR 不依赖镜像，但文档与 CHANGELOG 已写明这一点。

---

• Adds an optional push-relay service to deploy/saas/compose.yml (profile push, not started by a plain docker compose up -d): image ghcr.io/ama-link/armadra-push-relay, tag follows ARMADRA_CLOUD_VERSION (set PUSH_RELAY_VERSION if the version lines diverge); edge network only (needs egress to APNs/FCM, cannot reach postgres/redis); read-only rootfs, cap_drop: ALL, no-new-privileges; the image's own healthcheck.
• Its own secrets and variables: push_relay_secret (generated by init-secrets.sh, seals relay tokens) is required; the APNs .p8 and FCM service account are empty placeholder files with empty-by-default variables, and the relay starts without them (/health reports no platforms, register/push answer platformUnavailable; that behaviour comes from the companion Armadra PR).
• The reference nginx gains a push.<domain> site forwarding only /v1/register, /v1/push and /health, with per-IP rate limiting on register.
• .env.example, deploy/README.md (the deploy/saas description and variable table), a new runbook section "推送中继（可选）" and CHANGELOG Unreleased (zh and en) are updated.

The image first exists once Armadra v0.12.0 is tagged (AMA-Link/Armadra#698; pushed by push-relay-image.yml on tag release). Until then --profile push fails to pull; leaving it off changes nothing for existing deployments. Merging this PR does not depend on the image, and the docs and CHANGELOG say so.

关联 issue / Related issues

Closes #187

Refs AMA-Link/Armadra#658

改动范围 / Scope

• deploy / 镜像 / images（deploy/）
• docs
• 其余 / others: 无 / None

契约与协议变化 / Contract and protocol changes

• 契约节号 / Sections: 无 / None
• 协议版本 / Protocol version: 无 / None（deploy/compat.json 不变 / unchanged）
• 生成物 / Generated files: 无 / None

数据库迁移 / Database migrations

• 编号 / Number: 无 / None
• migrations.lock: 无 / None

测试 / Testing

• docker compose -f deploy/saas/compose.yml config：缺省服务集不含 push-relay；--profile push 含；PUSH_RELAY_VERSION 覆盖 ARMADRA_CLOUD_VERSION 生效 / default set excludes push-relay, --profile push includes it, PUSH_RELAY_VERSION overrides
• 实跑 / Live run: 用 Armadra#698 的 Dockerfile 在本机构建镜像并临时打成 …armadra-push-relay:0.12.0，docker compose --profile push up -d --no-deps push-relay（隔离项目名与网段）：容器 healthy，/health 答 {"ok":true,"platforms":[]}，根文件系统只读、cap_drop ALL、只在 edge 网络，容器内能访问外网；测完已 down 并删临时标签 / image built locally from the Armadra#698 Dockerfile and tagged temporarily; container healthy with no credentials, read-only rootfs, edge only, egress works; torn down and the temporary tag removed afterwards
• init-secrets.sh：新增三个文件，push_relay_secret 为 44 字符 base64（解出 32 字节），0444，重跑不覆盖 / adds three files, push_relay_secret is 44 base64 chars decoding to 32 bytes, mode 0444, re-runs do not overwrite
• 参考 nginx 模板：官方镜像 + 自签证书 nginx -t 通过 / reference nginx template passes nginx -t with the official image and a self-signed certificate
• pnpm format:check、pnpm lint、pnpm repo:check、pnpm ci:workflows、pnpm notices:check、pnpm repo:test（59 通过 / pass）
• 未跑 pnpm check 全量与镜像构建 / full pnpm check and image builds not run（改动只涉及 deploy/ 与文档 / only deploy/ and docs changed）

检查清单 / Checklist

• 不涉及代码、协议、迁移 / Touches no code, protocol or migrations
• 凭据一律是 secrets/ 下的文件，不进环境变量或版本库；secrets/ 已被忽略 / Credentials are files under secrets/, never environment values or committed
• 用户可见的变化已记进 CHANGELOG.md 的 Unreleased / Recorded in CHANGELOG.md Unreleased

需要维护者提供的外部条件 / External prerequisites

• Armadra v0.12.0 标签发布后镜像才存在，并需在 GHCR 把包设为公开（与其他镜像一致）。 / The image exists only after Armadra v0.12.0 is tagged; the GHCR package must be set public like the other images.
• 要真正开 iOS / Android 推送：发布方的 APNs .p8 与 Firebase 服务账号、push.<域> 的 DNS 与证书名；这些无法在 CI 或本地验证，本地只验证了无凭据启动。 / Real iOS/Android push needs the publisher's APNs .p8 and Firebase service account plus DNS and a certificate name for push.<domain>; none can be verified in CI or locally, only startup without credentials was.

已知限制 / Known limitations

• push.<域> 站点在没起 push-relay 时答 502，且证书不覆盖该名字时浏览器类客户端会报证书错误；运维手册里写了要求。 / The push.<domain> site answers 502 when push-relay is not running, and clients see a certificate error if the certificate does not cover the name; the runbook states the requirement.
• 参考代理没有为 /v1/push 加 IP 限流（中继自己按令牌每分钟 60 条限流）；core 的出口地址可能集中，不宜按 IP 限。 / The reference proxy does not rate-limit /v1/push by IP (the relay already limits per token, 60 per minute) since cores may share egress addresses.