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)中配置外部接收渠道与告警规则,第一时间获知平台依赖异常或运维任务失败。
支持的通知渠道
- 站内收件箱:默认内置,管理员可在控制台右上角铃铛查看历史通知。
- 6 类外部推送渠道:
email(SMTP 邮件,推荐)、webhook(签名 JSON 回调,推荐)、feishu(飞书机器人,支持签名,推荐)、dingtalk(钉钉机器人,支持签名,推荐)、wecom(企业微信机器人)、slack(Slack Incoming Webhook)。支持按渠道设置通知语言(zh-CN/en-US,Slack 默认英文,其余默认中文),保存后务必点击发送测试消息确认投递成功。
告警规则与直发兜底
- 内置告警规则:涵盖核心依赖不可用(PostgreSQL / Redis / Elasticsearch / Qdrant / 对象存储等,按依赖自动去重并在恢复后自动发送恢复通知)、运维任务失败(备份或定时清理异常)、已删除文档清理死信积压等。每条规则可独立配置严重级别、重复发送间隔(
repeat_interval)、恢复通知开关(notify_on_resolve)及目标外部渠道。 - API 直发兜底机制:元数据 PostgreSQL 不可读或索引工作器心跳持续中断 3 分钟时,API 使用已缓存的 HTTP 渠道直接发送告警。多个 API 副本通过 Redis 按依赖和渠道去重。Redis 不可用时,各副本仍会发送,接收方可能收到重复通知。
数据库故障期间请勿重启所有 API Pod。新进程须等待 PostgreSQL 可用才能启动。要收到此次故障的直发告警,至少一个在故障前已启动并缓存了渠道的 API 进程必须持续运行。建议部署至少两个 API 副本,并分布在不同节点上。
- 投递失败排查:投递明细会记录标准化错误码,常见原因包括
timeout/connection_error(网络或防火墙拦截)、blocked_address/invalid_url(命中 SSRF 内网保护策略)、http_<status>/provider_<code>(Webhook 验签失败或机器人限流)、smtp_not_configured/smtp_auth_failed/smtp_tls_error(SMTP 凭据或加密端口错误)。
3. 可观测性看板与索引死信处理
「平台管理 › 运维 › 可观测性」(/admin/observability)与「用量统计」(/admin/usage)提供开箱即用的运行监控面:
- 依赖健康与拓扑:实时展示 API、Worker、Parser、PostgreSQL、Redis、Elasticsearch、Qdrant 与对象存储的连通性与响应耗时。
- 索引死信与失败任务(
/admin/observability?view=indexing#failed-tasks):集中列出解析或索引重试耗尽进入死信队列的文档任务(原/admin/indexing/dead-letter入口已自动跳转至此)。管理员可查看失败阶段与报错堆栈,修复模型配额或解析器问题后一键重试;已删除文档的清理失败会按指数退避自动重试约 23 小时,超限积压时会触发告警。 - 动态日志级别与提示词采样:无需重启服务即可临时调高特定模块的日志级别(排查结束后及时恢复
INFO),或开启管理端提示词采样录制以定位复杂 Agent 推理问题。 - 用量聚合(
/admin/usage):按组织、用户、模型供应商与业务场景聚合 Token 消耗与文档解析量,用于项目对账与成本核算。 - 自助诊断助手与日志打包(
/admin/diagnostics):遇到复杂故障时,可直接使用只读的「诊断与支持」助手按回合 ID 取证,或执行scripts/diagnose.sh导出脱敏日志包;详见 诊断与支持。
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 文档中。
全链路关联顺序
- 从业务系统日志获取
request_id、chat_id或turn_id; - 在 API / MCP 调用记录 中查入口路径、
source_kind(如chat、mcp、openai、a2a)与状态码; - 用同一个
turn_id关联 Agent 内部触发的 MCP / 工具子调用(异步子工具可能不继承初始 HTTPrequest_id); - 用
chat_id或turn_id在 LLM 调用账本 查逐次模型 Token 与上游报错; - 若涉及权限变更或资源被删,再查 审计日志 定位操作人与操作时间。
数据保留期配置
保留期可在 /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 或外部合规存储。