Agent 模式

Agent 备份已弃用。 Databasus 现在使用 PostgreSQL 17 原生备份远程执行物理备份和 PITR 备份，数据库服务器上无需安装任何 agent。了解原因以及现在 PITR 备份的工作方式。

Databasus agent 为 PostgreSQL 数据库提供物理备份、增量备份、WAL 归档和时间点恢复 (PITR)。

什么时候使用 agent

对大多数数据库来说，远程备份是最简单的方式。Databasus 通过网络直接连接数据库，用 pg_dump 做逻辑备份，数据库服务器上不需要任何额外软件。远程备份对云托管数据库（RDS、Cloud SQL、Supabase）和自托管实例都适用。

agent 是为远程备份不够用的场景设计的：

基于 PITR 的灾难恢复 — 恢复到两次备份之间的任意一秒，数据丢失接近于零
物理备份 — 对整个数据库集群做文件级复制，大数据集的备份和恢复更快
不对外暴露的数据库 — agent 主动向外连接 Databasus，数据库无需公开端点
增量备份 — 持续的 WAL 段归档结合周期性的基础备份

应用内引导式配置

Databasus 直接在界面里提供交互式的安装和恢复指引。打开某个数据库的 agent 设置时，所有命令都已预填好你的具体值：架构、数据库 ID、agent 令牌、Databasus 主机地址和 PostgreSQL 部署类型。你可以逐条复制命令，在服务器上执行。

下面的文档覆盖同样的步骤，供查阅参考，也方便更喜欢在界面之外按指南操作的用户。

前提条件

PostgreSQL 15 或更新版本
Linux（amd64 或 arm64）
网络访问：agent 能连到你的 Databasus 实例（仅出站连接，数据库不需要能被 Databasus 访问到）

安装

第 1 步 — 下载 agent

在运行 PostgreSQL 的服务器上下载 agent 二进制文件。把 <DATABASUS_HOST> 替换成你的 Databasus 实例地址，把 <ARCH> 替换成 amd64 或 arm64。

curl -L -o databasus-agent "<DATABASUS_HOST>/api/v1/system/agent?arch=<ARCH>" && chmod +x databasus-agent

第 2 步 — 配置 postgresql.conf

在 postgresql.conf 中添加或更新以下设置，然后重启 PostgreSQL。

主机安装（把 <WAL_QUEUE_DIR> 替换成实际路径，例如 /opt/databasus/wal-queue）：

wal_level = replica
archive_mode = on
archive_command = 'cp %p <WAL_QUEUE_DIR>/%f.tmp && mv <WAL_QUEUE_DIR>/%f.tmp <WAL_QUEUE_DIR>/%f'

Docker 安装时，archive_command 中的路径（/wal-queue）是容器内部的路径，必须和卷挂载的目标路径一致，见第 5 步。

wal_level = replica
archive_mode = on
archive_command = 'cp %p /wal-queue/%f.tmp && mv /wal-queue/%f.tmp /wal-queue/%f'

第 3 步 — 配置 pg_hba.conf

在 pg_hba.conf 中加入下面这行。这是 pg_basebackup 做全量备份所必需的，不是为了流复制。按需调整地址和认证方式，然后重新加载 PostgreSQL。

host    replication   all   127.0.0.1/32   md5

第 4 步 — 授予 replication 权限

这是运行 pg_basebackup 的 PostgreSQL 要求，并不会创建副本。

ALTER ROLE <YOUR_PG_USER> WITH REPLICATION;

第 5 步 — 创建 WAL 队列目录

PostgreSQL 会把 WAL 归档文件放到这里，供 agent 上传。

mkdir -p /opt/databasus/wal-queue

确保该目录对 PostgreSQL 可写、对 agent 可读：

chown postgres:postgres /opt/databasus/wal-queue
chmod 755 /opt/databasus/wal-queue

Docker 安装时，WAL 队列目录必须是 PostgreSQL 容器和主机之间共享的卷挂载。agent 从主机路径读取 WAL 文件，而 PostgreSQL 通过 archive_command 写入容器内的路径。

# In your docker run command:
docker run ... -v /opt/databasus/wal-queue:/wal-queue ...

# Or in docker-compose.yml:
volumes:
  - /opt/databasus/wal-queue:/wal-queue

确保容器内的目录属于 postgres 用户：

# Inside the container (or via docker exec):
chown postgres:postgres /wal-queue

第 6 步 — 启动 agent

把 <ANGLE_BRACKETS> 占位符替换成你的实际值。

系统级 PostgreSQL（pg_basebackup 已在 PATH 中）：

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=host \
  --pg-wal-dir=/opt/databasus/wal-queue

安装在特定目录的 PostgreSQL（例如 /usr/lib/postgresql/17/bin）：

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=host \
  --pg-host-bin-dir=<PATH_TO_PG_BIN_DIR> \
  --pg-wal-dir=/opt/databasus/wal-queue

Docker（使用容器内部的 PostgreSQL 端口，通常是 5432，而不是映射到主机的端口）：

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=docker \
  --pg-docker-container-name=<CONTAINER_NAME> \
  --pg-wal-dir=/opt/databasus/wal-queue

安装之后

执行 start 后 agent 在后台运行
查看状态：./databasus-agent status
查看日志：工作目录下的 databasus.log
停止 agent：./databasus-agent stop

从 agent 备份恢复

把物理备份或增量备份恢复到目标目录。做时间点恢复时，加上 --target-time 参数恢复到指定时刻。

第 1 步 — 下载 agent

在要执行恢复的服务器上下载 agent 二进制文件（命令与安装的第 1 步相同）。

curl -L -o databasus-agent "<DATABASUS_HOST>/api/v1/system/agent?arch=<ARCH>" && chmod +x databasus-agent

第 2 步 — 停止 PostgreSQL

恢复前必须停止 PostgreSQL。目标目录必须为空。

pg_ctl -D <PGDATA_DIR> stop

Docker 环境下：

docker stop <CONTAINER_NAME>

第 3 步 — 执行恢复

把 <YOUR_AGENT_TOKEN> 替换成你的 agent 令牌，把 <PGDATA_DIR> 替换成一个空的 PostgreSQL 数据目录路径。

主机安装：

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --target-dir=<PGDATA_DIR>

Docker 安装（<HOST_PGDATA_PATH> 是主机上将被挂载为容器 pgdata 卷的路径）：

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --pg-type=docker \
  --target-dir=<HOST_PGDATA_PATH>

在（重新）创建 postgres 容器时，把 <HOST_PGDATA_PATH> 挂载到容器的 PGDATA 路径。该路径取决于主版本号：PostgreSQL 18+ 使用 /var/lib/postgresql/<major>/docker；PostgreSQL 17 及更早版本使用 /var/lib/postgresql/data。

# PostgreSQL 17 and earlier
docker run -d -v <HOST_PGDATA_PATH>:/var/lib/postgresql/data postgres:17

# PostgreSQL 18+
docker run -d -v <HOST_PGDATA_PATH>:/var/lib/postgresql/18/docker postgres:18

要做时间点恢复（PITR），加上 --target-time 和一个 RFC 3339 时间戳（例如 2025-01-15T14:30:00Z）：

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --target-dir=<PGDATA_DIR> \
  --target-time=<RFC3339_TIMESTAMP>

第 4 步 — 处理 archive_command

恢复出来的备份包含原来的 archive_command 配置。恢复完成后 PostgreSQL 归档 WAL 文件会失败，除非你二选一：

重新接入 agent — 挂载 WAL 队列目录并在恢复出来的实例上启动 Databasus agent，与最初的配置相同。
关闭归档 — 如果暂时不需要持续备份，在 postgresql.auto.conf 中注释掉或重置归档设置：

# In <PGDATA_DIR>/postgresql.auto.conf, remove or comment out:
# archive_mode = on
# archive_command = '...'

第 5 步 — 启动 PostgreSQL

启动 PostgreSQL 开始 WAL 恢复。它会自动重放 WAL 段。

pg_ctl -D <PGDATA_DIR> start

Docker 环境下：

docker start <CONTAINER_NAME>

第 6 步 — 清理

恢复完成后，删除 WAL 恢复目录：

rm -rf <PGDATA_DIR>/databasus-wal-restore/

工作原理

Databasus agent 是一个轻量的 Go 二进制程序，同时运行两个并发进程：

WAL 流式上传 — 大约每 10 秒从队列目录取出 WAL 段文件并上传到 Databasus
周期性基础备份 — 按配置的计划运行 pg_basebackup，为数据库集群创建完整的物理备份

恢复时，agent 下载基础备份和所有相关的 WAL 段，然后在 postgresql.auto.conf 中配置 recovery.signal 和 restore_command。PostgreSQL 启动后重放 WAL 段，直到到达目标恢复点。

连接始终由 agent 主动发起（出站方向）。数据库服务器不需要接受来自 Databasus 的入站连接，因此适合私有网络和有防火墙的环境。