Skip to content

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

Skip process lock (#2442)

Jiahui Zhou226ce46539cb
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index e2004769f..08fb143ad 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -853,6 +853,7 @@ Storage configuration for context data, including file storage (RAGFS) and vecto
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `workspace` | str | Local data storage path (main configuration) | "./data" |
+| `skip_process_lock` | bool | Whether to skip the startup process-lock check for `storage.workspace`. When enabled, OpenViking will not check or create the `.openviking.pid` lock file. | `false` |
| `agfs` | object | RAGFS (Rust-based AGFS) configuration | {} |
| `vectordb` | object | Vector database storage configuration | {} |
diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.md
index fc939f363..60200e01d 100644
--- a/docs/en/guides/03-deployment.md
+++ b/docs/en/guides/03-deployment.md
@@ -275,6 +275,58 @@ After startup, you can access:
- Web Studio: `http://localhost:1933/studio` (same origin as the API)
- Legacy entry point: `http://localhost:1934` (Caddy reverse proxy to 1933, kept for existing deployments)
+### Multi-instance notes
+
+For multi-instance deployments, prefer these settings:
+
+- Set `server.temp_upload.default_mode` to `"shared"` so uploaded temporary files can be consumed by a different replica.
+- Only set `storage.skip_process_lock` to `true` when multiple instances intentionally share the same `storage.workspace`. When enabled, OpenViking will no longer check or create `.openviking.pid`.
+- For QueueFS, prefer an explicit per-instance local SQLite path via `storage.agfs.queuefs.db_path`. If usage audit is enabled, prefer an explicit per-instance local SQLite path via `server.observability.usage_audit.sqlite_path` instead of mixing these files into a shared workspace volume.
+
+Example:
+
+```json
+{
+ "server": {
+ "temp_upload": {
+ "default_mode": "shared"
+ }
+ },
+ "storage": {
+ "skip_process_lock": true
+ }
+}
+```
+
+This example only applies when multiple instances intentionally share the same `workspace`. If each instance has its own local `workspace`, do not enable `skip_process_lock`.
+
+Example with explicit local SQLite paths for QueueFS and usage audit:
+
+```json
+{
+ "server": {
+ "temp_upload": {
+ "default_mode": "shared"
+ },
+ "observability": {
+ "usage_audit": {
+ "sqlite_path": "/var/lib/openviking-local/usage_audit.sqlite3"
+ }
+ }
+ },
+ "storage": {
+ "skip_process_lock": true,
+ "agfs": {
+ "queuefs": {
+ "db_path": "/var/lib/openviking-local/queue.db"
+ }
+ }
+ }
+}
+```
+
+This variant is useful when multiple instances share the same `workspace`, but QueueFS and usage audit SQLite files still need per-instance local paths.
+
For public HTTPS access, see the [Public Access Guide](12-public-access.md).
To build the image yourself, pass an explicit OpenViking version:
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 237079bb3..ca736fd01 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -823,6 +823,7 @@ AST 提取支持:Python、JavaScript/TypeScript、Rust、Go、Java、C/C++。
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `workspace` | str | 本地数据存储路径(主要配置) | "./data" |
+| `skip_process_lock` | bool | 是否跳过 `storage.workspace` 的启动进程锁检查。启用后,OpenViking 不会检查或创建 `.openviking.pid` 锁文件。 | `false` |
| `agfs` | object | RAGFS(Rust 实现的 AGFS)配置 | {} |
| `vectordb` | object | 向量库存储配置 | {} |
diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.md
index 53ff1f1db..cdef9d358 100644
--- a/docs/zh/guides/03-deployment.md
+++ b/docs/zh/guides/03-deployment.md
@@ -273,6 +273,58 @@ docker compose up -d
- Web Studio:`http://localhost:1933/studio`(与 API 同源)
- 兼容入口:`http://localhost:1934`(Caddy 反代到 1933,仅为已有部署保留)
+### 多实例部署注意事项
+
+多实例部署时,通常建议注意这几项配置:
+
+- 把 `server.temp_upload.default_mode` 设为 `"shared"`,这样临时上传文件可以被其他副本消费。
+- 只有在多个实例明确共享同一个 `storage.workspace` 时,才考虑把 `storage.skip_process_lock` 设为 `true`。启用后,OpenViking 不会再检查或创建 `.openviking.pid`。
+- 对 QueueFS,建议通过 `storage.agfs.queuefs.db_path` 显式指定实例本地的 SQLite 路径。如果启用了 usage audit,建议通过 `server.observability.usage_audit.sqlite_path` 显式指定实例本地的 SQLite 路径,不要默认和共享 workspace 卷混用。
+
+示例:
+
+```json
+{
+ "server": {
+ "temp_upload": {
+ "default_mode": "shared"
+ }
+ },
+ "storage": {
+ "skip_process_lock": true
+ }
+}
+```
+
+这个示例只适用于多个实例明确共享同一个 `workspace` 的场景。如果每个实例都有自己的本地 `workspace`,不要开启 `skip_process_lock`。
+
+如果你还需要为 QueueFS 和 usage audit 显式指定本地 SQLite 路径,可以参考:
+
+```json
+{
+ "server": {
+ "temp_upload": {
+ "default_mode": "shared"
+ },
+ "observability": {
+ "usage_audit": {
+ "sqlite_path": "/var/lib/openviking-local/usage_audit.sqlite3"
+ }
+ }
+ },
+ "storage": {
+ "skip_process_lock": true,
+ "agfs": {
+ "queuefs": {
+ "db_path": "/var/lib/openviking-local/queue.db"
+ }
+ }
+ }
+}
+```
+
+这个变体适用于多个实例共享同一个 `workspace`,但 QueueFS 和 usage audit 的 SQLite 文件仍然放在各实例本地路径的场景。
+
如需公网 HTTPS 访问,请参考 [公网访问指南](12-public-access.md)。
如需自行构建镜像,请显式传入 OpenViking 版本:
diff --git a/openviking/service/core.py b/openviking/service/core.py
index 8f73d583a..90eaab648 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -242,9 +242,15 @@ class OpenVikingService:
# Acquire advisory lock on data directory to prevent multi-process
# contention (see https://github.com/volcengine/OpenViking/issues/473).
- from openviking.utils.process_lock import acquire_data_dir_lock
+ if not self._config.storage.skip_process_lock:
+ from openviking.utils.process_lock import acquire_data_dir_lock
- acquire_data_dir_lock(self._config.storage.workspace)
+ acquire_data_dir_lock(self._config.storage.workspace)
+ else:
+ logger.warning(
+ "Skipping workspace process lock for '%s'; multi-process access may corrupt data",
+ self._config.storage.workspace,
+ )
if self._vikingdb_manager is None:
self._init_storage(
diff --git a/openviking_cli/utils/config/storage_config.py b/openviking_cli/utils/config/storage_config.py
index 2fa585400..059b1e4a6 100644
--- a/openviking_cli/utils/config/storage_config.py
+++ b/openviking_cli/utils/config/storage_config.py
@@ -23,6 +23,13 @@ class StorageConfig(BaseModel):
"""
workspace: str = Field(default="./data", description="Local data storage path (primary)")
+ skip_process_lock: bool = Field(
+ default=False,
+ description=(
+ "Skip the startup PID lock for the workspace directory. Use only when you "
+ "explicitly accept the risk of multi-process storage contention."
+ ),
+ )
agfs: AGFSConfig = Field(default_factory=AGFSConfig, description="AGFS configuration")
diff --git a/tests/test_task_backend_config.py b/tests/test_task_backend_config.py
index a1b9c024e..aa2a1bd42 100644
--- a/tests/test_task_backend_config.py
+++ b/tests/test_task_backend_config.py
@@ -40,6 +40,16 @@ def test_storage_config_ignores_deprecated_task_tracker_config(monkeypatch):
assert any("deprecated and ignored" in message for message in warnings)
+def test_storage_config_defaults_skip_process_lock_to_false():
+ config = StorageConfig()
+ assert config.skip_process_lock is False
+
+
+def test_storage_config_accepts_skip_process_lock():
+ config = StorageConfig(skip_process_lock=True)
+ assert config.skip_process_lock is True
+
+
def test_storage_config_builds_persistent_task_tracker():
tracker = StorageConfig().build_task_tracker(_FakeAgfs())
assert isinstance(tracker, TaskTracker)