审计

审计事件记录已认证的执行者、操作、判定结果、策略版本、job/task 标识符，以及带 SHA-256 哈希的输出对象引用。审计事件不存储命令输出正文或原始动作参数。原因（reason）属于审计元数据，因此原因中不能包含凭据和其他敏感数据。

PostgreSQL 存储一条连续的哈希链。每个事件对前一个哈希值和本事件的权威规范化载荷字节计算哈希。序列号在事务中分配；追加失败不会留下序列号空缺。网关运行期间，大约每五分钟添加一个检查点事件。带过滤条件的事件查询结果不一定是一条连续的链。

运行时权限和维护权限

使用独立的维护角色执行数据库迁移。网关运行时角色不能是超级用户、审计表的所有者或维护角色的成员。运行时角色对审计事件的权限是 INSERT 和 SELECT，没有 UPDATE/DELETE。导出游标单独授予更新权限。迁移完成后，由数据库管理员授予运行时所需的权限。

按月创建分区和数据保留属于维护职责。迁移会创建当前 UTC 月份及之后两个 UTC 月份的分区。须在这些分区用完之前安排维护。保留期默认约为一年，按月份边界计算。删除时会记录保留边界的哈希值。如果已注册的导出游标推进得不够远，删除操作会拒绝越过该游标。本版本没有通用的分区维护 CLI 命令。

持久化导出

在一个指定的网关实例上启用文件导出，该实例须挂载持久卷：

audit:
  export:
    enabled: true
  export_directory: /var/lib/allowops/audit
  cursor_name: primary-export
  max_file_bytes: 16777216

其他实例保持导出禁用。数据库游标推进之前，文件和目录会先完成同步（sync）。如果在游标推进之前发生崩溃，可能会重复投递；收集器必须按序列号去重，并拒绝同一序列号对应不同哈希值的记录。只收集已发布的 .jsonl 文件。隐藏的临时文件不是完整的导出。

指定实例停机期间，导出暂停。恢复时须同时恢复原来的卷和游标。把导出迁移到另一个实例时，须先停止旧的导出进程，再同时迁移卷和游标；不要在空卷上启动新游标并把它当作原有导出的延续。文件系统持久化不能证明数据已投递到独立归档。须单独监控和验证收集器。

使用 CLI 导出和验证

CLI 通过 ALLOWOPS_DATABASE_URL 访问数据库，不使用已保存的网关会话。通过进程环境变量提供最小权限的数据库凭据。这些命令不执行数据库迁移。

allowops audit export --from 2026-01-01T00:00:00Z \
  --to 2026-02-01T00:00:00Z --output audit.jsonl
allowops audit verify --file audit.jsonl --from-seq 1 --to-seq 100

导出时间使用 RFC3339 格式，起始时间包含在内，结束时间不包含在内。--output - 把 JSON Lines 写到 stdout。验证须提供 --from-seq/--to-seq，两端均包含在内；--file - 表示从 stdin 读取。不指定 --file 时，从 PostgreSQL 读取。单次验证范围最多 10000 个事件；更长的范围须拆分，并在各段之间传递已验证的边界值。哈希链无效时，命令以非零状态码退出，并返回第一个无效的序列号及原因。

比对外部锚点时，使用 --expected-preceding-hash 或 --expected-final-hash，值为从独立可信系统获取的 64 位十六进制 SHA-256。仅凭内部哈希一致，不能证明数据库管理员没有重写整条链。externally_anchored 表示已与调用方提供的锚点比对；该锚点是否可信由调用方负责。已删除的历史记录无法验证，也不会被默认视为有效。

把 audit.cursor_key_file 配置为一个私有文件，文件内容恰好为 32 字节原始随机数据。所有 API 实例和导出实例必须使用同一个密钥，并在重启后保留该密钥。Helm 通过 audit.cursorKeySecret / audit.cursorKeyKey 提供该密钥；Compose 生成该密钥，并与其他私有材料一起保留。更换密钥会使已有的 API 分页游标失效。如果省略该设置，网关会输出警告，并使用进程内的随机密钥；此时游标会在重启或副本变化后失效。对这类查询，去掉过期游标后重新查询。这不会改变已持久化的哈希链。