feat(manager-server): support SQLite database URLs

Dockerfile.manager-server

@@ -24,6 +24,5 @@ WORKDIR /app
 COPY --from=service-build /out/cpa-manager-plus /usr/local/bin/cpa-manager-plus
 ENV HTTP_ADDR=0.0.0.0:18317
 ENV USAGE_DATA_DIR=/data
-ENV USAGE_DB_PATH=/data/usage.sqlite
 EXPOSE 18317
 ENTRYPOINT ["cpa-manager-plus"]

apps/docs/deployment/docker.md

@@ -85,6 +85,8 @@ services:
     environment:
       HTTP_ADDR: '0.0.0.0:18317'
       USAGE_DB_PATH: '/data/usage.sqlite'
+      # 高级替代：删除上一行后启用完整 SQLite URL：
+      # USAGE_DB_URL: 'file:///data/usage.sqlite?_txlock=immediate&_pragma=journal_mode(DELETE)&_pragma=synchronous(EXTRA)&_pragma=busy_timeout(15000)&_pragma=foreign_keys(1)&_pragma=mmap_size(0)'
       CPA_MANAGER_DATA_KEY_PATH: '/data/data.key'
       # 托管部署建议显式设置：
       # CPA_MANAGER_ADMIN_KEY: "replace-with-a-long-random-admin-key"
@@ -189,7 +191,8 @@ http://host.docker.internal:8317
 | ---------------------------- | --------------------------------- | --------------------------------------- |
 | `HTTP_ADDR`                  | `0.0.0.0:18317`                   | Manager Server 监听地址。               |
 | `USAGE_DATA_DIR`             | `/data`                           | 数据目录。                              |
-| `USAGE_DB_PATH`              | `/data/usage.sqlite`              | SQLite 数据库路径。                     |
+| `USAGE_DB_URL`               | 空                                | 高级 SQLite `file:` URL；与 path 互斥。 |
+| `USAGE_DB_PATH`              | `/data/usage.sqlite`              | SQLite 数据库路径；URL 模式时移除。     |
 | `CPA_MANAGER_DATA_KEY_PATH`  | `/data/data.key`                  | 数据密钥路径。                          |
 | `CPA_MANAGER_ADMIN_KEY`      | 空                                | 显式设置 Manager Server 管理员密钥。    |
 | `CPA_MANAGER_ADMIN_KEY_FILE` | `/run/secrets/cpa_admin_key`      | 从文件读取管理员密钥。                  |
@@ -203,6 +206,8 @@ http://host.docker.internal:8317
 | `USAGE_POLL_INTERVAL_MS`     | `500`                             | 空闲轮询间隔。                          |
 | `USAGE_QUERY_LIMIT`          | `50000`                           | 最近用量事件返回上限。                  |
 
+普通部署保留 `USAGE_DB_PATH` 即可。使用 `USAGE_DB_URL` 时必须从 Compose 中删除 `USAGE_DB_PATH`，不能同时保留两个非空值。URL 中的 `&` 位于 YAML 单引号内，不需要额外转义。完整约束见 [Manager Server 指南](../operations/manager-server.md#高级-sqlite-database-url)。
+
 更多运行时配置见 [Manager Server 指南](../operations/manager-server.md)。
 
 :::
@@ -213,12 +218,12 @@ http://host.docker.internal:8317
 
 ```text
 /data/usage.sqlite
-/data/usage.sqlite-wal
-/data/usage.sqlite-shm
 /data/data.key
+/data/usage.sqlite-wal  # WAL 模式且文件存在时
+/data/usage.sqlite-shm  # WAL 模式且文件存在时
 ```
 
-备份必须包含 SQLite 文件和 `data.key`：
+备份必须包含 SQLite 主数据库、`data.key` 和当前实际存在的 sidecar 文件：
 
 ```bash
 docker run --rm \
@@ -292,6 +297,8 @@ docker compose run --rm --no-deps \
 docker compose start cpa-manager-plus
 ```
 
+如果 service 使用 `USAGE_DB_URL`，运行中间命令时删除 `--db-path /data/usage.sqlite`，让容器继承完整 URL；显式 path 会选择默认 SQLite 连接设置。
+
 如果 Compose 服务名不是 `cpa-manager-plus`，请替换为实际服务名。不要在 Manager Server 仍运行时执行，也不要从 Web UI 在线触发清理；该命令需要独占 SQLite 进程锁。完成后重新启动，维护状态会从数据库 metadata 自动恢复为 clean，UI Warning 也会自动消失。
 
 `cleanup-derived` 只处理派生清理、延后索引和旧索引替换，不会删除、重建或改写 authoritative `usage_events`。执行前仍应备份 `/data` 和 `data.key`。

apps/docs/deployment/native.md

@@ -130,13 +130,21 @@ USAGE_DATA_DIR=/var/lib/cpa-manager-plus ./cpa-manager-plus
 USAGE_DB_PATH=/var/lib/cpa-manager-plus/usage.sqlite ./cpa-manager-plus
 ```
 
+需要完整 SQLite driver 参数时，也可以只设置 `USAGE_DB_URL`：
+
+```bash
+USAGE_DB_URL='file:///var/lib/cpa-manager-plus/usage.sqlite?_txlock=immediate&_pragma=journal_mode(DELETE)&_pragma=synchronous(EXTRA)&_pragma=busy_timeout(15000)&_pragma=foreign_keys(1)&_pragma=mmap_size(0)' ./cpa-manager-plus
+```
+
+`USAGE_DB_URL` 与 `USAGE_DB_PATH` 互斥；不要同时设置。完整约束见 [Manager Server 指南](../operations/manager-server.md#高级-sqlite-database-url)。
+
 需要备份：
 
 ```text
 data/usage.sqlite
-data/usage.sqlite-wal
-data/usage.sqlite-shm
 data/data.key
+data/usage.sqlite-wal  # WAL 模式且文件存在时
+data/usage.sqlite-shm  # WAL 模式且文件存在时
 ```
 
 `data.key` 用来解密已保存的 CPA Management Key。丢失后只能重新保存 CPA 连接。
@@ -229,7 +237,7 @@ setup 后：
 1. 停止原生进程。
 2. 备份数据目录，包括 `data.key`。
 3. 解压新包。
-4. 复制 `config.json` 和 `data/`，或继续使用 `USAGE_DATA_DIR` / `USAGE_DB_PATH`。
+4. 复制 `config.json` 和 `data/`，或继续使用 `USAGE_DATA_DIR`、`USAGE_DB_PATH` 或 `USAGE_DB_URL`。URL 与 path 不能同时设置。
 5. 启动新二进制。
 
 systemd 示例：

apps/docs/en/deployment/docker.md

@@ -85,6 +85,8 @@ services:
     environment:
       HTTP_ADDR: '0.0.0.0:18317'
       USAGE_DB_PATH: '/data/usage.sqlite'
+      # Advanced alternative: remove the previous line before enabling a complete SQLite URL:
+      # USAGE_DB_URL: 'file:///data/usage.sqlite?_txlock=immediate&_pragma=journal_mode(DELETE)&_pragma=synchronous(EXTRA)&_pragma=busy_timeout(15000)&_pragma=foreign_keys(1)&_pragma=mmap_size(0)'
       CPA_MANAGER_DATA_KEY_PATH: '/data/data.key'
       # Recommended for managed deployments:
       # CPA_MANAGER_ADMIN_KEY: "replace-with-a-long-random-admin-key"
@@ -185,23 +187,26 @@ Do not use `127.0.0.1` from inside a container to reach CPA on the host. Inside
 
 ## Common Environment Variables
 
-| Variable                     | Default                           | Description                                      |
-| ---------------------------- | --------------------------------- | ------------------------------------------------ |
-| `HTTP_ADDR`                  | `0.0.0.0:18317`                   | Manager Server listen address.                   |
-| `USAGE_DATA_DIR`             | `/data`                           | Data directory.                                  |
-| `USAGE_DB_PATH`              | `/data/usage.sqlite`              | SQLite database path.                            |
-| `CPA_MANAGER_DATA_KEY_PATH`  | `/data/data.key`                  | Data key path.                                   |
-| `CPA_MANAGER_ADMIN_KEY`      | empty                             | Explicit Manager Server admin key.               |
-| `CPA_MANAGER_ADMIN_KEY_FILE` | `/run/secrets/cpa_admin_key`      | Read the admin key from a file.                  |
-| `CPA_MANAGER_DATA_KEY`       | empty                             | Explicit data encryption key.                    |
-| `CPA_MANAGER_DATA_KEY_FILE`  | `/run/secrets/cpa_data_key`       | Read the data encryption key from a file.        |
-| `CPA_UPSTREAM_URL`           | empty                             | Optional environment-managed CPA URL.            |
-| `CPA_MANAGEMENT_KEY`         | empty                             | Optional environment-managed CPA Management Key. |
-| `CPA_MANAGEMENT_KEY_FILE`    | `/run/secrets/cpa_management_key` | Read the CPA Management Key from a file.         |
-| `USAGE_COLLECTOR_MODE`       | `auto`                            | `auto`, `subscribe`, `http`, or `resp`.          |
-| `USAGE_BATCH_SIZE`           | `100`                             | Max collected records per batch.                 |
-| `USAGE_POLL_INTERVAL_MS`     | `500`                             | Idle poll interval.                              |
-| `USAGE_QUERY_LIMIT`          | `50000`                           | Max recent usage events returned.                |
+| Variable                     | Default                           | Description                                                    |
+| ---------------------------- | --------------------------------- | -------------------------------------------------------------- |
+| `HTTP_ADDR`                  | `0.0.0.0:18317`                   | Manager Server listen address.                                 |
+| `USAGE_DATA_DIR`             | `/data`                           | Data directory.                                                |
+| `USAGE_DB_URL`               | empty                             | Advanced SQLite `file:` URL; mutually exclusive with the path. |
+| `USAGE_DB_PATH`              | `/data/usage.sqlite`              | SQLite database path; remove it in URL mode.                   |
+| `CPA_MANAGER_DATA_KEY_PATH`  | `/data/data.key`                  | Data key path.                                                 |
+| `CPA_MANAGER_ADMIN_KEY`      | empty                             | Explicit Manager Server admin key.                             |
+| `CPA_MANAGER_ADMIN_KEY_FILE` | `/run/secrets/cpa_admin_key`      | Read the admin key from a file.                                |
+| `CPA_MANAGER_DATA_KEY`       | empty                             | Explicit data encryption key.                                  |
+| `CPA_MANAGER_DATA_KEY_FILE`  | `/run/secrets/cpa_data_key`       | Read the data encryption key from a file.                      |
+| `CPA_UPSTREAM_URL`           | empty                             | Optional environment-managed CPA URL.                          |
+| `CPA_MANAGEMENT_KEY`         | empty                             | Optional environment-managed CPA Management Key.               |
+| `CPA_MANAGEMENT_KEY_FILE`    | `/run/secrets/cpa_management_key` | Read the CPA Management Key from a file.                       |
+| `USAGE_COLLECTOR_MODE`       | `auto`                            | `auto`, `subscribe`, `http`, or `resp`.                        |
+| `USAGE_BATCH_SIZE`           | `100`                             | Max collected records per batch.                               |
+| `USAGE_POLL_INTERVAL_MS`     | `500`                             | Idle poll interval.                                            |
+| `USAGE_QUERY_LIMIT`          | `50000`                           | Max recent usage events returned.                              |
+
+Keep `USAGE_DB_PATH` for normal deployments. When using `USAGE_DB_URL`, remove `USAGE_DB_PATH` from Compose; the two values cannot both be non-empty. The `&` characters are inside a YAML single-quoted scalar and do not need additional escaping. See [Manager Server Guide](../operations/manager-server.md#advanced-sqlite-database-urls) for the complete constraints.
 
 For the full runtime reference, see [Manager Server Guide](../operations/manager-server.md).
 
@@ -213,12 +218,12 @@ Always mount `/data`. Docker defaults:
 
 ```text
 /data/usage.sqlite
-/data/usage.sqlite-wal
-/data/usage.sqlite-shm
 /data/data.key
+/data/usage.sqlite-wal  # when WAL mode is active and the file exists
+/data/usage.sqlite-shm  # when WAL mode is active and the file exists
 ```
 
-Backups must include both SQLite files and `data.key`:
+Backups must include the main SQLite database, `data.key`, and every sidecar file that currently exists:
 
 ```bash
 docker run --rm \
@@ -292,6 +297,8 @@ docker compose run --rm --no-deps \
 docker compose start cpa-manager-plus
 ```
 
+If the service uses `USAGE_DB_URL`, remove `--db-path /data/usage.sqlite` from the middle command so the container inherits the complete URL; an explicit path selects the default SQLite connection settings.
+
 Replace `cpa-manager-plus` if your Compose service uses another name. Do not run cleanup while Manager Server is still active, and do not trigger it from the web UI; the command requires the exclusive SQLite process lock. After restart, Manager Server derives the state from database metadata again, so the warning disappears automatically when maintenance is clean.
 
 `cleanup-derived` handles derived cleanup, deferred indexes, and legacy index replacement only. It never deletes, rebuilds, or rewrites authoritative `usage_events`. Back up `/data` and `data.key` first.

apps/docs/en/deployment/native.md

@@ -132,13 +132,21 @@ or:
 USAGE_DB_PATH=/var/lib/cpa-manager-plus/usage.sqlite ./cpa-manager-plus
 ```
 
+When complete SQLite driver parameters are required, set only `USAGE_DB_URL` instead:
+
+```bash
+USAGE_DB_URL='file:///var/lib/cpa-manager-plus/usage.sqlite?_txlock=immediate&_pragma=journal_mode(DELETE)&_pragma=synchronous(EXTRA)&_pragma=busy_timeout(15000)&_pragma=foreign_keys(1)&_pragma=mmap_size(0)' ./cpa-manager-plus
+```
+
+`USAGE_DB_URL` and `USAGE_DB_PATH` are mutually exclusive; do not set both. See [Manager Server Guide](../operations/manager-server.md#advanced-sqlite-database-urls) for the complete constraints.
+
 Back up:
 
 ```text
 data/usage.sqlite
-data/usage.sqlite-wal
-data/usage.sqlite-shm
 data/data.key
+data/usage.sqlite-wal  # when WAL mode is active and the file exists
+data/usage.sqlite-shm  # when WAL mode is active and the file exists
 ```
 
 `data.key` decrypts the saved CPA Management Key. If it is lost, save the CPA connection again.
@@ -231,7 +239,7 @@ For production, you can also run the process through systemd, launchd, Windows S
 1. Stop the native process.
 2. Back up the data directory, including `data.key`.
 3. Extract the new package.
-4. Copy over `config.json` and `data/`, or keep using `USAGE_DATA_DIR` / `USAGE_DB_PATH`.
+4. Copy over `config.json` and `data/`, or keep using `USAGE_DATA_DIR`, `USAGE_DB_PATH`, or `USAGE_DB_URL`. The URL and path cannot both be set.
 5. Start the new binary.
 
 systemd example:

apps/docs/en/migration/from-cpa-manager.md

@@ -19,11 +19,10 @@ If you never used the old `seakee/cpa-manager`, skip this page and use [Quick St
    - Docker volume is commonly `cpa-manager-data`.
    - Host directory mounts usually map to container `/data`.
    - Native packages default to `data/usage.sqlite` under the program directory.
-3. Stop the old container or process so SQLite WAL files stop changing.
+3. Stop the old container or process so the SQLite files stop changing.
 4. Back up the whole old data directory. Keep at least:
    - `usage.sqlite`
-   - `usage.sqlite-wal`
-   - `usage.sqlite-shm`
+   - Any current `usage.sqlite-wal` / `usage.sqlite-shm` files when WAL mode is active
 5. Decide the admin key strategy. During migration, explicitly setting `CPA_MANAGER_ADMIN_KEY` or `CPA_MANAGER_ADMIN_KEY_FILE` is recommended.
 
 ## Docker Volume Migration
@@ -53,6 +52,8 @@ services:
     environment:
       HTTP_ADDR: '0.0.0.0:18317'
       USAGE_DB_PATH: '/data/usage.sqlite'
+      # Advanced alternative: remove the previous line before setting a complete USAGE_DB_URL.
+      # USAGE_DB_URL: 'file:///data/usage.sqlite?_txlock=immediate&_pragma=journal_mode(DELETE)&_pragma=synchronous(EXTRA)&_pragma=busy_timeout(15000)&_pragma=foreign_keys(1)'
       CPA_MANAGER_DATA_KEY_PATH: '/data/data.key'
       CPA_MANAGER_ADMIN_KEY: 'replace-with-a-long-random-admin-key'
       USAGE_COLLECTOR_MODE: 'auto'
@@ -88,7 +89,7 @@ After startup, open `http://<host>:18317/management.html` and log in with the ad
 1. Stop the old `cpa-manager` process.
 2. Back up the old program directory, especially `data/usage.sqlite*`.
 3. Extract `cpa-manager-plus_<version>_<os>_<arch>`.
-4. Copy the old `data` directory into the new package directory, or set `USAGE_DATA_DIR` / `USAGE_DB_PATH` to the old data directory.
+4. Copy the old `data` directory into the new package directory, or set `USAGE_DATA_DIR`, `USAGE_DB_PATH`, or `USAGE_DB_URL` to the old database. The URL and path cannot both be set.
 5. Set an admin key for the first startup:
 
 ```bash

apps/docs/en/operations/backup.md

@@ -1,15 +1,17 @@
 # Backup And Restore
 
-CPAMP keeps request history, configuration, and encrypted credentials on the host. The common mistake is backing up only `usage.sqlite` and missing WAL/SHM files, `data.key`, or secret files in the install directory.
+CPAMP keeps request history, configuration, and encrypted credentials on the host. The common mistake is copying only `usage.sqlite` while the process is running, or missing current WAL/SHM files, `data.key`, or secret files in the install directory.
 
 ## Required Backup Files
 
-Back up these files as a set:
+After stopping Manager Server, back up these files as one set:
 
 - `usage.sqlite`
-- `usage.sqlite-wal`
-- `usage.sqlite-shm`
 - `data.key`
+- `usage.sqlite-wal` (when WAL mode is active and the file exists)
+- `usage.sqlite-shm` (when WAL mode is active and the file exists)
+
+`journal_mode=DELETE` normally has no WAL/SHM files. Do not manually delete sidecars to make the directory look clean; back up every file that actually exists after shutdown.
 
 If your deployment directory contains custom configuration files, back them up too. With the one-click installer, also back up `secrets/` under the install directory; full installation and env/secret-managed connections store the CPA Management Key in `secrets/cpa-management-key`.
 
@@ -63,10 +65,11 @@ Copy-Item -Recurse .\data .\data.backup
 
 1. Stop CPAMP.
 2. Restore the full data directory.
-3. Confirm that `usage.sqlite` and `data.key` come from the same backup.
-4. If the CPA connection is env/secret-managed, also restore `secrets/` from the install directory.
-5. Start CPAMP.
-6. Log in and check configuration, monitoring data, and collector status.
+3. Confirm that `usage.sqlite`, `data.key`, and any sidecars come from the same backup.
+4. If `USAGE_DB_URL` is used, confirm that the restore target is the URL path and that its declared journal mode matches the restored deployment.
+5. If the CPA connection is env/secret-managed, also restore `secrets/` from the install directory.
+6. Start CPAMP.
+7. Log in and check configuration, monitoring data, and collector status.
 
 If restore produces decryption errors, first check whether `data.key` matches the SQLite database.
 

apps/docs/en/operations/configuration.md

@@ -7,8 +7,8 @@ CPAMP stores its core data locally. During deployment, identify three things fir
 | File               | Description                                                                           |
 | ------------------ | ------------------------------------------------------------------------------------- |
 | `usage.sqlite`     | SQLite database for request events, configuration, prices, aliases, and related data. |
-| `usage.sqlite-wal` | SQLite WAL file. Back it up when present.                                             |
-| `usage.sqlite-shm` | SQLite SHM file. Back it up when present.                                             |
+| `usage.sqlite-wal` | May exist in WAL mode. Back it up when present.                                       |
+| `usage.sqlite-shm` | May exist in WAL mode. Back it up when present.                                       |
 | `data.key`         | Data key used to encrypt sensitive configuration written to SQLite.                   |
 
 Docker defaults:
@@ -25,6 +25,23 @@ Native package defaults:
 ./data/data.key
 ```
 
+## SQLite Database Location
+
+Use `USAGE_DATA_DIR` or `USAGE_DB_PATH` for normal deployments. When complete SQLite driver parameters are required, use the single `USAGE_DB_URL` setting instead; it is mutually exclusive with `USAGE_DB_PATH`. The equivalent `config.json` fields are `dbUrl` and `dbPath`, which are also mutually exclusive.
+
+Database-location precedence:
+
+```text
+environment USAGE_DB_URL / USAGE_DB_PATH
+> environment USAGE_DATA_DIR
+> config.json dbUrl / dbPath
+> default data/usage.sqlite
+```
+
+`USAGE_DB_URL` accepts only an absolute, local, persistent `file:` URI and requires explicit `_txlock=immediate`, foreign-key, journal-mode, synchronous, and positive busy-timeout settings. See [Manager Server Guide](./manager-server.md#advanced-sqlite-database-urls) for the complete syntax, examples, journal-mode transition rules, and network-filesystem limitations.
+
+When a URL is used and `CPA_MANAGER_DATA_KEY_PATH` is not set explicitly, `data.key` defaults to the URL database directory. With every database-location method, back up the database, `data.key`, and every SQLite sidecar file that currently exists as one set.
+
 ## Admin Key
 
 Full Docker and native Manager Server modes use a `cpamp_...` admin key for login.