databasus--databasus/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

PostgreSQL 备份工具

Databasus 是一款免费、开源且可自托管的 PostgreSQL 备份工具。支持将备份存储到多种存储后端（S3、Google Drive、FTP 等），并通过多种渠道发送进度通知（Slack、Discord、Telegram 等）。专注于低 RPO/RTO 的点时点恢复（Point-in-Time Recovery，PITR）

功能 • 安装 • 使用 • 许可证 • 贡献

🌐 Databasus 官网

---

✨ 功能

📦 备份类型

• 物理备份（Physical）：通过 PostgreSQL 原生增量备份机制对整个数据库集群进行文件级复制（了解更多）
  • 全量（Full）：集群的完整、自包含副本
  • 增量（Incremental）：仅保存自上次全量备份以来的变更，使备份体积更小、速度更快
  • WAL 流式传输（WAL streaming）：持续捕获数据库写入流，支持点时点恢复（Point-in-time recovery，PITR）。面向灾难恢复与接近零数据丢失场景而设计
• 逻辑备份（Logical）：以引擎专属二进制格式对数据库进行原生转储（已压缩，适合并行恢复）

🔄 定时备份

• 灵活调度：按小时、按天、按周、按月或 cron
• 精确时间：在指定时间执行备份（例如，在低流量时段的凌晨 4 点）
• 智能压缩：在均衡压缩下节省 4-8 倍空间（约 20% 开销）

🧪 恢复验证 （文档）

Databasus 会执行真实恢复以确认备份可用，而不仅仅检查磁盘完整性或校验和。

• 触发方式：每次备份后，或按灵活计划（按小时、按天、按周、按月或 cron）
• 真实恢复：启动数据库容器，执行恢复，并将恢复后大小与备份进行比对
• 报告：列出每张表及其行数
• 可选通知：通过任意已配置的通知渠道发送报告，或仅在失败时发送告警

🗑️ 保留策略

• 时间周期：在固定时长内保留备份（例如 7 天、3 个月、1 年）
• 数量：保留固定数量的最新备份（例如最近 30 个）
• GFS（Grandfather-Father-Son）：分层保留——分别独立保留按小时、按天、按周、按月、按年的备份，以实现细粒度的长期历史（企业需求）
• 大小限制：为单次备份和总存储设置上限，以控制存储用量

🗄️ 多存储目标 （查看支持列表）

• 本地存储：将备份保留在你的 VPS/服务器上
• 云存储：S3、Cloudflare R2、Google Drive、NAS、Dropbox、SFTP、Rclone 等
• 安全可控：所有数据始终由你掌控

📱 通知 （查看支持列表）

• 多渠道：Email、Telegram、Slack、Discord、webhooks
• 实时更新：成功与失败通知
• 团队集成：非常适合 DevOps 工作流

🔒 企业级安全 （文档）

• AES-256-GCM 加密：为备份文件提供企业级保护
• 零信任存储（Zero-trust storage）：备份经过加密，对攻击者毫无价值，因此可安全存放在 S3、Azure Blob Storage 等共享存储中
• 敏感信息加密：任何敏感数据均会加密，绝不会暴露，即使在日志或错误消息中也不例外
• 只读用户：Databasus 默认使用只读用户执行备份，且从不存储任何可修改你数据的内容

👥 适合团队使用 （文档）

• 工作区（Workspaces）：为不同项目或团队分组管理数据库、通知器与存储
• 访问管理：通过基于角色的权限控制谁可查看或管理特定数据库
• 审计日志：跟踪所有系统活动及用户所做的变更
• 用户角色：在工作区内分配查看者（viewer）、成员（member）、管理员（admin）或所有者（owner）角色

🎨 用户体验友好

• 设计师打磨的 UI：干净、直观的界面，细节考究
• 深色与浅色主题：选择适合你工作流的外观
• 移动端适配：在任何设备上随时随地查看备份状态

💾 支持的数据库

• PostgreSQL：14、15、16、17 和 18（物理与逻辑）
• MySQL：5.7 和 8（仅逻辑）
• MariaDB：10、11 和 12（仅逻辑）
• MongoDB：4.2+、5、6、7 和 8（仅逻辑）

🐳 自托管且安全

• 基于 Docker：易于部署与管理
• 隐私优先：所有数据保留在你的基础设施上
• 开源：Apache 2.0 许可，可逐行审查代码

📦 安装 （文档）

你有四种方式安装 Databasus：

• 自动化脚本（推荐）
• 简单 Docker run
• Docker Compose 配置
• 使用 Helm 的 Kubernetes

---

📦 安装

你有四种方式安装 Databasus：自动化脚本（推荐）、简单 Docker run，或 Docker Compose 配置。

选项 1：自动化安装脚本（推荐，仅 Linux）

安装脚本将：

• ✅ 安装 Docker 与 Docker Compose（若尚未安装）
• ✅ 设置 Databasus
• ✅ 配置系统重启后自动启动

sudo apt-get install -y curl && \
sudo curl -sSL https://raw.githubusercontent.com/databasus/databasus/refs/heads/main/install-databasus.sh \
| sudo bash

选项 2：简单 Docker run

运行 Databasus 的最简单方式：

docker run -d \
  --name databasus \
  -p 4005:4005 \
  -v ./databasus-data:/databasus-data \
  --restart unless-stopped \
  databasus/databasus:latest

这条命令将：

• ✅ 启动 Databasus
• ✅ 将所有数据存储在 ./databasus-data 目录中
• ✅ 在系统重启后自动重启

选项 3：Docker Compose 配置

创建一个 docker-compose.yml 文件，内容如下：

services:
  databasus:
    container_name: databasus
    image: databasus/databasus:latest
    ports:
      - "4005:4005"
    volumes:
      - ./databasus-data:/databasus-data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "databasus", "healthcheck"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s

然后运行：

docker compose up -d

选项 4：使用 Helm 部署 Kubernetes

对于 Kubernetes 部署，可直接从 OCI 镜像仓库安装。

使用 ClusterIP + port-forward（开发/测试）：

helm install databasus oci://ghcr.io/databasus/charts/databasus \
  -n databasus --create-namespace

kubectl port-forward svc/databasus-service 4005:4005 -n databasus
# Access at http://localhost:4005

使用 LoadBalancer（云环境）：

helm install databasus oci://ghcr.io/databasus/charts/databasus \
  -n databasus --create-namespace \
  --set service.type=LoadBalancer

kubectl get svc databasus-service -n databasus
# Access at http://<EXTERNAL-IP>:4005

使用 Ingress（基于域名的访问）：

helm install databasus oci://ghcr.io/databasus/charts/databasus \
  -n databasus --create-namespace \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=backup.example.com

更多选项（NodePort、TLS、Gateway API 的 HTTPRoute），请参阅 Helm chart README。

---

🚀 使用方法

1. 访问控制面板：前往 http://localhost:4005
2. 添加第一个待备份数据库：点击 "New Database" 并按照设置向导操作
3. 配置计划：可选择每小时、每天、每周、每月或 cron 间隔
4. 设置数据库连接：输入数据库凭据和连接信息
5. 选择存储：选择备份存放位置（本地、S3、Google Drive 等）
6. 配置保留策略：选择时间段、数量或 GFS，以控制备份保留时长
7. 添加通知（可选）：配置电子邮件、Telegram、Slack 或 webhook 通知
8. 保存并启动：Databasus 将验证设置并开始备份计划

🔑 重置密码 （文档）

如需重置密码，可使用内置的密码重置命令：

docker exec -it databasus ./main --new-password="YourNewSecurePassword123" --email="admin"

将 admin 替换为需要重置密码的用户的实际电子邮件地址。

💾 备份 Databasus 自身

安装完成后，也建议 备份 Databasus 自身，或至少复制用于加密的密钥（约需 30 秒）。这样，若你无法访问运行 Databasus 的服务器或其已损坏，仍可从加密备份中恢复。

---

🛡️ 安全与可靠性工程

Databasus 处理敏感数据，因此防范漏洞、未授权访问和数据泄露是首要关注点。我们在系统两侧都为此投入：代码本身（权限检查、加密、谨慎处理密钥）以及周边基础设施（依赖分析、CVE 响应、DevSecOps 最佳实践）。以下流水线会在每次提交和 PR 时自动运行。任何单一层次都无法独立奏效，但组合起来可降低存在漏洞的代码、不安全的依赖、损坏的镜像或无法恢复的备份进入发布的概率。

静态分析方面，我们结合多种独立检查。CodeQL 扫描整个代码库以发现安全问题。CodeRabbit 审查每个 PR，并运行 gitleaks 进行密钥扫描、semgrep 进行内联安全规则检查。Dockerfile 和 CI 工作流另有专属规则（固定 action 引用、最小权限、可疑基础镜像），因此不安全模式在合并前就会被标记。在这些按 PR 检查之上，OpenAI 的 Codex Security 会定期对整个代码库进行更深入的审计。这是一项独立计划，可发现狭窄的 PR 期扫描可能遗漏的架构性与横切问题。

依赖方面，Dependabot 对照 GitHub Advisory Database 监控我们所有依赖，并在 CVE 发布后数分钟内即予以披露。更新会经过冷却期，使新发布版本有机会成熟后再被采用。这是针对供应链攻击等受污染软件包事件的刻意防护。Dependency Review Action 会直接阻止引入新的 HIGH 或 CRITICAL 级 CVE 的任何 PR。

每次构建都会用 Trivy 扫描容器镜像。对 Dockerfile 的单独 Trivy 检查可在错误配置进入镜像前发现它们。所有 GitHub Actions 均固定到完整 commit SHA，而非 @v4 或 @main 这类浮动标签——它们在 2025 年曾是活跃的攻击向量。工作流默认采用最小权限，仅在实际需要时才按作业提升权限。

关键路径由单元测试和集成测试共同覆盖，针对每个受支持引擎及主要版本在真实数据库容器中运行。对备份工具而言，恢复路径最为关键，因此我们明确测试它：每个 PR 都会对这些真实容器运行完整的备份—恢复周期，验证备份能够端到端恢复，而不仅是成功写入。CI/CD 流水线的其余部分在每次 PR 时运行 lint、类型检查、完整测试套件、镜像冒烟测试和多架构构建。仅当全部通过才会发布版本。

发现漏洞？请通过 GitHub Security 选项卡报告。请参阅 SECURITY.md. 安全报告是最高优先级的工作队列。有关运行时应用安全（静态数据 AES-256-GCM、零信任存储、加密密钥、默认只读数据库用户），请参见上文 Features 部分的 Enterprise-grade security。

---

📝 许可证

本项目采用 Apache 2.0 License 许可——详见 LICENSE 文件。

🤝 贡献

欢迎贡献！请阅读 contributing guide 了解更多细节、优先级和规则。如果你想贡献但不知从何入手，可在 Telegram 上联系我 @rostislav_dugin

你也可以在 Telegram 上加入由开发者、DBA 和 DevOps 工程师组成的大型社区 @databasus_community.

AI 免责声明

在 issues 和 discussions 中，有人就项目开发中的 AI 使用提出问题。由于本项目聚焦安全、可靠性与生产使用，说明 AI 在开发流程中的用法十分重要。

首先，我们自豪地宣布，Databasus 已于 2026 年 3 月同时入选 Anthropic 的 Claude for Open Source 与 OpenAI 的 Codex for Open Source。对我们来说，这再次表明该项目被认可为重要的开源软件，且作为关键基础设施，值得两家全球领先 AI 公司独立支持。更多信息请见 databasus.com/faq.

尽管如此，我们对开发流程中 AI 的使用遵循以下规则：

AI 用作以下方面的辅助：

• 代码质量验证与漏洞查找
• 清理和改进文档、注释与代码
• 开发过程中的协助
• 人工审查后对 PR 和提交进行二次核对
• 通过 Codex Security 对 PR 进行额外安全分析

AI 不用于：

• 编写完整代码
• 「vibe code」式开发
• 未经人工逐行验证的代码
• 没有测试的代码

因此，AI 只是帮助开发者提高生产力并确保代码质量的助手和工具。实际工作由开发者完成。

此外，重要的是我们并不区分劣质人工代码与 AI vibe code。任何要合并的代码都有严格要求，以保持代码库可维护。

即使代码由人工手动编写，也不保证会被合并。完全不允许 vibe code，此类 PR 默认一律拒绝（参见 contributing guide).

这些规则背后的工程保障措施（CI、静态分析、依赖扫描、测试覆盖率与漏洞响应）详见上文 安全与可靠性工程。