mirror of
https://github.com/Awuqing/BackupX.git
synced 2026-09-05 07:26:43 +08:00
Merge main into feature/demo-showcase
This commit is contained in:
Awuqing
+81
-130
@@ -1,84 +1,48 @@
|
||||
{
|
||||
"home.badge": {
|
||||
"message": "开源备份控制平面 · v2.2.1",
|
||||
"description": "Version badge on the hero"
|
||||
},
|
||||
"home.title.part1": {
|
||||
"message": "面向自托管服务器的",
|
||||
"description": "Hero title, first line"
|
||||
},
|
||||
"home.title.part2": {
|
||||
"message": "备份编排平台。",
|
||||
"description": "Hero title accent second line"
|
||||
},
|
||||
"home.tagline": {
|
||||
"message": "在一个清爽控制台中管理文件、数据库、SAP HANA 和远程节点备份。控制平面自己掌握，存储后端灵活选择。",
|
||||
"description": "Tagline on the home page"
|
||||
},
|
||||
"home.pageTitle": {
|
||||
"message": "面向自托管服务器的备份编排",
|
||||
"description": "Page <title> element on the home page"
|
||||
},
|
||||
"home.getStarted": {
|
||||
"message": "快速开始",
|
||||
"description": "Primary CTA on the home page"
|
||||
},
|
||||
"home.metric.backends": {
|
||||
"message": "存储后端",
|
||||
"description": "Hero metric label: storage backends"
|
||||
},
|
||||
"home.metric.backupTypes": {
|
||||
"message": "远程执行",
|
||||
"description": "Hero metric label: backup types"
|
||||
},
|
||||
"home.metric.license": {
|
||||
"message": "开源协议",
|
||||
"description": "Hero metric label: license"
|
||||
},
|
||||
"home.visual.eyebrow": {"message": "BackupX 控制台"},
|
||||
"home.visual.title": {"message": "运维概览"},
|
||||
"home.visual.status": {"message": "健康"},
|
||||
"home.visual.success": {"message": "成功率"},
|
||||
"home.visual.nodes": {"message": "活跃节点"},
|
||||
"home.visual.targets": {"message": "存储目标"},
|
||||
"home.visual.row1.title": {"message": "PostgreSQL 夜间备份"},
|
||||
"home.visual.row1.desc": {"message": "加密归档已上传至 S3"},
|
||||
"home.visual.row2.title": {"message": "SAP HANA 快照"},
|
||||
"home.visual.row2.desc": {"message": "正在 agent-shanghai-02 上运行"},
|
||||
"home.visual.row3.title": {"message": "保留策略清理"},
|
||||
"home.visual.row3.desc": {"message": "下一次执行在 4 小时后"},
|
||||
"home.command.title": {"message": "使用 Docker 启动"},
|
||||
"home.badge": {"message": "BackupX 文档 · v2.2.1"},
|
||||
"home.title.part1": {"message": "可靠地运维 BackupX，"},
|
||||
"home.title.part2": {"message": "每一步都有依据。"},
|
||||
"home.tagline": {"message": "从部署控制平面、连接存储与远程 Agent，到持续观测和验证恢复，一套务实文档覆盖完整运维路径。"},
|
||||
"home.pageTitle": {"message": "面向自托管服务器的备份编排"},
|
||||
"home.getStarted": {"message": "使用 Docker 开始"},
|
||||
"home.viewSource": {"message": "查看源码"},
|
||||
"home.supported.label": {"message": "支持的运行环境"},
|
||||
"home.supported.docker": {"message": "Docker"},
|
||||
"home.supported.linux": {"message": "Linux"},
|
||||
"home.supported.windows": {"message": "Windows Agent"},
|
||||
"home.guide.label": {"message": "推荐文档路径"},
|
||||
"home.guide.kicker": {"message": "从这里开始"},
|
||||
"home.guide.hint": {"message": "为下一项工作选择指南"},
|
||||
"home.guide.install.title": {"message": "安装 BackupX"},
|
||||
"home.guide.install.desc": {"message": "Docker、Compose 或独立二进制"},
|
||||
"home.guide.cluster.title": {"message": "连接远程节点"},
|
||||
"home.guide.cluster.desc": {"message": "Agent、代理、私有 CA 与堡垒机"},
|
||||
"home.guide.security.title": {"message": "加固运维环境"},
|
||||
"home.guide.security.desc": {"message": "安全控制、监控与审计记录"},
|
||||
"home.guide.recovery.title": {"message": "准备恢复方案"},
|
||||
"home.guide.recovery.desc": {"message": "升级、回滚、恢复与故障排查"},
|
||||
|
||||
"section.features.tag": {
|
||||
"message": "核心能力",
|
||||
"description": "FEATURES section tag"
|
||||
},
|
||||
"section.features.title": {
|
||||
"message": "该有的都有，多余的没有",
|
||||
"description": "Features section title"
|
||||
},
|
||||
"section.features.subtitle": {
|
||||
"message": "备份 Runner、存储 Provider、调度、集群 — 每一块都经过打磨。",
|
||||
"description": "Features section subtitle"
|
||||
},
|
||||
|
||||
"feat.types.title": {"message": "多种备份类型"},
|
||||
"feat.types.desc": {"message": "文件与目录（支持多源路径），以及 MySQL、PostgreSQL、SQLite、SAP HANA 统一管理。"},
|
||||
"feat.storage.title": {"message": "70+ 存储后端"},
|
||||
"feat.storage.desc": {"message": "内置阿里云 OSS、腾讯云 COS、七牛、S3、Google Drive、WebDAV、FTP，以及 SFTP、Azure Blob、Dropbox 等 rclone 后端。"},
|
||||
"feat.scheduling.title": {"message": "调度与保留策略"},
|
||||
"feat.scheduling.desc": {"message": "基于 Cron 的可视化调度编辑器，支持按天数/份数自动保留和空目录清理。"},
|
||||
"feat.cluster.title": {"message": "多节点集群"},
|
||||
"feat.cluster.desc": {"message": "Master-Agent 基于 HTTP 长轮询。Agent 在本地执行任务并直接上传到存储 — 无需反向连通性。"},
|
||||
"feat.security.title": {"message": "默认安全"},
|
||||
"feat.security.desc": {"message": "JWT 认证、bcrypt、AES-256-GCM 加密配置、可选备份加密、完整审计日志。"},
|
||||
"feat.deploy.title": {"message": "部署轻量"},
|
||||
"feat.deploy.desc": {"message": "单个静态二进制 + 内嵌 SQLite。Docker 一键启动或裸机 — 零外部依赖。"},
|
||||
"feat.learnMore": {"message": "了解更多"},
|
||||
"section.features.tag": {"message": "文档路径"},
|
||||
"section.features.title": {"message": "从部署到恢复，不依赖猜测"},
|
||||
"section.features.subtitle": {"message": "每条路径都把产品能力与生产环境所需的配置、安全和运维决策直接关联。"},
|
||||
"feat.install.title": {"message": "安装与升级"},
|
||||
"feat.install.desc": {"message": "选择 Docker、Compose 或独立二进制，并保持部署过程可重复。"},
|
||||
"feat.types.title": {"message": "保护文件与数据库"},
|
||||
"feat.types.desc": {"message": "配置文件、MySQL、PostgreSQL、SQLite 和 SAP HANA 备份工作负载。"},
|
||||
"feat.storage.title": {"message": "连接存储目标"},
|
||||
"feat.storage.desc": {"message": "通过一致流程使用原生 Provider 或任意受支持的 rclone 后端。"},
|
||||
"feat.cluster.title": {"message": "构建远程节点集群"},
|
||||
"feat.cluster.desc": {"message": "通过代理、私有 CA 或 SSH 堡垒机部署仅出站连接的 Agent。"},
|
||||
"feat.monitor.title": {"message": "监控日常运行"},
|
||||
"feat.monitor.desc": {"message": "持续查看任务健康、存储容量、通知、日志和服务就绪状态。"},
|
||||
"feat.recovery.title": {"message": "按验证过的方案恢复"},
|
||||
"feat.recovery.desc": {"message": "预先准备升级、回滚点、恢复验证和事件故障排查。"},
|
||||
|
||||
"showcase.tag": {"message": "产品界面"},
|
||||
"showcase.title": {"message": "精心打磨的控制台，而非 DIY 脚本"},
|
||||
"showcase.subtitle": {"message": "每个页面都为运维而生 — 可观测优先，可配置次之。"},
|
||||
"showcase.title": {"message": "部署前先了解完整操作流程"},
|
||||
"showcase.subtitle": {"message": "每张产品截图都连接到对应指南，说明背后的任务、配置和运行模型。"},
|
||||
"showcase.tabs.label": {"message": "BackupX 产品界面"},
|
||||
"showcase.preview.label": {"message": "BackupX 控制台"},
|
||||
"showcase.tab.dashboard": {"message": "仪表盘"},
|
||||
"showcase.tab.tasks": {"message": "备份任务"},
|
||||
"showcase.tab.storage": {"message": "存储目标"},
|
||||
@@ -98,67 +62,54 @@
|
||||
"showcase.cta": {"message": "开始阅读文档"},
|
||||
|
||||
"community.tag": {"message": "社区"},
|
||||
"community.pageTitle": {"message": "社区、赞助商与贡献者"},
|
||||
"community.pageDescription": {"message": "赞助 BackupX，了解贡献者，并找到务实的参与方式。"},
|
||||
"community.title": {"message": "开放协作，面向长期运维"},
|
||||
"community.subtitle": {"message": "备份软件的信任来自透明发布、真实部署反馈，以及足够务实的贡献路径。"},
|
||||
"community.sponsor.kicker": {"message": "赞助商"},
|
||||
"community.sponsor.wallTitle": {"message": "赞助商"},
|
||||
"community.sponsor.title": {"message": "支持你依赖的备份基础设施"},
|
||||
"community.pageTitle": {"message": "社区、赞助与贡献者"},
|
||||
"community.pageDescription": {"message": "反馈真实部署约束、完善文档，或为 BackupX 提交可验证的改进。"},
|
||||
"community.title": {"message": "开放协作让运维知识持续完善"},
|
||||
"community.subtitle": {"message": "反馈真实部署约束、完善运行手册，或通过可复现验证提交聚焦的改动。"},
|
||||
"community.path.kicker": {"message": "贡献路径"},
|
||||
"community.path.guide": {"message": "贡献指南"},
|
||||
"community.path.issues.title": {"message": "反馈生产环境问题"},
|
||||
"community.path.issues.desc": {"message": "提交日志、部署拓扑和恢复预期。"},
|
||||
"community.path.docs.title": {"message": "完善文档与示例"},
|
||||
"community.path.docs.desc": {"message": "贡献存储、Agent 和数据库部署指南。"},
|
||||
"community.path.code.title": {"message": "提交聚焦的 Pull Request"},
|
||||
"community.path.code.desc": {"message": "保持改动可测试、可审查，并贴合现有架构。"},
|
||||
"community.contributor.kicker": {"message": "贡献者"},
|
||||
"community.contributor.all": {"message": "查看全部"},
|
||||
"community.contributor.source": {"message": "通过 GitHub contributors API 加载，并提供本地回退数据。"},
|
||||
"community.contributor.botRole": {"message": "自动化贡献者"},
|
||||
"community.contributor.githubRole": {"message": "GitHub 贡献者"},
|
||||
"community.contributor.contributions": {"message": "{count} 次贡献"},
|
||||
"community.sponsor.bandTitle": {"message": "支持长期维护"},
|
||||
"community.sponsor.bandDesc": {"message": "支持兼容性测试、恢复工作和面向运维者的文档。"},
|
||||
"community.sponsor.learnMore": {"message": "了解赞助方案"},
|
||||
"community.sponsor.title": {"message": "支持可靠的备份基础设施"},
|
||||
"community.sponsor.programDesc": {"message": "赞助将用于测试覆盖、恢复可信度、Provider 兼容性，以及运维人员可以直接应用的文档。"},
|
||||
"community.sponsor.cta": {"message": "赞助 BackupX"},
|
||||
"community.sponsor.openSlot": {"message": "赞助席位开放"},
|
||||
"community.sponsor.logo.project": {"message": "项目赞助"},
|
||||
"community.sponsor.logo.cloud": {"message": "云服务伙伴"},
|
||||
"community.sponsor.logo.object": {"message": "对象存储"},
|
||||
"community.sponsor.logo.cdn": {"message": "CDN 伙伴"},
|
||||
"community.sponsor.logo.database": {"message": "数据库伙伴"},
|
||||
"community.sponsor.logo.security": {"message": "安全审计"},
|
||||
"community.sponsor.logo.agent": {"message": "远程节点实验室"},
|
||||
"community.sponsor.logo.docs": {"message": "文档赞助"},
|
||||
"community.sponsor.logo.release": {"message": "发布赞助"},
|
||||
"community.sponsor.logo.s3": {"message": "S3 兼容"},
|
||||
"community.sponsor.logo.webdav": {"message": "WebDAV 伙伴"},
|
||||
"community.sponsor.logo.sftp": {"message": "SFTP 伙伴"},
|
||||
"community.sponsor.logo.docker": {"message": "容器伙伴"},
|
||||
"community.sponsor.logo.mirror": {"message": "镜像伙伴"},
|
||||
"community.sponsor.logo.restore": {"message": "恢复演练"},
|
||||
"community.sponsor.logo.qa": {"message": "测试实验室"},
|
||||
"community.sponsor.logo.oss": {"message": "开源支持"},
|
||||
"community.sponsor.logo.open": {"message": "赞助席位开放"},
|
||||
"community.sponsor.infrastructure.label": {"message": "基础设施"},
|
||||
"community.sponsor.infrastructure.title": {"message": "云与存储生态伙伴"},
|
||||
"community.sponsor.infrastructure.desc": {"message": "帮助 BackupX 覆盖对象存储、WebDAV、SFTP 以及区域云平台的真实验证。"},
|
||||
"community.sponsor.security.label": {"message": "安全"},
|
||||
"community.sponsor.security.title": {"message": "审计与可靠性支持者"},
|
||||
"community.sponsor.security.desc": {"message": "支持加密、恢复演练、发布签名和运维检查等强化工作。"},
|
||||
"community.sponsor.infrastructure.title": {"message": "云与存储兼容性"},
|
||||
"community.sponsor.infrastructure.desc": {"message": "支持对象存储、WebDAV、SFTP 和区域云平台的真实验证。"},
|
||||
"community.sponsor.security.label": {"message": "可靠性"},
|
||||
"community.sponsor.security.title": {"message": "安全与恢复工作"},
|
||||
"community.sponsor.security.desc": {"message": "支持加密审查、恢复演练、发布签名和运维检查。"},
|
||||
"community.sponsor.community.label": {"message": "社区"},
|
||||
"community.sponsor.community.title": {"message": "开源支持者"},
|
||||
"community.sponsor.community.desc": {"message": "支持文档、示例、平台测试和贡献者引导。"},
|
||||
"community.sponsor.community.title": {"message": "文档与贡献者支持"},
|
||||
"community.sponsor.community.desc": {"message": "改善指南、示例、平台测试和贡献者体验。"},
|
||||
"community.sponsor.tier.title": {"message": "支持方式"},
|
||||
"community.sponsor.tier.subtitle": {"message": "根据团队依赖 BackupX 的方式选择合适层级。"},
|
||||
"community.sponsor.tier.backer.name": {"message": "Backer"},
|
||||
"community.sponsor.tier.backer.amount": {"message": "适合个人与小团队"},
|
||||
"community.sponsor.tier.backer.desc": {"message": "支持文档、Issue 分流、兼容性测试和小型体验改进。"},
|
||||
"community.sponsor.tier.backer.desc": {"message": "支持文档、Issue 分流、兼容性测试和聚焦的易用性改进。"},
|
||||
"community.sponsor.tier.partner.name": {"message": "Partner"},
|
||||
"community.sponsor.tier.partner.amount": {"message": "适合存储与基础设施厂商"},
|
||||
"community.sponsor.tier.partner.desc": {"message": "支持 Provider 验证、部署示例、基准说明和集成指南。"},
|
||||
"community.sponsor.tier.enterprise.name": {"message": "Enterprise"},
|
||||
"community.sponsor.tier.enterprise.amount": {"message": "适合生产环境使用方"},
|
||||
"community.sponsor.tier.enterprise.desc": {"message": "赞助恢复演练、发布加固、审计和长期维护等可靠性工作。"},
|
||||
"community.contributor.kicker": {"message": "贡献者"},
|
||||
"community.contributor.all": {"message": "查看全部"},
|
||||
"community.contributor.source": {"message": "浏览器端通过 GitHub contributors API 获取。"},
|
||||
"community.contributor.botRole": {"message": "自动化贡献者"},
|
||||
"community.contributor.githubRole": {"message": "GitHub 贡献者"},
|
||||
"community.contributor.contributions": {"message": "{count} 次贡献"},
|
||||
"community.path.kicker": {"message": "贡献路径"},
|
||||
"community.path.issues.title": {"message": "反馈生产问题"},
|
||||
"community.path.issues.desc": {"message": "提交日志、部署拓扑和恢复预期。"},
|
||||
"community.path.docs.title": {"message": "完善文档与示例"},
|
||||
"community.path.docs.desc": {"message": "贡献存储、Agent 和数据库部署指南。"},
|
||||
"community.path.code.title": {"message": "提交聚焦的 PR"},
|
||||
"community.path.code.desc": {"message": "保持改动小而可测，并贴合现有架构。"},
|
||||
"sponsors.pageTitle": {"message": "赞助商"},
|
||||
"sponsors.pageDescription": {"message": "赞助 BackupX 的可靠性、文档、存储兼容性和长期维护。"},
|
||||
"sponsors.tag": {"message": "赞助商"},
|
||||
"sponsors.title": {"message": "赞助 BackupX 生态"},
|
||||
"sponsors.subtitle": {"message": "赞助帮助 BackupX 更贴近真实运维：经过验证的存储 Provider、可靠发布、恢复信心和更完善的文档。"}
|
||||
"community.sponsor.tier.enterprise.desc": {"message": "支持恢复演练、发布加固、审计和长期维护。"},
|
||||
|
||||
"sponsors.pageTitle": {"message": "赞助 BackupX"},
|
||||
"sponsors.pageDescription": {"message": "支持 BackupX 的可靠性、文档、存储兼容性和长期维护。"},
|
||||
"sponsors.tag": {"message": "赞助"},
|
||||
"sponsors.title": {"message": "让关键维护工作持续进行"},
|
||||
"sponsors.subtitle": {"message": "赞助用于真实 Provider 验证、可靠发布、恢复演练和更完善的运维文档。"}
|
||||
}
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
"version.label": {"message": "Next"},
|
||||
"sidebar.docs.category.Getting Started": {"message": "快速开始"},
|
||||
"sidebar.docs.category.Deployment": {"message": "部署"},
|
||||
"sidebar.docs.category.Operations": {"message": "运维"},
|
||||
"sidebar.docs.category.Features": {"message": "功能特性"},
|
||||
"sidebar.docs.category.Reference": {"message": "参考"},
|
||||
"sidebar.docs.category.Development": {"message": "开发"}
|
||||
|
||||
+35
-13
@@ -1,7 +1,7 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: 裸机部署
|
||||
description: 从预编译包或源码部署 BackupX（systemd + Nginx）。
|
||||
description: 从预编译包或源码加固部署 BackupX，Nginx 改为显式启用。
|
||||
---
|
||||
|
||||
# 裸机部署
|
||||
@@ -10,20 +10,31 @@ description: 从预编译包或源码部署 BackupX（systemd + Nginx）。
|
||||
|
||||
```bash
|
||||
# 下载对应平台的压缩包
|
||||
curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-v1.6.0-linux-amd64.tar.gz
|
||||
curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-linux-amd64.tar.gz
|
||||
curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-linux-amd64.tar.gz.sha256
|
||||
sha256sum -c backupx-linux-amd64.tar.gz.sha256
|
||||
|
||||
# 解压并安装
|
||||
tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
|
||||
tar xzf backupx-linux-amd64.tar.gz && cd backupx-*-linux-amd64
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
安装脚本自动完成以下步骤：
|
||||
|
||||
1. 创建系统用户 `backupx`
|
||||
2. 复制二进制到 `/opt/backupx/`
|
||||
3. 生成默认 `config.yaml`（含安全的 JWT/加密密钥）
|
||||
2. 复制二进制到 `/opt/backupx/bin/backupx`，并把 Web 控制台复制到 `/opt/backupx/web`
|
||||
3. 把默认配置安装到 `/etc/backupx/config.yaml`
|
||||
4. 安装并启用 `backupx.service` systemd 单元
|
||||
5. （可选）生成 Nginx 站点配置 — 参见 [Nginx 反向代理](./nginx)
|
||||
5. 默认不修改 Nginx；只有显式设置 `INSTALL_NGINX=1` 时才安装模板
|
||||
6. 验证首次初始化接口就绪后才报告安装成功
|
||||
|
||||
可执行文件与前端资源由 root 所有，只有 `/opt/backupx/data` 允许 `backupx` 服务账户写入。`/etc/backupx/config.yaml` 以 `root:backupx`、`0640` 权限安装。
|
||||
|
||||
仓库提供的 Nginx 模板只是起点，可能与现有默认站点冲突。先审核域名与 TLS 策略，再显式启用：
|
||||
|
||||
```bash
|
||||
sudo INSTALL_NGINX=1 ./install.sh
|
||||
```
|
||||
|
||||
如果要部署多节点集群，安装后请编辑 `/etc/backupx/config.yaml`，设置远程 Agent 可访问到的 Master URL：
|
||||
|
||||
@@ -57,17 +68,21 @@ sudo ./deploy/install.sh
|
||||
|
||||
```ini title="/etc/systemd/system/backupx.service"
|
||||
[Unit]
|
||||
Description=BackupX backup management service
|
||||
After=network.target
|
||||
Description=BackupX API Service
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=backupx
|
||||
Group=backupx
|
||||
WorkingDirectory=/opt/backupx
|
||||
ExecStart=/opt/backupx/backupx --config /opt/backupx/config.yaml
|
||||
ExecStart=/opt/backupx/bin/backupx -config /etc/backupx/config.yaml
|
||||
Restart=on-failure
|
||||
RestartSec=5s
|
||||
LimitNOFILE=65536
|
||||
RestartSec=5
|
||||
NoNewPrivileges=true
|
||||
UMask=0027
|
||||
LimitNOFILE=65535
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -79,17 +94,24 @@ WantedBy=multi-user.target
|
||||
sudo systemctl status backupx
|
||||
sudo journalctl -u backupx -f # 实时日志
|
||||
sudo systemctl restart backupx
|
||||
curl -fsS http://127.0.0.1:8340/api/auth/setup/status
|
||||
```
|
||||
|
||||
访问 `http://your-server:8340`，可按需切换到 English，然后在“系统初始化 / System setup”页面创建首个管理员。若监听端口不是默认值，请为安装脚本传入对应的 `HEALTH_URL`。
|
||||
|
||||
生产环境应通过 HTTPS 暴露 BackupX，或在防火墙限制 `8340` 端口。安装器不会自动修改防火墙。
|
||||
|
||||
替换版本前，应在服务停止时同时快照 `/etc/backupx`、`/opt/backupx/data`、已安装二进制和前端文件。请按[升级与恢复](../operations/upgrade-recovery)中的版本化流程操作；让旧版本二进制直接读取已由新版本迁移的数据库并不是安全回滚。
|
||||
|
||||
## 密码重置
|
||||
|
||||
忘记管理员密码时：
|
||||
|
||||
```bash
|
||||
/opt/backupx/backupx reset-password \
|
||||
/opt/backupx/bin/backupx reset-password \
|
||||
--username admin \
|
||||
--password 'newpass123' \
|
||||
--config /opt/backupx/config.yaml
|
||||
--config /etc/backupx/config.yaml
|
||||
```
|
||||
|
||||
Docker 等效命令：
|
||||
|
||||
+34
-3
@@ -1,7 +1,7 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: 配置参考
|
||||
description: server.yaml 所有配置项及对应的环境变量。
|
||||
description: config.yaml 全部服务端配置项及对应的环境变量。
|
||||
---
|
||||
|
||||
# 配置参考
|
||||
@@ -15,7 +15,11 @@ server:
|
||||
host: "0.0.0.0" # BACKUPX_SERVER_HOST
|
||||
port: 8340 # BACKUPX_SERVER_PORT
|
||||
mode: "release" # release | debug
|
||||
external_url: "" # BACKUPX_SERVER_EXTERNAL_URL — Agent 安装脚本使用的 Master 对外 URL
|
||||
external_url: "" # BACKUPX_SERVER_EXTERNAL_URL — 稳定的 Master 对外 URL
|
||||
trusted_proxies: # BACKUPX_SERVER_TRUSTED_PROXIES — 准确的代理 IP/CIDR
|
||||
- "127.0.0.1"
|
||||
- "::1"
|
||||
web_root: "" # BACKUPX_SERVER_WEB_ROOT — 前端构建目录
|
||||
|
||||
database:
|
||||
path: "./data/backupx.db" # BACKUPX_DATABASE_PATH — 内嵌 SQLite
|
||||
@@ -28,12 +32,15 @@ security:
|
||||
backup:
|
||||
temp_dir: "/tmp/backupx" # BACKUPX_BACKUP_TEMP_DIR
|
||||
max_concurrent: 2 # BACKUPX_BACKUP_MAX_CONCURRENT
|
||||
retries: 3 # 单次上传的 rclone 底层重试次数
|
||||
retries: 10 # 单次上传的 rclone 底层重试次数
|
||||
bandwidth_limit: "" # 例如 "10M" 表示限速 10 MB/s
|
||||
|
||||
log:
|
||||
level: "info" # debug | info | warn | error
|
||||
file: "./data/backupx.log"
|
||||
max_size: 100 # 单个日志文件上限，单位 MB
|
||||
max_backups: 3 # 保留的轮转文件数
|
||||
max_age: 30 # 保留天数
|
||||
```
|
||||
|
||||
## 密钥生成
|
||||
@@ -48,11 +55,18 @@ log:
|
||||
|--------|----------|
|
||||
| `server.port` | `BACKUPX_SERVER_PORT` |
|
||||
| `server.external_url` | `BACKUPX_SERVER_EXTERNAL_URL` |
|
||||
| `server.trusted_proxies` | `BACKUPX_SERVER_TRUSTED_PROXIES`（环境变量使用逗号分隔） |
|
||||
| `security.jwt_secret` | `BACKUPX_SECURITY_JWT_SECRET` |
|
||||
| `security.jwt_expire` | `BACKUPX_SECURITY_JWT_EXPIRE` |
|
||||
| `security.encryption_key` | `BACKUPX_SECURITY_ENCRYPTION_KEY` |
|
||||
| `log.level` | `BACKUPX_LOG_LEVEL` |
|
||||
| `backup.max_concurrent` | `BACKUPX_BACKUP_MAX_CONCURRENT` |
|
||||
| `backup.temp_dir` | `BACKUPX_BACKUP_TEMP_DIR` |
|
||||
| `backup.retries` | `BACKUPX_BACKUP_RETRIES` |
|
||||
| `backup.bandwidth_limit` | `BACKUPX_BACKUP_BANDWIDTH_LIMIT` |
|
||||
| `log.max_size` | `BACKUPX_LOG_MAX_SIZE` |
|
||||
| `log.max_backups` | `BACKUPX_LOG_MAX_BACKUPS` |
|
||||
| `log.max_age` | `BACKUPX_LOG_MAX_AGE` |
|
||||
|
||||
## Master 对外 URL
|
||||
|
||||
@@ -64,3 +78,20 @@ server:
|
||||
```
|
||||
|
||||
BackupX 会用这个地址渲染一键 Agent 安装脚本和 docker-compose 片段。该地址必须能被所有 Agent 主机访问。只有在 `X-Forwarded-Proto` / `X-Forwarded-Host` 可靠且正好指向 Agent 可访问地址时，才建议留空。
|
||||
|
||||
代理或 SSH 堡垒机场景可在安装向导中为单个 Agent 设置覆盖地址。目标侧的一次性安装链接与生成的 Agent 运行配置都会使用这个地址，浏览器仍使用正常的公开地址。
|
||||
|
||||
## 可信反向代理
|
||||
|
||||
BackupX 只接受 `server.trusted_proxies` 中来源提供的客户端转发头。默认仅允许本机 Nginx。代理运行在其他容器或主机时，加入准确 IP 或网段：
|
||||
|
||||
```yaml
|
||||
server:
|
||||
trusted_proxies:
|
||||
- "127.0.0.1"
|
||||
- "172.18.0.0/16"
|
||||
```
|
||||
|
||||
不要配置 `0.0.0.0/0`，因为登录限流、安装令牌限流和审计日志都依赖客户端地址。BackupX 直接暴露且不应信任任何转发头时可设置空列表。
|
||||
|
||||
修改安全密钥或数据库路径前，应同时备份完整数据目录和配置文件。经过验证的快照与回滚流程见[升级与恢复](../operations/upgrade-recovery)。
|
||||
|
||||
@@ -1,81 +1,98 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Docker 部署
|
||||
description: 生产级 Docker 部署方案，含 compose 配置、宿主目录挂载、环境变量覆盖。
|
||||
description: 带健康检查和持久化数据的加固单进程 Docker 部署。
|
||||
---
|
||||
|
||||
# Docker 部署
|
||||
|
||||
BackupX 官方 Docker 镜像 [`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx) 支持多架构（linux/amd64 + linux/arm64）。
|
||||
官方镜像 [`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx) 支持 `linux/amd64` 和 `linux/arm64`。
|
||||
|
||||
## Compose 文件
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
backupx:
|
||||
image: awuqing/backupx:latest
|
||||
image: ${BACKUPX_IMAGE:-awuqing/backupx:latest}
|
||||
container_name: backupx
|
||||
restart: unless-stopped
|
||||
init: true
|
||||
stop_grace_period: 30s
|
||||
ports:
|
||||
- "8340:8340"
|
||||
- "${BACKUPX_BIND_ADDRESS:-0.0.0.0}:${BACKUPX_PORT:-8340}:8340"
|
||||
volumes:
|
||||
- backupx-data:/app/data
|
||||
# 挂载需要备份的宿主机目录：
|
||||
- /var/www:/mnt/www:ro
|
||||
- /etc/nginx:/mnt/nginx-conf:ro
|
||||
# - /var/www:/mnt/www:ro
|
||||
# - /etc/nginx:/mnt/nginx-conf:ro
|
||||
security_opt:
|
||||
- no-new-privileges:true
|
||||
cap_drop:
|
||||
- ALL
|
||||
cap_add:
|
||||
- CHOWN
|
||||
- DAC_OVERRIDE
|
||||
- SETGID
|
||||
- SETUID
|
||||
environment:
|
||||
- TZ=Asia/Shanghai
|
||||
# 远程 Agent 需要通过公网或可路由地址连接 Master 时必须配置：
|
||||
# - BACKUPX_SERVER_EXTERNAL_URL=https://backup.example.com
|
||||
- BACKUPX_LOG_LEVEL=info
|
||||
- BACKUPX_BACKUP_MAX_CONCURRENT=2
|
||||
TZ: Asia/Shanghai
|
||||
# BACKUPX_SERVER_EXTERNAL_URL: https://backup.example.com
|
||||
BACKUPX_LOG_LEVEL: info
|
||||
BACKUPX_BACKUP_MAX_CONCURRENT: "2"
|
||||
healthcheck:
|
||||
test: ["CMD", "su-exec", "backupx:backupx", "wget", "-q", "-T", "3", "-O", "/dev/null", "http://127.0.0.1:8340/ready"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
start_period: 10s
|
||||
|
||||
volumes:
|
||||
backupx-data:
|
||||
```
|
||||
|
||||
启动：
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
入口脚本仅以 root 完成旧镜像数据的所有权迁移，随后只运行一个非 root `backupx` 进程；Compose 仅保留初始化所需的所有权与 UID/GID 切换能力。后端同时提供 API 与前端静态文件，默认不挂载 Docker Socket，也不打包 Docker CLI。生产环境应把 `BACKUPX_IMAGE` 固定到明确 Release 标签。
|
||||
|
||||
## 备份宿主机目录
|
||||
|
||||
想备份宿主机上的文件，需要将对应路径挂载进容器。在 Web UI 创建文件类型任务时，把源路径指向挂载后的容器内路径（如 `/mnt/www`）。
|
||||
按需挂载源目录，并在任务中使用容器内路径。容器中的 `backupx` 用户必须拥有读取权限；恢复目标应使用单独且范围受限的可写挂载。特权路径优先通过远程 Agent 处理；确实需要 Master 以 root 读取时，应显式设置 `user: "0:0"` 并审核每一个挂载。
|
||||
|
||||
## 多节点集群
|
||||
|
||||
如果要在其他机器部署 Agent，请在 Master 容器上设置 `BACKUPX_SERVER_EXTERNAL_URL`，值为所有 Agent 都能访问到的 URL：
|
||||
设置所有 Agent 可达的稳定地址：
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- BACKUPX_SERVER_EXTERNAL_URL=https://backup.example.com
|
||||
BACKUPX_SERVER_EXTERNAL_URL: https://backup.example.com
|
||||
```
|
||||
|
||||
Agent 跨不可信网络访问时建议使用 HTTPS。控制台生成的一键安装脚本和 docker-compose 片段会把这个值写成 `BACKUPX_AGENT_MASTER`。
|
||||
跨不可信网络必须使用 HTTPS。代理、私有 CA 和 SSH 堡垒机场景见 [多节点集群](../features/multi-node)。
|
||||
|
||||
## 环境变量
|
||||
外部反向代理运行在其他容器时，只把准确的 Docker 网桥网段加入 `BACKUPX_SERVER_TRUSTED_PROXIES`，例如 `172.18.0.0/16`，不要信任所有地址。
|
||||
|
||||
所有配置项都可以通过 `BACKUPX_` 前缀环境变量覆盖：
|
||||
## 环境变量覆盖
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- TZ=Asia/Shanghai
|
||||
- BACKUPX_SERVER_PORT=8340
|
||||
- BACKUPX_LOG_LEVEL=debug
|
||||
- BACKUPX_BACKUP_MAX_CONCURRENT=4
|
||||
- BACKUPX_BACKUP_TEMP_DIR=/tmp/backupx
|
||||
TZ: Asia/Shanghai
|
||||
BACKUPX_LOG_LEVEL: debug
|
||||
BACKUPX_BACKUP_MAX_CONCURRENT: "4"
|
||||
BACKUPX_BACKUP_TEMP_DIR: /tmp/backupx
|
||||
```
|
||||
|
||||
完整列表见 [配置参考](./configuration)。
|
||||
镜像内部端口固定为 `8340`，只通过 `BACKUPX_PORT` 修改宿主机发布端口。
|
||||
|
||||
## 升级
|
||||
|
||||
在 UI **系统设置 → 检查更新** 页面查看是否有新版，然后在宿主机上：
|
||||
## 升级前提
|
||||
|
||||
```bash
|
||||
docker compose pull && docker compose up -d
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
无需手工迁移：BackupX 启动时自动迁移 SQLite schema。
|
||||
等待状态变为 `healthy` 后再切换流量或移除旧部署。升级前应停止 Master 后做文件级复制，或对整个 `backupx-data` 卷创建原子快照。同一个数据卷必须只运行一个活动 Master；SQLite 不支持多个 Master 容器共享 `/app/data`。
|
||||
|
||||
生产环境应使用发布标签或镜像摘要而不是 `latest`，并保留与旧版本匹配的升级前数据快照。完整的升级、回滚和灾难恢复流程见[升级与恢复](../operations/upgrade-recovery)。
|
||||
|
||||
@@ -23,22 +23,50 @@ server {
|
||||
location /api/ {
|
||||
proxy_pass http://127.0.0.1:8340;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header Host $http_host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header X-Forwarded-Host $http_host;
|
||||
proxy_set_header X-Forwarded-Port $server_port;
|
||||
proxy_set_header Connection "";
|
||||
|
||||
# 大文件上传（用于恢复流程）
|
||||
client_max_body_size 0;
|
||||
proxy_request_buffering off;
|
||||
|
||||
# 实时日志使用 SSE，必须关闭缓冲
|
||||
proxy_buffering off;
|
||||
proxy_cache off;
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
}
|
||||
|
||||
# 兼容旧版本生成的安装地址；新版本通过上面的 /api/install/ 访问。
|
||||
location /install/ {
|
||||
proxy_pass http://127.0.0.1:8340/install/;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $http_host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header X-Forwarded-Host $http_host;
|
||||
proxy_set_header X-Forwarded-Port $server_port;
|
||||
}
|
||||
|
||||
# 避免探针和指标请求落入 SPA fallback。
|
||||
location = /health { proxy_pass http://127.0.0.1:8340/health; }
|
||||
location = /ready { proxy_pass http://127.0.0.1:8340/ready; }
|
||||
location = /metrics { proxy_pass http://127.0.0.1:8340/metrics; }
|
||||
}
|
||||
```
|
||||
|
||||
集群使用 Master 中转备份时必须保留 `proxy_request_buffering off`。否则 Nginx 会先把 Agent 上传的完整备份写入代理临时目录，再交给 BackupX，既失去流式传输优势，也可能占满代理磁盘。
|
||||
|
||||
如果 Nginx 运行在另一台主机或另一个容器，只把该代理的 IP 或网段加入 `server.trusted_proxies`，不要配置 `0.0.0.0/0`。登录限流、安装令牌限流和审计日志都依赖可信的客户端地址。
|
||||
|
||||
`/health`、`/ready` 和 `/metrics` 不需要 BackupX 认证。应只放行探针与 Prometheus 来源网段，或把这些 location 放在内部监听端口，避免直接暴露到互联网。
|
||||
|
||||
## certbot 配置 HTTPS
|
||||
|
||||
```bash
|
||||
@@ -49,5 +77,5 @@ sudo certbot --nginx -d backup.example.com
|
||||
certbot 会自动改写配置监听 443 并设置续期。
|
||||
|
||||
:::caution Agent 需要稳定的 URL
|
||||
如果 Master 部署在 HTTPS 后面，远程 Agent 的 `--master` 必须使用公网 HTTPS 地址。自签名证书需加 `--insecure-tls`（仅供测试）。
|
||||
如果 Master 部署在 HTTPS 后面，远程 Agent 的 `--master` 必须使用最终 HTTPS 地址，Agent 不会跟随重定向。私有 CA 应预先下发 PEM 证书并使用 `--ca-cert /path/to/ca.pem`；`--insecure-tls` 只用于短期测试。
|
||||
:::
|
||||
|
||||
@@ -6,7 +6,7 @@ description: 搭建 BackupX 本地开发环境 — 后端、前端、测试。
|
||||
|
||||
# 开发环境
|
||||
|
||||
**环境要求：** Go ≥ 1.25，Node.js ≥ 20，npm。
|
||||
**环境要求：** Go ≥ 1.25、Node.js 24 LTS、npm 11 或更高版本。
|
||||
|
||||
## 克隆与依赖
|
||||
|
||||
|
||||
+12
-2
@@ -12,12 +12,22 @@ BackupX 支持五种内置备份类型，类型决定了用哪个 runner 执行
|
||||
|
||||
## 文件 / 目录
|
||||
|
||||
打包（可选 gzip）一个或多个文件系统路径。
|
||||
文件任务提供三种备份模式：
|
||||
|
||||
- **全量归档** — 每次生成一份可独立使用的 tar 产物
|
||||
- **差异归档** — 只保存相对当前全量基线的变化，并按周期刷新全量基线
|
||||
- **CDC 去重仓库** — 按稳定的 512 KiB / 1 MiB / 4 MiB 内容边界切块，将新块合并到不可变的 32 MiB pack，每次运行只新增一份小型快照清单
|
||||
|
||||
CDC 仓库会在不同文件、不同快照之间复用相同内容。完整恢复、选择性恢复、完整性校验、下载为 tar、保留策略和垃圾回收都通过仓库索引定位分块。压缩与加密按块执行；启用加密时使用带密钥的块 ID，不暴露明文哈希。
|
||||
|
||||
当前仓库索引采用单写者模型，因此 CDC 模式仅在 Master 本机执行。如需保存多份完整仓库，请在任务中直接多选主存储目标。对象级副本复制会被禁用，因为只有快照清单、没有共享 pack 与索引并不是完整备份。
|
||||
|
||||
文件任务的通用选项：
|
||||
|
||||
- **源路径** 支持多个（UI 中每行一个）
|
||||
- **排除模式** 支持 gitignore 风格的通配符
|
||||
- 可选跟随符号链接、保留权限
|
||||
- 输出单个 `.tar` 或 `.tar.gz`
|
||||
- 全量与差异模式输出 `.tar`、`.tar.gz` 或 `.tar.zst`
|
||||
|
||||
## MySQL
|
||||
|
||||
|
||||
+177
-84
@@ -1,134 +1,227 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: 多节点集群
|
||||
description: Master-Agent 模式 — 通过 HTTP 长轮询把备份路由到远程服务器。
|
||||
description: 通过直连 HTTPS、正向代理或 SSH 堡垒机部署 BackupX Agent。
|
||||
---
|
||||
|
||||
# 多节点集群
|
||||
|
||||
BackupX 支持 Master-Agent 模式：备份任务可以指定在哪个节点执行，Agent 在本地完成备份并直接上传到存储。所有连接都由 Agent 主动发起，所以远程服务器只需要出站 HTTP 访问权限。
|
||||
BackupX 使用一个单活 Master 作为控制面，在每台源服务器运行 Agent。所有连接都由 Agent 主动发起：每 15 秒上报心跳，每 5 秒轮询命令，不需要为 Agent 开放入站端口。
|
||||
|
||||
## 架构
|
||||
## 架构与边界
|
||||
|
||||
```
|
||||
[Web 控制台] ─── JWT ──→ [Master (backupx)]
|
||||
↑ ↓
|
||||
│ │ HTTP 长轮询（Token 认证）
|
||||
│ ↓
|
||||
[Agent (backupx agent)] ← 运行在远程服务器
|
||||
↓
|
||||
[70+ 存储后端]
|
||||
```text
|
||||
[Web 控制台] ────────> [单活 Master + SQLite]
|
||||
^
|
||||
| Agent 主动 HTTP(S) 轮询
|
||||
+---------+---------+
|
||||
| | |
|
||||
[Agent B] [Agent C] [Agent D]
|
||||
| | |
|
||||
+----> 存储目标
|
||||
```
|
||||
|
||||
- **协议** — HTTP 长轮询，Agent 主动发起所有连接
|
||||
- **心跳** — Agent 每 15s 上报一次；Master 超过 45s 未收到心跳即判为离线
|
||||
- **下发** — Master 把 `run_task` 命令写入队列，Agent 轮询拉取
|
||||
- **执行** — Agent 复用 BackupRunner（file / mysql / postgresql / sqlite / saphana）并直接上传到存储
|
||||
- **安全** — 每个节点独立 Token；Agent 不持有 Master 的 JWT 密钥或 AES-256 加密密钥
|
||||
- 每个节点有独立 Agent Token，Agent 不持有 Master 的 JWT 密钥或配置加密密钥。
|
||||
- Master 超过 45 秒未收到心跳即把节点标记为离线。
|
||||
- Master 持久化命令，Agent 领取后在本机执行。
|
||||
- 网络存储通常由 Agent 直传；Master 本地存储可显式启用认证流式中转。
|
||||
|
||||
## 一键部署步骤
|
||||
:::warning Master 只能单活
|
||||
内置 SQLite 不是共享多写数据库。同一个数据目录只能运行一个 Master。控制面高可用应采用主备主机、持久卷快照以及稳定 DNS 或虚拟 IP，故障时确保旧 Master 停止后再启动备用实例。不要让多个 Master 副本同时挂载 `/app/data` 或同一个 `backupx.db`。
|
||||
:::
|
||||
|
||||
### 0. 为生产集群设置 Master 对外 URL
|
||||
BackupX 会设置 5 秒 SQLite busy timeout，并为命令队列建立查询索引，降低 Agent 并发轮询及任务更新时的锁竞争。数据库应位于本地文件系统或块存储。采用文件复制备份控制面时，先停止 Master 再复制整个数据目录；运行期间不要只复制 `backupx.db`。
|
||||
|
||||
生成 Agent 安装命令前，请先确认 Master URL 对所有目标主机稳定可达。
|
||||
## 选择网络路径
|
||||
|
||||
如果 BackupX 部署在 Docker、Nginx、负载均衡或外层反向代理后面，请在 Master 配置 `server.external_url` 或环境变量 `BACKUPX_SERVER_EXTERNAL_URL`：
|
||||
| 场景 | Agent Master 地址 | Agent 代理 URL | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| 可路由内网或公网服务 | `https://backup.example.com` | 留空 | 推荐，只需放行出站 TCP 443 |
|
||||
| 企业正向代理 | `https://backup.example.com` | `http://proxy.internal:3128` | 支持 HTTP(S) 与 SOCKS5(H) |
|
||||
| 通过堡垒机建立 SSH 动态转发 | `https://backup.internal` | `socks5h://127.0.0.1:1080` | 保留 TLS 主机名，并通过隧道解析内网 DNS |
|
||||
| SSH 固定本地转发 | `http://127.0.0.1:18340` | 留空 | HTTP 链路位于 SSH 内，只能绑定回环地址 |
|
||||
|
||||
```yaml title="config.yaml"
|
||||
私有 PKI 场景请填写目标节点上预置的 PEM CA 证书绝对路径。生产环境不要使用 `--insecure-tls`。
|
||||
|
||||
未配置显式代理时，Agent 到 Master 的 HTTP 流量会遵循 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`。systemd 服务通常不会继承交互式 Shell 环境，因此 systemd 部署应在安装向导或 Agent YAML 中明确配置代理。
|
||||
|
||||
## 准备 Master
|
||||
|
||||
生成命令前先设置稳定地址：
|
||||
|
||||
```yaml title="/etc/backupx/config.yaml"
|
||||
server:
|
||||
external_url: "https://backup.example.com"
|
||||
trusted_proxies:
|
||||
- "127.0.0.1"
|
||||
- "::1"
|
||||
# 代理不在本机时，只加入准确的代理 IP 或网段。
|
||||
# - "172.18.0.0/16"
|
||||
```
|
||||
|
||||
该 URL 会写入 systemd 单元、前台运行命令和 docker-compose 片段。如果地址不正确，Agent 可能安装成功但始终离线，因为它会持续轮询一个内网地址或仅浏览器可访问的地址。
|
||||
`external_url` 是默认安装入口和 Agent 运行地址。受限节点可以让目标机侧生成的安装 URL 与 Agent 运行地址同时改用隧道或内网地址，浏览器仍继续访问公网地址。
|
||||
|
||||
### 1. 打开安装向导
|
||||
跨不可信网络必须使用 HTTPS。Master 中转上传还要求反向代理关闭请求缓冲并允许大请求体，详见 [Nginx 反向代理](../deployment/nginx)。
|
||||
|
||||
Web 控制台 → **节点管理** → **添加节点**，打开三步向导：
|
||||
Agent 必须直接配置最终 API 地址，不能依赖 HTTP 跳转到 HTTPS。Agent 会主动拒绝重定向，避免认证 Token 被转发到非预期主机。
|
||||
|
||||
- **第一步 · 节点信息**：填写节点名称；或切换"批量创建"粘贴多行名称（每行一个，最多 50 个）
|
||||
- **第二步 · 部署参数**：选择安装模式（`systemd` 推荐、`Docker`、`前台运行` 调试用）、架构（默认自动检测）、Agent 版本（默认跟随 Master 版本）、有效期（5 分钟 / 15 分钟 / 1 小时 / 24 小时）、下载源（`GitHub` 直连或 `ghproxy` 镜像，国内服务器建议后者）
|
||||
- **第三步 · 安装命令**：一条一键安装命令 + 实时倒计时。点击复制，粘贴到目标机以 root 权限执行。默认命令会嵌入已渲染的安装脚本，目标机无需再通过反向代理访问 `/api/install/:token`；公开安装 URL 仍作为备用路径保留。
|
||||
## 部署 Agent
|
||||
|
||||
### 2. 目标机一条命令完成
|
||||
打开 **节点管理 → 添加节点**：
|
||||
|
||||
请直接使用 Web 控制台生成的命令。该命令会把安装脚本写入临时文件，校验 `BACKUPX_AGENT_INSTALL_V1` 魔数，再以 root 权限执行。
|
||||
1. 输入单个节点名，或在批量模式输入最多 50 个名称。
|
||||
2. 选择 systemd、Docker 或前台模式，以及架构、Agent Release、命令有效期和下载源。
|
||||
3. 选择 **直连** 或 **代理或堡垒机**。受限网络可填写节点专用 Master 地址、代理 URL 或私有 CA 路径。
|
||||
4. 把生成的命令复制到目标机，以 root 权限执行。
|
||||
|
||||
脚本会自动：
|
||||
备份和恢复宿主机文件时推荐 systemd，因为 Agent 需要访问任意本地路径。Docker Agent 只能看到显式挂载的目录；分配文件任务前，应使用只读备份源 volume，并为恢复目标单独配置范围受限的可写挂载。
|
||||
|
||||
1. 检测操作系统与架构（`uname -m`）
|
||||
2. 从 GitHub Release（或 ghproxy 镜像）下载匹配的 `backupx` 二进制
|
||||
3. 安装到 `/opt/backupx-agent`，创建系统用户 `backupx`
|
||||
4. 写入 `/etc/systemd/system/backupx-agent.service`（token 已烧入环境变量）
|
||||
5. 执行 `systemctl enable --now backupx-agent`
|
||||
6. 轮询 `/api/v1/agent/self`，直到 Master 确认 `status: online`（最多 30 秒）
|
||||
主命令通过一次性入口下载安装器，并在执行前校验脚本标记。向导会把所选 Agent 地址、显式代理和私有 CA 同时绑定到下载命令与安装后的 Agent 配置。如果目标网络仍无法访问安装入口，使用页面单独展示的嵌入式备用命令。嵌入式命令包含长期节点 Token，必须按密钥管理。
|
||||
|
||||
Docker 模式使用同一组环境变量约定：`BACKUPX_AGENT_MASTER`、`BACKUPX_AGENT_TOKEN` 和 `BACKUPX_AGENT_TEMP_DIR=/var/lib/backupx-agent/tmp`。容器启动后，安装脚本同样会探测 `/api/v1/agent/self`；如果节点没有上线，会输出 `docker ps` 与 `docker logs --tail=100 backupx-agent` 排查命令，并以非零状态退出。
|
||||
安装器会：
|
||||
|
||||
如果使用 URL 备用命令时 `curl` 输出 HTML，或 shell 报 `Syntax error: newline unexpected`，说明安装 URL 被 Web 控制台接管而不是转发到后端。需要确保 `/api/install/` 或 `/install/` 至少一个路径能转发到 BackupX 后端，或改用控制台生成的嵌入式命令。
|
||||
1. 检测 `linux/amd64` 或 `linux/arm64`。
|
||||
2. 配置显式代理时始终通过该代理下载 Release；否则使用主机的正常直连或环境代理路径，并在该版本提供 SHA-256 旁车文件时进行校验。
|
||||
3. 以 `0600` 权限写入 `/etc/backupx-agent/config.yaml` 和 `/etc/backupx-agent/agent.token`。
|
||||
4. 不把 Token 写入 systemd unit 或 Docker 环境元数据。
|
||||
5. 启动 Agent，并在 30 秒内轮询 `/api/v1/agent/self`。
|
||||
6. 节点未上线时返回非零状态，并输出 systemd 或 Docker 排查命令。
|
||||
|
||||
脚本是幂等的：升级或重装只需重新生成一条安装命令再跑一次。一次性安装链接在 TTL 到期或被首次消费后立即作废。
|
||||
旧版本如果没有校验文件，会显示兼容性警告后继续安装；新版本应始终发布并校验该文件。
|
||||
|
||||
### 3. 随时轮换 Agent Token
|
||||
|
||||
节点操作列（︙）→ **重新生成 Token**。新 Token 一次性显示，旧 Token 24 小时内仍有效，便于滚动替换无需停机。24 小时后旧 Token 被拒绝。
|
||||
|
||||
### 4. 批量部署
|
||||
|
||||
第一步选"批量创建"粘贴节点名（每行一个，最多 50 个）。第三步显示每个节点对应的命令表格，底部「导出 .sh」可打包为单个 shell 文件，方便 SSH 循环或 Ansible 任务。
|
||||
|
||||
### 5. 把任务路由到该节点
|
||||
|
||||
在 **备份任务** 页面新建任务时选择对应节点。任务触发时：
|
||||
|
||||
- 本机 / 未指定（`nodeId=0`）：Master 进程内直接执行
|
||||
- 远程节点：Master 写入命令队列 → Agent 拉取 → Agent 本地执行 → 上传 → 回报
|
||||
|
||||
节点列表会展示 Agent 健康与命令队列状态：pending/dispatched 深度、运行中的长任务、超时数、最旧活跃命令年龄和最近 Agent 错误。同样的队列深度、运行中命令数和超时快照会导出为 Prometheus 指标：
|
||||
|
||||
- `backupx_agent_command_queue_depth`
|
||||
- `backupx_agent_command_running`
|
||||
- `backupx_agent_command_timeout_total`
|
||||
|
||||
## 已知限制
|
||||
|
||||
- **加密备份仅支持 Master 本机执行**：Agent 不持有 Master 的 AES-256 密钥。创建或更新任务时，如果 `encrypt: true` 且选择了远程节点或节点池，会在入口直接拒绝
|
||||
- **目录浏览超时**：远程目录浏览通过命令队列做同步 RPC，默认 15s 超时
|
||||
- **派发命令超时**：Agent 领取但未完成的命令超过 10 分钟会被置 `timeout`
|
||||
|
||||
## CLI 参考
|
||||
### systemd 安装结果
|
||||
|
||||
```yaml title="/etc/backupx-agent/config.yaml"
|
||||
master: "https://backup.example.com"
|
||||
tokenFile: "/etc/backupx-agent/agent.token"
|
||||
heartbeatInterval: "15s"
|
||||
pollInterval: "5s"
|
||||
tempDir: "/var/lib/backupx-agent/tmp"
|
||||
proxyUrl: ""
|
||||
caCertFile: ""
|
||||
```
|
||||
backupx agent --help
|
||||
-master string Master URL
|
||||
-token string Agent 认证令牌
|
||||
-config string YAML 配置文件路径（优先级高于环境变量）
|
||||
-temp-dir string 本地临时目录（默认 /tmp/backupx-agent）
|
||||
-insecure-tls 跳过 TLS 证书校验（仅测试用）
|
||||
```
|
||||
|
||||
## systemd 单元
|
||||
|
||||
```ini title="/etc/systemd/system/backupx-agent.service"
|
||||
[Unit]
|
||||
Description=BackupX Agent
|
||||
After=network.target
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
StartLimitIntervalSec=300
|
||||
StartLimitBurst=10
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=backupx
|
||||
Environment="BACKUPX_AGENT_MASTER=https://master.example.com"
|
||||
Environment="BACKUPX_AGENT_TOKEN=your-token"
|
||||
ExecStart=/opt/backupx/backupx agent
|
||||
ExecStart=/opt/backupx-agent/backupx agent --config /etc/backupx-agent/config.yaml
|
||||
Restart=on-failure
|
||||
RestartSec=10s
|
||||
TimeoutStopSec=30s
|
||||
UMask=0077
|
||||
LimitNOFILE=65535
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
启用并启动：
|
||||
Agent 以 root 运行，因为文件备份和恢复路径可能属于任意系统用户。应严格限制谁能创建任务，以及谁能修改 root 所有的 Agent 配置。
|
||||
|
||||
## SSH 堡垒机示例
|
||||
|
||||
内网 Master 使用 HTTPS 时优先采用 SOCKS 隧道，这样 Master 主机名与证书校验保持不变。
|
||||
|
||||
先创建专用 SSH 账户，预置私钥和已经人工核对指纹的 `known_hosts`，再创建：
|
||||
|
||||
```sshconfig title="/etc/backupx-agent/ssh_config"
|
||||
Host backupx-bastion
|
||||
HostName bastion.example.com
|
||||
User backupx-tunnel
|
||||
IdentityFile /etc/backupx-agent/tunnel_ed25519
|
||||
IdentitiesOnly yes
|
||||
BatchMode yes
|
||||
UserKnownHostsFile /etc/backupx-agent/known_hosts
|
||||
StrictHostKeyChecking yes
|
||||
DynamicForward 127.0.0.1:1080
|
||||
ExitOnForwardFailure yes
|
||||
ServerAliveInterval 30
|
||||
ServerAliveCountMax 3
|
||||
```
|
||||
|
||||
```ini title="/etc/systemd/system/backupx-agent-tunnel.service"
|
||||
[Unit]
|
||||
Description=BackupX Agent SSH tunnel
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
Before=backupx-agent.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/bin/ssh -NT -F /etc/backupx-agent/ssh_config backupx-bastion
|
||||
Restart=always
|
||||
RestartSec=5s
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
再添加依赖覆写，让隧道不可用时 Agent 关闭失败而不是绕过堡垒机：
|
||||
|
||||
```ini title="/etc/systemd/system/backupx-agent.service.d/tunnel.conf"
|
||||
[Unit]
|
||||
Requires=backupx-agent-tunnel.service
|
||||
After=backupx-agent-tunnel.service
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl enable --now backupx-agent
|
||||
sudo journalctl -u backupx-agent -f
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now backupx-agent-tunnel backupx-agent
|
||||
```
|
||||
|
||||
在安装向导中保留内网 HTTPS Master 地址，把代理填写为 `socks5h://127.0.0.1:1080`。启用服务前必须通过独立渠道核对堡垒机 Host Key。
|
||||
|
||||
## 集中存储数据路径
|
||||
|
||||
| 目标 | 数据路径 |
|
||||
| --- | --- |
|
||||
| S3、WebDAV、FTP、云盘或其他网络后端 | Agent 直接流式上传到目标 |
|
||||
| 启用 **远程备份经 Master 中转** 的 `local_disk` | Agent 通过认证 Master API 流式上传，Master 写入本地挂载 |
|
||||
|
||||
中转不会在 Master 上额外创建一份完整临时副本，恢复时走反向流式通道。Nginx 必须关闭请求缓冲，才能保持该特性。
|
||||
|
||||
## 运维
|
||||
|
||||
```bash
|
||||
sudo systemctl status backupx-agent
|
||||
sudo journalctl -u backupx-agent -n 100 --no-pager
|
||||
sudo /opt/backupx-agent/backupx agent --config /etc/backupx-agent/config.yaml
|
||||
```
|
||||
|
||||
从节点操作菜单轮换 Token 后，在 24 小时重叠窗口内更新 `/etc/backupx-agent/agent.token` 并重启服务。
|
||||
|
||||
建议监控：
|
||||
|
||||
- `backupx_agent_command_queue_depth`
|
||||
- `backupx_agent_command_running`
|
||||
- `backupx_agent_command_timeout_total`
|
||||
- `backupx_node_online`
|
||||
|
||||
## CLI 参考
|
||||
|
||||
```text
|
||||
backupx agent --help
|
||||
-master string Master 地址
|
||||
-token string Agent Token
|
||||
-token-file string 从文件读取 Agent Token
|
||||
-config string YAML 配置文件路径
|
||||
-temp-dir string 本地临时目录
|
||||
-proxy-url string HTTP(S) 或 SOCKS5(H) 代理
|
||||
-ca-cert string 用于校验 Master 的 PEM CA 证书
|
||||
-insecure-tls 跳过 TLS 校验（仅测试）
|
||||
```
|
||||
|
||||
环境变量：`BACKUPX_AGENT_MASTER`、`BACKUPX_AGENT_TOKEN`、`BACKUPX_AGENT_TOKEN_FILE`、`BACKUPX_AGENT_HEARTBEAT`、`BACKUPX_AGENT_POLL`、`BACKUPX_AGENT_TEMP_DIR`、`BACKUPX_AGENT_PROXY_URL`、`BACKUPX_AGENT_CA_CERT_FILE`、`BACKUPX_AGENT_INSECURE_TLS`。
|
||||
|
||||
## 已知限制
|
||||
|
||||
- Master 使用内置 SQLite，只支持单活。
|
||||
- 加密备份仅支持 Master 本机执行，因为 Agent 不持有 Master 加密密钥。
|
||||
- 远程目录浏览是同步队列 RPC，默认超时 15 秒。
|
||||
- Agent 领取后长期不更新的命令会由 Master 超时监控处理。
|
||||
|
||||
+3
-1
@@ -19,7 +19,9 @@ BackupX 的目标是接入任何你想放置备份文件的地方。
|
||||
| **Google Drive** | Client ID/Secret + OAuth 授权 |
|
||||
| **WebDAV** | 地址 + 用户名/密码 |
|
||||
| **FTP / FTPS** | 主机 + 端口 + 用户名/密码 |
|
||||
| **本地磁盘** | 目标目录（绝对路径） |
|
||||
| **本地磁盘** | 目标目录（绝对路径）+ 可选的远程 Agent 经 Master 中转 |
|
||||
|
||||
新建本地磁盘目标默认开启 **远程备份经 Master 中转**。开启时，配置目录属于 Master，挂载到 Master 的存储服务器可集中接收多台源 Agent 的备份；如果该路径本就属于各 Agent，请关闭此选项。升级前已有目标保持原来的 Agent 本机落盘行为，只有显式开启后才会切换。
|
||||
|
||||
## Rclone 后端
|
||||
|
||||
|
||||
+25
-33
@@ -10,73 +10,65 @@ BackupX 以单个静态二进制发布。三种安装方式，按实际环境选
|
||||
|
||||
## Docker（推荐）
|
||||
|
||||
无需克隆仓库：
|
||||
下载仓库中的正式加固 Compose 文件并启动：
|
||||
|
||||
```bash
|
||||
docker run -d --name backupx \
|
||||
-p 8340:8340 \
|
||||
-v backupx-data:/app/data \
|
||||
awuqing/backupx:latest
|
||||
curl -fLO https://raw.githubusercontent.com/Awuqing/BackupX/main/docker-compose.yml
|
||||
docker compose up -d
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
或使用 `docker compose`：
|
||||
该 Compose 配置启用 init 与优雅停止，持久化 `/app/data`，以非特权用户运行应用，删除不必要能力，并通过 `/ready` 检查健康。[`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx) 镜像支持 `linux/amd64` 和 `linux/arm64`。
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
backupx:
|
||||
image: awuqing/backupx:latest
|
||||
container_name: backupx
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "8340:8340"
|
||||
volumes:
|
||||
- backupx-data:/app/data
|
||||
# 挂载需要备份的宿主机目录（按需添加）：
|
||||
# - /var/www:/mnt/www:ro
|
||||
# - /etc/nginx:/mnt/nginx-conf:ro
|
||||
environment:
|
||||
- TZ=Asia/Shanghai
|
||||
生产环境应创建受保护的 `.env`，固定 Release 而不是依赖 `latest`：
|
||||
|
||||
volumes:
|
||||
backupx-data:
|
||||
```dotenv
|
||||
BACKUPX_IMAGE=awuqing/backupx:vX.Y.Z
|
||||
BACKUPX_BIND_ADDRESS=127.0.0.1
|
||||
TZ=Asia/Shanghai
|
||||
```
|
||||
|
||||
Docker Hub：[`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx)，支持 linux/amd64 和 linux/arm64。
|
||||
反向代理位于同一主机时使用回环绑定；需要直接访问时，应选择明确的监听接口并配置防火墙。宿主机备份源应只读挂载，或在源主机部署 Agent。完整配置见 [Docker 部署](../deployment/docker)。
|
||||
|
||||
## 预编译包（裸机）
|
||||
|
||||
从 [Releases 页面](https://github.com/Awuqing/BackupX/releases) 下载对应平台的压缩包，执行安装脚本：
|
||||
|
||||
```bash
|
||||
sha256sum -c backupx-v*-linux-amd64.tar.gz.sha256
|
||||
tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
|
||||
sudo ./install.sh # 创建系统用户、安装到 /opt/backupx、配置 systemd + Nginx
|
||||
sudo ./install.sh # 创建系统用户、安装到 /opt/backupx、配置 systemd
|
||||
```
|
||||
|
||||
安装脚本会自动：
|
||||
|
||||
1. 创建 `backupx` 系统用户
|
||||
2. 安装二进制到 `/opt/backupx/backupx`
|
||||
3. 生成 `/opt/backupx/config.yaml`（含安全默认值）
|
||||
2. 安装二进制到 `/opt/backupx/bin/backupx`，并把 Web 控制台安装到 `/opt/backupx/web`
|
||||
3. 生成 `/etc/backupx/config.yaml`（含安全默认值）
|
||||
4. 注册并启用 `backupx.service` systemd 单元
|
||||
5. （可选）配置 Nginx 反向代理
|
||||
5. 默认不修改 Nginx；只有显式设置 `INSTALL_NGINX=1` 时才安装模板
|
||||
6. 等待 `/api/auth/setup/status` 就绪；启动失败时输出 systemd 诊断并返回非零状态
|
||||
|
||||
## 从源码构建
|
||||
|
||||
依赖：Go ≥ 1.25，Node.js ≥ 20。
|
||||
依赖：Go ≥ 1.25、Node.js 24 LTS、npm 11 或更高版本。
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
|
||||
make build
|
||||
# 或使用国内镜像加速构建 Docker
|
||||
make docker-cn
|
||||
sudo ./deploy/install.sh
|
||||
```
|
||||
|
||||
`make build` 完成后，二进制位于 `server/bin/backupx`，构建好的 Web UI 位于 `web/dist/`。
|
||||
安装脚本会直接使用这两个路径，不需要 Docker 运行时。如果已有配置修改了默认端口，可覆盖就绪检查地址，例如：`sudo HEALTH_URL=http://127.0.0.1:9000/api/auth/setup/status ./deploy/install.sh`。
|
||||
|
||||
自动安装兜底虚拟主机可能接管现有站点，因此 Nginx 模板改为显式启用。请先审核 `deploy/nginx.conf`，确认适合当前主机后再执行 `sudo INSTALL_NGINX=1 ./deploy/install.sh`。
|
||||
|
||||
## 验证安装
|
||||
|
||||
```bash
|
||||
backupx --version # 输出如 v1.6.0
|
||||
/opt/backupx/bin/backupx --version
|
||||
curl -fsS http://127.0.0.1:8340/api/auth/setup/status
|
||||
```
|
||||
|
||||
打开浏览器访问 `http://your-server:8340`，会进入初始化管理员账户页面。
|
||||
打开浏览器访问 `http://your-server:8340`，可在右上角选择 **中文** 或 **English**。全新数据库会显示“系统初始化 / System setup”，在这里创建首个管理员用户名和密码。如果没有出现初始化表单，请先重试上面的状态接口，不要直接尝试登录。
|
||||
|
||||
+1
@@ -57,5 +57,6 @@ description: 部署 BackupX、添加存储目标、创建第一个备份任务
|
||||
## 继续阅读
|
||||
|
||||
- 了解 [备份类型](/docs/features/backup-types) 和 [存储后端](/docs/features/storage-backends)
|
||||
- 上线生产前阅读[安全加固](/docs/operations/security)、[监控与告警](/docs/operations/monitoring)和[升级与恢复](/docs/operations/upgrade-recovery)
|
||||
- 使用 SAP HANA？参考 [SAP HANA 支持](/docs/features/sap-hana)
|
||||
- 管理多台服务器？参考 [多节点集群](/docs/features/multi-node)
|
||||
|
||||
@@ -21,7 +21,7 @@ description: BackupX——自托管服务器备份管理平台概览。
|
||||
```
|
||||
[Web 控制台] ─── JWT ──→ [Master (backupx)]
|
||||
│
|
||||
│ HTTP 长轮询（Token 认证）
|
||||
│ Agent 主动 HTTP 轮询（Token 认证）
|
||||
▼
|
||||
[Agent (backupx agent)]
|
||||
│
|
||||
@@ -35,6 +35,8 @@ description: BackupX——自托管服务器备份管理平台概览。
|
||||
|
||||
- **第一次使用 BackupX？** 先看 [快速开始](/docs/getting-started/quick-start)
|
||||
- **生产部署？** 参考 [部署指南](/docs/deployment/docker)
|
||||
- **规划升级或灾备？** 按[升级与恢复](/docs/operations/upgrade-recovery)执行
|
||||
- **生产运维？** 先阅读[安全加固](/docs/operations/security)与[监控和告警](/docs/operations/monitoring)
|
||||
- **SAP HANA 用户？** 支持 `hdbsql` Runner 和原生 Backint 两种模式 — 详见 [SAP HANA](/docs/features/sap-hana)
|
||||
- **管理多台服务器？** 参考 [多节点集群](/docs/features/multi-node)
|
||||
- **程序化集成？** 参考 [API 参考](/docs/reference/api)
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: 监控与告警
|
||||
description: 健康探针、Prometheus 指标、初始告警规则和运维验证。
|
||||
---
|
||||
|
||||
# 监控与告警
|
||||
|
||||
BackupX 提供低开销健康端点和独立 Prometheus Registry。监控既要覆盖控制面，也要覆盖备份、恢复、验证和复制的实际结果。
|
||||
|
||||
## 探针
|
||||
|
||||
| 端点 | 含义 | 预期响应 |
|
||||
| --- | --- | --- |
|
||||
| `/health` | 存活：HTTP 进程可响应 | HTTP 200，`status: live` |
|
||||
| `/ready` | 就绪：进程可访问 SQLite | 正常为 HTTP 200 与 `status: ready`；数据库故障为 HTTP 503 |
|
||||
| `/api/health` | 带 API 前缀的存活别名 | 与 `/health` 相同 |
|
||||
| `/api/ready` | 带 API 前缀的就绪别名 | 与 `/ready` 相同 |
|
||||
| `/metrics` | Prometheus 指标 | 指标启用时为 HTTP 200 |
|
||||
|
||||
`/health` 用作 liveness，`/ready` 用作 readiness 或负载均衡流量判断。外部存储暂时不可用不应直接触发进程重启，应通过任务和存储目标告警处理。
|
||||
|
||||
~~~bash
|
||||
curl -fsS http://127.0.0.1:8340/health
|
||||
curl -fsS http://127.0.0.1:8340/ready
|
||||
curl -fsS http://127.0.0.1:8340/metrics | head
|
||||
~~~
|
||||
|
||||
这些端点不需要认证，只允许编排器和监控网段访问。
|
||||
|
||||
## Prometheus 抓取
|
||||
|
||||
~~~yaml
|
||||
scrape_configs:
|
||||
- job_name: backupx
|
||||
scheme: https
|
||||
metrics_path: /metrics
|
||||
static_configs:
|
||||
- targets: [backup.example.com]
|
||||
~~~
|
||||
|
||||
Nginx 终止 TLS 时，应只放行 Prometheus 源地址访问 `/metrics`。内部采集器每 30 秒刷新存储、节点、命令队列和 SLA Gauge。
|
||||
|
||||
## BackupX 指标
|
||||
|
||||
| 指标 | 类型 | 标签 | 用途 |
|
||||
| --- | --- | --- | --- |
|
||||
| `backupx_app_info` | gauge | `version` | 当前版本元数据 |
|
||||
| `backupx_task_run_total` | counter | `status`、`task_type` | 备份结果 |
|
||||
| `backupx_task_run_duration_seconds` | histogram | `task_type` | 备份耗时分布 |
|
||||
| `backupx_task_bytes_total` | counter | `task_type` | 备份产出字节数 |
|
||||
| `backupx_task_running` | gauge | 无 | 当前备份并发 |
|
||||
| `backupx_storage_used_bytes` | gauge | `target_name`、`target_type` | 按目标记录的使用量 |
|
||||
| `backupx_node_online` | gauge | `node_name`、`role` | 节点在线状态，1 或 0 |
|
||||
| `backupx_agent_command_queue_depth` | gauge | `node_name`、`role` | 待处理与已派发命令 |
|
||||
| `backupx_agent_command_running` | gauge | `node_name`、`role` | Agent 长任务数 |
|
||||
| `backupx_agent_command_timeout_total` | gauge | `node_name`、`role` | 超时命令数快照 |
|
||||
| `backupx_verify_run_total` | counter | `status` | 验证结果 |
|
||||
| `backupx_restore_run_total` | counter | `status` | 恢复结果 |
|
||||
| `backupx_replication_run_total` | counter | `status` | 复制结果 |
|
||||
| `backupx_sla_breach_tasks` | gauge | 无 | 超出已配置 RPO 的启用任务数 |
|
||||
|
||||
同一端点还注册了标准 Go Runtime 与进程指标。
|
||||
|
||||
## 初始告警规则
|
||||
|
||||
应根据各环境计划与 RPO 调整窗口和阈值：
|
||||
|
||||
~~~yaml
|
||||
groups:
|
||||
- name: backupx
|
||||
rules:
|
||||
- alert: BackupXTargetDown
|
||||
expr: up{job="backupx"} == 0
|
||||
for: 2m
|
||||
labels:
|
||||
severity: critical
|
||||
annotations:
|
||||
summary: BackupX metrics endpoint is unreachable
|
||||
|
||||
- alert: BackupXNotReady
|
||||
expr: probe_success{job="backupx-ready"} == 0
|
||||
for: 2m
|
||||
labels:
|
||||
severity: critical
|
||||
annotations:
|
||||
summary: BackupX readiness check is failing
|
||||
|
||||
- alert: BackupXBackupFailure
|
||||
expr: sum(increase(backupx_task_run_total{status="failed"}[15m])) > 0
|
||||
labels:
|
||||
severity: warning
|
||||
annotations:
|
||||
summary: A BackupX backup failed
|
||||
|
||||
- alert: BackupXSLABreach
|
||||
expr: backupx_sla_breach_tasks > 0
|
||||
for: 5m
|
||||
labels:
|
||||
severity: critical
|
||||
annotations:
|
||||
summary: One or more backup tasks are outside RPO
|
||||
|
||||
- alert: BackupXAgentOffline
|
||||
expr: backupx_node_online{role="agent"} == 0
|
||||
for: 2m
|
||||
labels:
|
||||
severity: warning
|
||||
annotations:
|
||||
summary: BackupX Agent is offline
|
||||
|
||||
- alert: BackupXAgentQueueBacklog
|
||||
expr: backupx_agent_command_queue_depth > 20
|
||||
for: 10m
|
||||
labels:
|
||||
severity: warning
|
||||
annotations:
|
||||
summary: BackupX Agent command queue is growing
|
||||
~~~
|
||||
|
||||
`BackupXNotReady` 示例假定存在名为 `backupx-ready` 的 Blackbox 探针任务。未部署 Blackbox Exporter 时，应改用负载均衡或编排器的 readiness 信号。
|
||||
|
||||
## 运维仪表盘
|
||||
|
||||
建议同时展示：
|
||||
|
||||
- 按任务类型统计成功率与失败率。
|
||||
- P50、P95、最大执行时长及其与备份窗口的关系。
|
||||
- 产出字节数与预期数据变化率。
|
||||
- 当前任务数与 `backup.max_concurrent`。
|
||||
- 离线 Agent、队列深度、运行命令和超时数变化。
|
||||
- 存储增长、提供商剩余容量和保留策略清理。
|
||||
- SLA 违约数及关键任务最近成功备份时间。
|
||||
- 验证、恢复和复制成功率。
|
||||
|
||||
Prometheus 存储使用量来自 BackupX 记录元数据，不一定等同于提供商计费容量，应另行监控提供商配额和文件系统剩余空间。
|
||||
|
||||
## 部署后验证
|
||||
|
||||
安装、升级、代理变更或恢复后：
|
||||
|
||||
1. 分别从本机和公开代理检查存活与就绪。
|
||||
2. 确认 Prometheus 只看到一个活动 Master，并带有预期版本标签。
|
||||
3. 确认所有预期 Agent 的 `backupx_node_online == 1`。
|
||||
4. 执行小型备份并确认成功 Counter 增长。
|
||||
5. 执行验证或隔离恢复并确认对应 Counter 增长。
|
||||
6. 触发测试通知并验证告警投递链路。
|
||||
|
||||
探针或指标异常时继续参考[故障排查](./troubleshooting)。
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: 安全加固
|
||||
description: 生产环境的网络暴露、角色、密钥、Agent、容器和公开端点控制。
|
||||
---
|
||||
|
||||
# 安全加固
|
||||
|
||||
BackupX 统一接触源文件、数据库凭据、存储凭据和恢复目标，应把 Master 作为安全敏感的控制面部署，而不是普通的公开 Web 应用。
|
||||
|
||||
## 推荐暴露模型
|
||||
|
||||
| 组件 | 入站访问 | 出站访问 |
|
||||
| --- | --- | --- |
|
||||
| Master | 管理员与 Agent 的 HTTPS；指标只对监控网段开放 | 存储提供商、通知端点、版本检查 |
|
||||
| Agent | 不需要入站端口 | Master HTTPS 与分配的存储目标 |
|
||||
| SQLite 数据 | 仅本地或块存储文件系统 | 无 |
|
||||
|
||||
反向代理与 Docker 位于同一主机时，把 Docker 绑定到 `127.0.0.1`：
|
||||
|
||||
~~~dotenv
|
||||
BACKUPX_BIND_ADDRESS=127.0.0.1
|
||||
~~~
|
||||
|
||||
裸机仅允许本机代理访问时，把 `server.host` 设置为回环地址；其他情况应使用主机或网络防火墙限制 TCP 8340。
|
||||
|
||||
## TLS 与反向代理
|
||||
|
||||
- 所有不可信网络段都使用 HTTPS。
|
||||
- `server.external_url` 设置为 Agent 可访问的稳定地址。
|
||||
- `server.trusted_proxies` 只加入准确代理 IP 或网段，禁止信任 `0.0.0.0/0`。
|
||||
- Agent 使用最终 HTTPS 地址，不要依赖重定向。
|
||||
- 私有 PKI 应向 Agent 下发 PEM CA，并配置 `caCertFile` 或 `--ca-cert`。
|
||||
- `--insecure-tls` 只用于临时测试。
|
||||
- Master 中转上传和 SSE 日志需要关闭 Nginx 请求与响应缓冲。
|
||||
|
||||
必须经过 SSH 堡垒机时，将隧道绑定到回环地址，严格校验主机密钥，使用专用账号与密钥，并让 Agent 服务依赖隧道。详见[多节点集群](../features/multi-node)。
|
||||
|
||||
## 角色与 API Key
|
||||
|
||||
| 角色 | 预期权限 |
|
||||
| --- | --- |
|
||||
| `viewer` | 读取仪表盘、任务、记录、报表与审计数据；不能浏览节点文件系统或修改资源 |
|
||||
| `operator` | viewer 权限，加上任务、存储、通知、备份、恢复、验证和文件浏览操作 |
|
||||
| `admin` | operator 权限，加上用户、API Key、设置、节点生命周期、安装令牌和 Token 轮换 |
|
||||
|
||||
为每位人员创建独立命名账号，不共享初始管理员。特权账号应启用双因素认证或通行密钥，并定期检查可信设备与恢复码。
|
||||
|
||||
用户 JWT 是无状态令牌。登出只会删除客户端副本，无法撤销已被复制到其他位置的 Token。应把 `security.jwt_expire` 设置为可接受的最短时长，保护 Bearer Token；必须使全部会话失效时轮换 JWT 密钥。
|
||||
|
||||
API Key 与交互式用户使用相同的角色检查。明文只在创建时显示一次，数据库只保存带密钥哈希。自动化应使用最低必要角色、设置有效期、保存在密钥管理系统，并及时撤销闲置 Key。监控不应使用管理员 Key。
|
||||
|
||||
## 保护控制面密钥
|
||||
|
||||
- `/etc/backupx/config.yaml` 应为 `root:backupx`、模式 `0640`，数据目录只允许服务账号访问。
|
||||
- `jwt_secret` 和 `encryption_key` 留空时，自动生成值会写入 SQLite 数据库，因此必须备份完整数据目录。
|
||||
- 加密密钥丢失或替换后，已有存储凭据将无法解密。
|
||||
- 数据库包含密码哈希、配置密钥、Agent Token、API Key 哈希、可信设备状态和审计数据。快照应加密并设置保留策略。
|
||||
- 不要把 Token 写入 shell 历史、Issue、截图或支持包。
|
||||
|
||||
每个节点有独立的长期 Agent Token。systemd 安装器把它保存到 `/etc/backupx-agent/agent.token`，模式为 `0600`。人员变更、主机入侵或意外泄露后应轮换 Token，在重叠窗口内更新文件并重启 Agent。
|
||||
|
||||
一次性安装 URL 有效期为 5 分钟至 24 小时，使用后立即失效。URL 与内嵌备用命令都应视为秘密，因为生成的安装材料会配置长期节点 Token。
|
||||
|
||||
## 容器与主机权限
|
||||
|
||||
正式 Compose 会删除全部能力，只添加旧数据卷所有权迁移与切换到非特权 `backupx` 用户所需的能力。保留 `no-new-privileges`，不要挂载 Docker Socket。
|
||||
|
||||
备份源应只读挂载；只有恢复目标确实需要时才添加独立、范围明确的可写挂载。需要高权限文件访问时，优先部署宿主机 Agent，而不是让 Master 容器以 root 运行。
|
||||
|
||||
systemd Master 以 `backupx` 运行。Agent 通常以 root 运行，因为它可能备份或恢复属于任意系统用户的文件。应限制任务创建权限并保护 root 所有的 Agent 配置。
|
||||
|
||||
## 公开端点
|
||||
|
||||
以下端点有意不使用 BackupX JWT 或 API Key 认证：
|
||||
|
||||
- `/health` 与 `/api/health`
|
||||
- `/ready` 与 `/api/ready`
|
||||
- `/metrics`
|
||||
- 一次性 `/install/:token` 与 `/api/install/:token` 路由
|
||||
|
||||
健康响应包含状态、版本、运行时间、时间戳和就绪检查；就绪失败时可能带有数据库错误细节。`/metrics` 还会包含节点与存储目标标签。应在防火墙或反向代理只允许监控网段访问探针与指标，不要缓存或记录完整安装令牌 URL。
|
||||
|
||||
## 备份加密边界
|
||||
|
||||
加密备份任务只能在 Master 执行，因为远程 Agent 不会收到 Master 加密密钥。不要通过复制 Master 密钥到 Agent 来绕过这个边界。Agent 任务需要加密时，应根据要求使用传输层加密和存储提供商的服务端加密。
|
||||
|
||||
每次调整密钥管理后都应验证加密备份恢复。缺少密钥的备份不可恢复。
|
||||
|
||||
## 审计与事故响应
|
||||
|
||||
BackupX 会记录特权操作，并可把签名审计事件转发到外部 Webhook。高价值审计记录应发送到独立管理的 SIEM 或追加写存储，避免受损 Master 删除唯一副本。
|
||||
|
||||
怀疑入侵时：
|
||||
|
||||
1. 隔离 Master，但不要删除证据。
|
||||
2. 撤销泄露的 API Key，轮换受影响的 Agent Token 与存储凭据。
|
||||
3. JWT 与加密密钥只能按计划迁移；直接更换加密密钥会使已保存加密配置失效。
|
||||
4. 审查用户、可信设备、API Key、节点、设置、恢复与删除事件。
|
||||
5. 无法确认完整性时，从已知可信的控制面快照恢复。
|
||||
|
||||
应用与数据库配套恢复流程见[升级与恢复](./upgrade-recovery)。
|
||||
+160
@@ -0,0 +1,160 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: 故障排查
|
||||
description: Master、反向代理、Agent、备份工具和 SQLite 的安全诊断顺序。
|
||||
---
|
||||
|
||||
# 故障排查
|
||||
|
||||
从最先失败的边界开始并保留证据。在确认原因前，不要删除数据库、重建卷、一次性轮换所有 Token 或重新安装。
|
||||
|
||||
## 快速分流
|
||||
|
||||
| 现象 | 首项检查 | 可能边界 |
|
||||
| --- | --- | --- |
|
||||
| Web 控制台不可用 | 本机 `/health`，再检查代理 `/health` | 进程、监听、防火墙、代理或静态文件 |
|
||||
| `/health` 正常但 `/ready` 为 503 | 服务日志、数据库路径、磁盘、权限 | SQLite 或数据文件系统 |
|
||||
| 登录循环或客户端 IP 错误 | 转发头与 `trusted_proxies` | 反向代理信任 |
|
||||
| 实时日志停止更新 | Nginx 响应缓冲与超时 | SSE 代理路径 |
|
||||
| 中转上传停滞或代理磁盘占满 | 请求缓冲与 Body 上限 | 反向代理 |
|
||||
| Agent 离线 | Agent 日志、最终 Master URL、代理、DNS、CA | Agent 到 Master 网络 |
|
||||
| 备份启动后失败 | 记录日志、源路径、数据库原生工具 | Runner 或权限 |
|
||||
| 恢复失败 | 记录日志、目标挂载与写权限 | 存储读取或目标权限 |
|
||||
|
||||
## 无敏感信息的状态采集
|
||||
|
||||
Docker Master：
|
||||
|
||||
~~~bash
|
||||
docker compose ps
|
||||
docker compose logs --tail=200 backupx
|
||||
curl -i http://127.0.0.1:8340/health
|
||||
curl -i http://127.0.0.1:8340/ready
|
||||
~~~
|
||||
|
||||
裸机 Master：
|
||||
|
||||
~~~bash
|
||||
sudo systemctl status backupx --no-pager
|
||||
sudo journalctl -u backupx -n 200 --no-pager
|
||||
sudo ss -lntp | grep 8340
|
||||
curl -i http://127.0.0.1:8340/health
|
||||
curl -i http://127.0.0.1:8340/ready
|
||||
~~~
|
||||
|
||||
systemd Agent：
|
||||
|
||||
~~~bash
|
||||
sudo systemctl status backupx-agent --no-pager
|
||||
sudo journalctl -u backupx-agent -n 200 --no-pager
|
||||
sudo systemctl status backupx-agent-tunnel --no-pager
|
||||
~~~
|
||||
|
||||
最后一条只适用于堡垒机部署。共享输出前，移除 Authorization 头、API Key、Agent Token、安装 URL、数据库密码、存储凭据、代理凭据以及会暴露敏感拓扑的私有路径。
|
||||
|
||||
## Web 控制台或首次初始化
|
||||
|
||||
检查无需认证的初始化端点：
|
||||
|
||||
~~~bash
|
||||
curl -fsS http://127.0.0.1:8340/api/auth/setup/status
|
||||
~~~
|
||||
|
||||
API 正常但浏览器出现空白页或 JSON 时：
|
||||
|
||||
- 确认 Release 包含前端文件。
|
||||
- 裸机检查 `/opt/backupx/web` 可读；显式配置时确认 `server.web_root` 正确。
|
||||
- Docker 确认运行正式镜像，且自定义挂载未覆盖镜像内前端目录。
|
||||
- Nginx 静态模式确认 `root /opt/backupx/web` 和 SPA fallback 存在。
|
||||
- 版本变更后清理旧 Service Worker 或浏览器缓存。
|
||||
|
||||
认证失败先校验系统时间，再排查 TOTP 或通行密钥。确认浏览器 Origin 与最终 HTTPS 主机一致，并从审计日志检查限流、禁用用户或已撤销可信设备。
|
||||
|
||||
## 反向代理
|
||||
|
||||
验证并重载 Nginx：
|
||||
|
||||
~~~bash
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
curl -i https://backup.example.com/health
|
||||
curl -i https://backup.example.com/ready
|
||||
~~~
|
||||
|
||||
常见修正：
|
||||
|
||||
- HTTP 413：API 路由设置 `client_max_body_size 0`。
|
||||
- 中转上传占满代理临时目录：设置 `proxy_request_buffering off`。
|
||||
- SSE 日志批量到达或断开：设置 `proxy_buffering off`、关闭代理缓存并增加读取超时。
|
||||
- 一键安装返回 HTML：代理 `/api/` 并保留旧版 `/install/` 路由。
|
||||
- Agent 收到重定向：配置最终 HTTPS Master URL，不使用 HTTP 地址。
|
||||
- 审计中所有用户都是代理 IP：只把真实代理 IP 或网段加入 `server.trusted_proxies`。
|
||||
|
||||
以完整的 [Nginx 配置](../deployment/nginx)作为对照基线。
|
||||
|
||||
## Agent 离线
|
||||
|
||||
Agent 通常每 15 秒发送一次心跳，45 秒无心跳后会被标记离线。
|
||||
|
||||
1. 确认 Agent 与可选隧道服务运行。
|
||||
2. 确认 Master URL 没有重定向，且可在 Agent 主机解析。
|
||||
3. 检查显式 `proxyUrl`；DNS 必须经过 SSH 动态隧道时使用 `socks5h://`。
|
||||
4. 确认私有 CA 路径存在且可读，不要长期改为跳过 TLS。
|
||||
5. 检查到 Master 与分配存储后端的出站防火墙。
|
||||
6. 确认 `/etc/backupx-agent/agent.token` 存在且模式为 `0600`。
|
||||
7. Token 已轮换时，在重叠窗口内写入新值并重启 Agent。
|
||||
|
||||
不要把 Token 直接放进会保存到 shell 历史的诊断命令。Agent 日志中的 401 通常表示 Token 缺失、重叠期已结束或节点不匹配；连续连接错误通常来自 URL、DNS、代理、隧道、防火墙或 CA。
|
||||
|
||||
## 备份任务失败
|
||||
|
||||
修改任务前先打开备份记录并阅读完整日志。
|
||||
|
||||
- 文件任务路径在所选 Master 或 Agent 上解析，确认路径存在于该主机命名空间。
|
||||
- Docker 只能看到已挂载路径，备份源通常应只读。
|
||||
- MySQL 要求执行主机 `PATH` 中存在 `mysqldump`。
|
||||
- PostgreSQL 要求执行主机 `PATH` 中存在 `pg_dump`。
|
||||
- SAP HANA Runner 模式要求对应客户端工具与环境。
|
||||
- 确认服务账号可读源路径并可写临时目录。
|
||||
- 从控制台测试所选存储目标。
|
||||
- 远端存储应检查 DNS、出站策略、提供商配额、时钟偏差和代理。
|
||||
|
||||
配置多个目标时，应查看逐目标结果，不要假定所有副本都失败。修复失败目标时保留已经成功的远端产物。
|
||||
|
||||
## 恢复、下载或验证失败
|
||||
|
||||
- 确认远端产物仍存在且存储凭据可读取。
|
||||
- 确认执行恢复的主机挂载了目标路径。
|
||||
- 使用独立可写恢复目录，不要把所有备份源都改为可写。
|
||||
- 检查目标与 Agent 临时目录剩余空间。
|
||||
- 加密备份必须能取得原 Master 加密密钥。
|
||||
- CDC 仓库的 Manifest、索引和共享 Pack 必须一起保留，单独 Manifest 不是完整备份。
|
||||
|
||||
诊断时优先恢复到隔离目录，不要反复覆盖生产源。
|
||||
|
||||
## SQLite 与就绪故障
|
||||
|
||||
`/health` 为 200 而 `/ready` 为 503 时：
|
||||
|
||||
1. 从服务日志读取准确数据库错误。
|
||||
2. 检查磁盘空间、inode、路径所有权和挂载状态。
|
||||
3. 确认数据目录只被一个 Master 进程或容器使用。
|
||||
4. SQLite 应位于本地或块存储文件系统，不放在共享多写或不可靠网络文件系统。
|
||||
5. 检查外部备份或防病毒进程是否长期占用文件。
|
||||
|
||||
BackupX 使用 5 秒 SQLite busy timeout，但这不会把 SQLite 变成集群数据库。不能通过启动另一个 Master 解决锁冲突。文件级复制应先停服，再复制整个数据目录。
|
||||
|
||||
## 升级问题材料
|
||||
|
||||
提交 Issue 时提供：
|
||||
|
||||
- BackupX 版本、安装方式、操作系统和架构。
|
||||
- 故障影响 Master、Agent、代理、存储目标还是单个任务。
|
||||
- 覆盖首次失败时段的脱敏日志。
|
||||
- `/health` 与 `/ready` 的 HTTP 状态和响应体。
|
||||
- 最小复现步骤，以及是否始于升级或配置变更。
|
||||
- 脱敏后的相关代理配置。
|
||||
|
||||
不要向公开 Issue 附加 `backupx.db`、`.env`、完整配置、Agent Token 文件、API Key、安装命令或存储凭据。
|
||||
|
||||
涉及完整性或回滚时，应停止破坏性变更并参考[升级与恢复](./upgrade-recovery)。
|
||||
+153
@@ -0,0 +1,153 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: 升级与恢复
|
||||
description: 备份控制面、安全升级、配套回滚并恢复故障 Master。
|
||||
---
|
||||
|
||||
# 升级与恢复
|
||||
|
||||
备份产物与 BackupX 控制面属于两个不同的恢复域。对象存储中可能仍保留全部归档，但 Master 数据库丢失会同时丢失用户、加密后的存储凭据、计划、记录、节点 Token 和审计历史，因此两者都必须保护。
|
||||
|
||||
## 必须遵守的规则
|
||||
|
||||
1. 同一个数据目录或 SQLite 数据库只能运行一个活动 Master。
|
||||
2. 停止 Master 后快照完整数据目录与配置，或使用覆盖整个存储卷的原子快照。
|
||||
3. 旧应用版本必须与其升级前数据快照配套保留。启动时会执行数据库迁移，只切回旧二进制或旧镜像不是安全回滚。
|
||||
4. 控制面快照应保存到 Master 主机之外，并定期验证恢复。
|
||||
5. 停止 Master 前，先等待正在运行的备份、恢复、验证和复制任务结束。
|
||||
|
||||
| 部署方式 | 持久化控制面数据 | 配置与版本状态 |
|
||||
| --- | --- | --- |
|
||||
| Docker | `backupx-data` 卷中的 `/app/data` | Compose 文件、受保护的 `.env`、固定的镜像标签或摘要 |
|
||||
| 裸机 | `/opt/backupx/data` | `/etc/backupx`、`/opt/backupx/bin`、`/opt/backupx/web`、systemd unit |
|
||||
|
||||
配置未显式提供 JWT 与加密密钥时，自动生成的值保存在 SQLite 数据库中。所有控制面快照都应按敏感数据管理。
|
||||
|
||||
## 变更前检查
|
||||
|
||||
升级、迁移主机或修改安全密钥前：
|
||||
|
||||
- 记录当前 BackupX 版本以及准确的镜像摘要或 Release 校验和。
|
||||
- 确认 `/ready` 返回 HTTP 200，并检查近期失败记录。
|
||||
- 等待正在运行的备份、恢复、验证和复制结束。
|
||||
- 测试至少一个存储目标，并确认 Agent 在线。
|
||||
- 创建完整控制面快照，校验后复制到异机。
|
||||
- 可额外导出任务定义供人工审阅。任务导出不包含数据库密码与存储凭据，不能代替数据库快照。
|
||||
- 开始前确定回滚条件与维护窗口截止时间。
|
||||
|
||||
## 快照 Docker 部署
|
||||
|
||||
下面的示例无需直接访问 Docker 卷目录，即可生成一致的文件级副本：
|
||||
|
||||
~~~bash
|
||||
snapshot="backupx-control-plane-$(date -u +%Y%m%dT%H%M%SZ)"
|
||||
install -d -m 0700 "$snapshot"
|
||||
|
||||
docker compose stop backupx
|
||||
docker cp backupx:/app/data "$snapshot/data"
|
||||
cp docker-compose.yml "$snapshot/"
|
||||
if [ -f .env ]; then cp .env "$snapshot/"; fi
|
||||
docker compose start backupx
|
||||
|
||||
tar -czf "$snapshot.tar.gz" "$snapshot"
|
||||
sha256sum "$snapshot.tar.gz" > "$snapshot.tar.gz.sha256"
|
||||
curl -fsS http://127.0.0.1:8340/ready
|
||||
~~~
|
||||
|
||||
复制失败时，应先恢复已停止的服务，再继续排查。归档中的 `.env` 和数据库可能包含凭据，必须限制访问。如果块存储或云平台快照能原子覆盖整个卷，也可以直接使用。
|
||||
|
||||
## 快照裸机部署
|
||||
|
||||
~~~bash
|
||||
snapshot="/var/backups/backupx/backupx-control-plane-$(date -u +%Y%m%dT%H%M%SZ).tar.gz"
|
||||
sudo install -d -m 0700 /var/backups/backupx
|
||||
|
||||
sudo systemctl stop backupx
|
||||
sudo tar --acls --xattrs -C / -czf "$snapshot" \
|
||||
etc/backupx \
|
||||
etc/systemd/system/backupx.service \
|
||||
opt/backupx/bin \
|
||||
opt/backupx/web \
|
||||
opt/backupx/data
|
||||
sudo systemctl start backupx
|
||||
|
||||
sudo sha256sum "$snapshot" | sudo tee "$snapshot.sha256"
|
||||
curl -fsS http://127.0.0.1:8340/ready
|
||||
~~~
|
||||
|
||||
把归档及校验和复制到受保护的异机存储。不要在服务运行时只复制 `backupx.db`。
|
||||
|
||||
## 升级 Docker
|
||||
|
||||
1. 在 `BACKUPX_IMAGE` 中使用 Release 标签或不可变摘要，受控生产升级不要使用 `latest`。
|
||||
2. 创建并验证升级前快照。
|
||||
3. 拉取并重建服务：
|
||||
|
||||
~~~bash
|
||||
docker compose pull backupx
|
||||
docker compose up -d backupx
|
||||
docker compose ps
|
||||
docker compose logs --tail=100 backupx
|
||||
curl -fsS http://127.0.0.1:8340/ready
|
||||
~~~
|
||||
|
||||
4. 登录后测试存储目标，确认 Agent 心跳，并执行一个小型备份以及一次恢复或验证演练。
|
||||
5. 观察窗口结束前保留旧镜像引用与快照。
|
||||
|
||||
Master 完成后再小批量升级 Agent。除非变更目标就是网络配置，否则不要改动节点专用代理、私有 CA、Token 文件和堡垒机参数。
|
||||
|
||||
## 升级裸机
|
||||
|
||||
下载目标 Release 与校验和，完成校验后解压。安装器会保留已有的 `/etc/backupx/config.yaml`，替换二进制、前端文件和 systemd unit，并重启服务。
|
||||
|
||||
~~~bash
|
||||
sha256sum -c backupx-vX.Y.Z-linux-amd64.tar.gz.sha256
|
||||
tar xzf backupx-vX.Y.Z-linux-amd64.tar.gz
|
||||
cd backupx-vX.Y.Z-linux-amd64
|
||||
sudo ./install.sh
|
||||
|
||||
sudo systemctl status backupx --no-pager
|
||||
curl -fsS http://127.0.0.1:8340/ready
|
||||
~~~
|
||||
|
||||
运行安装器前必须先创建停服快照。升级后的业务检查与 Docker 相同。
|
||||
|
||||
## 回滚
|
||||
|
||||
回滚是配套操作：必须同时恢复旧应用版本和紧邻升级前创建的数据快照。
|
||||
|
||||
Docker 应保留故障卷用于分析，把快照恢复到新的空卷，Compose 同时指向该卷与旧镜像标签，然后只启动一个 Master。裸机应停止服务并保留故障现场，从同一归档恢复旧配置、二进制、前端、数据目录和 unit，重新加载 systemd 后启动。
|
||||
|
||||
回滚后检查：
|
||||
|
||||
~~~bash
|
||||
curl -fsS http://127.0.0.1:8340/health
|
||||
curl -fsS http://127.0.0.1:8340/ready
|
||||
~~~
|
||||
|
||||
随后验证登录、存储访问、计划、Agent 心跳、一次备份和一次非破坏性恢复演练。在事故原因明确前不要删除故障现场。
|
||||
|
||||
## 恢复丢失的 Master
|
||||
|
||||
1. 按快照记录准备同架构主机与完全相同的应用版本。
|
||||
2. 替代主机先与生产流量隔离，并确保旧 Master 无法再次启动。
|
||||
3. 按原权限恢复配置和完整数据目录。
|
||||
4. 只启动一个 Master，在本机检查 `/ready`。
|
||||
5. 本地验证完成后再切换稳定 DNS 名称或虚拟 IP。
|
||||
6. 检查用户、存储目标、任务、记录、通知和审计历史。
|
||||
7. 数据库内 Token 与节点一致时，已有 Agent 会自动重连；可能泄露的 Token 必须调查并轮换。
|
||||
8. 执行小型备份及恢复或验证演练后再结束事故处理。
|
||||
|
||||
恢复控制面不会重新生成外部备份产物，它们仍位于原存储目标。反过来，任务 JSON 导出只适合辅助重建计划，不包含密钥、存储定义和部分节点绑定，不能作为完整灾备。
|
||||
|
||||
## 验证恢复计划
|
||||
|
||||
至少每季度把近期快照恢复到隔离网络，启动快照记录的 BackupX 版本并验证：
|
||||
|
||||
- 不接触生产 Master 时，`/ready` 能恢复正常。
|
||||
- 管理员可登录，已加密的存储配置可读取。
|
||||
- 任务、节点、记录和审计数量合理。
|
||||
- 可以测试一个存储目标而不写入生产数据。
|
||||
- 选定备份可验证，或可恢复到隔离目录。
|
||||
|
||||
记录恢复耗时和最新可恢复快照时间，这两个实测值才是控制面的真实 RTO 与 RPO。
|
||||
@@ -1,135 +1,268 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: API 参考
|
||||
description: REST API 端点 — 统一以 /api 为前缀，使用 JWT Bearer 认证。
|
||||
description: BackupX REST 端点、认证方式、角色边界、流式响应和公开探针。
|
||||
---
|
||||
|
||||
# API 参考
|
||||
|
||||
所有端点都以 `/api` 为前缀，使用 JWT Bearer 令牌认证（通过 `POST /api/auth/login` 获取）。Agent 专用端点使用 `X-Agent-Token` 头认证。
|
||||
交互式 API 以 `/api` 为根路径。大多数端点接受用户 JWT 或 API Key；Agent 协议使用节点专用 Token。公开探针和一次性安装器在文末单列。
|
||||
|
||||
## 认证
|
||||
|
||||
| 方法 | 端点 | 说明 |
|
||||
|------|------|------|
|
||||
| `GET` | `/api/auth/setup/status` | 查询是否需要初始化管理员 |
|
||||
| `POST` | `/api/auth/setup` | 初始化首个管理员（仅当系统无任何用户时） |
|
||||
| `POST` | `/api/auth/login` | 登录，返回 JWT |
|
||||
| `POST` | `/api/auth/logout` | 登出（使当前 Token 失效） |
|
||||
| `GET` | `/api/auth/profile` | 当前用户信息 |
|
||||
| `PUT` | `/api/auth/password` | 修改密码 |
|
||||
### 用户 JWT
|
||||
|
||||
通过 `POST /api/auth/login` 获取 JWT，并作为 Bearer Token 发送：
|
||||
|
||||
~~~bash
|
||||
curl -H "Authorization: Bearer $BACKUPX_TOKEN" \
|
||||
https://backup.example.com/api/backup/tasks
|
||||
~~~
|
||||
|
||||
根据账号和系统设置，登录过程还可能要求邮件或短信 OTP、TOTP、恢复码、可信设备 Token 或 WebAuthn。
|
||||
|
||||
### API Key
|
||||
|
||||
管理员可在控制台或通过 `POST /api/api-keys` 创建 API Key。明文 `bax_...` 只返回一次。
|
||||
|
||||
~~~bash
|
||||
curl -H "X-Api-Key: $BACKUPX_API_KEY" \
|
||||
https://backup.example.com/api/dashboard/stats
|
||||
~~~
|
||||
|
||||
也支持 `Authorization: Bearer bax_...`。API Key 带有 `admin`、`operator` 或 `viewer` 角色，可禁用并可设置有效期。
|
||||
|
||||
### Agent Token
|
||||
|
||||
Agent 协议 Handler 从 `X-Agent-Token` 验证节点 Token。它不是用户凭据，不能用于交互式资源 API。
|
||||
|
||||
### 权限标记
|
||||
|
||||
下表使用这些标记：
|
||||
|
||||
| 标记 | 所需权限 |
|
||||
| --- | --- |
|
||||
| 公开 | 不需要 JWT 或 API Key；安装路由仍要求一次性 Token |
|
||||
| 已认证 | 任意 `viewer`、`operator` 或 `admin` |
|
||||
| 运维 | `operator` 或 `admin` |
|
||||
| 管理员 | 仅 `admin` |
|
||||
| Agent | 有效的节点专用 Agent Token |
|
||||
|
||||
viewer 可使用读取端点，但不能浏览节点文件系统；operator 可以执行和修改备份资源；admin 还可管理用户、API Key、设置、节点、安装令牌和节点 Token 轮换。角色不满足时返回 HTTP 403。
|
||||
|
||||
## 认证与账号安全
|
||||
|
||||
| 方法 | 端点 | 权限 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/auth/setup/status` | 公开 | 查询是否需要创建首个管理员 |
|
||||
| `POST` | `/api/auth/setup` | 公开 | 系统无用户时创建首个管理员 |
|
||||
| `POST` | `/api/auth/login` | 公开 | 完成密码或 MFA 登录并获取 JWT |
|
||||
| `POST` | `/api/auth/otp/send` | 公开 | 发送已配置的登录 OTP |
|
||||
| `POST` | `/api/auth/webauthn/login/options` | 公开 | 开始通行密钥登录 |
|
||||
| `POST` | `/api/auth/logout` | 已认证 | 确认登出；客户端必须丢弃无状态 JWT |
|
||||
| `GET` | `/api/auth/profile` | 已认证 | 读取当前账号 |
|
||||
| `PUT` | `/api/auth/password` | 已认证 | 修改当前账号密码 |
|
||||
| `POST` | `/api/auth/2fa/setup` | 已认证 | 准备 TOTP 注册 |
|
||||
| `POST` | `/api/auth/2fa/enable` | 已认证 | 验证后启用 TOTP |
|
||||
| `POST` | `/api/auth/2fa/recovery-codes` | 已认证 | 重新生成恢复码 |
|
||||
| `DELETE` | `/api/auth/2fa` | 已认证 | 停用 TOTP |
|
||||
| `PUT` | `/api/auth/otp/config` | 已认证 | 更新 OTP 登录配置 |
|
||||
| `POST` | `/api/auth/webauthn/register/options` | 已认证 | 开始注册通行密钥 |
|
||||
| `POST` | `/api/auth/webauthn/register/finish` | 已认证 | 完成通行密钥注册 |
|
||||
| `GET` | `/api/auth/webauthn/credentials` | 已认证 | 列出通行密钥 |
|
||||
| `DELETE` | `/api/auth/webauthn/credentials/:id` | 已认证 | 删除通行密钥 |
|
||||
| `GET` | `/api/auth/trusted-devices` | 已认证 | 列出可信设备 |
|
||||
| `DELETE` | `/api/auth/trusted-devices/:id` | 已认证 | 撤销可信设备 |
|
||||
|
||||
账号安全端点应使用交互式 JWT，不应使用自动化 API Key。
|
||||
|
||||
## 系统与存储目标
|
||||
|
||||
| 方法 | 端点 | 权限 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/system/info` | 已认证 | 版本与系统信息 |
|
||||
| `GET` | `/api/system/update-check` | 已认证 | 检查可用 Release |
|
||||
| `GET` | `/api/storage-targets` | 已认证 | 存储目标列表 |
|
||||
| `POST` | `/api/storage-targets` | 运维 | 创建目标 |
|
||||
| `POST` | `/api/storage-targets/test` | 运维 | 测试未保存配置 |
|
||||
| `GET` | `/api/storage-targets/rclone/backends` | 已认证 | 可用 rclone 后端 |
|
||||
| `POST` | `/api/storage-targets/google-drive/auth-url` | 运维 | 开始 Google Drive 授权 |
|
||||
| `POST` | `/api/storage-targets/google-drive/complete` | 运维 | 完成 Google Drive 授权 |
|
||||
| `GET` | `/api/storage-targets/google-drive/callback` | 已认证 | 处理 OAuth 回调 |
|
||||
| `GET` | `/api/storage-targets/:id` | 已认证 | 读取目标 |
|
||||
| `PUT` | `/api/storage-targets/:id` | 运维 | 更新目标 |
|
||||
| `DELETE` | `/api/storage-targets/:id` | 运维 | 删除目标 |
|
||||
| `PUT` | `/api/storage-targets/:id/star` | 运维 | 切换收藏 |
|
||||
| `POST` | `/api/storage-targets/:id/test` | 运维 | 测试已保存目标 |
|
||||
| `GET` | `/api/storage-targets/:id/usage` | 已认证 | 读取已记录用量 |
|
||||
| `GET` | `/api/storage-targets/:id/google-drive/profile` | 已认证 | 读取已连接 Google Drive 账号 |
|
||||
|
||||
## 备份任务
|
||||
|
||||
| 方法 | 端点 | 说明 |
|
||||
|------|------|------|
|
||||
| `GET` | `/api/backup/tasks` | 列表 |
|
||||
| `POST` | `/api/backup/tasks` | 创建 |
|
||||
| `GET` | `/api/backup/tasks/:id` | 详情 |
|
||||
| `PUT` | `/api/backup/tasks/:id` | 更新 |
|
||||
| `DELETE` | `/api/backup/tasks/:id` | 删除 |
|
||||
| `PUT` | `/api/backup/tasks/:id/toggle` | 启用 / 禁用 |
|
||||
| `POST` | `/api/backup/tasks/:id/run` | 手动触发一次执行 |
|
||||
| 方法 | 端点 | 权限 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/backup/tasks` | 已认证 | 任务列表 |
|
||||
| `GET` | `/api/backup/tasks/tags` | 已认证 | 任务标签 |
|
||||
| `GET` | `/api/backup/tasks/export` | 已认证 | 下载全部任务 JSON，或用 `?ids=1,2` 选择任务 |
|
||||
| `POST` | `/api/backup/tasks/import` | 运维 | 导入任务，最大 1 MiB |
|
||||
| `POST` | `/api/backup/tasks/batch/toggle` | 运维 | 批量启用或停用 |
|
||||
| `POST` | `/api/backup/tasks/batch/delete` | 运维 | 批量删除 |
|
||||
| `POST` | `/api/backup/tasks/batch/run` | 运维 | 批量执行 |
|
||||
| `GET` | `/api/backup/tasks/:id` | 已认证 | 读取任务 |
|
||||
| `POST` | `/api/backup/tasks` | 运维 | 创建任务 |
|
||||
| `PUT` | `/api/backup/tasks/:id` | 运维 | 更新任务 |
|
||||
| `DELETE` | `/api/backup/tasks/:id` | 运维 | 删除任务 |
|
||||
| `PUT` | `/api/backup/tasks/:id/toggle` | 运维 | 启用或停用 |
|
||||
| `POST` | `/api/backup/tasks/:id/run` | 运维 | 触发备份 |
|
||||
| `POST` | `/api/backup/tasks/:id/verify` | 运维 | 从任务触发验证 |
|
||||
|
||||
## 备份记录
|
||||
任务导出会主动排除数据库密码与存储凭据，适合迁移和审阅，不是完整控制面备份。
|
||||
|
||||
| 方法 | 端点 | 说明 |
|
||||
|------|------|------|
|
||||
| `GET` | `/api/backup/records` | 列表（支持筛选） |
|
||||
| `GET` | `/api/backup/records/:id` | 记录详情 |
|
||||
| `GET` | `/api/backup/records/:id/logs/stream` | 实时日志（SSE） |
|
||||
| `GET` | `/api/backup/records/:id/download` | 下载备份产物 |
|
||||
| `POST` | `/api/backup/records/:id/restore` | 恢复到原始源 |
|
||||
| `DELETE` | `/api/backup/records/:id` | 删除记录 |
|
||||
| `POST` | `/api/backup/records/batch-delete` | 批量删除 |
|
||||
## 备份与恢复记录
|
||||
|
||||
## 存储目标
|
||||
| 方法 | 端点 | 权限 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/backup/records` | 已认证 | 列出并筛选备份记录 |
|
||||
| `POST` | `/api/backup/records/batch-delete` | 运维 | 批量删除记录 |
|
||||
| `GET` | `/api/backup/records/:id` | 已认证 | 读取备份记录 |
|
||||
| `GET` | `/api/backup/records/:id/logs/stream` | 已认证 | 通过 SSE 输出日志 |
|
||||
| `GET` | `/api/backup/records/:id/download` | 已认证 | 下载产物 |
|
||||
| `GET` | `/api/backup/records/:id/contents` | 已认证 | 浏览支持类型的产物内容 |
|
||||
| `POST` | `/api/backup/records/:id/restore` | 运维 | 启动恢复 |
|
||||
| `POST` | `/api/backup/records/:id/replicate` | 运维 | 复制已有产物 |
|
||||
| `POST` | `/api/backup/records/:id/verify` | 运维 | 验证已有产物 |
|
||||
| `PUT` | `/api/backup/records/:id/lock` | 运维 | 设置保留锁 |
|
||||
| `DELETE` | `/api/backup/records/:id` | 运维 | 删除记录及受管产物 |
|
||||
| `GET` | `/api/restore/records` | 已认证 | 恢复记录列表 |
|
||||
| `GET` | `/api/restore/records/:id` | 已认证 | 恢复记录详情 |
|
||||
| `GET` | `/api/restore/records/:id/logs/stream` | 已认证 | 恢复日志 SSE |
|
||||
| `GET` | `/api/replication/records` | 已认证 | 复制记录列表 |
|
||||
| `GET` | `/api/replication/records/:id` | 已认证 | 复制记录详情 |
|
||||
| `GET` | `/api/verify/records` | 已认证 | 验证记录列表 |
|
||||
| `GET` | `/api/verify/records/:id` | 已认证 | 验证记录详情 |
|
||||
| `GET` | `/api/verify/records/:id/logs/stream` | 已认证 | 验证日志 SSE |
|
||||
|
||||
| 方法 | 端点 | 说明 |
|
||||
|------|------|------|
|
||||
| `GET` | `/api/storage-targets` | 列表 |
|
||||
| `POST` | `/api/storage-targets` | 创建 |
|
||||
| `GET` | `/api/storage-targets/:id` | 详情 |
|
||||
| `PUT` | `/api/storage-targets/:id` | 更新 |
|
||||
| `DELETE` | `/api/storage-targets/:id` | 删除 |
|
||||
| `POST` | `/api/storage-targets/test` | 用待审核配置测试连接 |
|
||||
| `POST` | `/api/storage-targets/:id/test` | 重测已保存的目标 |
|
||||
| `PUT` | `/api/storage-targets/:id/star` | 切换收藏状态 |
|
||||
| `GET` | `/api/storage-targets/:id/usage` | 查询远端存储用量（支持此能力的后端） |
|
||||
| `GET` | `/api/storage-targets/rclone/backends` | 列出可用的 rclone 后端 |
|
||||
| `POST` | `/api/storage-targets/google-drive/auth-url` | 启动 Google Drive OAuth |
|
||||
| `POST` | `/api/storage-targets/google-drive/complete` | 完成 OAuth 流程 |
|
||||
## 模板、报表与仪表盘
|
||||
|
||||
## 节点（集群）
|
||||
| 方法 | 端点 | 权限 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/task-templates` | 已认证 | 任务模板列表 |
|
||||
| `GET` | `/api/task-templates/:id` | 已认证 | 读取任务模板 |
|
||||
| `POST` | `/api/task-templates` | 运维 | 创建模板 |
|
||||
| `PUT` | `/api/task-templates/:id` | 运维 | 更新模板 |
|
||||
| `DELETE` | `/api/task-templates/:id` | 运维 | 删除模板 |
|
||||
| `POST` | `/api/task-templates/:id/apply` | 运维 | 从模板创建任务 |
|
||||
| `GET` | `/api/reports/compliance` | 已认证 | 合规证据 |
|
||||
| `GET` | `/api/reports/compliance/export` | 已认证 | 导出合规 CSV |
|
||||
| `GET` | `/api/dashboard/stats` | 已认证 | 汇总统计 |
|
||||
| `GET` | `/api/dashboard/timeline` | 已认证 | 最近活动 |
|
||||
| `GET` | `/api/dashboard/sla` | 已认证 | RPO 与 SLA 状态 |
|
||||
| `GET` | `/api/dashboard/cluster` | 已认证 | 集群概览 |
|
||||
| `GET` | `/api/dashboard/breakdown` | 已认证 | 任务与记录分布 |
|
||||
| `GET` | `/api/dashboard/node-performance` | 已认证 | 节点性能 |
|
||||
|
||||
| 方法 | 端点 | 说明 |
|
||||
|------|------|------|
|
||||
| `GET` | `/api/nodes` | 节点列表 |
|
||||
| `POST` | `/api/nodes` | 创建节点并返回 Token |
|
||||
| `GET` | `/api/nodes/:id` | 节点详情 |
|
||||
| `PUT` | `/api/nodes/:id` | 重命名 |
|
||||
| `DELETE` | `/api/nodes/:id` | 删除（有关联任务时会被拒绝） |
|
||||
| `GET` | `/api/nodes/:id/fs/list` | 浏览目录（远程节点走 Agent 异步 RPC） |
|
||||
## 通知、设置与管理
|
||||
|
||||
## Agent 协议（X-Agent-Token）
|
||||
| 方法 | 端点 | 权限 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/notifications` | 已认证 | 通知渠道列表 |
|
||||
| `GET` | `/api/notifications/:id` | 已认证 | 读取渠道 |
|
||||
| `POST` | `/api/notifications` | 运维 | 创建渠道 |
|
||||
| `PUT` | `/api/notifications/:id` | 运维 | 更新渠道 |
|
||||
| `DELETE` | `/api/notifications/:id` | 运维 | 删除渠道 |
|
||||
| `POST` | `/api/notifications/test` | 运维 | 测试未保存配置 |
|
||||
| `POST` | `/api/notifications/:id/test` | 运维 | 测试已保存渠道 |
|
||||
| `GET` | `/api/settings` | 已认证 | 读取系统设置 |
|
||||
| `PUT` | `/api/settings` | 管理员 | 更新系统设置 |
|
||||
| `GET` | `/api/users` | 管理员 | 用户列表 |
|
||||
| `POST` | `/api/users` | 管理员 | 创建用户 |
|
||||
| `PUT` | `/api/users/:id` | 管理员 | 更新用户 |
|
||||
| `POST` | `/api/users/:id/2fa/reset` | 管理员 | 重置用户第二因素 |
|
||||
| `DELETE` | `/api/users/:id` | 管理员 | 删除用户 |
|
||||
| `GET` | `/api/api-keys` | 管理员 | API Key 列表，不返回明文 |
|
||||
| `POST` | `/api/api-keys` | 管理员 | 创建 API Key，明文仅返回一次 |
|
||||
| `PUT` | `/api/api-keys/:id/toggle` | 管理员 | 启用或停用 API Key |
|
||||
| `DELETE` | `/api/api-keys/:id` | 管理员 | 撤销 API Key |
|
||||
|
||||
Agent CLI 专用端点，通过 `X-Agent-Token` 头认证而非 JWT。
|
||||
## 审计、事件、搜索与发现
|
||||
|
||||
| 方法 | 端点 | 说明 |
|
||||
|------|------|------|
|
||||
| `POST` | `/api/agent/heartbeat` | 上报心跳（返回节点 ID） |
|
||||
| `POST` | `/api/agent/commands/poll` | 领取一条待执行命令 |
|
||||
| `POST` | `/api/agent/commands/:id/result` | 上报命令结果 |
|
||||
| `GET` | `/api/agent/tasks/:id` | 拉取任务规格（含解密后的存储配置） |
|
||||
| `POST` | `/api/agent/records/:id` | 追加日志 / 更新记录状态 |
|
||||
| 方法 | 端点 | 权限 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/audit-logs` | 已认证 | 列出并筛选审计记录 |
|
||||
| `GET` | `/api/audit-logs/export` | 已认证 | 导出审计记录 |
|
||||
| `GET` | `/api/events/stream` | 已认证 | 通过 SSE 输出实时应用事件 |
|
||||
| `GET` | `/api/search` | 已认证 | 搜索支持的资源 |
|
||||
| `POST` | `/api/database/discover` | 已认证 | 按提供的连接信息发现数据库 |
|
||||
|
||||
## 通知
|
||||
## 节点
|
||||
|
||||
| 方法 | 端点 | 说明 |
|
||||
|------|------|------|
|
||||
| `GET` | `/api/notifications` | 列表 |
|
||||
| `POST` | `/api/notifications` | 创建 |
|
||||
| `GET` | `/api/notifications/:id` | 详情 |
|
||||
| `PUT` | `/api/notifications/:id` | 更新 |
|
||||
| `DELETE` | `/api/notifications/:id` | 删除 |
|
||||
| `POST` | `/api/notifications/test` | 用待审核配置测试 |
|
||||
| `POST` | `/api/notifications/:id/test` | 重测已保存的通知器 |
|
||||
| 方法 | 端点 | 权限 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/nodes` | 已认证 | 节点列表 |
|
||||
| `GET` | `/api/nodes/:id` | 已认证 | 节点详情 |
|
||||
| `GET` | `/api/nodes/:id/fs/list` | 运维 | 浏览所选节点文件系统 |
|
||||
| `POST` | `/api/nodes` | 管理员 | 创建节点 |
|
||||
| `POST` | `/api/nodes/batch` | 管理员 | 批量创建最多 50 个节点 |
|
||||
| `PUT` | `/api/nodes/:id` | 管理员 | 更新节点 |
|
||||
| `DELETE` | `/api/nodes/:id` | 管理员 | 删除未被引用的节点 |
|
||||
| `POST` | `/api/nodes/:id/install-tokens` | 管理员 | 创建一次性安装器 |
|
||||
| `GET` | `/api/nodes/:id/install-script-preview` | 管理员 | 预览安装材料 |
|
||||
| `POST` | `/api/nodes/:id/rotate-token` | 管理员 | 轮换长期节点 Token |
|
||||
|
||||
## 仪表盘
|
||||
## Agent 协议
|
||||
|
||||
| 方法 | 端点 | 说明 |
|
||||
|------|------|------|
|
||||
| `GET` | `/api/dashboard/stats` | 概览统计 |
|
||||
| `GET` | `/api/dashboard/timeline` | 最近活动时间线 |
|
||||
这些路由供 `backupx agent` 使用，Handler 内部通过节点 Token 认证。
|
||||
|
||||
## 审计 / 系统 / 设置
|
||||
| 方法 | 端点 | 权限 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `POST` | `/api/agent/heartbeat` | Agent | 上报心跳与节点状态 |
|
||||
| `POST` | `/api/agent/commands/poll` | Agent | 领取待执行命令 |
|
||||
| `POST` | `/api/agent/commands/:id/result` | Agent | 上报命令结果 |
|
||||
| `GET` | `/api/agent/tasks/:id` | Agent | 获取可执行任务规格 |
|
||||
| `POST` | `/api/agent/records/:id` | Agent | 追加日志或更新备份状态 |
|
||||
| `PUT` | `/api/agent/records/:id/artifacts/:targetId` | Agent | 向 Master 流式中转产物 |
|
||||
| `GET` | `/api/agent/restores/:id/spec` | Agent | 获取恢复指令 |
|
||||
| `GET` | `/api/agent/restores/:id/artifact` | Agent | 流式读取恢复产物 |
|
||||
| `POST` | `/api/agent/restores/:id` | Agent | 更新恢复状态 |
|
||||
| `GET` | `/api/v1/agent/self` | Agent | 安装时校验节点身份 |
|
||||
|
||||
| 方法 | 端点 | 说明 |
|
||||
|------|------|------|
|
||||
| `GET` | `/api/audit-logs` | 审计日志 |
|
||||
| `GET` | `/api/system/info` | 系统信息 |
|
||||
| `GET` | `/api/system/update-check` | 检查新版本 |
|
||||
| `GET` | `/api/settings` | 系统级设置 |
|
||||
| `PUT` | `/api/settings` | 更新系统设置 |
|
||||
## 公开运维与安装路由
|
||||
|
||||
## 响应结构
|
||||
| 方法 | 端点 | 权限 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/health` | 公开 | 存活检查 |
|
||||
| `GET` | `/api/health` | 公开 | 带 API 前缀的存活别名 |
|
||||
| `GET` | `/ready` | 公开 | SQLite 就绪检查 |
|
||||
| `GET` | `/api/ready` | 公开 | 带 API 前缀的就绪别名 |
|
||||
| `GET` | `/metrics` | 公开 | Prometheus 指标 |
|
||||
| `GET` | `/install/:token` | 公开 | 消费一次性 Agent 安装令牌 |
|
||||
| `GET` | `/api/install/:token` | 公开 | 带 API 前缀的安装路由 |
|
||||
| `GET` | `/install/:token/compose.yml` | 公开 | 生成 Docker Agent Compose |
|
||||
| `GET` | `/api/install/:token/compose.yml` | 公开 | 带 API 前缀的 Docker Compose 路由 |
|
||||
|
||||
成功响应统一为：
|
||||
探针与指标应只对监控网段开放。安装 Token 是单次、限时秘密，不能写入公开日志。
|
||||
|
||||
```json
|
||||
## 响应格式
|
||||
|
||||
大多数 JSON 成功响应为：
|
||||
|
||||
~~~json
|
||||
{
|
||||
"code": "OK",
|
||||
"message": "",
|
||||
"data": { /* 实际数据 */ }
|
||||
"message": "success",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
错误返回 HTTP 4xx/5xx，并带：
|
||||
错误使用 HTTP 4xx 或 5xx，并带稳定业务码：
|
||||
|
||||
```json
|
||||
~~~json
|
||||
{
|
||||
"code": "BACKUP_TASK_NOT_FOUND",
|
||||
"message": "备份任务不存在",
|
||||
"data": null
|
||||
"message": "备份任务不存在"
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
客户端应按 HTTP 状态和 `code` 分支，不要依赖本地化的 `message`。
|
||||
|
||||
产物下载、任务 JSON 导出、审计或合规导出、安装器响应和 `/metrics` 使用各自原生 Content-Type，不使用 JSON Envelope。日志与事件流使用 `text/event-stream`，反向代理必须关闭响应缓冲。
|
||||
|
||||
@@ -17,26 +17,33 @@ backupx --version
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--config <path>` | 配置文件路径（默认 `./config.yaml`） |
|
||||
| `--config <path>` | 显式配置文件路径；省略时使用下方查找路径 |
|
||||
| `--version` | 打印版本后退出 |
|
||||
|
||||
未提供 `--config` 时，服务端依次查找 `./config.yaml`、`./server/config.yaml` 和 `/etc/backupx/config.yaml`。`BACKUPX_*` 环境变量会覆盖对应服务端配置项，详见[配置参考](../deployment/configuration)。
|
||||
|
||||
## `backupx agent`
|
||||
|
||||
以 Agent 模式运行，连接到 Master。详见 [多节点集群](../features/multi-node)。
|
||||
|
||||
```bash
|
||||
backupx agent --master http://master:8340 --token <token>
|
||||
backupx agent --master https://backup.example.com --token-file /etc/backupx-agent/agent.token
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--master <url>` | Master URL |
|
||||
| `--token <token>` | Agent 认证令牌 |
|
||||
| `--config <path>` | YAML 配置文件（优先级高于环境变量） |
|
||||
| `--temp-dir <path>` | 本地临时目录（默认 `/tmp/backupx-agent`） |
|
||||
| `--token-file <path>` | 从文件读取 Agent Token，服务与容器部署推荐使用 |
|
||||
| `--config <path>` | 加载 Agent YAML；提供后不再加载基于环境变量的 Agent 配置 |
|
||||
| `--temp-dir <path>` | 本地临时目录（默认 `/var/lib/backupx-agent/tmp`） |
|
||||
| `--proxy-url <url>` | 显式 HTTP(S) 或 SOCKS5(H) 代理 |
|
||||
| `--ca-cert <path>` | 用于校验 Master 的 PEM CA 证书 |
|
||||
| `--insecure-tls` | 跳过 TLS 校验（仅测试用） |
|
||||
|
||||
环境变量：`BACKUPX_AGENT_MASTER`、`BACKUPX_AGENT_TOKEN`、`BACKUPX_AGENT_HEARTBEAT`、`BACKUPX_AGENT_POLL`、`BACKUPX_AGENT_TEMP_DIR`、`BACKUPX_AGENT_INSECURE_TLS`。
|
||||
Agent 配置优先级为显式 CLI 参数高于 YAML。未提供 `--config` 时，配置从 `BACKUPX_AGENT_MASTER`、`BACKUPX_AGENT_TOKEN`、`BACKUPX_AGENT_TOKEN_FILE`、`BACKUPX_AGENT_HEARTBEAT`、`BACKUPX_AGENT_POLL`、`BACKUPX_AGENT_TEMP_DIR`、`BACKUPX_AGENT_PROXY_URL`、`BACKUPX_AGENT_CA_CERT_FILE` 和 `BACKUPX_AGENT_INSECURE_TLS` 加载。未设置显式代理时，Agent 还会遵循 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`。
|
||||
|
||||
`--token` 优先于 `--token-file`。长期 Token 应放在仅 root 可读的文件中，不要进入命令历史。私有 CA 与 `--insecure-tls` 不能同时启用。
|
||||
|
||||
## `backupx backint`
|
||||
|
||||
@@ -54,6 +61,8 @@ backupx backint -f <function> -i <input> -o <output> -p <params>
|
||||
| `-p <path>` | 参数文件 |
|
||||
| `-u / -c / -l / -v` | 接收但忽略（兼容 SAP 约定） |
|
||||
|
||||
`-p` 参数文件必须定义 `STORAGE_TYPE`，并提供 `STORAGE_CONFIG_JSON` 或 `STORAGE_CONFIG`。可选项包括 `PARALLEL_FACTOR`、`COMPRESS`、`LOG_FILE`、`CATALOG_DB` 和 `KEY_PREFIX`。
|
||||
|
||||
## `backupx reset-password`
|
||||
|
||||
直接在 SQLite 中重置管理员密码，无需重启服务。
|
||||
@@ -67,3 +76,5 @@ backupx reset-password --username admin --password 'newpass123' [--config /path/
|
||||
| `--username` | 目标用户名（默认 `admin`） |
|
||||
| `--password` | 新密码（最少 8 字符，必填） |
|
||||
| `--config` | 配置文件路径（用于定位数据库文件） |
|
||||
|
||||
该命令应在可访问配置中 SQLite 路径的 Master 主机执行。不要把新密码直接写入长期保留的 shell 历史。
|
||||
|
||||
@@ -1,23 +1,14 @@
|
||||
{
|
||||
"link.title.Docs": {"message": "文档"},
|
||||
"link.title.Features": {"message": "功能"},
|
||||
"link.title.More": {"message": "更多"},
|
||||
"link.title.Community": {"message": "社区"},
|
||||
"link.title.Sponsors": {"message": "赞助商"},
|
||||
"link.title.Documentation": {"message": "文档"},
|
||||
"link.title.Operations": {"message": "运维"},
|
||||
"link.title.Project": {"message": "项目"},
|
||||
"link.item.label.Introduction": {"message": "简介"},
|
||||
"link.item.label.Quick Start": {"message": "快速开始"},
|
||||
"link.item.label.Installation": {"message": "安装"},
|
||||
"link.item.label.SAP HANA": {"message": "SAP HANA"},
|
||||
"link.item.label.Multi-Node Cluster": {"message": "多节点集群"},
|
||||
"link.item.label.API Reference": {"message": "API 参考"},
|
||||
"link.item.label.Configuration": {"message": "配置"},
|
||||
"link.item.label.Monitoring": {"message": "监控"},
|
||||
"link.item.label.Security": {"message": "安全"},
|
||||
"link.item.label.Troubleshooting": {"message": "故障排查"},
|
||||
"link.item.label.GitHub": {"message": "GitHub"},
|
||||
"link.item.label.Releases": {"message": "Releases"},
|
||||
"link.item.label.Docker Hub": {"message": "Docker Hub"},
|
||||
"link.item.label.Issues": {"message": "Issues"},
|
||||
"link.item.label.Contributors": {"message": "贡献者"},
|
||||
"link.item.label.Pull Requests": {"message": "Pull Requests"},
|
||||
"link.item.label.Sponsor": {"message": "赞助"},
|
||||
"link.item.label.Sponsor BackupX": {"message": "赞助 BackupX"},
|
||||
"link.item.label.Partnership": {"message": "合作伙伴"},
|
||||
"link.item.label.Sponsor tiers": {"message": "赞助层级"}
|
||||
"link.item.label.Releases": {"message": "发布版本"},
|
||||
"link.item.label.Community": {"message": "社区"}
|
||||
}
|
||||
|
||||
@@ -1,22 +1,8 @@
|
||||
{
|
||||
"item.label.Docs": {
|
||||
"message": "文档",
|
||||
"description": "Navbar item: Docs"
|
||||
},
|
||||
"item.label.Downloads": {
|
||||
"message": "下载",
|
||||
"description": "Navbar item: Downloads"
|
||||
},
|
||||
"item.label.Community": {
|
||||
"message": "社区",
|
||||
"description": "Navbar item: Community"
|
||||
},
|
||||
"item.label.Sponsors": {
|
||||
"message": "赞助商",
|
||||
"description": "Navbar item: Sponsors"
|
||||
},
|
||||
"item.label.GitHub": {
|
||||
"message": "GitHub",
|
||||
"description": "Navbar item: GitHub"
|
||||
}
|
||||
"item.label.Docs": {"message": "文档"},
|
||||
"item.label.Deployment": {"message": "部署"},
|
||||
"item.label.Operations": {"message": "运维"},
|
||||
"item.label.API": {"message": "API"},
|
||||
"item.label.Community": {"message": "社区"},
|
||||
"item.label.GitHub": {"message": "GitHub"}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user