触发数据库备份#

验证状态：已源码核验、未联调；适用基线：源码归纳 @ 2026-09-14

用途与场景#

让数据库备份 Agent 在主机上执行一次手动备份脚本（pg_dump + gzip）。当前 Web 数据库备份页「触发备份」按钮调用本操作，成功后立刻刷新备份列表。

使用位置#

页面/功能	角色或空间分支
数据库备份页触发按钮	机构/管理员页面；Agent 签名鉴权

端点#

POST /agent-api/v1/db/backup — 触发一次 PostgreSQL 数据库备份。

端点全量事实（参数、请求/响应字段、错误码、权限点）见清单层 agent · db-backup-trigger 触发一次 PostgreSQL 数据库备份。

动线与完成判据#

status=200 且 data.outfile 非空表示备份脚本执行成功且产物文件名已知（同步完成语义）；脚本非零退出或 stdout 无产物行按技术错误信封拒绝（backup_handler.rs:65-81）。Web 成功后立即以新签名刷新列表。

错误与边界#

签名错误同查询数据库备份列表（Agent 鉴权出口）；脚本失败/无产物按技术错误信封拒绝。幂等性：重复提交会再次执行完整备份脚本并产生新文件，不幂等；重试前应先查列表确认。无并发防护的源码证据——并发的两次触发会并行跑两个脚本（PQueue 只在 Web 单页内串行）。

调用关系与资源清理#

无长连接资源。前置时间源见读取 Agent 服务器时间；产物供查询数据库备份列表与下载数据库备份消费。

已知缺口#

备份脚本本体（scripts/backup_db_manual.sh）的内部行为（pg_dump 参数、失败重试、磁盘清理）在 Agent 仓库 scripts/ 内，本票未逐行核验其数据库语义；部署环境 token prefix 与签名一致性未联调；并发触发的服务器侧行为未核验。