wal-g/wal-g

# WAL-G   [](https://goreportcard.com/report/github.com/wal-g/wal-g) [](https://wal-g.readthedocs.io/?badge=latest) [本文档也可在 wal-g.readthedocs.io 查看](https://wal-g.readthedocs.io) WAL-G 是一款用于 PostgreSQL、MySQL/MariaDB 和 MS SQL Server 的归档恢复工具（也支持 MongoDB 和 Redis 的 beta 版本）。 WAL-G 是 WAL-E 的继任者，两者存在一些关键差异。WAL-G 使用 LZ4、LZMA、ZSTD 或 Brotli 压缩算法，支持多处理器以及 Postgres 的非独占基础备份。有关 WAL-G 最初设计和实现的更多信息，请参阅 Citus Data 博客中的文章 ["Citus 推出 WAL-G：更快的 Postgres 灾难恢复"](https://www.citusdata.com/blog/2017/08/18/introducing-wal-g-faster-restores-for-postgres/)。 **目录** - [安装](#installation) - [配置](#configuration) - [用法](#usage) - [数据库](#databases) - [开发](#development) - [安装说明](#installing) - [测试](#testing) - [Windows 开发](#development-on-windows) - [故障排除](#troubleshooting) - [作者](#authors) - [许可证](#license) - [致谢](#acknowledgments) - [交流群](#chat) ## 安装 最新版本 WAL-G 的 Linux AMD 64 预编译二进制文件可以在 [Releases 选项卡](https://github.com/wal-g/wal-g/releases)下获取。 二进制文件的名称采用以下格式：`wal-g-DBNAME-OSNAME`，其中 `DBNAME` 代表数据库名称（例如 pg、mysql），`OSNAME` 代表用于构建二进制文件的操作系统名称。 要解压该二进制文件，请使用： ``` tar -zxvf wal-g-DBNAME-OSNAME-amd64.tar.gz mv wal-g-DBNAME-OSNAME-amd64 /usr/local/bin/wal-g ``` 例如，针对 Postgres 和 Ubuntu 24.04： ``` tar -zxvf wal-g-pg-24.04-amd64.tar.gz mv wal-g-pg-24.04-amd64 /usr/local/bin/wal-g ``` 对于其他系统，请查阅 [开发](#development)章节以获取更多信息。 WAL-G 支持 bash 和 zsh 的自动补全。运行 `wal-g help completion` 以获取更多信息。 ## 配置 你可以通过以下两种方式配置 WAL-G： 1. 使用环境变量 2. 使用配置文件 可以使用 `--config /path` 标志来指定配置文件所在的路径。或者，你也可以设置 `WALG_CONFIG_PATH` 环境变量来指定配置文件的路径，这样就不需要每次都传递该标志。 我们支持 [viper 包](https://github.com/spf13/viper)支持的所有格式：JSON、YAML、envfile 以及[其他格式](https://github.com/spf13/viper#reading-config-files)。 以下文档中提到的每个配置变量，既可以指定为环境变量，也可以指定为配置文件中的字段。 ### 存储 要配置 WAL-G 存储备份的位置，请查阅 [Storages](STORAGES.md)章节。 ### 压缩 * `WALG_COMPRESSION_METHOD` 用于配置备份所使用的压缩方法。可用的选项有：`lz4`、`lzma`、`zstd`、`brotli`、`none`。默认方法是 `lz4`。LZ4 是最快的方法，但压缩率较差。 LZMA 的速度要慢得多。但是，它对备份的压缩效果大约比 LZ4 好 6 倍。Brotli 和 zstd 在速度和压缩率之间取得了良好的平衡，其压缩率大约比 LZ4 好 3 倍。None 压缩方法会禁用压缩。 ### 加密 * `YC_CSE_KMS_KEY_ID` 用于配置用于客户端加密和解密的 Yandex Cloud KMS 密钥。默认情况下，不使用加密。 * `YC_SERVICE_ACCOUNT_KEY_FILE` 用于配置包含 Yandex Cloud 服务账户私钥的文件名。如果未设置，将使用来自元数据服务 的 token 向 Yandex Cloud KMS 发起 API 调用。 * `WALG_LIBSODIUM_KEY` 用于配置使用 libsodium 进行加密和解密。WAL-G 使用一种只需密钥的[算法](https://download.libsodium.org/doc/secret-key_cryptography/secretstream#algorithm)。libsodium 密钥是固定大小为 32 字节的密钥。为了获得最佳的加密安全性，建议使用随机的 32 字节密钥。要生成随机密钥，你可以使用类似 `openssl rand -hex 32`（将 `WALG_LIBSODIUM_KEY_TRANSFORM` 设置为 `hex`）或 `openssl rand -base64 32`（将 `WALG_LIBSODIUM_KEY_TRANSFORM` 设置为 `base64`）的命令。 * `WALG_LIBSODIUM_KEY_PATH` 类似于 `WALG_LIBSODIUM_KEY`，但其值为文件系统上密钥的路径。文件内容将会去除首尾空白字符。 * `WALG_LIBSODIUM_KEY_TRANSFORM` 应用于 `WALG_LIBSODIUM_KEY` 以获取所需的 32 字节密钥的转换方式。支持的转换有 `base64`、`hex` 或 `none`（默认）。 `none` 选项的存在是为了向后兼容，用户输入将通过截断或零填充转换为 32 字节。 * `WALG_GPG_KEY_ID` (替代形式 `WALE_GPG_KEY_ID`) ⚠️ **已弃用** 用于配置用于加密和解密的 GPG 密钥。默认情况下，不使用加密。公钥环会缓存在文件 "/.walg_key_cache" 中。 * `WALG_PGP_KEY` 用于配置使用 OpenPGP 标准进行加密和解密。你可以使用 `\n` 符号将多行密钥合并为一行（通常用于 daemontools 和 envdir 的情况）。 当你需要执行 ```wal-fetch``` 或 ```backup-fetch``` 命令时，请设置*私钥*值。 当你需要执行 ```wal-push``` 或 ```backup-push``` 命令时，请设置*公钥*值。 请记住，*私钥*同时也包含*公钥*。 * `WALG_PGP_KEY_PATH` 类似于 `WALG_PGP_KEY`，但其值为文件系统上密钥的路径。 * `WALG_PGP_KEY_PASSPHRASE` 如果你的*私钥*使用*密码*进行了加密，你应该设置用于解密的*密码*。 * `WALG_ENVELOPE_PGP_KEY` 用于配置使用存储在密钥管理系统中的信封 PGP 密钥进行加密和解密。 此选项允许你通过将 PGP 密钥存储在 KMS 中来安全管理它们。 至关重要的是要确保传递的密钥是使用 kms 加密并使用 *base64* 编码的。 此外，密钥中必须同时包含*私钥*和*公钥*部分，因为信封密钥将被注入到元数据中，并在稍后的 `wal/backup-fetch` 中使用。 请注意，目前仅支持配置 Yandex Cloud Key Management Service (KMS)。 在尝试使用此功能之前，请确保你已经设置并配置好了下面提到的 Yandex Cloud KMS。 * `WALG_ENVELOPE_CACHE_EXPIRATION` 此设置控制 kms 响应的过期时间。默认值为 `0`，表示将密钥永久存储在内存中。 请注意，如果在过期后系统无法在 kms 中重新解密密钥，将使用之前的响应。 * `WALG_ENVELOPE_PGP_YC_ENDPOINT` Endpoint 是指使用 SDK 访问的 Yandex.Cloud 的 API endpoint。大多数用户不需要显式设置它。 * `WALG_ENVELOPE_PGP_YC_CSE_KMS_KEY_ID` 类似于 `YC_CSE_KMS_KEY_ID`，但仅用于信封 pgp 密钥。 * `WALG_ENVELOPE_PGP_YC_SERVICE_ACCOUNT_KEY_FILE` 类似于 `YC_SERVICE_ACCOUNT_KEY_FILE`，但仅用于信封 pgp 密钥。 * `WALG_ENVELOPE_PGP_KEY_PATH` 类似于 `WALG_ENVELOPE_PGP_KEY`，但其值为文件系统上密钥的路径。 ### 监控 * `WALG_STATSD_ADDRESS` 用于启用向 [statsd](https://github.com/statsd/statsd) 或 [statsd_exporter](https://github.com/prometheus/statsd_exporter) 发布指标。指标将通过 UDP 尽力发送。statsd 的默认端口为 `8125`。 * `WALG_STATSD_EXTRA_TAGS` 使用此设置可以向 WAL-G 发布到 statsd 的指标添加静态标签（`host`、`operation`、`database` 等）。 如果你想出于测试目的进行演示，可以使用 docker-compose 文件中的 graphite 服务。 ### 性能分析 性能分析对于识别 WAL-G 内部的瓶颈非常有用。 * `PROFILE_SAMPLING_RATIO` 一个介于 0 和 1 之间的浮点数，定义了启用 profiler 的可能性。设置为 1 时，它将始终运行。这允许对调用进行概率采样。由于 WAL-G 进程可能每秒被创建多次（例如 wal-g wal-push），我们不希望对所有进程都进行性能分析。 * `PROFILE_MODE` 要使用的 pprof profiler 类型。可以是 `cpu`、`mem`、`mutex`、`block`、`threadcreation`、`trace`、`goroutine` 中的一种。有关更多信息，请参阅 [runtime/pprof 文档](https://pkg.go.dev/runtime/pprof)。默认为 `cpu`。 * `PROFILE_PATH` 用于存储 profile 的目录。默认为 `$TMPDIR`。 ### 速率限制 * `WALG_NETWORK_RATE_LIMIT` 在 ```backup-push```/```backup-fetch``` 操作期间的网络流量速率限制，单位为字节每秒。 ### 数据库特定选项 **所选数据库还有更多可用选项。请在[数据库](#databases)中查看** ## 用法 WAL-G 目前支持针对所有类型数据库的以下命令： ### ``backup-list`` 列出可用备份的名称和创建时间。 ``--pretty`` 标志以表格形式打印列表 ``--json`` 标志以 JSON 格式打印列表，如果与 ``--pretty`` 结合使用则会美化输出 ``--detail`` 标志打印额外的备份详细信息，如果与 ``--pretty`` 结合使用则美化输出，如果与 ``--json`` 结合使用则进行 JSON 编码 ### ``delete`` 用于删除备份及它们之前的 WAL。默认情况下，``delete`` 将执行模拟运行。如果你想执行删除，必须在命令末尾添加 ``--confirm`` 标志。标记为永久的备份不会被删除。 对于 **PostgreSQL**，``delete retain`` 和 ``delete before`` 默认使用嵌入在每个备份名称中的时间线和 WAL 段对备份进行排序。在**大版本升级**（例如 ``pg_upgrade``）之后，时间线通常会重置，而较旧的备份仍保留在同一个存储中，因此该顺序**可能不**是按时间顺序排列的，并且 ``retain`` 可能会错误地删除**新**备份。在 ``delete`` 时传递全局标志 ``--use-sentinel-time``，以便在可用时根据来自 sentinel/metadata 的备份开始时间进行排序；请参阅 [PostgreSQL.md](PostgreSQL.md#delete-retention-ordering-and-use-sentinel-time)。 ``delete`` 可以在四种模式下运行：``retain``、``before``、``everything`` 和 ``target``。 ``retain`` [FULL|FIND_FULL] %number% [--after %name|time%] 如果指定了 ``FULL``，则保留 ``%number%`` 个完整备份以及它们之间的所有内容。如果使用了 ``--after`` 标志，则保留 $number$ 个最近的备份以及在此 ``%name|time%`` 之后（包括在内）创建的备份。 ``before`` [FIND_FULL] %name% 如果指定了 `FIND_FULL`，WAL-G 将计算保留所有增量备份所需的最小备份。如果未指定 ``FIND_FULL``，并且调用可能会产生孤立的增量备份，则调用将失败并返回列表。 ``everything`` [FORCE] ``target`` [FIND_FULL] %name% | --target-user-data %data% 将删除由名称或用户数据指定的备份。与其他删除命令不同，此命令不删除任何已归档的 WAL。 （仅适用于 Postgres 和 MySQL）默认情况下，如果提供增量备份作为目标，WAL-G 还将删除所有依赖的增量备份。如果指定了 `FIND_FULL`，WAL-G 将删除与目标具有相同基础备份的所有备份。 ### 示例 ``everything`` 所有备份都将被删除（如果没有永久备份的话） ``everything FORCE`` 所有备份，包括永久备份，都将被删除 ``retain 5`` 如果第 5 个是增量备份，将会失败 ``retain FULL 5`` 将保留 5 个完整备份及其所有增量备份 ``retain FIND_FULL 5`` 将为第 5 个备份找到必要的完整备份，并保留其后的所有内容 ``retain 5 --after 2019-12-12T12:12:12`` 保留 5 个最近的备份以及 2019-1212 12:12:12 之后创建的备份 ``retain FULL 5 --use-sentinel-time`` (PostgreSQL) 与 ``retain FULL 5`` 相同，但是按照 sentinel 的开始时间对备份进行排序——在跨时间线重置（例如大版本升级后）混合备份时使用；运行删除时仍需添加 ``--confirm`` ``before base_000010000123123123`` 如果 `base_000010000123123123` 是增量备份，将会失败 ``before FIND_FULL base_000010000123123123`` 将保留 base_000010000123123123 的基础备份之后的所有内容 ``target base_0000000100000000000000C9`` 删除基础备份和所有依赖它的增量备份 `` target --target-user-data "{ \"x\": [3], \"y\": 4 }"`` 删除由用户数据指定的备份 ``target base_0000000100000000000000C9_D_0000000100000000000000C4`` 删除增量备份和所有依赖它的增量备份 ``target FIND_FULL base_0000000100000000000000C9_D_0000000100000000000000C4`` 删除增量备份以及具有相同基础备份的所有增量备份 **所选数据库引擎还有更多可用命令。请在[数据库](#databases)中查看** ## 存储工具 `wal-g st` 命令系列允许与配置的存储进行直接交互。 [存储工具文档](StorageTools.md) ## 数据库 ### PostgreSQL [有关安装、配置和用法的信息](PostgreSQL.md) ### MySQL/MariaDB [有关安装、配置和用法的信息](MySQL.md) ### SQLServer [有关安装、配置和用法的信息](SQLServer.md) ### Mongo [Beta] [有关安装、配置和用法的信息](MongoDB.md) ### FoundationDB [开发中] [有关安装、配置和用法的信息](FoundationDB.md) ### Redis [Beta] [有关安装、配置和用法的信息](Redis.md) ### Greenplum / Cloudberry [可用于生产环境] [有关安装、配置和用法的信息](Greenplum.md) ### ETCD [开发中] [有关安装、配置和用法的信息](ETCD.md) ## 开发 以下步骤描述了如何为 PostgreSQL 构建 WAL-G，但该过程对于其他数据库也是相同的。例如，要为 MySQL 构建 WAL-G，请使用 `make mysql_build` 而不是 `make pg_build`。 可选： - 要使用 brotli 压缩器和解压器进行构建，请设置 `USE_BROTLI` 环境变量。 - 要使用 libsodium 进行构建，请设置 `USE_LIBSODIUM` 环境变量。 - 要使用 lzo 解压器进行构建，请设置 `USE_LZO` 环境变量。 ### 安装说明 #### Ubuntu ``` # 安装最新版 Go 编译器 sudo add-apt-repository ppa:longsleep/golang-backports sudo apt update sudo apt install golang-go # 安装 lib 依赖 sudo apt install libbrotli-dev liblzo2-dev libsodium-dev curl cmake # 获取项目并构建 # Go 1.15 及以下版本 go get github.com/wal-g/wal-g # Go 1.16+ - 只需将 repository 克隆到 $GOPATH # 如果你想节省空间，请添加 --depth=1 或 --single-branch git clone https://github.com/wal-g/wal-g $(go env GOPATH)/src/github.com/wal-g/wal-g cd $(go env GOPATH)/src/github.com/wal-g/wal-g # 可选的 exports（见上文） export USE_BROTLI=1 export USE_LIBSODIUM=1 export USE_LZO=1 make deps make pg_build main/pg/wal-g --version ``` 用户也可以使用 `make pg_install` 安装 WAL-G。在安装之前指定 `GOBIN` 环境变量，允许用户指定安装位置。默认情况下，`make pg_install` 会将编译后的二进制文件放在根目录 (`/`) 中。 ``` export USE_BROTLI=1 export USE_LIBSODIUM=1 export USE_LZO=1 make pg_clean make deps GOBIN=/usr/local/bin make pg_install ``` #### macOS ``` # brew 命令是 Mac OS 的 Homebrew brew install cmake # 获取项目并构建 # Go 1.15 及以下版本 go get github.com/wal-g/wal-g # Go 1.16+ - 只需将 repository 克隆到 $GOPATH # 如果你想节省空间，请添加 --depth=1 或 --single-branch git clone https://github.com/wal-g/wal-g $(go env GOPATH)/src/github.com/wal-g/wal-g cd $(go env GOPATH)/src/github.com/wal-g/wal-g export USE_BROTLI=1 export USE_LIBSODIUM="true" # since we're linking libsodium later ./link_brotli.sh ./link_libsodium.sh make install_and_build_pg # 如果你需要安装 GOBIN=/usr/local/bin make pg_install ``` 要在 ARM64 上构建，请设置相应的 `GOOS`/`GOARCH` 环境变量： ``` env GOOS=darwin GOARCH=arm64 make install_and_build_pg ``` 要在 ARM 架构的 MacOS 上构建 linux 版本： ``` GOOS=linux GOARCH=amd64 make mysql_build ``` 编译后要运行的二进制文件是 `main/pg/wal-g` ### 测试 WAL-G 非常依赖单元测试。这些测试不需要 S3 配置，因为上传/下载部分是使用 mock 对象进行测试的。单元测试可以使用以下命令运行 ``` ./link_brotli.sh export USE_BROTLI=1 make unittest ``` 有关测试的更多信息，请查阅 [test](test)、[testtools](testtools) 以及 [Makefile](Makefile) 中的 `unittest` 部分。 WAL-G 将执行一次往返压缩/解压测试，该测试会生成一个数据目录（例如 data...）、压缩文件目录（例如 compressed）和解压文件目录（例如 extracted）。只有当原始数据目录中的文件与解压目录中的文件匹配时，这些目录才会被清理。 可以使用以下命令获取测试覆盖率： ``` export USE_BROTLI=1 make coverage ``` 此命令会生成 `coverage.out` 文件，并打开覆盖率的 HTML 表示形式。 ### Windows 开发 [有关安装和用法的信息](Windows.md) ## 故障排除 开始排查故障的一个好方法是设置以下一个或两个环境变量： * `WALG_LOG_LEVEL=DEVEL` 打印出 WAL-G 使用的配置以及所执行命令的详细日志。 * `S3_LOG_LEVEL=DEVEL` 如果你的命令似乎卡住了，可能是 S3 无法连接、证书问题或其他与 S3 相关的问题。 设置此环境变量后，你可以看到来自 S3 的请求和响应。 ## 作者 * [Katie Li](https://github.com/katie31) * [Daniel Farina](https://github.com/fdr) 另请参阅参与此项目的[贡献者](CONTRIBUTORS.md)列表。 ## 许可证 本项目基于 Apache License, Version 2.0 授权，但 lzo 支持基于 GPL 3.0+ 授权。有关更多详细信息，请参阅 [LICENSE.md](../LICENSE.md) 文件。 ## 致谢 没有 [Citus Data](https://www.citusdata.com/) 的支持，就不会有 WAL-G 的诞生。 WAL-G 的诞生得益于 Citus 的暑期工程实习生 Katie Li 与 WAL-E 的原作者 Daniel Farina 的合作，Daniel Farina 目前担任 Citus Cloud 团队的首席工程师。Citus Data 还有一个[Postgres 的开源扩展](https://github.com/citusdata)，它可以横向分发数据库查询，从而提供极高的扩展性和性能。 WAL-G 的开发由 [Yandex Cloud](https://cloud.yandex.com) 提供支持 ## 交流群 我们有一个 [Slack 群组](https://postgresteam.slack.com/messages/CA25P48P2)和一个 [Telegram 聊天室](https://t.me/joinchat/C03q9FOwa7GgIIW5CwfjrQ)来讨论 WAL-G 的用法和开发。要加入 PostgreSQL slack，请使用[邀请应用](https://postgres-slack.herokuapp.com)。

标签：EVTX分析, Go, PostgreSQL, Ruby工具, 搜索引擎查询, 数据库备份, 数据归档, 日志审计, 测试用例, 灾难恢复, 请求拦截