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

新增中英文升级恢复、安全加固、监控告警与故障排查手册，校正安装部署、CLI 与 API 参考，并修复安全密钥环境变量注入及其回归测试。

docs-site/docs/deployment/bare-metal.md

@@ -68,8 +68,9 @@ The installed unit:
 
 ```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 @@ Open `http://your-server:8340`, switch to English if desired, and create the fir
 
 For production, expose BackupX through HTTPS or restrict port `8340` at the firewall. The installer does not make firewall changes.
 
+Before replacing a release, snapshot `/etc/backupx`, `/opt/backupx/data`, the installed binary, and web assets while the service is stopped. Follow the versioned procedure in [Upgrade and Recovery](../operations/upgrade-recovery); running an older binary against a database already migrated by a newer release is not a safe rollback.
+
 ## Password reset
 
 If the admin password is lost:

docs-site/docs/deployment/configuration.md

@@ -1,7 +1,7 @@
 ---
 sidebar_position: 4
 title: Configuration Reference
-description: All server.yaml configuration keys with defaults and matching environment variables.
+description: All config.yaml server keys with defaults and matching environment variables.
 ---
 
 # Configuration Reference
@@ -32,12 +32,15 @@ security:
 backup:
   temp_dir: "/tmp/backupx"    # BACKUPX_BACKUP_TEMP_DIR
   max_concurrent: 2           # BACKUPX_BACKUP_MAX_CONCURRENT
-  retries: 3                  # Per-upload rclone low-level retries
+  retries: 10                 # Per-upload rclone low-level retries
   bandwidth_limit: ""         # e.g. "10M" to cap transfers at 10 MB/s
 
 log:
   level: "info"               # debug | info | warn | error
   file: "./data/backupx.log"
+  max_size: 100               # MB per log file
+  max_backups: 3              # rotated files retained
+  max_age: 30                 # retention in days
 ```
 
 ## Secret generation
@@ -53,11 +56,17 @@ The environment wins when both file and env are set. All dot-paths become unders
 | `server.port` | `BACKUPX_SERVER_PORT` |
 | `server.external_url` | `BACKUPX_SERVER_EXTERNAL_URL` |
 | `server.trusted_proxies` | `BACKUPX_SERVER_TRUSTED_PROXIES` (comma-separated for env) |
+| `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 external URL
 
@@ -70,7 +79,7 @@ server:
 
 This value is used when BackupX renders one-click Agent install scripts and docker-compose snippets. It must be reachable from every Agent host. Leave it empty only when `X-Forwarded-Proto` / `X-Forwarded-Host` are reliable and point to the same URL that Agents can access.
 
-The install wizard can set an Agent-specific runtime URL for a proxy or SSH-bastion node. The public install link continues to use `server.external_url`, while the generated Agent config uses that override.
+The install wizard can set an Agent-specific URL for a proxy or SSH-bastion node. That override is used by both the target-side one-time install URL and the generated Agent runtime configuration, while the browser continues to use the normal public address.
 
 ## Trusted reverse proxies
 
@@ -84,3 +93,5 @@ server:
 ```
 
 Do not configure `0.0.0.0/0`: client addresses feed authentication throttling, install-token throttling, and audit records. Set an empty list when BackupX is exposed directly and should trust no forwarded headers.
+
+Back up the complete data directory and configuration before changing security keys or database paths. See [Upgrade and Recovery](../operations/upgrade-recovery) for a tested snapshot and rollback sequence.

docs-site/docs/deployment/docker.md

@@ -85,7 +85,7 @@ environment:
 
 The image's internal port is fixed at `8340`; change only the published host port with `BACKUPX_PORT`.
 
-## Upgrade and rollback preparation
+## Upgrade prerequisites
 
 ```bash
 docker compose pull
@@ -94,3 +94,5 @@ docker compose ps
 ```
 
 Wait for `healthy` before switching traffic or removing an old deployment. Before upgrades, stop the Master for a file-level copy or take an atomic snapshot of the entire `backupx-data` volume. Keep exactly one active Master for a data volume; SQLite does not support multiple Master containers sharing `/app/data`.
+
+Use a release tag or digest instead of `latest`, and keep the matching pre-upgrade data snapshot. The complete upgrade, rollback, and disaster-recovery procedure is in [Upgrade and Recovery](../operations/upgrade-recovery).

docs-site/docs/deployment/nginx.md

@@ -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 "";
 
         # Large uploads (restore flow)
         client_max_body_size 0;
@@ -36,9 +37,28 @@ server {
 
         # Live log stream uses SSE — buffering must be off
         proxy_buffering off;
+        proxy_cache off;
         proxy_read_timeout 3600s;
         proxy_send_timeout 3600s;
     }
+
+    # Compatibility route for installers generated by older releases.
+    # Current installers use /api/install/ through the API block above.
+    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;
+    }
+
+    # Keep probes and metrics out of the 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 +66,8 @@ server {
 
 If Nginx runs on another host or in another container, add only that proxy IP or subnet to `server.trusted_proxies`. Do not use `0.0.0.0/0`; BackupX uses the trusted client address for login throttling, install-token throttling, and audit records.
 
+`/health`, `/ready`, and `/metrics` do not require BackupX authentication. Allow probe and Prometheus source networks explicitly, or keep these locations on an internal listener instead of exposing them to the Internet.
+
 ## HTTPS with certbot
 
 ```bash
@@ -56,5 +78,5 @@ sudo certbot --nginx -d backup.example.com
 Certbot rewrites the config to listen on 443 with auto-renewal.
 
 :::caution Agent needs a stable URL
-If Master is behind HTTPS, remote Agent deployments must use the public HTTPS URL for `--master`. Self-signed certs require `--insecure-tls` (testing only).
+If Master is behind HTTPS, remote Agent deployments must use the final HTTPS URL for `--master`; redirects are not followed. For a private CA, pre-provision its PEM certificate and use `--ca-cert /path/to/ca.pem`. Reserve `--insecure-tls` for short-lived testing.
 :::