运维、告警、备份与审计

围绕平台管理「运维」与「设置 › 通知」页面,建立从日常可观测性、索引死信处置、每日数据库自动备份与恢复、依赖故障告警到合规审计追溯的完整运维闭环。

1. 运维任务与每日数据库自动备份

自 v2.12.17 起,原有依赖 Kubernetes 外部 CronJob 的定期清理任务全面迁移为应用内调度;自 v2.12.18 起,新增每日数据库自动备份并默认开启,所有任务的开关、执行时间(UTC)、保留天数、试运行(Dry Run)与历史执行日志均在「平台管理 › 运维 › 运维任务」(/admin/maintenance)统一管理。

v2.12.18 升级提示:每日数据库备份默认开启 — 升级后平台默认每天 02:00 UTC 分别导出元数据 PostgreSQL 与图谱 PostgreSQL(若独立部署),并在目标存储中保留最新 7 份。如果本地磁盘余量紧张,请第一时间在 /admin/maintenance 配置外部 S3 备份目标,或按需暂时关闭该任务(改由现有 DBA 备份体系接管)。

内置运维任务清单

所有定时时间均为 UTC,清理任务单次超时 30 分钟,数据库备份单次超时 4 小时:

任务 ID 默认状态 默认调度(UTC) 作用与说明
database_backup 默认开启 每日 02:00 导出元数据 DB(及独立图谱 DB)至 backups/<installation_id>/...,保留最新 7 份并生成清单(Manifest);支持配置独立外部 S3 备份目标
audit_log_cleanup 默认开启 每日 03:00 按审计日志保留天数清理过期记录
llm_invocation_ledger_cleanup 默认开启 每日 03:15 按 LLM 调用账本保留天数清理过期明细
api_invocation_ledger_cleanup 默认开启 每日 03:30 按 API / MCP 调用记录保留天数清理过期明细
graph_curation_cleanup 默认开启 每日 03:45 清理过期知识图谱治理任务记录
rate_limit_reject_cleanup 默认开启 每日 04:00 清理过期请求限流拒绝明细
search_history_cleanup 默认关闭 每日 04:15 按保留期清理历史检索记录
usage_parse_cleanup 默认关闭 每日 04:30 按保留期清理文档解析用量流水
dataset_cleanup 默认关闭 每日 04:45 清理过期/孤儿评测数据(单批上限 500,支持 Dry Run 预演)

从数据库备份恢复

在 /admin/maintenance 的备份历史列表中展开任意一份成功备份,可直接复制对应的清单路径(manifest)与恢复命令。恢复必须在停写或维护窗口下执行:

Docker Compose 环境:

# 恢复内置默认存储中的备份
docker compose run --rm --no-deps --entrypoint python indexing-worker \
  -m aperag.cli.backup_restore --manifest '<MANIFEST_PATH>'

# 若备份存放在外部 S3 目标,挂载凭据文件并追加 --target-file
docker compose run --rm --no-deps --entrypoint python indexing-worker \
  -m aperag.cli.backup_restore --manifest '<MANIFEST_PATH>' \
  --target-file /run/secrets/backup-target.json

Kubernetes 环境:

kubectl exec -n <NAMESPACE> <RESTORE_POD> -- \
  python -m aperag.cli.backup_restore --manifest '<MANIFEST_PATH>' \
  --target-file /run/secrets/backup-target.json   # 仅外部 S3 目标需要

数据库备份仅包含 PostgreSQL 元数据与图谱数据;文档原文件、Elasticsearch 与 Qdrant 索引需依赖对象存储与向量/全文引擎自身的持久化卷或快照策略(也可在数据库恢复后针对缺失知识库重建索引)。

2. 通知渠道与内置告警规则

在「平台管理 › 设置 › 通知与告警」(/admin/notifications)中配置外部接收渠道与告警规则,第一时间获知平台依赖异常或运维任务失败。

支持的通知渠道

告警规则与直发兜底

3. 可观测性看板与索引死信处理

「平台管理 › 运维 › 可观测性」(/admin/observability)与「用量统计」(/admin/usage)提供开箱即用的运行监控面:

4. 审计日志、调用账本与保留期管理

排查合规审计与调用链路时,先区分四类数据源的统计口径(四者计数单位不同,切勿直接相加或混用):

排查问题 数据源与后台入口 管理接口 计数单位
谁在何时创建、修改或删除了资源 审计日志(/admin/audit-logs) GET /api/v2/audit-logs 一次受审计的 HTTP 写操作
哪个用户 / API Key 调用了 API、MCP、A2A 或 Turn API / MCP 调用记录(/admin/observability) GET /api/v2/admin/observability/api-invocations 一条接口调用或 Turn 事件
哪个模型 / 供应商产生了 Token、耗时或上游错误 LLM 调用账本(/admin/observability) GET /api/v2/admin/observability/llm-ledger 单次上游模型请求
按天/按组织汇总的模型与解析用量报表 用量统计(/admin/usage) GET /api/v2/admin/usage/stats 时间窗聚合统计

非公开 OpenAPI 说明:/api/v2/audit-logs 及下方保留期管理接口均要求平台管理员会话(或已授权 OAuth,不接受数据 API Key),且出于安全边界主动不暴露在公开 OpenAPI 文档中。

全链路关联顺序

  1. 从业务系统日志获取 request_id、chat_id 或 turn_id;
  2. 在 API / MCP 调用记录 中查入口路径、source_kind(如 chat、mcp、openai、a2a)与状态码;
  3. 用同一个 turn_id 关联 Agent 内部触发的 MCP / 工具子调用(异步子工具可能不继承初始 HTTP request_id);
  4. 用 chat_id 或 turn_id 在 LLM 调用账本 查逐次模型 Token 与上游报错;
  5. 若涉及权限变更或资源被删,再查 审计日志 定位操作人与操作时间。

数据保留期配置

保留期可在 /admin/maintenance 页面调整,也可由管理员调用对应 GET / PUT 接口(请求体 {"retention_days": 30})批量配置:

数据源 默认保留 可配范围 保留期管理接口
审计日志 7 天 1–30 天 /api/v2/audit-logs/retention
LLM 调用账本 30 天 1–30 天 /api/v2/admin/observability/llm-ledger/retention
API / MCP 调用记录 30 天 1–30 天 /api/v2/admin/observability/api-invocations/retention

调整保留期仅影响后续定时清理任务,无法恢复已被清理的历史数据。若有长期合规留存要求(如 180 天或 1 年),请定期将脱敏后的审计元数据导出至企业 SIEM 或外部合规存储。

下一步