备份配置

Nginx UI 配置中的备份部分控制备份操作的安全性和访问权限。此部分确保备份功能在定义的安全边界内运行，同时提供灵活的存储选项。

概述

Nginx UI 提供全面的备份功能，包括：

• 手动备份：通过 Web 界面按需创建备份
• 自动备份：使用可视化 cron 编辑器的定时备份任务
• 多种备份类型：支持 Nginx 配置、Nginx UI 配置或自定义目录备份
• 存储选项：本地存储和 S3 兼容的对象存储
• 安全性：配置数据使用 AES 加密的加密备份

GrantedAccessPath

• 类型：[]string
• 默认值：[]（空数组）
• 版本：>= v2.0.0

这是备份操作最关键的安全设置。它定义了允许进行备份操作的目录路径列表，包括备份源路径和存储目标路径。

用途

GrantedAccessPath 设置作为安全边界：

• 防止未授权访问：将备份操作限制在明确授权的目录内
• 保护系统文件：防止意外备份或访问敏感的系统目录
• 强制访问控制：确保所有备份路径都在管理员定义的边界内
• 防止路径遍历：阻止尝试访问允许范围外的目录

配置格式

[backup]
GrantedAccessPath = /var/backups
GrantedAccessPath = /home/user/backups

路径验证规则

1. 前缀匹配：使用适当的边界检查进行前缀匹配验证路径
2. 路径清理：所有路径都经过标准化处理以防止目录遍历攻击（如 ../ 序列）
3. 精确边界：/tmp 允许 /tmp/backup 但不允许 /tmpfoo 以防止混淆
4. 空默认值：默认情况下，为了最大安全性，不允许任何自定义目录备份操作

安全考虑

• 默认安全：默认的空配置确保在明确配置之前不允许任何自定义目录备份操作
• 显式配置：管理员必须有意识地定义允许的路径
• 定期审查：根据操作需要定期审查和更新允许的路径
• 最小权限：仅授予真正需要备份功能的目录访问权限

备份类型

配置备份

备份 Nginx 或 Nginx UI 配置时：

• 加密：所有配置备份都使用 AES 加密自动加密
• 密钥管理：加密密钥自动生成并与备份文件一起保存
• 完整性验证：SHA-256 哈希确保备份完整性
• 元数据：包含版本信息和时间戳以提供恢复上下文

自定义目录备份

对于自定义目录备份：

• 无加密：自定义目录备份存储为标准 ZIP 文件，不加密
• 路径验证：源目录必须在 GrantedAccessPath 边界内
• 灵活内容：可以备份允许路径内的任何目录结构

存储配置

本地存储

• 路径验证：存储路径必须在 GrantedAccessPath 边界内
• 目录创建：如果存储目录不存在，会自动创建
• 权限：备份文件使用安全权限（0600）创建

S3 存储

对于 S3 兼容的对象存储：

• 必需字段：存储桶名称、访问密钥 ID 和秘密访问密钥是必需的
• 可选字段：可以为自定义 S3 提供商配置端点 URL 和区域

自动备份调度

可视化 Cron 编辑器

自动备份使用可视化 cron 编辑器界面，允许您：

• 选择频率：从每日、每周、每月或自定义计划中选择
• 设置时间：选择备份执行的具体小时和分钟
• 预览计划：查看备份计划的人类可读描述

任务管理

• 状态跟踪：每个备份任务跟踪执行状态（待处理、成功、失败）
• 错误日志：失败的备份包含详细的错误消息以便故障排除

备份保留

默认情况下，自动备份任务每次运行都会新增一个备份文件，旧文件不会被删除。在任务上设置 保留备份数 可以限制该任务保留的备份数量：

• 默认值：0 表示保留全部备份
• 数量限制：设置为正数时，每次备份成功后只保留最新的这么多份备份，更早的备份会被删除。带有加密密钥文件的备份会连同其 .key 文件一起删除
• 存储：本地存储和 S3 存储均适用
• 范围：只处理存储路径下直接存放、且符合该任务命名规则（<name>_<timestamp>.zip，自定义目录备份为 custom_dir_<name>_<timestamp>.zip）的文件，其他文件不会被改动。<name> 中不能用于文件名的字符会被替换为 _
• 同名冲突：如果另一个任务会把同名的备份文件写到同一个存储路径（例如 web prod 和 web/prod，或者自定义目录任务 web 和名为 custom_dir_web 的任务），两者的备份无法区分。此时任务会跳过清理并发送警告通知，直到其中一个任务改名或改用单独的存储路径
• 改名的任务：任务改名或更换存储路径之前写入的备份不再匹配该任务，不会被删除。如不再需要，请手动清理
• 启用版本控制的 S3 存储桶：在启用了版本控制的存储桶中，删除旧备份只会添加删除标记，存储空间由存储桶的生命周期规则释放，而不是由清理操作释放
• 失败处理：如果某个旧备份删除失败，会记录一条警告，备份任务本身仍然视为成功

此配置在保持严格安全边界的同时启用备份操作，确保备份功能不会被滥用来访问未授权的系统区域。