mirror of
https://github.com/Awuqing/BackupX.git
synced 2026-08-15 09:24:02 +08:00
docs: 完善部署与运维文档 (#107)
新增中英文升级恢复、安全加固、监控告警与故障排查手册，校正安装部署、CLI 与 API 参考，并修复安全密钥环境变量注入及其回归测试。
This commit is contained in:
Wu Qing
@@ -1,135 +1,268 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: API Reference
|
||||
description: REST API endpoints — all under /api with JWT Bearer authentication.
|
||||
description: BackupX REST endpoints, authentication methods, role boundaries, streaming responses, and public probes.
|
||||
---
|
||||
|
||||
# API Reference
|
||||
|
||||
All endpoints are prefixed with `/api` and authenticated with a JWT Bearer token, obtained via `POST /api/auth/login`. Agent endpoints use `X-Agent-Token` instead.
|
||||
The interactive API is rooted at `/api`. Most endpoints accept either a user JWT or an API key; Agent protocol endpoints use a node-specific token. Public probes and one-time installers are listed separately.
|
||||
|
||||
## Authentication
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/api/auth/setup/status` | Check whether admin initialization is needed |
|
||||
| `POST` | `/api/auth/setup` | Initialize the first admin (only when no user exists) |
|
||||
| `POST` | `/api/auth/login` | Log in and receive a JWT |
|
||||
| `POST` | `/api/auth/logout` | Log out (invalidate current token) |
|
||||
| `GET` | `/api/auth/profile` | Current user profile |
|
||||
| `PUT` | `/api/auth/password` | Change password |
|
||||
### User JWT
|
||||
|
||||
## Backup Tasks
|
||||
Obtain a JWT through `POST /api/auth/login` and send it as a Bearer token:
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/api/backup/tasks` | List tasks |
|
||||
| `POST` | `/api/backup/tasks` | Create |
|
||||
| `GET` | `/api/backup/tasks/:id` | Detail |
|
||||
| `PUT` | `/api/backup/tasks/:id` | Update |
|
||||
| `DELETE` | `/api/backup/tasks/:id` | Delete |
|
||||
| `PUT` | `/api/backup/tasks/:id/toggle` | Enable / disable |
|
||||
| `POST` | `/api/backup/tasks/:id/run` | Trigger a manual run |
|
||||
~~~bash
|
||||
curl -H "Authorization: Bearer $BACKUPX_TOKEN" \
|
||||
https://backup.example.com/api/backup/tasks
|
||||
~~~
|
||||
|
||||
## Backup Records
|
||||
The login flow may require OTP, TOTP, recovery code, a trusted-device token, or WebAuthn depending on account and system settings.
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/api/backup/records` | List records with filters |
|
||||
| `GET` | `/api/backup/records/:id` | Record detail |
|
||||
| `GET` | `/api/backup/records/:id/logs/stream` | Live logs (SSE) |
|
||||
| `GET` | `/api/backup/records/:id/download` | Download the artifact |
|
||||
| `POST` | `/api/backup/records/:id/restore` | Restore to the original source |
|
||||
| `DELETE` | `/api/backup/records/:id` | Delete a record |
|
||||
| `POST` | `/api/backup/records/batch-delete` | Bulk delete |
|
||||
### API key
|
||||
|
||||
## Storage Targets
|
||||
An administrator creates API keys in the console or through `POST /api/api-keys`. The plaintext `bax_...` value is returned only once.
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/api/storage-targets` | List |
|
||||
| `POST` | `/api/storage-targets` | Create |
|
||||
| `GET` | `/api/storage-targets/:id` | Detail |
|
||||
| `PUT` | `/api/storage-targets/:id` | Update |
|
||||
| `DELETE` | `/api/storage-targets/:id` | Delete |
|
||||
| `POST` | `/api/storage-targets/test` | Test connection with pending config |
|
||||
| `POST` | `/api/storage-targets/:id/test` | Re-test a saved target |
|
||||
| `PUT` | `/api/storage-targets/:id/star` | Toggle favourite |
|
||||
| `GET` | `/api/storage-targets/:id/usage` | Query remote usage (where supported) |
|
||||
| `GET` | `/api/storage-targets/rclone/backends` | List all available rclone backends |
|
||||
| `POST` | `/api/storage-targets/google-drive/auth-url` | Start Google Drive OAuth |
|
||||
| `POST` | `/api/storage-targets/google-drive/complete` | Complete OAuth flow |
|
||||
~~~bash
|
||||
curl -H "X-Api-Key: $BACKUPX_API_KEY" \
|
||||
https://backup.example.com/api/dashboard/stats
|
||||
~~~
|
||||
|
||||
## Nodes (Cluster)
|
||||
`Authorization: Bearer bax_...` is also accepted. API keys carry an `admin`, `operator`, or `viewer` role and can be disabled or given an expiry.
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/api/nodes` | List nodes |
|
||||
| `POST` | `/api/nodes` | Create a node and return its token |
|
||||
| `GET` | `/api/nodes/:id` | Node detail |
|
||||
| `PUT` | `/api/nodes/:id` | Rename |
|
||||
| `DELETE` | `/api/nodes/:id` | Delete (rejected if tasks are still attached) |
|
||||
| `GET` | `/api/nodes/:id/fs/list` | Browse a directory (remote nodes use an async RPC via Agent) |
|
||||
### Agent token
|
||||
|
||||
## Agent Protocol (X-Agent-Token)
|
||||
Agent protocol handlers authenticate the node token supplied in `X-Agent-Token`. This token is not a user credential and must not be used with the interactive resource API.
|
||||
|
||||
Dedicated endpoints for the Agent CLI. Authenticated via the `X-Agent-Token` header instead of JWT.
|
||||
### Access labels
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `POST` | `/api/agent/heartbeat` | Report liveness; returns the node ID |
|
||||
| `POST` | `/api/agent/commands/poll` | Claim one pending command |
|
||||
| `POST` | `/api/agent/commands/:id/result` | Report command result |
|
||||
| `GET` | `/api/agent/tasks/:id` | Fetch task spec with decrypted storage configs |
|
||||
| `POST` | `/api/agent/records/:id` | Append logs / update record status |
|
||||
The tables use these labels:
|
||||
|
||||
## Notifications
|
||||
| Label | Required access |
|
||||
| --- | --- |
|
||||
| Public | No JWT or API key; an install route still requires its one-time token |
|
||||
| Auth | Any authenticated `viewer`, `operator`, or `admin` |
|
||||
| Operator | `operator` or `admin` |
|
||||
| Admin | `admin` only |
|
||||
| Agent | Valid node-specific Agent token |
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/api/notifications` | List |
|
||||
| `POST` | `/api/notifications` | Create |
|
||||
| `GET` | `/api/notifications/:id` | Detail |
|
||||
| `PUT` | `/api/notifications/:id` | Update |
|
||||
| `DELETE` | `/api/notifications/:id` | Delete |
|
||||
| `POST` | `/api/notifications/test` | Test with pending config |
|
||||
| `POST` | `/api/notifications/:id/test` | Re-test a saved notifier |
|
||||
Viewers can use read endpoints except node filesystem browsing. Operators can run and mutate backup resources. Administrators additionally manage users, API keys, settings, nodes, install tokens, and node-token rotation. A rejected role returns HTTP 403.
|
||||
|
||||
## Dashboard
|
||||
## Authentication and account security
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/api/dashboard/stats` | Overview statistics |
|
||||
| `GET` | `/api/dashboard/timeline` | Recent activity timeline |
|
||||
| Method | Endpoint | Access | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/auth/setup/status` | Public | Check whether first-admin setup is required |
|
||||
| `POST` | `/api/auth/setup` | Public | Create the first administrator when no user exists |
|
||||
| `POST` | `/api/auth/login` | Public | Complete password or MFA login and obtain a JWT |
|
||||
| `POST` | `/api/auth/otp/send` | Public | Send a configured login OTP |
|
||||
| `POST` | `/api/auth/webauthn/login/options` | Public | Begin passkey login |
|
||||
| `POST` | `/api/auth/logout` | Auth | Acknowledge logout; the client must discard its stateless JWT |
|
||||
| `GET` | `/api/auth/profile` | Auth | Read the current account |
|
||||
| `PUT` | `/api/auth/password` | Auth | Change the current account password |
|
||||
| `POST` | `/api/auth/2fa/setup` | Auth | Prepare TOTP enrollment |
|
||||
| `POST` | `/api/auth/2fa/enable` | Auth | Enable TOTP after verification |
|
||||
| `POST` | `/api/auth/2fa/recovery-codes` | Auth | Regenerate recovery codes |
|
||||
| `DELETE` | `/api/auth/2fa` | Auth | Disable TOTP |
|
||||
| `PUT` | `/api/auth/otp/config` | Auth | Update OTP login configuration |
|
||||
| `POST` | `/api/auth/webauthn/register/options` | Auth | Begin passkey registration |
|
||||
| `POST` | `/api/auth/webauthn/register/finish` | Auth | Finish passkey registration |
|
||||
| `GET` | `/api/auth/webauthn/credentials` | Auth | List passkeys |
|
||||
| `DELETE` | `/api/auth/webauthn/credentials/:id` | Auth | Delete a passkey |
|
||||
| `GET` | `/api/auth/trusted-devices` | Auth | List trusted devices |
|
||||
| `DELETE` | `/api/auth/trusted-devices/:id` | Auth | Revoke a trusted device |
|
||||
|
||||
## Audit / System / Settings
|
||||
Use an interactive JWT, not an automation API key, for account-security endpoints.
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/api/audit-logs` | Audit log list |
|
||||
| `GET` | `/api/system/info` | System information |
|
||||
| `GET` | `/api/system/update-check` | Check for a newer release |
|
||||
| `GET` | `/api/settings` | System-level settings |
|
||||
| `PUT` | `/api/settings` | Update system settings |
|
||||
## System and storage targets
|
||||
|
||||
## Response Envelope
|
||||
| Method | Endpoint | Access | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/system/info` | Auth | Version and system information |
|
||||
| `GET` | `/api/system/update-check` | Auth | Check available releases |
|
||||
| `GET` | `/api/storage-targets` | Auth | List storage targets |
|
||||
| `POST` | `/api/storage-targets` | Operator | Create a target |
|
||||
| `POST` | `/api/storage-targets/test` | Operator | Test an unsaved configuration |
|
||||
| `GET` | `/api/storage-targets/rclone/backends` | Auth | List available rclone backends |
|
||||
| `POST` | `/api/storage-targets/google-drive/auth-url` | Operator | Start Google Drive authorization |
|
||||
| `POST` | `/api/storage-targets/google-drive/complete` | Operator | Complete Google Drive authorization |
|
||||
| `GET` | `/api/storage-targets/google-drive/callback` | Auth | Handle the OAuth callback |
|
||||
| `GET` | `/api/storage-targets/:id` | Auth | Read a target |
|
||||
| `PUT` | `/api/storage-targets/:id` | Operator | Update a target |
|
||||
| `DELETE` | `/api/storage-targets/:id` | Operator | Delete a target |
|
||||
| `PUT` | `/api/storage-targets/:id/star` | Operator | Toggle favorite state |
|
||||
| `POST` | `/api/storage-targets/:id/test` | Operator | Test a saved target |
|
||||
| `GET` | `/api/storage-targets/:id/usage` | Auth | Read recorded usage |
|
||||
| `GET` | `/api/storage-targets/:id/google-drive/profile` | Auth | Read the connected Google Drive profile |
|
||||
|
||||
All successful responses follow the shape:
|
||||
## Backup tasks
|
||||
|
||||
```json
|
||||
| Method | Endpoint | Access | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/backup/tasks` | Auth | List tasks |
|
||||
| `GET` | `/api/backup/tasks/tags` | Auth | List task tags |
|
||||
| `GET` | `/api/backup/tasks/export` | Auth | Download all task definitions, or select them with `?ids=1,2` |
|
||||
| `POST` | `/api/backup/tasks/import` | Operator | Import task definitions, up to 1 MiB |
|
||||
| `POST` | `/api/backup/tasks/batch/toggle` | Operator | Enable or disable tasks in bulk |
|
||||
| `POST` | `/api/backup/tasks/batch/delete` | Operator | Delete tasks in bulk |
|
||||
| `POST` | `/api/backup/tasks/batch/run` | Operator | Run tasks in bulk |
|
||||
| `GET` | `/api/backup/tasks/:id` | Auth | Read a task |
|
||||
| `POST` | `/api/backup/tasks` | Operator | Create a task |
|
||||
| `PUT` | `/api/backup/tasks/:id` | Operator | Update a task |
|
||||
| `DELETE` | `/api/backup/tasks/:id` | Operator | Delete a task |
|
||||
| `PUT` | `/api/backup/tasks/:id/toggle` | Operator | Enable or disable a task |
|
||||
| `POST` | `/api/backup/tasks/:id/run` | Operator | Trigger a backup |
|
||||
| `POST` | `/api/backup/tasks/:id/verify` | Operator | Trigger verification from a task |
|
||||
|
||||
Task export intentionally excludes database passwords and storage credentials. It is useful for migration and review, not a complete control-plane backup.
|
||||
|
||||
## Backup and restore records
|
||||
|
||||
| Method | Endpoint | Access | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/backup/records` | Auth | List and filter backup records |
|
||||
| `POST` | `/api/backup/records/batch-delete` | Operator | Delete records in bulk |
|
||||
| `GET` | `/api/backup/records/:id` | Auth | Read a backup record |
|
||||
| `GET` | `/api/backup/records/:id/logs/stream` | Auth | Stream logs with server-sent events |
|
||||
| `GET` | `/api/backup/records/:id/download` | Auth | Download an artifact |
|
||||
| `GET` | `/api/backup/records/:id/contents` | Auth | Browse artifact contents where supported |
|
||||
| `POST` | `/api/backup/records/:id/restore` | Operator | Start a restore |
|
||||
| `POST` | `/api/backup/records/:id/replicate` | Operator | Replicate an existing artifact |
|
||||
| `POST` | `/api/backup/records/:id/verify` | Operator | Verify an existing artifact |
|
||||
| `PUT` | `/api/backup/records/:id/lock` | Operator | Set retention lock state |
|
||||
| `DELETE` | `/api/backup/records/:id` | Operator | Delete a record and its managed artifact |
|
||||
| `GET` | `/api/restore/records` | Auth | List restore records |
|
||||
| `GET` | `/api/restore/records/:id` | Auth | Read a restore record |
|
||||
| `GET` | `/api/restore/records/:id/logs/stream` | Auth | Stream restore logs |
|
||||
| `GET` | `/api/replication/records` | Auth | List replication records |
|
||||
| `GET` | `/api/replication/records/:id` | Auth | Read a replication record |
|
||||
| `GET` | `/api/verify/records` | Auth | List verification records |
|
||||
| `GET` | `/api/verify/records/:id` | Auth | Read a verification record |
|
||||
| `GET` | `/api/verify/records/:id/logs/stream` | Auth | Stream verification logs |
|
||||
|
||||
## Templates, reports, and dashboard
|
||||
|
||||
| Method | Endpoint | Access | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/task-templates` | Auth | List task templates |
|
||||
| `GET` | `/api/task-templates/:id` | Auth | Read a task template |
|
||||
| `POST` | `/api/task-templates` | Operator | Create a template |
|
||||
| `PUT` | `/api/task-templates/:id` | Operator | Update a template |
|
||||
| `DELETE` | `/api/task-templates/:id` | Operator | Delete a template |
|
||||
| `POST` | `/api/task-templates/:id/apply` | Operator | Create tasks from a template |
|
||||
| `GET` | `/api/reports/compliance` | Auth | Read compliance evidence |
|
||||
| `GET` | `/api/reports/compliance/export` | Auth | Export compliance evidence as CSV |
|
||||
| `GET` | `/api/dashboard/stats` | Auth | Summary statistics |
|
||||
| `GET` | `/api/dashboard/timeline` | Auth | Recent activity |
|
||||
| `GET` | `/api/dashboard/sla` | Auth | RPO and SLA status |
|
||||
| `GET` | `/api/dashboard/cluster` | Auth | Cluster summary |
|
||||
| `GET` | `/api/dashboard/breakdown` | Auth | Task and record breakdown |
|
||||
| `GET` | `/api/dashboard/node-performance` | Auth | Per-node performance |
|
||||
|
||||
## Notifications, settings, and administration
|
||||
|
||||
| Method | Endpoint | Access | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/notifications` | Auth | List notification channels |
|
||||
| `GET` | `/api/notifications/:id` | Auth | Read a channel |
|
||||
| `POST` | `/api/notifications` | Operator | Create a channel |
|
||||
| `PUT` | `/api/notifications/:id` | Operator | Update a channel |
|
||||
| `DELETE` | `/api/notifications/:id` | Operator | Delete a channel |
|
||||
| `POST` | `/api/notifications/test` | Operator | Test an unsaved configuration |
|
||||
| `POST` | `/api/notifications/:id/test` | Operator | Test a saved channel |
|
||||
| `GET` | `/api/settings` | Auth | Read system settings |
|
||||
| `PUT` | `/api/settings` | Admin | Update system settings |
|
||||
| `GET` | `/api/users` | Admin | List users |
|
||||
| `POST` | `/api/users` | Admin | Create a user |
|
||||
| `PUT` | `/api/users/:id` | Admin | Update a user |
|
||||
| `POST` | `/api/users/:id/2fa/reset` | Admin | Reset a user's second factor |
|
||||
| `DELETE` | `/api/users/:id` | Admin | Delete a user |
|
||||
| `GET` | `/api/api-keys` | Admin | List API keys without plaintext values |
|
||||
| `POST` | `/api/api-keys` | Admin | Create an API key and return its plaintext once |
|
||||
| `PUT` | `/api/api-keys/:id/toggle` | Admin | Enable or disable an API key |
|
||||
| `DELETE` | `/api/api-keys/:id` | Admin | Revoke an API key |
|
||||
|
||||
## Audit, events, search, and discovery
|
||||
|
||||
| Method | Endpoint | Access | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/audit-logs` | Auth | List and filter audit records |
|
||||
| `GET` | `/api/audit-logs/export` | Auth | Export audit records |
|
||||
| `GET` | `/api/events/stream` | Auth | Stream real-time application events with SSE |
|
||||
| `GET` | `/api/search` | Auth | Search supported resources |
|
||||
| `POST` | `/api/database/discover` | Auth | Discover databases from supplied connection details |
|
||||
|
||||
## Nodes
|
||||
|
||||
| Method | Endpoint | Access | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/api/nodes` | Auth | List nodes |
|
||||
| `GET` | `/api/nodes/:id` | Auth | Read a node |
|
||||
| `GET` | `/api/nodes/:id/fs/list` | Operator | Browse the selected node filesystem |
|
||||
| `POST` | `/api/nodes` | Admin | Create a node |
|
||||
| `POST` | `/api/nodes/batch` | Admin | Create up to 50 nodes |
|
||||
| `PUT` | `/api/nodes/:id` | Admin | Update a node |
|
||||
| `DELETE` | `/api/nodes/:id` | Admin | Delete an unreferenced node |
|
||||
| `POST` | `/api/nodes/:id/install-tokens` | Admin | Create a one-time installer |
|
||||
| `GET` | `/api/nodes/:id/install-script-preview` | Admin | Preview generated install material |
|
||||
| `POST` | `/api/nodes/:id/rotate-token` | Admin | Rotate the long-lived node token |
|
||||
|
||||
## Agent protocol
|
||||
|
||||
These routes are for the `backupx agent` process and authenticate inside the handler with the node token.
|
||||
|
||||
| Method | Endpoint | Access | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `POST` | `/api/agent/heartbeat` | Agent | Report liveness and node state |
|
||||
| `POST` | `/api/agent/commands/poll` | Agent | Claim a pending command |
|
||||
| `POST` | `/api/agent/commands/:id/result` | Agent | Report a command result |
|
||||
| `GET` | `/api/agent/tasks/:id` | Agent | Fetch a runnable task specification |
|
||||
| `POST` | `/api/agent/records/:id` | Agent | Append logs or update backup state |
|
||||
| `PUT` | `/api/agent/records/:id/artifacts/:targetId` | Agent | Stream a relayed artifact to the Master |
|
||||
| `GET` | `/api/agent/restores/:id/spec` | Agent | Fetch restore instructions |
|
||||
| `GET` | `/api/agent/restores/:id/artifact` | Agent | Stream a restore artifact |
|
||||
| `POST` | `/api/agent/restores/:id` | Agent | Update restore state |
|
||||
| `GET` | `/api/v1/agent/self` | Agent | Validate node identity during installation |
|
||||
|
||||
## Public operational and install routes
|
||||
|
||||
| Method | Endpoint | Access | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/health` | Public | Liveness |
|
||||
| `GET` | `/api/health` | Public | API-prefixed liveness alias |
|
||||
| `GET` | `/ready` | Public | SQLite readiness |
|
||||
| `GET` | `/api/ready` | Public | API-prefixed readiness alias |
|
||||
| `GET` | `/metrics` | Public | Prometheus metrics |
|
||||
| `GET` | `/install/:token` | Public | Consume a one-time Agent installer token |
|
||||
| `GET` | `/api/install/:token` | Public | API-prefixed installer route |
|
||||
| `GET` | `/install/:token/compose.yml` | Public | Render a Docker Agent Compose file |
|
||||
| `GET` | `/api/install/:token/compose.yml` | Public | API-prefixed Docker Compose route |
|
||||
|
||||
Restrict probes and metrics to monitoring networks. Install tokens are single-use, time-limited secrets and must not be written to public logs.
|
||||
|
||||
## Response formats
|
||||
|
||||
Most JSON successes use:
|
||||
|
||||
~~~json
|
||||
{
|
||||
"code": "OK",
|
||||
"message": "",
|
||||
"data": { /* actual payload */ }
|
||||
"message": "success",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
Errors return an HTTP 4xx/5xx plus:
|
||||
Errors use an HTTP 4xx or 5xx status plus a stable application code:
|
||||
|
||||
```json
|
||||
~~~json
|
||||
{
|
||||
"code": "BACKUP_TASK_NOT_FOUND",
|
||||
"message": "备份任务不存在",
|
||||
"data": null
|
||||
"message": "备份任务不存在"
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
Clients should branch on the HTTP status and `code`, not the localized `message`.
|
||||
|
||||
Artifact downloads, task JSON export, audit or compliance exports, installer responses, and `/metrics` return their native content types instead of the JSON envelope. Log and event streams use `text/event-stream`; reverse proxies must keep response buffering disabled.
|
||||
|
||||
@@ -17,15 +17,17 @@ backupx --version
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--config <path>` | Path to config YAML (default: `./config.yaml`) |
|
||||
| `--config <path>` | Explicit config YAML path; omitted uses the search paths below |
|
||||
| `--version` | Print version and exit |
|
||||
|
||||
When `--config` is omitted, the server searches `./config.yaml`, `./server/config.yaml`, and `/etc/backupx/config.yaml`. `BACKUPX_*` environment variables override matching server configuration keys. See [Configuration Reference](../deployment/configuration).
|
||||
|
||||
## `backupx agent`
|
||||
|
||||
Run in Agent mode, connecting to a Master. See [Multi-Node Cluster](../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
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
@@ -33,13 +35,15 @@ backupx agent --master http://master:8340 --token <token>
|
||||
| `--master <url>` | Master URL |
|
||||
| `--token <token>` | Agent auth token |
|
||||
| `--token-file <path>` | Read the Agent Token from a file; preferred for services and containers |
|
||||
| `--config <path>` | YAML config (takes precedence over env) |
|
||||
| `--temp-dir <path>` | Local temp directory (default `/tmp/backupx-agent`) |
|
||||
| `--config <path>` | Load Agent YAML; when present, environment-based Agent config is not loaded |
|
||||
| `--temp-dir <path>` | Local temp directory (default `/var/lib/backupx-agent/tmp`) |
|
||||
| `--proxy-url <url>` | Explicit HTTP(S) or SOCKS5(H) proxy |
|
||||
| `--ca-cert <path>` | PEM CA certificate used to verify the Master |
|
||||
| `--insecure-tls` | Skip TLS verification (testing only) |
|
||||
|
||||
Environment variables: `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`. When no explicit proxy URL is set, the Agent also honors `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`.
|
||||
Agent precedence is explicit CLI flags over a YAML file. If `--config` is not supplied, Agent settings are loaded from `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`, and `BACKUPX_AGENT_INSECURE_TLS`. When no explicit proxy URL is set, the Agent also honors `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`.
|
||||
|
||||
`--token` overrides `--token-file`. Keep long-lived tokens in a root-readable file rather than command history. A private CA and `--insecure-tls` cannot be enabled together.
|
||||
|
||||
## `backupx backint`
|
||||
|
||||
@@ -57,6 +61,8 @@ backupx backint -f <function> -i <input> -o <output> -p <params>
|
||||
| `-p <path>` | Parameter file |
|
||||
| `-u / -c / -l / -v` | Accepted and ignored for SAP compatibility |
|
||||
|
||||
The `-p` file must define `STORAGE_TYPE` and either `STORAGE_CONFIG_JSON` or `STORAGE_CONFIG`. Optional keys include `PARALLEL_FACTOR`, `COMPRESS`, `LOG_FILE`, `CATALOG_DB`, and `KEY_PREFIX`.
|
||||
|
||||
## `backupx reset-password`
|
||||
|
||||
Reset an admin password directly in the SQLite database. No server restart needed.
|
||||
@@ -70,3 +76,5 @@ backupx reset-password --username admin --password 'newpass123' [--config /path/
|
||||
| `--username` | Target username (default: `admin`) |
|
||||
| `--password` | New password (min 8 chars, required) |
|
||||
| `--config` | Config path (used to locate the database file) |
|
||||
|
||||
Run this command on the Master host with access to the configured SQLite path. Avoid placing the new password directly in retained shell history.
|
||||
|
||||
Reference in New Issue
Block a user