Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs: correct authenticated deployment and restore procedures (#5191)

Zayn Jarvis6a6a4495277b
diff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.md
index f857721b1..24dd21872 100644
--- a/docs/en/configuration/01-server.md
+++ b/docs/en/configuration/01-server.md
@@ -331,9 +331,7 @@ See [Encryption](../guides/08-encryption.md) for provider and key-management set
"prefetch_search_topn": 5,
"extraction_enabled": true,
"session_skill_extraction_enabled": false,
- "link_enabled": false,
- "v2_lock_retry_interval_seconds": 0.2,
- "v2_lock_max_retries": 0
+ "link_enabled": false
}
}
```
@@ -349,8 +347,6 @@ See [Encryption](../guides/08-encryption.md) for provider and key-management set
| `extraction_enabled` | boolean | `true` | Extract long-term memories on session commit |
| `session_skill_extraction_enabled` | boolean | `false` | Also extract reusable skills |
| `link_enabled` | boolean | `false` | Generate and resolve memory links |
-| `v2_lock_retry_interval_seconds` | number, `>= 0` | `0.2` | Memory-lock retry interval |
-| `v2_lock_max_retries` | integer, `>= 0` | `0` | Retry limit; `0` means unlimited |
## Parser Settings
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index af4d803f7..f8c16fd1a 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -444,7 +444,7 @@ OpenViking also expects dense float vectors throughout storage and retrieval, so
**gemini provider example:**
-> **Note:** Requires `pip install "google-genai>=1.0.0"`. For async batching: `pip install "openviking[gemini-async]"`.
+> **Note:** Requires `google-genai>=1.0.0` in the server environment — uv install: `uv tool install openviking --upgrade --with "google-genai>=1.0.0"`; pip install: `pip install "google-genai>=1.0.0"`. For async batching use the extra instead: `uv tool install "openviking[gemini-async]" --upgrade` or `pip install "openviking[gemini-async]"`.
```json
{
@@ -1518,39 +1518,6 @@ Local backends add the fields to an existing collection and rebuild the scalar i
For existing remote collections, including Volcengine VikingDB, provision these fields and scalar indexes before startup; OpenViking validates but does not alter the remote schema. Volcengine API-key data-plane mode also requires the context collection and configured index to exist. See [Resource Access Control (ACL)](../concepts/15-acl.md) for permission semantics.
-<details>
-<summary><b>openGauss</b></summary>
-
-Requires an openGauss server with native `vector` support and a remote-capable database user.
-Install the optional driver with `pip install "openviking[opengauss]"`.
-In the official container, the initial `omm` user may be restricted for remote login; create a normal user for OpenViking if needed.
-
-```json
-{
- "storage": {
- "vectordb": {
- "name": "context",
- "backend": "opengauss",
- "project": "default",
- "distance_metric": "cosine",
- "dimension": 1024,
- "opengauss": {
- "host": "127.0.0.1",
- "port": 5432,
- "user": "openviking",
- "password": "your-password",
- "db_name": "postgres",
- "schema": "public",
- "mode": "standalone"
- }
- }
- }
-}
-```
-
-Set `mode` to `"distributed"` for openGauss distributed deployments; OpenViking will attempt to mark metadata tables as reference tables and distribute collection tables by `id`.
-</details>
-
## Config Files
@@ -1656,14 +1623,14 @@ Local directory uploads respect `.gitignore` files (root and nested). `ignore_di
For trusted gateway deployments, CLI flags can override these identity fields per command:
```bash
-openviking --account acme --user alice ls viking://
+ov --account acme --user alice ls viking://
```
For `add-resource`, upload filter flags are merged additively with `ovcli.conf` defaults:
```bash
# ovcli.conf: upload.exclude="*.log"
-openviking add-resource ./docs --exclude "*.tmp"
+ov add-resource ./docs --exclude "*.tmp"
# effective exclude sent to server: "*.log,*.tmp"
```
@@ -1709,7 +1676,7 @@ When running OpenViking as an HTTP service, add a `server` section to `ov.conf`:
|-------|------|-------------|---------|
| `host` | str | Bind address | `127.0.0.1` |
| `port` | int | Bind port | `1933` |
-| `auth_mode` | str | Authentication mode: `"api_key"` or `"trusted"`. Default is `"api_key"` | `"api_key"` |
+| `auth_mode` | str / null | Built-in modes: `"dev"`, `"api_key"`, `"trusted"`, `"oidc"`, `"ldap"`. When omitted/null, infer `api_key` from a non-empty `root_api_key`; otherwise infer `dev`. | `null` |
| `root_api_key` | str | Root API key for multi-tenant auth in `api_key` mode. In `trusted` mode it is optional on localhost, but required for any non-localhost deployment; it does not become the source of user identity | `null` |
| `profile_enabled` | bool | Whether to allow request-scoped cProfile via `profile=1` on HTTP requests. When disabled, the server ignores that query parameter. When enabled, the CLI can display the returned `profile`, while the Python HTTP client currently triggers profiling but does not automatically attach the top-level `profile` field to most SDK return values. | `false` |
| `cors_origins` | list | Allowed CORS origins | `["*"]` |
@@ -1723,9 +1690,9 @@ When running OpenViking as an HTTP service, add a `server` section to `ov.conf`:
| `user_config_defaults.memory_policy` | object | Deployment default memory extraction policy used when neither the Session nor the User has an explicit policy. | `null` |
| `agent_evolution.enabled` | bool | Instance-wide Agent Evolution switch. When enabled, session commits may generate or update cases, trajectories, and experiences according to the session `memory_policy`. When disabled, production of these memory types stops for every account and user. Existing memories remain readable and searchable. | `false` |
-`api_key` mode uses API keys and is the default. `trusted` mode trusts `X-OpenViking-Account` / `X-OpenViking-User` headers from a trusted gateway or internal caller.
+Omitting `auth_mode` (or setting it to `null`) selects `api_key` when a non-empty `root_api_key` is configured, and `dev` otherwise. `dev` is allowed only on localhost and accepts requests without authentication. An empty-string `root_api_key` is invalid.
-When `root_api_key` is configured in `api_key` mode, the server enables multi-tenant authentication. Use the Admin API to create accounts and user keys. In `trusted` mode, ordinary requests do not require user registration first; each request is resolved as `USER` from the injected identity headers. However, skipping `root_api_key` in `trusted` mode is allowed only on localhost. Development mode only applies when `auth_mode = "api_key"` and `root_api_key` is not set.
+Explicit `auth_mode: "api_key"` requires a non-empty `root_api_key`, including on localhost; without it, startup fails instead of falling back to development mode. Use the root key with the Admin API to create accounts and user/admin keys; use those tenant-bound keys for data access. `trusted` mode accepts account/user identity headers from a trusted gateway and does not require user-key provisioning first. Its root key is optional only on localhost and required for non-localhost binds. For role resolution, OIDC/LDAP setup, and gateway requirements, see [Authentication](04-authentication.md).
`user_config_defaults` provides deployment defaults for add targets and memory extraction. For add operations, explicit request targets still win: `add_resource.to` / `add_resource.parent` take precedence over user defaults, and `add_skill.target_uri` takes precedence over user defaults. Memory policy precedence is Session policy > User `settings/user_config.json` policy > `server.user_config_defaults.memory_policy` > kernel default. `agent_evolution.enabled` is shared by the entire OpenViking instance and has no per-user override. Running HTTP server workers read the current Agent Evolution value from the resolved `ov.conf` when a session commits, so a valid file update applies without restarting the server.
@@ -1954,7 +1921,7 @@ For detailed encryption explanations, see [Data Encryption](../concepts/10-encry
"extra_request_body": {}
},
"rerank": {
- "provider": "volcengine|openai",
+ "provider": "vikingdb|cohere|openai|litellm",
"api_key": "string",
"model": "string",
"api_base": "string",
@@ -1995,7 +1962,7 @@ For detailed encryption explanations, see [Data Encryption](../concepts/10-encry
"lock_expire": 300.0
},
"vectordb": {
- "backend": "local|remote",
+ "backend": "local|cuvs|http|volcengine|vikingdb",
"url": "string",
"project": "string"
}
diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.md
index e6cdcd52b..26a06c79c 100644
--- a/docs/en/guides/03-deployment.md
+++ b/docs/en/guides/03-deployment.md
@@ -115,10 +115,13 @@ After=network.target
[Service]
Type=simple
+# Replace with the user and group that run OpenViking
+User=your-username
+Group=your-group
# Replace with your working directory
WorkingDirectory=/var/lib/openviking
-# Choose one of the following start methods
-ExecStart=/usr/bin/openviking-server
+# Use the absolute executable path from your installation
+ExecStart=/path/to/your/python/bin/openviking-server
Restart=always
RestartSec=5
# Path to config file
@@ -128,6 +131,8 @@ Environment="OPENVIKING_CONFIG_FILE=/etc/openviking/ov.conf"
WantedBy=multi-user.target
```
+Before starting, replace every placeholder. Run `command -v openviking-server` as the service user to find the executable, create the working directory, and grant that user access to the config, workspace, and any local encryption key. The config shown here is `/etc/openviking/ov.conf`; a config generated under your own home directory is not automatically used by this unit. Omitting `User` from a system service runs it as root.
+
### Manage the Service
After creating the service file, use the following commands to manage the OpenViking service:
@@ -153,8 +158,12 @@ sudo journalctl -u openviking.service -f
### Python SDK
+```bash
+python -m pip install --upgrade openviking-sdk
+```
+
```python
-import openviking as ov
+import openviking_sdk as ov
client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")
client.initialize()
diff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.md
index 9497ab1ba..20af8d719 100644
--- a/docs/en/guides/04-authentication.md
+++ b/docs/en/guides/04-authentication.md
@@ -79,6 +79,8 @@ Trusted deployments can also call Admin API through a trusted gateway. There are
- Present the trusted deployment's `root_api_key`. For `/api/v1/admin/*`, the server treats the request as ROOT after validating that key.
- Optionally also present `X-OpenViking-Account` + `X-OpenViking-User` when the admin route targets a specific account/user. Those headers must match the target URL and are kept as the request identity, but authorization still comes from the trusted `root_api_key`.
+The role-update API only promotes users to ADMIN. Trusted Admin API authorization comes from the validated deployment root key; creating a ROOT user is not required or supported.
+
Example using a trusted upstream identity:
```bash
@@ -88,12 +90,6 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \
-H "Content-Type: application/json" \
-d '{"account_id": "platform", "admin_user_id": "gateway-admin"}'
-# Then promote it to root if it needs cross-account admin access
-curl -X PUT http://localhost:1933/api/v1/admin/accounts/platform/users/gateway-admin/role \
- -H "X-API-Key: your-secret-root-key" \
- -H "Content-Type: application/json" \
- -d '{"role": "root"}'
-
# Then, in trusted mode, use that identity to call Admin API
curl -X POST http://localhost:1933/api/v1/admin/accounts \
-H "X-API-Key: your-secret-root-key" \
diff --git a/docs/en/guides/08-encryption.md b/docs/en/guides/08-encryption.md
index ee85089d9..885ea3cf7 100644
--- a/docs/en/guides/08-encryption.md
+++ b/docs/en/guides/08-encryption.md
@@ -55,6 +55,8 @@ Edit `~/.openviking/ov.conf`:
### 3. Verify
+Restart the server after changing encryption settings, and run this example against that server. Install the [Python SDK](../api/01-overview.md#using-python-sdk-client-without-configuration-file) in the environment running the script.
+
```python
import asyncio
from pathlib import Path
@@ -62,28 +64,29 @@ from openviking_sdk import AsyncHTTPClient
async def test():
- client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")
- await client.initialize()
-
- # add_resource expects a file path or URL
- sample = Path("./encrypted-sample.txt")
- sample.write_text("Hello, encrypted world!", encoding="utf-8")
- await client.add_resource(
- path=str(sample),
- options={"reason": "Test encryption"},
- )
-
- # Read resource (automatically decrypted)
- results = await client.find(query="encrypted")
- print(f"Found {len(results)} results")
-
- await client.close()
+ # OPENVIKING_API_KEY: use a tenant-bound user/admin key when authentication is enabled.
+ client = AsyncHTTPClient(url="http://localhost:1933")
+ try:
+ await client.initialize()
+ sample = Path("./encrypted-sample.txt")
+ sample.write_text("Hello, encrypted world!", encoding="utf-8")
+ imported = await client.add_resource(
+ path=str(sample),
+ wait=True,
+ timeout=120,
+ )
+ results = await client.find(
+ query="encrypted", target_uri=imported["root_uri"]
+ )
+ print(f"Found {len(results.get('resources', []))} resources")
+ finally:
+ await client.close()
asyncio.run(test())
```
-Done! Now all written data is automatically encrypted.
+It waits for import processing and checks retrieval; successful retrieval alone does not prove encryption at rest. Use [Check File Content](#method-1-check-file-content) to inspect the stored file header.
## API Key Hashing Configuration
@@ -409,10 +412,12 @@ ov backup ./backups/before-encryption.ovpack
```
2. Stop OpenViking. Enable encryption and point the storage configuration at a **new, empty** workspace/backend. Keep the original data and encryption key backup until verification is complete.
-3. Start the encrypted environment and restore the logical backup. Restore writes the package content through the encrypted storage layer:
+3. Start the encrypted environment. In API key mode, first create the target account and a restore operator with an admin key, then point the CLI at the target using that key, as described in [Full Backup and Restore](09-ovpack.md#full-backup-and-restore). Restore writes the package content through the encrypted storage layer:
+
+Account initialization creates scope directories, so `fail` would reject this restore. Confirm that the target contains only the newly created account's initial content before using `overwrite` below. If it already contains business data, stop and follow the target-backup and conflict-review steps in the OVPack guide instead.
```bash
-ov restore ./backups/before-encryption.ovpack --on-conflict fail
+ov restore ./backups/before-encryption.ovpack --on-conflict overwrite
```
4. Verify resource, user, session, and index data before switching traffic. OVPack excludes runtime/internal state such as queues, uploads, locks, and watches; recreate or validate those separately.
diff --git a/docs/en/guides/09-ovpack.md b/docs/en/guides/09-ovpack.md
index 5351dc814..3502ed261 100644
--- a/docs/en/guides/09-ovpack.md
+++ b/docs/en/guides/09-ovpack.md
@@ -10,6 +10,8 @@ validates the manifest, file list, directory list, and checksums so package
content cannot drift from the manifest. If an attacker can rewrite both content
and manifest, rely on external signatures, secure transport, and access control.
+Storage encryption does not encrypt the exported package. Export reads through the transparent decryption layer and writes plaintext content into a normal ZIP archive. Protect the `.ovpack` file independently during storage and transfer; possession of the archive is enough to read its content without the source storage key.
+
## Supported Scope
Regular `export/import` handles one package root:
@@ -40,16 +42,22 @@ Multi-write storage only replicates writes that happen after it is enabled. It
does not automatically copy historical files that already existed before
`storage.agfs.backups` was turned on.
-When migrating an existing environment to multi-write mode, first move the
-existing dataset with OVPack, then enable multi-write storage.
+To seed the primary and replicas together, enable multi-write on the **empty target environment before restoring** the package:
+
+1. Pause application writes and export or back up each source account.
+2. Configure the target primary and backup backends, including their write policies, then start the target server and provision its restore identity.
+3. Restore or import through that server so historical content passes through the configured write fanout.
+4. Check synchronization status for every restored scope and verify the expected files in each replica before switching traffic. Asynchronous replication can still be pending after restore returns.
+5. Resume writes after validating content and index integrity. Keep the source and backup until verification is complete.
+
+For example, using the target account's admin key:
-Recommended flow:
+```bash
+ov system backend sync-status viking://resources
+ov system backend sync-status viking://user
+```
-1. Use `ov backup` or `ov export` to export the current dataset.
-2. Restore or import the dataset into the target storage environment.
-3. Validate data and index integrity in the target environment.
-4. Configure and enable multi-write storage.
-5. Resume normal writes and let multi-write handle future incremental copies.
+Restoring first and enabling backups afterwards only replicates subsequent writes; it does not seed historical content into replicas.
For more details, see the [Multi-Write Storage Guide](./13-multi-write-storage.md).
@@ -165,10 +173,34 @@ Backup reads live files and is not an atomic point-in-time snapshot. Content
that changes during backup may represent different moments. Pause writes during
the backup window when strict consistency is required.
-When restoring into a new environment, restore content first and then create
-users with the same `user_id` values found in the package. Existing user
-directories do not mean that user accounts exist, and the target environment
-generates new API keys.
+In API key mode, a new target needs an account and an admin identity **before** restore. The root key can create that identity but cannot call tenant-scoped pack APIs. Set `OPENVIKING_ROOT_API_KEY` to the target root key, then call the target server to create the account with a restore operator whose user ID is absent from the package:
+
+```bash
+curl -f -X POST http://localhost:1933/api/v1/admin/accounts \
+ -H "X-API-Key: $OPENVIKING_ROOT_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"account_id": "acme", "admin_user_id": "restore-operator"}'
+```
+
+Use the returned `user_key` as `api_key` in a dedicated target client config, for example `restore.ovcli.conf`:
+
+```json
+{
+ "url": "http://localhost:1933",
+ "api_key": "<target-admin-user-key>"
+}
+```
+
+Account initialization already creates scope directories. Consequently, `fail` rejects a restore even when this new account contains no business data; choosing a different restore operator does not avoid that scope-level check. Confirm that the target contains **only the newly created account's initial content**, then restore with `overwrite`:
+
+```bash
+OPENVIKING_CLI_CONFIG_FILE=./restore.ovcli.conf \
+ ov restore ./backups/openviking.ovpack --on-conflict overwrite
+```
+
+For an existing target account, use its admin key instead of creating it again. If it contains business data, do not run this command unchanged: pause writes, back up the target, and review the package paths against target content before deciding what may be overwritten, or use a separate clean target. `overwrite` replaces matching paths; a file/directory type conflict can remove the existing subtree. `fail` checks for existing scope roots, not individual file conflicts, and `skip` skips the whole restore when a scope exists. Each backup/restore is account-scoped; repeat with the appropriate identity for other accounts.
+
+After restoring content, register the remaining users with the same `user_id` values found in the package. Existing user directories do not mean that user accounts exist. The target generates new API keys; source keys are not restored. Verify reads with each target user's key before switching clients.
## Python SDK
@@ -326,7 +358,7 @@ curl -X POST http://localhost:1933/api/v1/pack/backup \
The table above describes regular `import`. For full `restore`, `overwrite`
performs a merge-upsert: missing target paths are created, matching paths are
-overwritten, and target-only paths absent from the backup are preserved. Restore
+overwritten, and target-only paths absent from the backup are normally preserved. If a package file replaces an existing directory (or vice versa), restore removes the conflicting target first; existing descendants of that directory are also removed. Restore
does not delete the full `viking://resources` or `viking://user` tree, and it
does not create or write the aggregate `viking://user` container itself.
Vectors are restored or recomputed only for package content that is added or
diff --git a/docs/en/guides/12-public-access.md b/docs/en/guides/12-public-access.md
index 1bdd98289..e14999934 100644
--- a/docs/en/guides/12-public-access.md
+++ b/docs/en/guides/12-public-access.md
@@ -14,6 +14,41 @@ public HTTPS domain.
Prerequisites: a public domain, ports 80 + 443 reachable, DNS pointing at
your host.
+## Authenticate before exposing the proxy
+
+Configure authentication before publishing any route, including when the upstream listens on `127.0.0.1`. A reverse proxy makes that localhost service reachable from the internet. The default `dev` mode accepts requests as ROOT; TLS and `OPENVIKING_PUBLIC_BASE_URL` do not add authentication.
+
+For API key authentication, merge this section into `ov.conf`, replace the placeholder with a secret, and restart the server:
+
+```json
+{
+ "server": {
+ "auth_mode": "api_key",
+ "root_api_key": "<your-secret-root-key>"
+ }
+}
+```
+
+Use the root key only for administration, such as creating the account and its first admin through the [Admin API](04-authentication.md#managing-accounts-and-users). Use the resulting user/admin key for tenant data APIs. Do not put the root key in a public browser client or configure the proxy to attach it to all requests. Keep the backend port private so clients use the intended HTTPS entrypoint.
+
+Before allowing users to connect, check the public URL:
+
+```bash
+# Expected: 401 in the API key setup above, never a successful directory listing.
+curl -sS -o /dev/null -w '%{http_code}\n' \
+ 'https://ov.your-domain.com/api/v1/fs/ls?uri=viking://resources'
+
+# Set OPENVIKING_API_KEY to a tenant-bound user/admin key first. Expected: 200.
+curl -sS -o /dev/null -w '%{http_code}\n' \
+ -H "X-API-Key: $OPENVIKING_API_KEY" \
+ 'https://ov.your-domain.com/api/v1/fs/ls?uri=viking://resources'
+
+# Health is intentionally unauthenticated; 200 here does not verify access control.
+curl -sS https://ov.your-domain.com/health
+```
+
+If you use OIDC or a trusted identity gateway instead, follow that mode's [authentication requirements](04-authentication.md) and verify rejection of unauthenticated data requests. Do not expose a `trusted` backend directly to callers who can supply their own identity headers.
+
<a id="adding-https-for-public-access"></a>
## Option A: bundled Caddy with auto Let's Encrypt (recommended)
@@ -36,7 +71,7 @@ as the issuer in OAuth metadata and `WWW-Authenticate` headers) and Caddy
```caddyfile
{$OPENVIKING_PUBLIC_BASE_URL} {
- reverse_proxy openviking:1933
+ reverse_proxy openviking:{$OPENVIKING_SERVER_PORT:1933}
# Pin ACME registration email (optional):
# tls {$OV_ACME_EMAIL}
}
@@ -158,7 +193,7 @@ or in `ov.conf`:
## Compatibility note: the `:1934` single-upstream proxy
`docker compose up` also ships a Caddy reverse proxy on port 1934, simply
-`reverse_proxy openviking:1933` — **kept only for compatibility with
+`reverse_proxy openviking:{$OPENVIKING_SERVER_PORT:1933}` — **kept only for compatibility with
deployments that already bookmarked 1934**. New deployments can connect to
1933 directly; there is no routing value here. Remove the caddy service and
the 1934 port mapping in `docker-compose.yml` if you don't need it.
diff --git a/docs/en/guides/13-multi-write-storage.md b/docs/en/guides/13-multi-write-storage.md
index 0916b5eee..e812966aa 100644
--- a/docs/en/guides/13-multi-write-storage.md
+++ b/docs/en/guides/13-multi-write-storage.md
@@ -9,7 +9,7 @@ Multi-write lives inside RAGFS. The Python SDK, HTTP API, and CLI usage remain u
- You already have a working `ov.conf`.
- The primary backend has been verified to read and write correctly.
- If you plan to use S3-compatible storage, prepare the bucket, endpoint, and access credentials first.
-- If you need to migrate existing data, migrate that dataset before enabling multi-write.
+- For existing data, follow the [OVPack multi-write migration workflow](./09-ovpack.md#working-with-multi-write-storage); enabling backups alone does not copy historical files.
## Minimal Configuration
@@ -359,16 +359,7 @@ Rules:
Multi-write only replicates writes that happen after it is enabled. It does not automatically copy historical files.
-Recommended migration flow:
-
-1. Stop writes or freeze the write window.
-2. Use OVPack or another controlled tool to migrate historical data to the target backup.
-3. Validate the target backend's data integrity.
-4. Configure and enable `storage.agfs.backups`.
-5. Resume writes.
-6. Observe sync state and error logs.
-
-If freezing writes is not possible, do one full migration first, then a short write pause for incremental validation, and only then enable multi-write.
+For OVPack migration, follow [Working with Multi-Write Storage](./09-ovpack.md#working-with-multi-write-storage): configure multi-write on the clean target before restoring through that server, then verify each replica before resuming writes. That guide also covers target account initialization and restore conflict handling.
## Verifying the Configuration
@@ -408,7 +399,7 @@ Backups are write-only by default. To make a backup serve reads, configure:
### Why do historical files not appear in the backup after enabling multi-write?
-Multi-write only handles new writes after it is enabled. Historical data must be migrated separately through OVPack, object-storage copy workflows, or future backfill capabilities.
+Multi-write only handles new writes after it is enabled. For historical data, follow the [OVPack migration workflow](./09-ovpack.md#working-with-multi-write-storage); enabling backups does not backfill it.
### Can async mode guarantee that the newest data is immediately readable from a backup?
diff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.md
index 5d2fc4c4b..8de2112ef 100644
--- a/docs/zh/configuration/01-server.md
+++ b/docs/zh/configuration/01-server.md
@@ -331,9 +331,7 @@ Provider 和密钥管理配置见[加密指南](../guides/08-encryption.md)。
"prefetch_search_topn": 5,
"extraction_enabled": true,
"session_skill_extraction_enabled": false,
- "link_enabled": false,
- "v2_lock_retry_interval_seconds": 0.2,
- "v2_lock_max_retries": 0
+ "link_enabled": false
}
}
```
@@ -349,8 +347,6 @@ Provider 和密钥管理配置见[加密指南](../guides/08-encryption.md)。
| `extraction_enabled` | boolean | `true` | session commit 时是否抽取长期记忆 |
| `session_skill_extraction_enabled` | boolean | `false` | 是否同时抽取可复用 Skill |
| `link_enabled` | boolean | `false` | 是否生成和解析记忆链接 |
-| `v2_lock_retry_interval_seconds` | number,`>= 0` | `0.2` | 记忆锁获取失败后的重试间隔 |
-| `v2_lock_max_retries` | integer,`>= 0` | `0` | 最大重试次数;`0` 表示不限次数 |
## 解析器配置
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index da847caf2..88ada4f4e 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -414,7 +414,7 @@ OpenAI 已于 2026 年 8 月 31 日[停止在 ChatGPT 登录的 Codex 中提供
**gemini provider 配置示例:**
-> **注意:** 需安装 `pip install "google-genai>=1.0.0"`。异步批量嵌入:`pip install "openviking[gemini-async]"`。
+> **注意:** 需要在服务端环境安装 `google-genai>=1.0.0`——uv 安装:`uv tool install openviking --upgrade --with "google-genai>=1.0.0"`;pip 安装:`pip install "google-genai>=1.0.0"`。异步批量嵌入改用 extra:`uv tool install "openviking[gemini-async]" --upgrade` 或 `pip install "openviking[gemini-async]"`。
```json
{
@@ -1493,39 +1493,6 @@ acl_inherited_grants
火山向量库等远端 backend 的存量 collection 需要由部署方预先添加这些字段和 scalar index,OpenViking 只校验 schema。`volcengine` API key 数据面模式还要求 context collection 和配置的 index 已存在。权限模型详见 [资源访问控制(ACL)](../concepts/15-acl.md)。
-<details>
-<summary><b>openGauss</b></summary>
-
-需要 openGauss 服务端支持原生 `vector` 类型,并使用允许远程连接的数据库用户。
-可通过 `pip install "openviking[opengauss]"` 安装可选驱动。
-官方容器中的初始 `omm` 用户可能限制远程登录,必要时请为 OpenViking 创建普通数据库用户。
-
-```json
-{
- "storage": {
- "vectordb": {
- "name": "context",
- "backend": "opengauss",
- "project": "default",
- "distance_metric": "cosine",
- "dimension": 1024,
- "opengauss": {
- "host": "127.0.0.1",
- "port": 5432,
- "user": "openviking",
- "password": "your-password",
- "db_name": "postgres",
- "schema": "public",
- "mode": "standalone"
- }
- }
- }
-}
-```
-
-分布式 openGauss 部署可将 `mode` 设为 `"distributed"`;OpenViking 会尝试把元数据表标记为 reference table,并按 `id` 分布集合表。
-</details>
-
## 配置文件
@@ -1628,14 +1595,14 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远
trusted 网关部署下,也可以在单次命令里用 CLI 参数覆盖这些身份字段:
```bash
-openviking --account acme --user alice ls viking://
+ov --account acme --user alice ls viking://
```
对于 `add-resource`,上传过滤参数会与 `ovcli.conf` 默认值做合并(追加),不会覆盖:
```bash
# ovcli.conf: upload.exclude="*.log"
-openviking add-resource ./docs --exclude "*.tmp"
+ov add-resource ./docs --exclude "*.tmp"
# 实际发送给服务端的 exclude: "*.log,*.tmp"
```
@@ -1681,8 +1648,8 @@ openviking add-resource ./docs --exclude "*.tmp"
|------|------|------|--------|
| `host` | str | 绑定地址 | `127.0.0.1` |
| `port` | int | 绑定端口 | `1933` |
-| `auth_mode` | str | 认证模式:`"api_key"` 或 `"trusted"`。默认值为 `"api_key"` | `"api_key"` |
-| `root_api_key` | str | Root API Key。在 `api_key` 模式下启用多租户认证;在 `trusted` 模式下它只是可选附加保护,不负责解析普通用户身份 | `null` |
+| `auth_mode` | str / null | 内置模式:`"dev"`、`"api_key"`、`"trusted"`、`"oidc"`、`"ldap"`。省略或设为 null 时,有非空 `root_api_key` 则推导为 `api_key`,否则为 `dev`。 | `null` |
+| `root_api_key` | str | `api_key` 模式必填的 Root API Key;`trusted` 模式仅在 localhost 可省略,非 localhost 部署必填,不负责解析普通用户身份 | `null` |
| `profile_enabled` | bool | 是否允许 HTTP 请求通过 `profile=1` 开启请求级 cProfile。关闭时服务端会忽略该请求参数;开启后,CLI 可以显示返回的 `profile`,而 Python HTTP client 默认只触发服务端 profile,不会把顶层 `profile` 字段自动附着到大多数 SDK 返回值上。 | `false` |
| `cors_origins` | list | CORS 允许的来源 | `["*"]` |
| `public_base_url` | str | MCP `add_resource` 工具向客户端返回的上传指令里使用的对外可见 base URL。解析顺序:环境变量 `OPENVIKING_PUBLIC_BASE_URL` → 本字段 → 请求头 `X-Forwarded-Host` / `X-Forwarded-Proto` → 请求头 `Host` → 监听地址兜底。当 server 部署在反向代理后且代理不转发 `X-Forwarded-*` 时,请显式设置本字段(或环境变量)。 | `null` |
@@ -1695,9 +1662,9 @@ openviking add-resource ./docs --exclude "*.tmp"
| `user_config_defaults.memory_policy` | object | Session 和 User 都未显式配置策略时使用的部署级默认记忆抽取策略。 | `null` |
| `agent_evolution.enabled` | bool | 实例级 Agent 进化开关。开启时,session commit 可按 session `memory_policy` 生成或更新 cases、trajectories 和 experiences;关闭时,所有账号和用户均停止生产这三类记忆。已有记忆仍可读取和检索。 | `false` |
-`api_key` 模式使用 API Key 认证,也是默认模式;`trusted` 模式信任上游网关或受信调用方注入的 `X-OpenViking-Account` / `X-OpenViking-User` 请求头。
+省略 `auth_mode`(或设为 `null`)时,配置了非空 `root_api_key` 则选择 `api_key`,否则选择 `dev`。`dev` 仅允许监听 localhost,不进行身份认证。`root_api_key` 不能配置为空字符串。
-在 `api_key` 模式下配置 `root_api_key` 后,服务端启用正式多租户认证,并通过 Admin API 创建工作区和用户 key。在 `trusted` 模式下,普通请求不需要先注册 user key;每个请求都会根据注入的身份头解析成 `USER`。只有在 `auth_mode = "api_key"` 且未配置 `root_api_key` 时,服务端才会进入开发模式。
+显式设置 `auth_mode: "api_key"` 时,包括 localhost 在内都必须提供非空 `root_api_key`;缺少该 key 会导致启动失败,不会回退到开发模式。使用 root key 调用 Admin API 创建 account 和 user/admin key,数据访问使用这些绑定租户身份的 key。`trusted` 模式接受可信网关注入的 account/user 身份头,无需预先创建 user key;其 root key 仅在 localhost 可省略,监听非 localhost 地址时必填。角色解析、OIDC/LDAP 配置与网关要求参见 [身份认证](04-authentication.md)。
`user_config_defaults` 提供添加目标和记忆抽取的部署级默认配置。添加操作中,显式请求目标仍然优先:`add_resource.to` / `add_resource.parent` 优先于用户默认值,`add_skill.target_uri` 优先于用户默认值。记忆策略优先级为 Session 策略 > User `settings/user_config.json` 策略 > `server.user_config_defaults.memory_policy` > 内核默认策略。`agent_evolution.enabled` 是当前 OpenViking 实例的统一开关,不支持用户级覆盖。HTTP Server 的 worker 会在 session commit 时从解析后的 `ov.conf` 读取当前 Agent 进化配置,因此合法的文件更新无需重启服务即可生效。
@@ -1925,7 +1892,7 @@ Task 记录文件位于所属账号的系统目录:
"extra_request_body": {}
},
"rerank": {
- "provider": "volcengine|openai",
+ "provider": "vikingdb|cohere|openai|litellm",
"api_key": "string",
"model": "string",
"api_base": "string",
@@ -1966,7 +1933,7 @@ Task 记录文件位于所属账号的系统目录:
"lock_expire": 300.0
},
"vectordb": {
- "backend": "local|remote",
+ "backend": "local|cuvs|http|volcengine|vikingdb",
"url": "string",
"project": "string"
}
diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.md
index 7a48c2256..d2900a371 100644
--- a/docs/zh/guides/03-deployment.md
+++ b/docs/zh/guides/03-deployment.md
@@ -121,7 +121,7 @@ User=your-username
Group=your-group
# 替换为工作目录
WorkingDirectory=/var/lib/openviking
-# 以下两种启动方式二选一
+# 使用实际安装位置中的绝对路径
ExecStart=/path/to/your/python/bin/openviking-server
Restart=always
RestartSec=5
@@ -132,6 +132,8 @@ Environment="OPENVIKING_CONFIG_FILE=/etc/openviking/ov.conf"
WantedBy=multi-user.target
```
+启动前替换所有占位值。以服务用户运行 `command -v openviking-server` 确认可执行文件路径,创建工作目录,并让该用户能够访问配置、workspace 及本地加密密钥。此 unit 使用 `/etc/openviking/ov.conf`,不会自动使用你个人 home 目录下生成的配置。系统服务省略 `User` 会以 root 运行。
+
### 管理服务
创建好服务文件后,使用以下命令管理 OpenViking 服务:
@@ -157,8 +159,12 @@ sudo journalctl -u openviking.service -f
### Python SDK
+```bash
+python -m pip install --upgrade openviking-sdk
+```
+
```python
-import openviking as ov
+import openviking_sdk as ov
client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")
client.initialize()
diff --git a/docs/zh/guides/04-authentication.md b/docs/zh/guides/04-authentication.md
index 49ae032e0..a739fa6aa 100644
--- a/docs/zh/guides/04-authentication.md
+++ b/docs/zh/guides/04-authentication.md
@@ -480,6 +480,8 @@ ACL 用户组是例外:组和成员通过 [Admin API](../api/08-admin.md#用
- 携带受信部署自身的 `root_api_key`。对于 `/api/v1/admin/*`,服务端校验该 key 后会将请求视为 ROOT。
- 如果 Admin 路由指向具体 account/user,也可以同时携带 `X-OpenViking-Account` + `X-OpenViking-User`。这些 header 必须与目标 URL 匹配,并会保留为请求身份;授权仍来自受信 `root_api_key`。
+角色更新 API 只支持将用户提升为 ADMIN。Trusted Admin API 的管理权限来自已校验的部署 root key,无需也不支持创建 ROOT 用户。
+
下面是“受信上游身份”这种方式的示例:
```bash
@@ -489,12 +491,6 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \
-H "Content-Type: application/json" \
-d '{"account_id": "platform", "admin_user_id": "gateway-admin"}'
-# 如果它需要跨 account 的管理权限,再提升为 root
-curl -X PUT http://localhost:1933/api/v1/admin/accounts/platform/users/gateway-admin/role \
- -H "X-API-Key: your-secret-root-key" \
- -H "Content-Type: application/json" \
- -d '{"role": "root"}'
-
# 然后,在 trusted 模式下使用该身份调用 Admin API
curl -X POST http://localhost:1933/api/v1/admin/accounts \
-H "X-API-Key: your-secret-root-key" \
diff --git a/docs/zh/guides/08-encryption.md b/docs/zh/guides/08-encryption.md
index c3ed9dfb0..0375db75f 100644
--- a/docs/zh/guides/08-encryption.md
+++ b/docs/zh/guides/08-encryption.md
@@ -55,6 +55,8 @@ ov system crypto init-key --output-file ~/.openviking/master.key
### 3. 验证
+修改加密配置后重启服务,再对该服务运行示例。在运行脚本的环境中安装 [Python SDK](../api/01-overview.md#完全不依赖配置文件使用-python-sdk-客户端)。
+
```python
import asyncio
from pathlib import Path
@@ -62,28 +64,29 @@ from openviking_sdk import AsyncHTTPClient
async def test():
- client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")
- await client.initialize()
-
- # add_resource 接收文件路径或 URL
- sample = Path("./encrypted-sample.txt")
- sample.write_text("Hello, encrypted world!", encoding="utf-8")
- await client.add_resource(
- path=str(sample),
- options={"reason": "测试加密"},
- )
-
- # 读取资源(自动解密)
- results = await client.find(query="encrypted")
- print(f"找到 {len(results)} 个结果")
-
- await client.close()
+ # 启用认证时,将 OPENVIKING_API_KEY 设置为绑定租户身份的 user/admin key。
+ client = AsyncHTTPClient(url="http://localhost:1933")
+ try:
+ await client.initialize()
+ sample = Path("./encrypted-sample.txt")
+ sample.write_text("Hello, encrypted world!", encoding="utf-8")
+ imported = await client.add_resource(
+ path=str(sample),
+ wait=True,
+ timeout=120,
+ )
+ results = await client.find(
+ query="encrypted", target_uri=imported["root_uri"]
+ )
+ print(f"找到 {len(results.get('resources', []))} 个资源")
+ finally:
+ await client.close()
asyncio.run(test())
```
-完成!现在所有写入的数据都会自动加密。
+示例会等待导入处理完成并检查检索;检索成功本身不能证明文件已加密。请按下方“验证加密”的文件内容检查步骤确认存储文件头。
## API Key 哈希配置
@@ -409,10 +412,12 @@ ov backup ./backups/before-encryption.ovpack
```
2. 停止 OpenViking,启用加密,并将存储配置指向**全新的空** workspace/backend。验证完成前保留原数据和加密密钥备份。
-3. 启动加密环境后恢复逻辑备份。恢复过程会通过加密存储层写入 package 内容:
+3. 启动加密环境。API Key 模式下,先创建目标 account 和持有 admin key 的恢复操作用户,再让 CLI 使用该 key 连接目标环境,参见 [全量备份和恢复](09-ovpack.md#全量备份和恢复)。恢复过程会通过加密存储层写入 package 内容:
+
+创建 account 会生成 scope 目录,因此 `fail` 会拒绝这次恢复。仅在确认目标只有新建 account 的预置内容后,使用下方的 `overwrite`。如果已有业务数据,先停止操作,按 OVPack 指南备份目标并审查冲突。
```bash
-ov restore ./backups/before-encryption.ovpack --on-conflict fail
+ov restore ./backups/before-encryption.ovpack --on-conflict overwrite
```
4. 切流前验证资源、用户、session 和索引数据。OVPack 不包含 queue、upload、lock、watch 和 relation 文件等运行时/内部状态,这些内容需要单独重建或验证。
diff --git a/docs/zh/guides/09-ovpack.md b/docs/zh/guides/09-ovpack.md
index 2bf623044..eb187c342 100644
--- a/docs/zh/guides/09-ovpack.md
+++ b/docs/zh/guides/09-ovpack.md
@@ -7,6 +7,8 @@ OVPack 不是裸 ZIP 拷贝,也不是可信发布格式。导入会校验 mani
checksum,保证包内容没有偏离 manifest;如果攻击者能同时篡改文件和 manifest,仍需要依赖
外部签名、传输安全和访问控制。
+存储加密不会加密导出的备份包。导出会经过透明解密层读取文件,再把明文内容写入普通 ZIP 归档。应独立保护 `.ovpack` 文件的存储和传输;拿到归档即可读取内容,无需源存储的密钥。
+
## 支持范围
普通 `export/import` 处理一个包根:
@@ -31,15 +33,22 @@ Session 通过 user 命名空间一起迁移,路径为
## 与多写存储配合
-多写存储只复制启用之后的新写入,不会自动同步启用之前已经存在的历史文件。将已有环境迁移到多写模式时,建议先用 OVPack 完成存量数据迁移,再开启 `storage.agfs.backups`。
+多写存储只复制启用之后的新写入,不会自动同步启用之前已经存在的历史文件。如需同时为 primary 和副本写入存量,应在**空目标环境恢复之前**启用多写:
+
+1. 暂停业务写入,按源 account 分别导出或备份。
+2. 配置目标 primary、backup backend 及其写策略,启动目标服务并创建恢复身份。
+3. 通过该服务恢复或导入,使存量内容经过已配置的多写分发。
+4. 对每个恢复的 scope 检查同步状态,并在切流前验证各副本中的文件。恢复返回时,异步复制仍可能未完成。
+5. 验证内容和索引完整性后再恢复业务写入;验证完成前保留源数据和备份。
+
+例如,使用目标 account 的 admin key 检查:
-推荐流程:
+```bash
+ov system backend sync-status viking://resources
+ov system backend sync-status viking://user
+```
-1. 使用 `ov backup` 或 `ov export` 导出现有内容。
-2. 在目标存储环境恢复或导入数据。
-3. 校验目标环境内容和索引状态。
-4. 配置并启用多写存储。
-5. 恢复正常写入,让后续增量由多写机制复制。
+先恢复再启用 backups 只会复制后续写入,不能把历史内容补到副本。
更多说明见 [多写存储指南](./13-multi-write-storage.md)。
@@ -144,8 +153,34 @@ ov restore ./backups/openviking.ovpack --on-conflict overwrite
备份是在线逐文件读取,不是同一时刻的原子快照。备份期间仍在变化的内容可能来自不同时间点;
需要严格一致性时,应由使用方在备份窗口暂停写入。
-恢复到新环境时,先恢复内容,再使用备份中的相同 `user_id` 创建用户。用户目录已存在不代表
-用户账号已经创建,API Key 会由目标环境重新生成。
+API Key 模式下,新目标必须在恢复**之前**具备 account 和管理员身份。root key 可以创建这个身份,但不能调用租户级 pack API。先将 `OPENVIKING_ROOT_API_KEY` 设置为目标 root key,再调用目标服务创建 account,并选择一个不在备份包中的用户 ID 作为恢复操作用户:
+
+```bash
+curl -f -X POST http://localhost:1933/api/v1/admin/accounts \
+ -H "X-API-Key: $OPENVIKING_ROOT_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"account_id": "acme", "admin_user_id": "restore-operator"}'
+```
+
+把返回的 `user_key` 作为 `api_key` 写入专用的目标客户端配置,例如 `restore.ovcli.conf`:
+
+```json
+{
+ "url": "http://localhost:1933",
+ "api_key": "<target-admin-user-key>"
+}
+```
+
+创建 account 已会生成 scope 目录。因此,即使新 account 还没有业务数据,`fail` 也会拒绝恢复;使用不同的恢复操作用户不能避开这个 scope 级检查。确认目标**只有新建 account 的预置内容**后,再使用 `overwrite`:
+
+```bash
+OPENVIKING_CLI_CONFIG_FILE=./restore.ovcli.conf \
+ ov restore ./backups/openviking.ovpack --on-conflict overwrite
+```
+
+如果目标 account 已存在,使用它的 admin key,不要重复创建。如果其中已有业务数据,不要直接照抄这条恢复命令:先暂停写入、备份目标,并比对包内路径和目标内容,明确允许覆盖的内容,或使用独立的干净目标。`overwrite` 会替换同路径内容;文件与目录的类型冲突可能删除已有子树。`fail` 检查 scope 根是否存在,不是逐文件冲突预检;`skip` 在 scope 已存在时跳过整次恢复。每次备份/恢复均以 account 为边界;其他 account 需要使用对应身份分别处理。
+
+恢复内容后,再按备份中的相同 `user_id` 注册其余用户。用户目录已存在不代表用户账号已创建。目标会生成新 API Key,不会恢复源 key;切换客户端前,应使用各目标用户的 key 验证读取。
## Python SDK
@@ -301,6 +336,8 @@ curl -X POST http://localhost:1933/api/v1/pack/backup \
`skip` 是 root 级跳过,不是文件级补齐导入。
+文件和目录类型冲突是合并覆盖的例外:如果包内文件替换目标目录(或反向替换),恢复会先删除冲突目标;该目录已有的后代也会被删除。
+
上表描述普通 `import`。全量 `restore` 的 `overwrite` 使用合并覆盖:包内不存在的目标路径会
创建,同路径内容会覆盖,目标环境中仅有而备份中没有的路径会保留。恢复不会删除整个
`viking://resources` 或 `viking://user`,也不会创建或写入 `viking://user` 聚合目录本身。
diff --git a/docs/zh/guides/12-public-access.md b/docs/zh/guides/12-public-access.md
index d5e86a60b..5f607715c 100644
--- a/docs/zh/guides/12-public-access.md
+++ b/docs/zh/guides/12-public-access.md
@@ -11,6 +11,41 @@ OpenViking 默认在 1933 端口对外提供 REST API、MCP、OAuth、`.well-kno
前提:有公网域名、80 + 443 端口可达、DNS 已指向。
+## 先配置认证,再开放反向代理
+
+发布任何路由前都要配置认证,即使上游只监听 `127.0.0.1`。反向代理会让这个本地服务可从公网访问。默认 `dev` 模式以 ROOT 身份接受请求;TLS 和 `OPENVIKING_PUBLIC_BASE_URL` 都不会增加身份认证。
+
+使用 API Key 认证时,将下面的配置合并到 `ov.conf`,用密钥替换占位值,然后重启服务:
+
+```json
+{
+ "server": {
+ "auth_mode": "api_key",
+ "root_api_key": "<your-secret-root-key>"
+ }
+}
+```
+
+root key 仅用于管理操作,例如通过 [Admin API](04-authentication.md) 创建 account 和首个管理员。租户数据 API 使用返回的 user/admin key。不要把 root key 放进公开的浏览器客户端,也不要让反向代理为所有请求自动附加 root key。后端端口应保持私有,让客户端通过预期的 HTTPS 入口访问。
+
+允许用户接入前,在公网 URL 上验证:
+
+```bash
+# 上述 API Key 配置下预期为 401,不能成功返回目录列表。
+curl -sS -o /dev/null -w '%{http_code}\n' \
+ 'https://ov.your-domain.com/api/v1/fs/ls?uri=viking://resources'
+
+# 先将 OPENVIKING_API_KEY 设置为绑定租户身份的 user/admin key。预期为 200。
+curl -sS -o /dev/null -w '%{http_code}\n' \
+ -H "X-API-Key: $OPENVIKING_API_KEY" \
+ 'https://ov.your-domain.com/api/v1/fs/ls?uri=viking://resources'
+
+# health 刻意不要求认证;这里的 200 不能证明访问控制已生效。
+curl -sS https://ov.your-domain.com/health
+```
+
+如果使用 OIDC 或可信身份网关,应遵循对应模式的 [认证要求](04-authentication.md),并验证未认证的数据请求会被拒绝。不要让可自行填写身份请求头的调用者直接访问 `trusted` 后端。
+
<a id="添加-https公网访问"></a>
## 方式 A:用自带 Caddy 自动签发 Let's Encrypt 证书(推荐)
@@ -32,7 +67,7 @@ [email protected] # 可选;推荐用于 Let's Encrypt
```caddyfile
{$OPENVIKING_PUBLIC_BASE_URL} {
- reverse_proxy openviking:1933
+ reverse_proxy openviking:{$OPENVIKING_SERVER_PORT:1933}
# 绑定 ACME 注册邮箱(可选):
# tls {$OV_ACME_EMAIL}
}
diff --git a/docs/zh/guides/13-multi-write-storage.md b/docs/zh/guides/13-multi-write-storage.md
index 6212dfae7..37d352d39 100644
--- a/docs/zh/guides/13-multi-write-storage.md
+++ b/docs/zh/guides/13-multi-write-storage.md
@@ -9,7 +9,7 @@
- 已有可用的 `ov.conf`。
- 已确认 primary backend 可以正常读写。
- 如果要接入 S3 兼容存储,已准备好 bucket、endpoint 和访问凭据。
-- 如果要迁移已有数据,先完成存量数据迁移,再启用多写。
+- 如需迁移已有数据,请遵循 [OVPack 多写迁移流程](./09-ovpack.md#与多写存储配合);仅启用 backups 不会复制历史文件。
## 最小配置
@@ -359,16 +359,7 @@ Exclude 用于让某个 backup 跳过匹配文件。
多写只复制启用之后的新写入,不会自动复制历史文件。
-推荐迁移流程:
-
-1. 停止或冻结写入窗口。
-2. 使用 OVPack 或其他受控工具把存量数据迁移到目标 backup。
-3. 校验目标 backend 的数据完整性。
-4. 配置并启用 `storage.agfs.backups`。
-5. 恢复写入。
-6. 观察同步状态和错误日志。
-
-如果无法冻结写入,可以先做一次全量迁移,再短暂停写做增量校验,最后启用多写。
+使用 OVPack 迁移时,请遵循 [与多写存储配合](./09-ovpack.md#与多写存储配合):先在干净目标配置多写,再通过该服务恢复,验证各副本后恢复业务写入。目标 account 初始化和恢复冲突处理也在该流程中说明。
## 验证配置
@@ -408,7 +399,7 @@ backup 默认只参与写入,不参与读取。需要在 backup 上显式配
### 为什么启用多写后历史文件没有出现在 backup?
-多写只处理启用后的新写入。历史文件需要先通过 OVPack、对象存储复制或后续 backfill 能力迁移。
+多写只处理启用后的新写入。历史文件请按 [OVPack 迁移流程](./09-ovpack.md#与多写存储配合) 处理;启用 backups 不会自动补齐。
### 异步模式下能否保证立即读到 backup 的最新数据?