efrecon/influx-backup

InfluxDB Backup

概述

此工具（及Docker容器）可定期对Influx数据库（的部分数据）执行备份，并仅保留最新备份。根据命令行选项-mode的值，它支持两种完全不同的备份类型：

• 当该选项值为backup（默认值）时，将对（部分）数据库执行完整的原始备份，包括元数据存储。
• 当该选项值为csv时，将对数据库的数据系列执行CSV备份。如有需要，可执行增量备份，或选择特定的数据系列和/或数据库。为覆盖更多使用场景并控制存储，部分命令行选项仅影响CSV备份操作的行为。

注：此项目的内部工作机制仍在开发中，但已在生产环境中运行。该项目仅针对influxdb的OSS版本进行了测试。此脚本源于本地需求，如需更清晰的设计，还需结构调整和改进。欢迎任何拉取请求！https://hub.docker.com/r/efrecon/influx-backup/容器适用于大多数https://hub.docker.com/r/efrecon/influx-backup/tags/版本。实现具有前向兼容性，能够检测过去和未来基于Alpine的Influx镜像，详见此处。

使用示例

本节提供如何使用此项目定期备份Influx数据库的快速说明。命令行选项的详细描述见下一节。

定期原始备份

假设在名为influxdb的主机上运行Influx（如Docker环境），以下命令将每半小时对所有数据库执行备份快照，存储在/mnt/external（可能是远程文件系统）下的子目录中：

bash
backup.tcl -host influxdb -period 1800 -root /mnt/external

一次性CSV导出

基于上述相同主机，以下命令将仅导出名称中包含example的数据系列为CSV。备份将创建在/mnt/external的子目录中，其中一级子目录为当前日期，二级子目录为数据库名称：

bash
backup.tcl -mode csv -host influxdb -period -1 -root /mnt/external \
           -dst "%date%/%db%" -accept "*example*" -latest ""

将生成与匹配*example*的数据系列数量相同的CSV文件，文件名大致与系列名称对应，并使用gzip压缩。磁盘上文件的最终名称由-basename选项的默认值控制，并使用-charset指定的默认字符集。

累积CSV转换

假设在名为db的数据库中有一个每小时更新的数据系列example，以下命令将生成一个未压缩的CSV文件，包含从命令启动时开始的所有历史数据。这是使用特定InfluxQL相对查询执行增量备份的示例：

bash
backup.tcl -mode csv -host influxdb -period 3600 -root /mnt/external \
           -dst "" -databases "db" -accept "example" -latest "" \
           -compress "" -combine on \
           -query "SELECT * from \"%serie%\" WHERE time > now() and time <= now()"

命令行选项

该工具仅识别单破折号的“长”命令行选项。所有选项均需带参数，且仅最后一个选项会被考虑。

-host

Influx运行的主机名或IP，默认为localhost。

-port

Influx守护进程运行的端口号，默认为8088。网络连接需正确配置bind-address。

-cliport

用于常规CLI连接的主机端口号，默认为8086。备份工具将使用此端口列出数据库或数据系列。

-username

具有系统管理员权限的用户名，默认为空字符串（Influx的默认行为是一旦声明用户就开始限制认证）。

-password

管理员用户的密码。从安全角度，将密码作为参数传递通常不方便：建议使用-password_file。

-password_file

包含管理员用户密码的文件路径。可与Dockersecrets一起使用。-password选项始终优先，仅当-password值为空时才考虑-password_file的内容。密码中的尾随空格（包括换行符）将自动删除。

-root

所有创建的备份将存储在该目录下。通常，-root下会为每个备份创建带时间戳的子目录。此行为可通过-dst命令行选项在一定程度上控制。所有备份目录不存在时将自动创建。

默认存储在/backup，作为Docker容器时为导出卷。

-format

指定创建备份子目录时日期时间戳的格式。默认为%Y%m%d-%H%M%S，其中%开头的标记是本地时区当前日期和时间各部分的占位符。例如，在UTC时区的机器上，Mon Jan 2 15:04:05 UTC 2006使用默认模板将转换为20060102-15:04:05。完整的模板列表可参考此处。

-dst

指定每个备份的子目录目标位置，路径相对于备份的主-root。根据备份模式，路径中可使用多个%包围的标记，这些标记将在备份时动态解析：

• %date%：解析为当前日期（由-format选项指定），适用于所有备份形式。
• %db或%database%（等效）：解析为正在备份的数据库名称，仅在相关时使用。
• %serie%：解析为正在备份的数据系列名称，仅适用于csv备份。

-databases

该选项的值应为空格分隔的数据库名称列表，这些数据库应存在于Influx主机上。默认值为空，此时将考虑所有现有数据库，且每次运行备份时会重新获取数据库列表，以适应新增或删除的数据库。

-period

备份周期（秒）。实现将此周期作为备份开始时间目标，考虑到备份操作可能需要一定时间。默认值为900秒（每15分钟）。当周期为空字符串或小于0时，将生成单次备份，便于将脚本置于crond等调度守护进程控制下。周期也可采用人类可读形式，如"1w"、"2 months 4d"或"2y -3 m"（不带引号），详见下一节。

-wait

指定（定期）备份在执行第一次备份前等待的秒数。当-wait包含冒号:时，冒号两侧分别表示最小时间和最大时间，将在其间随机选择。当最小值为空时，默认为0；当最大值为空（但存在冒号）时，默认为-period的值。所有值（无冒号时为秒数，有冒号时为最小值和最大值）均可使用人类可读周期（见-period）。人类可读周期的详细描述见下一节。默认等待时间为0，即立即开始备份。

-keep

指定保留的备份数量。旧备份将自动删除以控制磁盘空间。将该选项值设为0（或负数）将保留所有备份。默认保留3个最新备份。删除旧备份时，将通过-format指定的日期格式从目录名称中提取日期。

-compress

当设置为默认值gzip时，将csv备份通过gzip可执行文件进行压缩。该选项的值应为二进制文件的路径，也可指定其他压缩工具。注意，当使用-combine选项时，将通过gzip的-d命令行选项进行解压缩，这意味着如果使用其他压缩二进制文件，其应支持-d选项进行解压缩，且行为与gzip类似。

将该选项设为空字符串可完全关闭压缩。

-accept和-reject

这两个选项的值可用于限制备份为csv文件的数据系列。每个选项可包含空格分隔的glob风格过滤器列表，首先通过-accept选择所有现有数据系列，然后通过-reject排除部分系列。默认值分别为*和空字符串，即接受所有系列（*匹配任何字符串）且不排除任何系列。

-basename

用于指定创建的CSV文件的基本名称。可包含与-dst选项相同的%包围的标记。最终基本名称可通过-map进行进一步子字符串替换。最终名称将使用-charset指定的字符集进行清理。

basename的默认值为%serie%，将为数据库中的每个数据系列创建一个csv文件。

-map

生成CSV文件的最终名称前，可使用-map选项的值将子字符串替换为其他字符串。该选项应接受空格分隔的子字符串及其替换列表。可用于将内部表示转换为对外部客户端或合作伙伴更有意义的命名约定。默认值为空映射。

-charset

CSV文件名允许的字符集。该字符集在通过-basename和-map的所有转换后应用。默认接受A-Z、a-z、0-9和少数标点符号。所有不属于该集合的字符将替换为下划线。注意，目录分隔符应明确（且始终）排除在该集合之外。

-link

非空时，指定作为“最新”备份的路径位置。可包含与-dst选项相同的%包围的标记（除%serie%），并将该位置创建为指向最新备份目录的符号链接。实现优先（并计算）从-root目录开始的相对目录。默认值为latest，将在-root目录下创建（并更新）名为latest的目录，指向最新备份。

-query

执行CSV备份时用于数据提取的InfluxQL查询。将针对-database、-accept和-reject选项指定的每个数据库和数据系列执行该查询。

执行前，查询将进行两次转换：首先替换-dst中指定的%包围的标记；其次替换基于日期的%开头的占位符标记（见-format的标记参考）。

该选项的默认值为select * from "%serie%"，可有效选择给定时间序列的所有值。注意，%serie%将自动替换为所选系列的名称。指定不同查询可用于执行数据库的增量CSV备份，例如通过选择相对于当前日期和时间的数据，并结合-keep -1和-combine使用。

-combine

当值设为on时，将查询结果追加到之前查询的CSV文件末尾。结合-keep -1和相对InfluxQL查询使用时，将生成包含所有相关数据的不断增长的CSV文件。

该选项的值可为任何布尔表示，即on、off、true、false、0、1均被识别。

-influx

influx shell的完整路径，相对路径将通过PATH变量解析。默认为influx。

-influxd

influxd数据库进程的完整路径，相对路径将通过PATH变量解析。默认为influxd。

-quote

CSV文件中用于引用的字符。注意，当该字符与Influx导出CSV时使用的字符不同时，将转换CSV输出。默认为"，这是Influx使用的字符，且因Influx遵循RFC 4180而无法更改。

-separator

CSV文件中用于分隔的字符。注意，当该字符与Influx导出CSV时使用的字符不同时，将转换CSV输出。默认为,，这是Influx使用的字符，且因Influx遵循RFC 4180而无法更改。

人类可读周期

多个命令行选项允许使用人类可读格式表示周期。该格式由整数（可正可负）后跟单位说明（月、小时等）组成。识别的单位包括year（年）、month（月）、week（周）、day（日）、hour（时）、minute（分）、second（秒）（单复数均可）。这些单位可缩写为单个字母，部分字母区分大小写，分别为：y、m、d、h、M、s。

致谢

此脚本的开发由Lindborg Systems和SCOTT项目赞助。