Skip to content

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

fix(docker): keep relative workspaces inside the persistent mount (#4961)

Evo8f20fbff025b
diff --git a/Dockerfile b/Dockerfile
index bb4a32038..1ea8fcfe8 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -107,7 +107,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
ripgrep \
&& rm -rf /var/lib/apt/lists/*
-WORKDIR /app
+# Resolve relative storage paths inside the persistent mount.
+WORKDIR /app/.openviking
COPY --from=py-builder /app/.venv /app/.venv
# Fail the image build if VikingBot and the separately released SDK drift apart.
@@ -128,7 +129,7 @@ EXPOSE 1933
HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
CMD ["openviking-entrypoint", "--healthcheck"]
-# All persistent state (ov.conf, ovcli.conf, workspace data) lives under
+# Default persistent state (ov.conf, ovcli.conf, workspace data) lives under
# /app/.openviking, which mirrors the host's ~/.openviking layout. Mount one
# volume there to persist everything across container restarts:
# docker run -v ~/.openviking:/app/.openviking <image>
diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.md
index fc139e12e..87d782af4 100644
--- a/docs/en/guides/03-deployment.md
+++ b/docs/en/guides/03-deployment.md
@@ -184,7 +184,7 @@ curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
### Docker
-OpenViking provides pre-built Docker images published to GitHub Container Registry. All persistent state — `ov.conf`, `ovcli.conf`, and the workspace data — lives under `/app/.openviking` inside the container, so a single mount is enough:
+OpenViking provides pre-built Docker images published to GitHub Container Registry. The runtime working directory is `/app/.openviking`, so the default `storage.workspace` (`./data`) resolves to `/app/.openviking/data`. The default workspace, `ov.conf`, and `ovcli.conf` therefore share one persistent mount. If you configure an absolute workspace outside this directory, mount that path separately:
```bash
docker run -d \
@@ -211,6 +211,8 @@ Since the server binds to `0.0.0.0` inside the container (required for Docker po
The server will refuse to start without it. You can override the bind address via the `OPENVIKING_SERVER_HOST` environment variable if needed.
+**Upgrading from an older image:** images that started in `/app` resolved `./data` to `/app/data`, outside the default mount. Before removing the old container, stop it and back up its configured workspace (for example, `docker cp openviking:/app/data ./openviking-data-backup`). Restore that backup into the mounted host workspace, normally `~/.openviking/data`, before starting the replacement. Do not overwrite an existing workspace without checking which data to retain. Absolute workspace paths are unchanged; other relative paths now resolve from `/app/.openviking`.
+
Upgrade the container:
```bash
docker stop openviking
diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.md
index fc924569b..093e7d6b0 100644
--- a/docs/zh/guides/03-deployment.md
+++ b/docs/zh/guides/03-deployment.md
@@ -182,7 +182,7 @@ curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
### Docker
-OpenViking 提供预构建的 Docker 镜像,发布在 GitHub Container Registry。容器内所有持久化状态(`ov.conf`、`ovcli.conf` 以及工作区数据)都放在 `/app/.openviking` 下,挂载一个目录即可:
+OpenViking 提供预构建的 Docker 镜像,发布在 GitHub Container Registry。运行目录为 `/app/.openviking`,因此默认的 `storage.workspace`(`./data`)解析为 `/app/.openviking/data`。默认工作区、`ov.conf` 和 `ovcli.conf` 共用一个持久卷。若将工作区配置为此目录以外的绝对路径,需要另外挂载该路径:
```bash
docker run -d \
@@ -209,6 +209,8 @@ Docker 镜像默认会同时启动:
未设置时服务将拒绝启动。如需自定义绑定地址,可通过环境变量 `OPENVIKING_SERVER_HOST` 覆盖。
+**从旧镜像升级:** 运行目录为 `/app` 的旧镜像会把 `./data` 解析为默认挂载之外的 `/app/data`。删除旧容器前,先停止容器并备份其实际工作区(例如 `docker cp openviking:/app/data ./openviking-data-backup`)。启动替换容器前,将备份恢复到挂载的宿主机工作区,通常为 `~/.openviking/data`。若目标工作区已存在,先确认要保留的数据,不要直接覆盖。绝对工作区路径不变;其他相对路径现在以 `/app/.openviking` 为基准。
+
升级容器的方式
```bash
docker stop openviking
diff --git a/tests/misc/test_root_docker_image_packaging.py b/tests/misc/test_root_docker_image_packaging.py
index 029816b40..c702dcd07 100644
--- a/tests/misc/test_root_docker_image_packaging.py
+++ b/tests/misc/test_root_docker_image_packaging.py
@@ -1,6 +1,9 @@
import re
from pathlib import Path
+import pytest
+import yaml
+
REPO_ROOT = Path(__file__).resolve().parents[2]
@@ -122,3 +125,22 @@ def test_rust_crates_declare_the_repo_minimum_rust_version():
):
cargo_toml = _read_text(relative_path)
assert f'rust-version = "{min_rust_version}"' in cargo_toml
+
+
[email protected]("storage", [{}, {"workspace": "./data"}, {"workspace": "./custom"}])
+def test_docker_relative_workspace_is_inside_persistent_mount(tmp_path, monkeypatch, storage):
+ from openviking_cli.utils.config.storage_config import StorageConfig
+
+ runtime = _read_text("Dockerfile").rsplit("\nFROM ", maxsplit=1)[1]
+ workdir = re.findall(r"^WORKDIR (.+)$", runtime, re.MULTILINE)[-1]
+ compose = yaml.safe_load(_read_text("docker-compose.yml"))
+ mount_target = compose["services"]["openviking"]["volumes"][0].split(":")[1]
+ container_cwd = tmp_path / workdir.lstrip("/")
+ container_cwd.mkdir(parents=True)
+ monkeypatch.chdir(container_cwd)
+
+ config = StorageConfig(**storage)
+
+ assert Path(config.workspace).is_relative_to(tmp_path / mount_target.lstrip("/"))
+ assert config.agfs.path == config.workspace
+ assert config.vectordb.path == config.workspace