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
Skip process lock (#2442)
Jiahui Zhou226ce46539cb
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 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.mdindex 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.mdindex 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.mdindex 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.pyindex 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.pyindex 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.pyindex 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)