Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: add S3-compatible storage pitfalls to multi-write guide (#3390)
blakejia12b4aab13d6f
diff --git a/docs/en/guides/13-multi-write-storage.md b/docs/en/guides/13-multi-write-storage.mdindex b0375432a..c16385161 100644--- a/docs/en/guides/13-multi-write-storage.md+++ b/docs/en/guides/13-multi-write-storage.md@@ -75,7 +75,8 @@ You can configure more than one backup. The following example writes to both a l"endpoint": "https://s3.example.com","access_key": "your-access-key","secret_key": "your-secret-key",- "prefix": "openviking"+ "prefix": "openviking",+ "directory_marker_mode": "none"}}]@@ -91,6 +92,48 @@ Recommendations:- The backup path or bucket should not point to the same physical location as the primary backend.- Changing a backup `name` affects historical sync metadata recognition, so treat that as a production change.+### S3-Compatible Storage Notes++When using S3-compatible services (MinIO, RustFS, Ceph, etc.), the `s3` section requires additional fields:++| Field | Required? | Description |+| --- | --- | --- |+| `use_path_style` | Yes for most S3-compatible | Set to `true` for path-style URLs (`http://host/bucket/key`). Most S3-compatible services require this. |+| `directory_marker_mode` | Yes for S3-compatible | **Must be explicitly set to `"none"`**. Without this, the RAGFS Rust binding panics with `AGFSConfigError: invalid directory_marker_mode: null` during startup, causing a silent crash loop. |+| `use_ssl` | Optional | Set to `false` for HTTP endpoints (e.g. `http://localhost:9000`). |++**Minimal S3-compatible example (RustFS/MinIO):**++```json+{+ "name": "s3-backup",+ "backend": "s3",+ "s3": {+ "bucket": "my-bucket",+ "endpoint": "http://localhost:9000",+ "access_key": "your-access-key",+ "secret_key": "your-secret-key",+ "prefix": "openviking",+ "use_ssl": false,+ "use_path_style": true,+ "directory_marker_mode": "none"+ }+}+```++> **Why is `directory_marker_mode` required?**+>+> S3-compatible storage services handle "directories" differently from AWS S3. The RAGFS Rust binding must know whether to write directory marker objects when creating directories. Valid values are `"none"`, `"empty"`, and `"nonempty"`. For S3-compatible services that don't use directory markers (RustFS, MinIO, Ceph, etc.), set this to `"none"`. If omitted, the Rust binding defaults to `null` which is rejected, causing the server to crash silently during startup with `AGFSConfigError: invalid directory_marker_mode: null`.++### Docker Networking for S3 Backup++When running OpenViking in Docker with an S3 backup on the same host:++- **Linux Docker**: Use `--network host` or the host's LAN IP. Docker bridge network can reach the host's LAN via gateway IP (e.g. `172.17.0.1:9000`).+- **macOS/Windows Docker Desktop**: `--network host` is **not supported** on Docker Desktop. Use `host.docker.internal` as the S3 endpoint (maps to the host's localhost). Alternatively, use the host's LAN IP.++If the server crashes silently on startup with S3 backup enabled, check the Docker networking first. The RAGFS Rust binding will produce `dispatch failure` if the S3 endpoint is unreachable from inside the container.+## Choosing a Sync Mode### Async Modediff --git a/docs/zh/guides/13-multi-write-storage.md b/docs/zh/guides/13-multi-write-storage.mdindex 32a6473f0..1549592a0 100644--- a/docs/zh/guides/13-multi-write-storage.md+++ b/docs/zh/guides/13-multi-write-storage.md@@ -75,7 +75,8 @@"endpoint": "https://s3.example.com","access_key": "your-access-key","secret_key": "your-secret-key",- "prefix": "openviking"+ "prefix": "openviking",+ "directory_marker_mode": "none"}}]@@ -91,6 +92,48 @@- backup 的底层路径或 bucket 应避免与 primary 指向同一物理位置。- 修改 backup `name` 会影响历史同步元数据的识别,生产环境应谨慎变更。+### S3 兼容存储注意事项++使用 S3 兼容服务(MinIO、RustFS、Ceph 等)时,`s3` 段需要额外配置以下字段:++| 字段 | 是否必填 | 说明 |+| --- | --- | --- |+| `use_path_style` | 大多数 S3 兼容服务必填 | 设置为 `true` 使用路径风格 URL(`http://host/bucket/key`)。大多数 S3 兼容服务需要此配置。 |+| `directory_marker_mode` | S3 兼容服务必填 | **必须显式设置为 `"none"`**。如果不配置,RAGFS Rust binding 启动时会报 `AGFSConfigError: invalid directory_marker_mode: null` 并静默崩溃。 |+| `use_ssl` | 可选 | HTTP 端点(如 `http://localhost:9000`)需要设置为 `false`。 |++**S3 兼容存储最小示例(RustFS/MinIO):**++```json+{+ "name": "s3-backup",+ "backend": "s3",+ "s3": {+ "bucket": "my-bucket",+ "endpoint": "http://localhost:9000",+ "access_key": "your-access-key",+ "secret_key": "your-secret-key",+ "prefix": "openviking",+ "use_ssl": false,+ "use_path_style": true,+ "directory_marker_mode": "none"+ }+}+```++> **为什么需要 `directory_marker_mode`?**+>+> S3 兼容存储服务对"目录"的处理方式与 AWS S3 不同。RAGFS Rust binding 必须知道创建目录时是否需要写入目录标记对象。合法取值为 `"none"`、`"empty"` 和 `"nonempty"`。对于不使用目录标记的 S3 兼容服务(RustFS、MinIO、Ceph 等),设置为 `"none"`。如果省略,Rust binding 默认值为 `null`(不合法),导致服务端在启动时静默崩溃,报错 `AGFSConfigError: invalid directory_marker_mode: null`。++### Docker 网络配置++在 Docker 中运行 OpenViking 并配置同主机的 S3 备份时,需要注意:++- **Linux Docker**:使用 `--network host` 或宿主机局域网 IP。Docker bridge 网络可通过网关 IP(如 `172.17.0.1:9000`)访问宿主机局域网。+- **macOS/Windows Docker Desktop**:`--network host` **不支持**。S3 端点使用 `host.docker.internal`(映射为宿主机的 localhost),或使用宿主机局域网 IP。++如果启用 S3 备份后服务静默崩溃,请优先排查 Docker 网络。RAGFS Rust binding 在容器内无法访问 S3 端点时会报 `dispatch failure` 错误。+## 同步模式选择### 异步模式