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

新增中英文升级恢复、安全加固、监控告警与故障排查手册，校正安装部署、CLI 与 API 参考，并修复安全密钥环境变量注入及其回归测试。
2026-09-04 23:16:41 +08:00 · 2026-08-09 13:51:38 +08:00
parent 5827074334
commit bdd16dafa8
35 changed files with 1844 additions and 317 deletions
@@ -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)中的版本化流程操作；让旧版本二进制直接读取已由新版本迁移的数据库并不是安全回滚。
+
 ## 密码重置

 忘记管理员密码时：
@@ -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)。
@@ -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)。
@@ -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` 只用于短期测试。
 :::