Databasus v3.63.1 配置参数详解

目标：以 v3.63.1 实测为准，讲清 Databasus 的全部配置面——数据目录结构与加密主密钥、数据库连接参数（逻辑/物理/SSL/SSH 隧道）、备份计划与保留策略、存储与通知渠道、健康检查与恢复验证代理、以及实例级管理命令。全部参数均经过 2026-10-24 的真实部署验证，配套部署过程见《Databasus v3.63.1 Docker Compose 部署指南》。

一、环境信息

• 实测日期：2026-10-24；实测版本：v3.63.1（GET /api/v1/system/version 返回 {"version":"3.63.1"}）；
• 部署形态：Docker Compose 单体服务（内嵌 PostgreSQL 元数据库），数据目录 databasus-data/；
• 配置来源三类：① 数据目录中的文件与目录（磁盘态）；② Web 控制台/API 写入的库内配置（运行态）；③ 容器启动参数与管理命令（进程态）。Databasus 没有单一主配置文件，配置以「目录结构 + 库内配置」为主；
• 本文引用的响应/回显均来自实测环境（工作区 prod-workspace，接入 PostgreSQL 16 逻辑、PostgreSQL 17 物理、MySQL 8.0 三个备份目标）。

二、数据目录结构（磁盘态）

Databasus 的一切持久化都在 databasus-data/（安装脚本默认 /opt/databasus/databasus-data，Compose 部署为挂载卷路径）。实测目录结构：

databasus-data/
├── secret.key        # 加密主密钥：全部凭据与备份加密的根
├── instance.json     # 实例标识信息
├── databasus.log     # 应用与审计日志（默认同时落文件）
├── pgdata/           # 内部 PostgreSQL 数据目录（全部配置与备份元数据）
└── backups/          # 本地存储目的地下的备份文件
    ├── pg16-appdb-20261024-092116-<backupId>.dump       # pg_dump custom 加密产物
    ├── pg16-appdb-....dump.metadata                     # 备份元数据
    ├── pg17-physical-FULL-...-<backupId>.manifest       # 物理备份清单
    └── pg17-physical-FULL-...-<backupId>.metadata

官方 FAQ 对「备份 Databasus 自身」给出两档口径：

1. 只保恢复能力：仅需备份 secret.key——凭据密文无主密钥不可读，凭 secret.key 即可在无 Databasus 实例的情况下手工解密恢复备份（官方提供 manual recovery 指引）；
2. 完整重建实例：备份 secret.key + pgdata/（含全部配置、计划与备份历史），在新服务器重建 databasus-data 目录结构后启动即可恢复整个管理台。

secret.key 丢失即永久失去全部加密备份与凭据，务必离线单独保管。

三、数据库连接参数（备份目标）

三类备份目标的连接配置以「类型判别 + 引擎子对象」结构存储。实测创建请求与回读字段如下。

3.1 逻辑备份目标（PostgreSQL / MySQL / MariaDB / MongoDB）

创建请求体（POST /api/v1/databases/create，实测字段）：

{
  "name": "pg16-appdb",
  "workspaceId": "<工作区ID>",
  "type": "POSTGRES_LOGICAL",
  "postgresqlLogical": {
    "host": "10.89.67.2", "port": 5432,
    "username": "backup_ro", "password": "q1w2e3r4",
    "database": "appdb",
    "cpuCount": 2
  }
}

• type 枚举：POSTGRES_LOGICAL / POSTGRES_PHYSICAL / MYSQL / MARIADB / MONGODB；
• 引擎子对象字段名与类型一一对应：postgresqlLogical、postgresqlPhysical、mysql、mariadb、mongodb；
• cpuCount 位于引擎子对象内（顶层传无效），控制并行转储的并发度，实测漏传时报 cpu count must be greater than 0；
• PostgreSQL 的库名字段是 database（不是 databaseName），传错时报 database name is required for single database backup (pg_dump)；
• 逻辑备份可选 includeSchemas / 排除表清单，用于缩小备份范围。

3.2 物理备份目标（仅 PostgreSQL 17+）

{
  "type": "POSTGRES_PHYSICAL",
  "postgresqlPhysical": {
    "host": "10.89.67.3", "port": 5432,
    "username": "appuser", "password": "q1w2e3r4"
  }
}

物理备份无单库概念（整集群级），故无 database 字段；要求目标角色具备 REPLICATION 权限且 pg_hba.conf 放行复制连接（排障实录见部署指南 5.2）；目标实例需 PostgreSQL 17+ 并开启 summarize_wal。远程物理备份走标准复制协议，数据库服务器上无需安装任何组件，兼容 RDS/Cloud SQL 等托管库。

3.3 SSL 与 SSH 隧道

实测回读的连接对象中还包含以下可选项（默认关闭）：

• sslMode：disable（默认）/ require / verify-ca / verify-full，配 sslClientCert / sslClientKey / sslRootCert 三项证书字段（PEM 内容直接粘贴，无需挂文件）；
• isHttps：MySQL/MariaDB 走 HTTPS 代理连接时的开关；
• sshTunnel：{"isEnabled":false,"host":"","port":22,"username":"","authType":"PASSWORD"...}——目标库在内网时经堡垒机 SSH 隧道接入，认证支持密码与私钥两种（authType）。

凭据安全：密码字段落库即 AES-256-GCM 加密，回读呈 enc:<密文> 前缀，API 与 UI 均不回明文；主密钥在 secret.key 不入库。

3.4 接入预检与只读用户

接入前可先调 POST /api/v1/databases/test-connection-direct 做免创建的连通性预检（字段结构同 create）。Databasus 对逻辑备份用户执行三层只读校验（角色级非超管、库级无 CREATE/TEMP、表级零写权限），并额外校验「pg_dump 能导出的对象全部可读」——实测只读角色缺 SEQUENCE 的 SELECT 会被拒绝并精确列出缺失对象（Missing SELECT on: public.customers_id_seq, ...）。配套提供两个一键端点：/api/v1/databases/create-readonly-user（创建只读备份用户）与 /api/v1/databases/create-replication-only-user（创建仅复制权限用户，供物理备份使用）。

四、备份计划参数（运行态核心）

备份计划按「逻辑备份」与「物理备份」两套独立配置。

4.1 逻辑备份计划（backup-configs/save）

GET /api/v1/backup-configs/database/<id> 回读的完整结构（实测）：

{
  "databaseId": "2b4356f2-...",
  "isBackupsEnabled": false,
  "retentionPolicyType": "TIME_PERIOD",
  "retentionTimePeriod": "3_MONTH",
  "retentionCount": 0,
  "retentionGfsHours": 0, "retentionGfsDays": 0,
  "retentionGfsWeeks": 0, "retentionGfsMonths": 0, "retentionGfsYears": 0,
  "backupInterval": {"type": "DAILY", "timeOfDay": "04:00"},
  "storage": null, "storageId": null,
  "sendNotificationsOn": ["BACKUP_FAILED", "BACKUP_SUCCESS"],
  "isRetryIfFailed": true,
  "maxFailedTriesCount": 3,
  "encryption": "NONE"
}

逐项说明与实测注意点：

1. backupInterval：HOURLY / DAILY / WEEKLY / MONTHLY / CRON；daily/weekly/monthly 必须给 timeOfDay（UTC 时刻），缺时报 time of day is required for daily, weekly and monthly intervals；cron 为 UTC 表达式；
2. 保留策略三选一（retentionPolicyType）：
   • TIME_PERIOD：retentionTimePeriod 取值 DAY/WEEK/MONTH/3_MONTH/6_MONTH/YEAR/2_YEARS/…/5_YEARS/FOREVER（字符串枚举，非天数）；
   • COUNT：retentionCount 保留最近 N 份；
   • GFS：retentionGfsHours/Days/Weeks/Months/Years 五层各自保留数，缺省 0 表示该层不启用；
   • 实测保存计划时若完全不带保留字段会报 retention time period is required；
3. storage：保存请求传 {"storage": {"id": "<存储ID>"}} 对象形式（实测顶层传 storageId 字符串不生效）；未绑定存储时手动备份会静默失败（API 返回成功，服务日志 backup config storage ID is nil）；
4. encryption：NONE / ENCRYPTED。ENCRYPTED 即 AES-256-GCM，每份备份独立派生密钥（主密钥 + 备份 ID + 随机盐），实测开启后产物落盘为密文且响应中 encryption: "ENCRYPTED"；
5. 通知绑定：sendNotificationsOn 事件枚举含 BACKUP_SUCCESS / BACKUP_FAILED（物理链另有 CHAIN_BROKEN / WAL_GAP）；
6. 重试：isRetryIfFailed + maxFailedTriesCount（默认 3）。

4.2 物理备份计划（backup-configs/physical/save）

GET /api/v1/backup-configs/physical/database/<id> 回读（实测）：

{
  "databaseId": "9ab183c2-...",
  "isBackupsEnabled": false,
  "fullBackupInterval": {"type": "DAILY", "timeOfDay": "04:00"},
  "incrementalBackupInterval": {"type": "", "timeOfDay": null},
  "retention": "FULL_BACKUPS",
  "chainsRetention": {"count": 0},
  "fullBackupsRetention": {"policy": "LAST_N", "count": 7, "gfsHours": 0, "gfsDays": 0, "gfsWeeks": 0, "gfsMonths": 0, "gfsYears": 0},
  "walLagThresholdBytes": 0,
  "storage": null, "storageId": null,
  "encryption": "NONE",
  "sendNotificationsOn": ["BACKUP_FAILED", "BACKUP_SUCCESS", "CHAIN_BROKEN", "WAL_GAP"]
}

要点：

• 双计划结构：全量（fullBackupInterval）与增量（incrementalBackupInterval）各自独立调度；
• 备份链模式：创建数据库时可选 FULL（仅全量）/ FULL_INCREMENTAL（全量+块级增量）/ FULL_INCREMENTAL_WAL_STREAM（再加 WAL 持续流，支持 PITR）；手动触发时 type 取 FULL / INCREMENTAL / WAL（小写，实测传大写 FULL 报 oneof 校验错误）；
• 保留策略：retention 取 CHAINS（按链保留，chainsRetention.count）或 FULL_BACKUPS（按全量份数，fullBackupsRetention.policy 取 LAST_N 或 GFS）；
• walLagThresholdBytes：WAL 流落后字节数阈值，超限触发 WAL_GAP 告警。

五、存储目的地参数

存储以判别式结构存储（实测创建 LOCAL 后回读）：

{
  "id": "44c8c746-...", "workspaceId": "fa0e4f67-...",
  "type": "LOCAL", "name": "local-main",
  "localStorage": null, "s3Storage": null, "googleDriveStorage": null,
  "nasStorage": null, "azureBlobStorage": null,
  "ftpStorage": null, "sftpStorage": null, "rcloneStorage": null,
  "lastSaveError": null
}

• type 枚举：LOCAL / S3 / GOOGLE_DRIVE / NAS / AZURE_BLOB / FTP / SFTP / RCLONE；
• 每类目的地的参数填在同名子对象中（如 S3 的 s3Storage），二进制中可见 S3 支持 storageClass 存储类分级（STANDARD / STANDARD_IA / ONEZONE_IA / INTELLIGENT_TIERING / REDUCED_REDUNDANCY / GLACIER_IR）；
• 通用操作：/api/v1/storages/<id>/test（连通性测试）、/api/v1/storages/<id>/transfer（跨工作区迁移，会检查该存储被多少数据库引用，databases-count 端点）；
• lastSaveError 记录最近一次向该存储写入失败的详情，排障先看它。

六、通知渠道参数

通知渠道结构与存储同构（notifierType + 各引擎子对象）。实测创建 WEBHOOK 的请求体：

{
  "name": "ops-webhook",
  "workspaceId": "fa0e4f67-...",
  "notifierType": "WEBHOOK",
  "webhookNotifier": {
    "webhookUrl": "http://10.89.67.1:8146/databasus-hook",
    "webhookMethod": "POST",
    "headers": [],
    "skipTlsVerify": false
  }
}

实测结论：

• 请求字段名为 notifierType（响应中显示 type）；直连 API 误传 type 会触发服务端 panic（unknown notifier type: ""，HTTP 500 空响应），属 v3.63.1 已知坑；
• notifierType 枚举：WEBHOOK / TELEGRAM / EMAIL / SLACK / DISCORD / TEAMS / MATTERMOST；各子对象分别为 webhookNotifier / telegramNotifier / emailNotifier / slackNotifier / discordNotifier / mattermostNotifier；
• WEBHOOK 的 webhookMethod 枚举为 POST / GET；headers 是数组结构（传对象会报反序列化错误）；skipTlsVerify 自签证书场景用；
• WEBHOOK 通知实测载荷（备份成功事件）：

{"heading":"✅ Backup completed for database \"pg16-appdb\" (workspace \"prod-workspace\")",
 "message":"Backup completed successfully in 0m 0s.\nCompressed backup size: 0.01 MB"}

• 配套端点：/api/v1/notifiers/<id>/test（发送测试通知）、/api/v1/notifiers/direct-test（免创建直测）、/api/v1/notifiers/<id>/transfer（跨工作区迁移）。

七、健康检查与实例级配置

7.1 健康检查配置

GET /api/v1/healthcheck-config 为按数据库的连通性探测配置：Databasus 按分钟级间隔探测已接入数据库的可达性，连续失败判定宕机触发 HEALTHCHECK_FAILURE 通知，恢复时触发恢复通知，探测历史可在 UI 查看（/api/v1/healthcheck-attempts/<id>）。

7.2 双健康端点的取舍

官方明确警告：监控端点不得用作编排存活探针——「降级但仍在服务」返回 503 会误杀健康容器。

7.3 用户与安全设置

实例级安全设置（Settings 页 / users/settings 端点）：

• 强制两步验证：开启后密码登录需输入邮箱六位码（10 分钟有效、错 5 次作废、重发替换旧码）；前置条件是实例已配置邮件服务器且全部活跃管理员有真实邮箱；已登录会话不受影响。运维兜底：docker exec -it databasus ./main --disable-2fa（操作会记入审计日志）；
• OAuth 登录：Google / GitHub（回调路径 /api/v1/auth/google/callback、/api/v1/auth/github/callback）；
• 审计日志：/api/v1/audit-logs/global（全局）与 /api/v1/audit-logs/users/<id>（按用户），实测创建数据库、触发备份等操作均有 log_type=audit 记录（含用户、工作区、请求 ID）；
• OpenTelemetry：应用与审计日志可导出到外部系统，默认同时落本地 databasus.log。

八、恢复验证代理参数

自动恢复验证代理（独立 Go 二进制）的四个预算参数实测口径：

预算按并发作业均摊（单作业下限 1 CPU + 512 MB，预算不足时代理自动下调上报的并发度）。子命令四件套：start（守护进程化，参数写入工作目录 databasus-verification.json，重启可免参）、status、stop（进行中作业回报失败并重新入队）、run（前台运行，供 systemd/容器托管）。代理连接 Databasus 必须为 https，本地测试 HTTP 需显式 --allow-insecure-http。令牌只显示一次，泄露用控制台 Rotate token。

验证调度按数据库配置：After backup（每次备份后即验）或 hourly/daily/weekly/monthly/cron；同库新备份到达时自动取消排队中的旧验证，只验最新一份。结果五态：Pending / Running / Successful / Failed / Canceled。

九、实例管理命令与部署侧参数

9.1 管理命令（容器内 ./main）

实测可用（官方 README 与文档一致）：

docker exec -it databasus ./main --create-user --email="ops@example.com" --password="密码" --role=admin  # 免 UI 建号，可重复执行（幂等）
docker exec -it databasus ./main --new-password="新密码" --email="owner@example.com"                    # 重置密码
docker exec -it databasus ./main --list-admins                                                          # 列出管理员
docker exec -it databasus ./main --disable-2fa                                                          # 关闭强制 2FA（记审计日志）

--role 取 admin / member，密码至少 8 位，--name 可选显示名。

9.2 部署侧参数速查

• 端口：容器内固定 4005，宿主侧自定义映射（本文 8142）；
• 数据卷：唯一必需挂载 ./databasus-data:/databasus-data；
• 健康检查：test: ["CMD", "databasus", "healthcheck"]，start_period 建议 120s（首次启动最长约 2 分钟）;
• 重启策略：restart: unless-stopped；
• 升级：docker compose stop → 拉新镜像（可先 docker system prune -a 清缓存）→ 改标签 up -d；升级前备份 databasus-data；
• Postgresus 迁移：官方明确「只改镜像名不够」，新旧数据目录与内部库命名不同，需新卷全新安装后手工重建配置。

十、配置排障速查表

本文与部署指南实测沉淀的配置类错误对照：

十一、常见问题

1. 改了配置为什么不生效？ 备份计划、存储、通知均为库内配置保存即生效，无需重启；instance.json 与 secret.key 属实例身份文件，切勿手工编辑；
2. 如何验证我的计划配置对了？ 绑定存储后先手动触发一次备份（部署指南 6.4），看备份列表与存储目录产物，再依赖调度器按计划自动跑；
3. 加密备份如何脱离 Databasus 恢复？ 凭 secret.key 走官方 manual recovery 流程手工解密，或重新搭建实例导入 secret.key 后在 UI 下载解密；
4. 更多同类工具的配置参考？ 站内可对照 《BorgBackup 配置参数详解》、《pgBackRest 2.60.0 配置参数详解》与 《Backupninja 1.2.2 配置文件体系详解》——三者代表文件驱动型备份工具的配置范式，与 Databasus 的「库内配置 + Web 界面」范式互补。

十二、参考链接

1. 官方文档 Advanced config：https://databasus.com/advanced-config
2. 官方安装文档：https://databasus.com/installation
3. 官方安全文档（加密与 2FA 设计）：https://databasus.com/security
4. GitHub 仓库：https://github.com/databasus/databasus
5. 站内同组件：《Databasus v3.63.1 介绍与选型指南》、《Databasus v3.63.1 Docker Compose 部署指南》