运维

备份和恢复

须备份以下内容：PostgreSQL、S3 输出对象和生命周期配置、网关 TLS 和主机 CA 材料、目录公钥、身份配置，以及指定的审计导出卷。导出游标须与对应的文件一起保留；共享的 audit.cursor_key_file 密钥须在各网关实例之间保持一致。私钥和凭据须通过密钥管理系统的备份流程保护。审计检查点须保存在独立的信任域中。

在隔离环境中测试恢复。须检查 schema 兼容性、数据库权限、身份登录、主机连接、目录分发和审计验证。从相互兼容的备份点恢复对象引用和对象。缺失或已过期的对象必须报告为不可用；审计链有效不代表这些对象的内容已恢复。

主机备份包括 /var/lib/allowops/（私有身份和目录状态）和 /var/lib/allowops-exec/ （由 root 所有的最高版本记录）。不要把一台主机的身份克隆到另一台主机。只保留目录字节而丢失最高版本状态，会削弱回滚检测。这类恢复须作为经过评审的信任恢复处理，不能作为常规文件复制处理。

升级顺序

先升级网关，再使用目标版本中经过验证的制品升级主机。网关支持与自身相同的主版本和上一个主版本的主机（主版本为 0 的网关只支持主版本 0），但会拒绝完整 SemVer 版本比网关新的主机。网关支持某个主机版本之前，不要引入该主机版本。

可以用示例动作 agent_upgrade（risk: dangerous、run_as: root）在线升级主机。该动作从主机已配置的 apt 或 yum 仓库安装所选的 allowops-agent 版本。安装后，它通过一个临时 systemd timer 在约 5 秒后重启 agent，使 task 结果先送达网关。version 枚举中只列出不高于网关的版本，每次升级网关后发布新目录。主机已是所请求版本时，该动作不做任何操作。安装后的版本与请求不一致时，该动作失败且不重启。该动作不执行降级。apt/yum 按仓库配置校验软件包签名。使用主机选择器分批推进，并通过专用的策略规则授予该动作。版本高于网关的主机会被拒绝，须在主机上降级。

使用维护数据库角色执行该版本的数据库迁移。Helm 使用 pre-install/pre-upgrade 迁移 hook；自行管理二进制文件的部署须单独执行 allowops-gateway migrate。须保持运行时角色受限的审计权限。回滚二进制文件之前，须评审迁移兼容性；不要编辑迁移历史，也不要假定较新的 schema 能与较旧的网关一起工作。

SIGTERM 会停止接收新工作，在配置的宽限期内等待进行中的工作结束，并要求主机重新连接。须为容器终止留出足够时间。断开连接会终止活动的 task 进程组，不会重放 task。取消和断开连接不会撤销已经产生的副作用。

升级后，须验证运行中镜像的 digest 或只有新代码才有的行为，然后检查认证登录、主机清单、一个已授权的测试动作、该动作的输出和审计。仅凭上报的版本号或 commit，不能确定新的可执行文件正在处理请求。主机安装包会启用服务，但不会启动服务；由运维人员控制重启。

密钥和 token 轮换

目录密钥轮换见签名与发布：分发新公钥，发布双签名的包，确认主机已加载，然后删除旧密钥。已泄露的密钥须在主机上撤销，不能只在网关上撤销。

对于服务 token，先签发替换 token，更新一个客户端，验证访问正常，再撤销旧 token。不同客户端使用不同账号，撤销时更简单。密码和 token 不能出现在进程参数和 shell 跟踪输出中。

网关 TLS CA 指纹（pin）与主机身份 CA 是两个不同的对象。续期网关 TLS 证书时，须使用预期的名称和完整证书链。更换已固定的 TLS CA 时，运维人员须协调更新每台主机上配置的指纹。通过 Helm init 容器复制的密钥发生变化后，须重启工作负载。不要把替换主机身份 CA 作为常规轮换操作：原地轮换主机 CA 不在 MVP 范围内。如果必须更换该信任关系，须规划受控的重新注册。

存储和保留

使用已有的 S3 bucket，配置输出的 region/endpoint，并通过 AWS SDK 凭据链提供凭据。须配置加密支持：输出上传时请求 AES256 服务端加密。SeaweedFS 需要单独配置其 SSE 密钥。保留期由 bucket 生命周期策略决定；网关不会自动设置。预期的默认值为一年。

SeaweedFS 生命周期配置 API 和压缩输出操作有本地集成测试覆盖。实际的延迟过期删除须由运维人员在配置的保留周期内验证。依赖删除功能之前，须检查所选存储的版本及其加密和生命周期行为。完整输出的写入是异步的；即使 job 成功，也须监控持久化失败。output_stored 标志用于区分执行结果和持久化结果。

监控和恢复

使用 HTTPS GET /health/live 检查存活状态，使用 /health/ready 检查就绪状态。PostgreSQL 连接或 schema 失败时返回 HTTP 503。输出存储失败时，就绪检查仍返回 HTTP 200，并带有 degraded: true；须监控响应正文和输出持久化，不能把 HTTP 200 当作所有依赖都正常的证明。allowops-gateway health 命令检查状态和 TLS，但不会因降级标志而失败。健康检查端点不验证用户登录或动作授权。

须同步时钟。目录激活允许五分钟的时钟偏差；偏差过大可能导致证书或目录验证失败。须监控离线主机、目录加载失败、不支持的动作、输出持久化、审计导出延迟和依赖健康状态。目录过期和 token 过期须在到期前续期。主机清单中的加载报告反映最后一次完整报告，离线主机也是如此；这些报告不能证明主机当前的执行环境。

join token 须使用较短的有效期和有限的使用次数。确认已注册主机的身份之后，再设置授权标签。删除主机会使其证书失效；同名的替换主机会获得一个新的不可变 ID。主机凭据不能作为 API 身份使用。

如果发布或管理操作在可能已提交之后返回审计结果错误，重试前须先读取该资源。如果执行响应丢失，再次提交前须先查看 job。系统不提供通用的副作用“恰好一次”保证。网关实例丢失后，可能需要对 task 进行对账，且不会重放。

新版本通知

网关可以在有新版本时通知控制台用户。该功能默认关闭；未启用时，网关不发出任何对外请求：

update_check:
  enabled: true
  url: https://liubing0806.github.io/allowops/version.json
  interval: 24h

url 必须使用 HTTPS 且不含凭据，interval 不能小于 1h。网关无法访问互联网时，把 url 指向清单文件的内部副本。清单是一个 JSON 对象，包含 version（严格 SemVer）和可选的 published_at（RFC 3339）。文档构建时根据 CHANGELOG.md 中第一个版本标题生成发布的清单。

每次检查只发送一个 GET 请求，请求头为 User-Agent: allowops-gateway/<version>，不发送其他内容。请求使用环境变量中的代理，最多跟随三次 HTTPS 重定向，最多读取 64 KiB。各网关实例在 PostgreSQL 中共享同一个检查结果，因此一个集群大约每个间隔获取一次。网关只发出通知；网关不会下载或安装任何内容。开发构建报告 dev，并且不会显示通知。

有新版本时，侧边栏在网关版本旁显示 Update 标记，点击后打开 GitHub 版本说明；概览页在 Needs attention 下列出该版本。系统页面显示检查是否启用、最后一次检查的时间、最后一次错误、agent 版本比网关旧的主机数量；网关实例运行不同版本时，系统页面会显示警告。