真正理解onedump，要从它处理的任务开始：简化数据库备份、导出与恢复操作的管理工具，适合日常数据维护。在数据与知识处理场景里，常见问题是数据结构、更新策略和可追溯性会决定结果是否可信，这正是评估时需要盯住的地方。短测时我会用一份规模可控且答案已知的数据集试跑，并保留模式兼容、增量更新、查询结果和来源追踪的结果，方便团队复盘。它更像给需要保留数据来路与变更记录的使用者准备的可审查方案，是否长期使用应由试跑数据决定。

Onedump 是一种数据库管理工具，可简化跨多个数据库和存储目标的备份和恢复任务。

特点

• 数据库从不同源备份到不同目的地。
• MySQL 零依赖转储（带有内置 mysql 本机转储程序）。
• 支持具有依赖项的转储程序（mysqldump 和 pg_dump）。
• MySQL binlog 备份到 AWS S3。
• MySQL 从二进制日志恢复。
• MySQL 慢日志解析器。
• 可恢复和并发 SFTP 文件传输。
• 从 S3 存储桶加载配置。
• 松弛通知。
• 维护包含所有依赖项的 docker 映像。

目录

• 安装
  • 二进制
  • Docker 镜像
• 先决条件
• 运行 Onedump
• 工作原理
• 原生 MySQL 自卸车
• 慢日志解析器
• MySQL binlog 备份到 AWS S3
• MySQL binlog 恢复
• 可恢复并发 SFTP 文件传输
• 贡献

支持的源数据库

• MySQL
• PostgreSQL

支持的存储目的地

• 本地文件系统
• AWS S3
• 谷歌云端硬盘
• Dropbox
• SFTP

安装

onedump 通过发布过程提供二进制文件和 Docker 镜像。

二进制

onedump 二进制文件可从 https://github.com/liweiyi88/onedump/releases. 获取 使用适合您的 OS 的最新版本的二进制文件。 下载二进制文件并将其移动到 $PATH 环境变量（e.g.、/usr/local/bin/onedump）中的文件夹后，为其授予可执行权限（e.g.、sudo chmod +x /usr/local/bin/onedump）。然后你应该能够运行它：

$ onedump

Docker镜像

Docker 镜像也可以在 Docker Hub 中找到。

何时使用 Docker 镜像

1. 您希望在 Kubernetes、ECS 或任何其他容器环境中运行 onedump。

2. 目前，onedump 不提供开箱即用的本机 PostgreSQL 转储器。因此，对于 PostgreSQL，您需要在同一台机器上安装 pg_dump。 Docker镜像包含pg_dump，可以更轻松地运行onedump，无需额外手动安装。

3. 当当前的原生 MySQL 转储器不能满足您的需求而您需要 mysqldump 时。

使用特定的 pg_dump 版本

docker镜像包含mysql客户端、postgresql15-client和postgresql16-client。默认情况下它使用 postgresql16-client。但是，您可以传递环境 PG_VERSION 来在 15 和 16 之间切换 postgresql 客户端版本。例如，docker run -e PG_VERSION=15 julianli/onedump:v1.5.0-arm64 -f config.yaml。

尽管我们同时维护 ARM64 和 AMD64 Docker 映像，但通常您需要的是生产 Linux 计算机上的 AMD64 映像。例如：julianli/onedump:v1.5.0-amd64*

先决条件

onedump 提供本机 MySQL 转储程序，允许您使用 onedump 二进制文件转储 MySQL 数据库内容，而无需在计算机上安装 mysqldump。

如果您需要更高级的 MySQL 转储功能或 PostgreSQL 转储，您可能需要使用 mysqldump 或 pg_dump 转储程序，您需要在计算机上安装以下依赖项。

MySQL: mysql-client
PostgreSQL: postgresql-client

如果您使用我们维护的 Docker 映像，则默认包含这些工具。或者，如果需要进一步自定义，您可以自行扩展或构建 Docker 映像。

运行onedump

onedump 只有一个简单的命令来加载配置文件并根据配置转储 DB 内容。它有两种加载配置文件的方法。

选项 1.从本地目录加载配置文件

安装 onedump 后，您应该能够将其作为简单的 cli 命令运行。例如：

$ onedump -f /path/to/config.yaml

config.yaml 包含 yaml 格式的所有 DB 备份作业。对于所有可配置项目。参见 配置

选项 2.从 S3 存储桶加载配置

此外，您还可以将配置文件存储在 AWS S3 存储桶中，而不是从本地目录加载配置文件。运行 cli 命令从 S3 存储桶加载配置文件

$ onedump -f backup-config/config.yaml --s3-bucket mybucket

在这种情况下，您传递 --s3-bucket 选项来指示 onedump 应从名为 mybucket 的 s3 存储桶加载配置内容。然后onedump会将文件路径选项backup-config/config.yaml视为s3密钥。默认情况下，onedump 将使用任何 AWS 环境变量与 S3 交互，如果未找到环境变量，则它将使用 ~/.aws/credentials 文件中默认配置文件的凭据。要覆盖这些默认凭据，您可以传递 --aws-key、--aws-region 和 --aws-secret 选项。

配置举例

对于所有可配置项目和说明。参见 配置

转储本地 DB 到 2 个本地目录

jobs:
- name: local-dump
  dbdriver: mysql
  dbdsn: root@tcp(127.0.0.1)/test_local
  gzip: true
  storage:
    local:
      - path: /Users/jack/Desktop/mydb.sql
      - path: /Users/jack/Desktop/mydb2.sql

通过 SSH 转储远程 DB 并保存到本地目录和 S3 存储桶

jobs:
- name: ssh-dump
  dbdriver: mysql
  dbdsn: user:password@tcp(127.0.0.1:3306)/mydb
  sshhost: mywebsite.com
  sshuser: root
  sshkey: |-
    -----BEGIN OPENSSH PRIVATE KEY-----
    b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAACFwAAAAdzc2gtcn...
    -----END OPENSSH PRIVATE KEY-----
  storage:
    local:
      - path: /Users/jack/Desktop/db.sql
    s3:
      - bucket: mys3bucket
        key: backup/mydb.sql
        region: ap-southeast-2
        access-key-id: awsaccesskey
        secret-access-key: awssecret
        session-token: <session-token> # optional, specify the value if you assume a role.

多个转储到不同的存储

jobs:
- name: local-dump
  dbdriver: mysql
  dbdsn: root@tcp(127.0.0.1)/test_local
  storage:
    local:
      - path: /Users/jack/Desktop/mydb.sql
- name: ssh-dump
  dbdriver: mysql
  dbdsn: user:password@tcp(127.0.0.1:3306)/mydb
  sshhost: mywebsite.com
  sshuser: root
  sshkey: |-
    -----BEGIN OPENSSH PRIVATE KEY-----
    b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAACFwAAAAdzc2gtcn...
    -----END OPENSSH PRIVATE KEY-----
  storage:
    s3:
      - bucket: mys3bucket
        key: backup/mydb.sql
        region: ap-southeast-2
        access-key-id: awsaccesskey
        secret-access-key: awssecret
        session-token: <session-token> # optional, specify the value if you assume a role.

控制最大并发作业数

您可以通过在配置文件中设置 maxjobs 选项（默认情况下为 10 个作业）来控制同时运行的作业数量。例如：

maxjobs: 20
jobs:
- name: local-dump
  dbdriver: mysql
  ...

松弛通知

notifier:
    slack:
      - incomingwebhook: https://hooks.slack.com/services/A0B8A11N4N/...
jobs:
- name: local-dump
  dbdriver: mysql
  dbdsn: root@tcp(127.0.0.1)/test_local
  gzip: true
  storage:
    local:
      - path: /Users/jack/Desktop/mydb.sql

推荐

当您控制机器并希望将 onedump 作为普通 cli 命令运行时，从本地目录加载配置非常方便。但是，您有责任确保配置文件安全地存储在该计算机中，或者您可能自己负责静态加密。

另一方面，当您关心安全性（加密、版本控制和细粒度权限控制等）并且不方便使用持久卷来存储配置文件时（e.g。通过 docker 容器运行它），从 S3 存储桶加载配置会更好。而不是将配置文件从 S3 下载到本地目录。 onedump 将通过 AWS API 将配置直接从 S3 加载到内存。

它是如何运作的

onedump 的主要用例是使用配置文件运行一个命令。它将数据库从不同的驱动程序转储到不同的目的地。

连接到数据库

onedump 通过两种方式连接到数据库：直接网络访问或 SSH。

通过网络访问连接数据库

无论是从本地 DB 还是机器可以直接拨号的 DB 主机转储。您可以在配置文件中创建一个 job 可配置项

jobs:
- name: exec-dump
  dbdriver: mysql
  dbdsn: user:password@tcp(10.10.10.1)/dbname
  # the rest of config...

dbdriver 和 dbdsn 是能够连接到数据库的必填字段。对于本例，DB 主机位于具有 IP 地址 10.10.10.1 的专用网络中。当运行 onedump 的机器位于同一专用网络中时，可以连接到 DB。

通过SSH连接数据库

当启用 SSH 时，您还可以连接到远程数据库。在配置文件中创建job可配置项

jobs:
- name: ssh-dump
  dbdriver: mysql
  dbdsn: user:password@tcp(127.0.0.1:3306)/dbname
  sshhost: mywebsite.com
  sshuser: root
  sshkey: |-
    -----BEGIN OPENSSH PRIVATE KEY-----
    b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAACFwAAAAdzc2gtcn...
    -----END OPENSSH PRIVATE KEY-----
  # the rest of config...

对于这种情况，您需要传递三个额外的配置选项：sshhost、sshuser 和 sshkey 来告诉 onedump 通过 ssh 与远程数据库通信。

将 DB 保存到存储

需要为转储作业配置至少一个存储。例如，我们希望它转储本地 DB 并将内容保存在本地目录以及 S3 存储桶中。

jobs:
- name: local-dump
  dbdriver: mysql
  dbdsn: root@tcp(127.0.0.1)/db
  storage:
    local:
      - path: /Users/jack/Desktop/db.sql
    s3:
      - bucket: mybucket
        key: db-backup/mydb.sql
        region: ap-southeast-2
        access-key-id: MYKEY...
        secret-access-key: AWSSECRET..
        session-token: <session-token> # optional, specify the value if you assume a role.

设置 cron 作业

通过传递 cron 表达式以 cron 模式运行 onedump。

$ onedump -f /path/to/config.yaml -c 21h

原生MySQL自卸车

MySQL 本机转储程序提供与 mysqldump 类似的用户体验。然而，它并没有实现mysqldump的所有功能。它适用于大多数基本用例，但有一些限制：

1. 它不支持 MySQL 空间数据类型。例如，如果您使用 GEOMETRY、POINT 或 POLYGON 等空间数据类型，请使用 mysqldump 作为转储程序。

2. 它不支持所有 mysqldump 选项。目前支持--skip-add-drop-table和--skip-add-locks

如果本机 MySQL 转储程序不能满足您的需求，那么切换到 mysqldump 很容易。只需将配置文件中的dbdriver更新为mysqldump即可：

jobs:
- dbdriver: mysqldump
  ...

慢日志解析器

onedump还具有内置功能（与onedump slow [flags]一起运行）来解析MySQL慢日志并按以下结构打印JSON。

{ok: bool, error: string, results: []SlowResult}

例如

{"ok":true,"error":"","results":[{"time":"2023-10-15T12:36:05.987654Z","user":"admin[admin]","host_ip":"[192.168.1.101]","query_time":12.890323,"lock_time":0.001456,"rows_sent":100,"rows_examined":100000,"thread_id":0,"errno":0,"killed":0,"bytes_received":0,"bytes_sent":0,"read_first":0,"read_last":0,"read_key":0,"read_next":0,"read_prev":0,"read_rnd":0,"read_rnd_next":0,"sort_merge_passes":0,"sort_range_count":0,"sort_rows":0,"sort_scan_count":0,"created_tmp_disk_tables":0,"created_tmp_tables":0,"count_hit_tmp_table_size":0,"start":"","end":"","query":"SELECT customer_id, COUNT(*) as order_count FROM orders GROUP BY customer_id HAVING order_count > ?"}]}

用途

// parse a single file
$onedump slow -f /path/to/file/slow.log

// parse a folder
$onedump slow -f /path/to/folder 

// Parse a folder or file by searching for filenames that match the pattern
$onedump slow -f /path/to/folder-or-file -p="*slow.log"

// Mask query values with ?
$onedump slow -f /path/to/file -m="true"

MySQL binlog 备份到 AWS S3

binlog sync-s3 命令允许您将 MySQL 二进制日志 (binlog) 文件备份到 AWS S3 存储桶。这对于实现时间点恢复特别有用。

详细使用方法请参考文档。

MySQL 二进制日志恢复

binlog restore 命令可用作时间点恢复过程的一部分。它重播二进制日志中的事件并将数据恢复到指定的时间点。

详细使用方法请参考文档。

可恢复和并发 SFTP 文件传输

sync sftp 命令提供了一种使用 SFTP 协议将文件从源传输到远程目标的有效方法。它支持各种选项来适应不同的用例。

详细使用方法请参考文档。