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

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

docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/api.md

@@ -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

@@ -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 历史。