GithubBackup/BackupX
1
0
Fork 0
mirror of https://github.com/Awuqing/BackupX.git synced 2026-09-05 15:37:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 完善部署与运维文档 (#107)

Browse Source 
新增中英文升级恢复、安全加固、监控告警与故障排查手册，校正安装部署、CLI 与 API 参考，并修复安全密钥环境变量注入及其回归测试。
This commit is contained in:
Wu Qing
2026-08-09 13:51:38 +08:00
committed by GitHub
parent 5827074334
commit bdd16dafa8
35 changed files with 1844 additions and 317 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
+1
View File
@@ -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": "开发"}
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/deployment/bare-metal.md
+5 -2
View File
@@ -68,8 +68,9 @@ 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
@@ -100,6 +101,8 @@ curl -fsS http://127.0.0.1:8340/api/auth/setup/status
生产环境应通过 HTTPS 暴露 BackupX，或在防火墙限制 `8340` 端口。安装器不会自动修改防火墙。
替换版本前，应在服务停止时同时快照 `/etc/backupx`、`/opt/backupx/data`、已安装二进制和前端文件。请按[升级与恢复](../operations/upgrade-recovery)中的版本化流程操作；让旧版本二进制直接读取已由新版本迁移的数据库并不是安全回滚。
## 密码重置
忘记管理员密码时：
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/deployment/configuration.md
+14 -3
View File
@@ -1,7 +1,7 @@
---
sidebar_position: 4
title: 配置参考
description: server.yaml 所有配置项及对应的环境变量。
description: config.yaml 全部服务端配置项及对应的环境变量。
---
# 配置参考
@@ -32,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 # 保留天数
```
## 密钥生成
@@ -53,11 +56,17 @@ 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
@@ -70,7 +79,7 @@ server:
BackupX 会用这个地址渲染一键 Agent 安装脚本和 docker-compose 片段。该地址必须能被所有 Agent 主机访问。只有在 `X-Forwarded-Proto` / `X-Forwarded-Host` 可靠且正好指向 Agent 可访问地址时，才建议留空。
代理或 SSH 堡垒机场景可在安装向导中为单个 Agent 设置运行地址。公开安装链接仍使用 `server.external_url`，生成的 Agent 配置则使用该覆盖地址。
代理或 SSH 堡垒机场景可在安装向导中为单个 Agent 设置覆盖地址。目标侧的一次性安装链接与生成的 Agent 运行配置都会使用这个地址，浏览器仍使用正常的公开地址。
## 可信反向代理
@@ -84,3 +93,5 @@ server:
```
不要配置 `0.0.0.0/0`，因为登录限流、安装令牌限流和审计日志都依赖客户端地址。BackupX 直接暴露且不应信任任何转发头时可设置空列表。
修改安全密钥或数据库路径前，应同时备份完整数据目录和配置文件。经过验证的快照与回滚流程见[升级与恢复](../operations/upgrade-recovery)。
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/deployment/docker.md
+3 -1
View File
@@ -85,7 +85,7 @@ environment:
镜像内部端口固定为 `8340`，只通过 `BACKUPX_PORT` 修改宿主机发布端口。
## 升级与回退准备
## 升级前提
```bash
docker compose pull
@@ -94,3 +94,5 @@ docker compose ps
```
等待状态变为 `healthy` 后再切换流量或移除旧部署。升级前应停止 Master 后做文件级复制，或对整个 `backupx-data` 卷创建原子快照。同一个数据卷必须只运行一个活动 Master；SQLite 不支持多个 Master 容器共享 `/app/data`。
生产环境应使用发布标签或镜像摘要而不是 `latest`，并保留与旧版本匹配的升级前数据快照。完整的升级、回滚和灾难恢复流程见[升级与恢复](../operations/upgrade-recovery)。
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/deployment/nginx.md
+22 -1
View File
@@ -29,6 +29,7 @@ server {
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;
@@ -36,9 +37,27 @@ server {
# 实时日志使用 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; }
}
```
@@ -46,6 +65,8 @@ server {
如果 Nginx 运行在另一台主机或另一个容器，只把该代理的 IP 或网段加入 `server.trusted_proxies`，不要配置 `0.0.0.0/0`。登录限流、安装令牌限流和审计日志都依赖可信的客户端地址。
`/health`、`/ready` 和 `/metrics` 不需要 BackupX 认证。应只放行探针与 Prometheus 来源网段，或把这些 location 放在内部监听端口，避免直接暴露到互联网。
## certbot 配置 HTTPS
```bash
@@ -56,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` 只用于短期测试。
:::
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/installation.md
+11 -24
View File
@@ -10,38 +10,25 @@ 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)。
## 预编译包（裸机）
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/quick-start.md
+1
View File
@@ -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)
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/intro.md
+2
View File
@@ -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)
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/operations/monitoring.md
+149
View File
@@ -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)。
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/operations/security.md
+102
View File
@@ -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)。
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/operations/troubleshooting.md
+160
View File
@@ -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)。
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/operations/upgrade-recovery.md
+153
View File
@@ -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。
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/api.md
+229 -96
View File
@@ -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`，反向代理必须关闭响应缓冲。
docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/cli.md
+13 -5
View File
@@ -17,15 +17,17 @@ 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
```
| 参数 | 说明 |
@@ -33,13 +35,15 @@ backupx agent --master http://master:8340 --token <token>
| `--master <url>` | Master URL |
| `--token <token>` | Agent 认证令牌 |
| `--token-file <path>` | 从文件读取 Agent Token，服务与容器部署推荐使用 |
| `--config <path>` | YAML 配置文件（优先级高于环境变量） |
| `--temp-dir <path>` | 本地临时目录（默认 `/tmp/backupx-agent`） |
| `--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_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`。
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`
@@ -57,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 中重置管理员密码，无需重启服务。
@@ -70,3 +76,5 @@ backupx reset-password --username admin --password 'newpass123' [--config /path/
| `--username` | 目标用户名（默认 `admin`） |
| `--password` | 新密码（最少 8 字符，必填） |
| `--config` | 配置文件路径（用于定位数据库文件） |
该命令应在可访问配置中 SQLite 路径的 Master 主机执行。不要把新密码直接写入长期保留的 shell 历史。