mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-29 20:05:25 +08:00
docs: explain safe Box data paths for Docker deployments (#126)
Co-authored-by: dadachann <[email protected]>
This commit is contained in:
Hyu
@@ -21,6 +21,10 @@ git clone https://github.com/langbot-app/LangBot
|
||||
cd LangBot/docker
|
||||
```
|
||||
|
||||
<Warning>
|
||||
If the project is under `/root`, configure `LANGBOT_BOX_ROOT` as described in “Sandbox data directory” below before starting. Otherwise, security rules will reject the default sandbox path.
|
||||
</Warning>
|
||||
|
||||
Start the containers with the recommended `all` profile, which enables Box Runtime-dependent features by default, including the sandbox, stdio MCP hosting, and Skill add/edit:
|
||||
|
||||
```bash
|
||||
@@ -53,6 +57,26 @@ Linux `pylibseekdb` wheel, so the host macOS version does not limit embedded
|
||||
mode inside the container. Keep the default `vdb.use: chroma` when SeekDB is
|
||||
not needed.
|
||||
|
||||
## Sandbox data directory
|
||||
|
||||
With the `all` or `box` profile, sandbox data defaults to `${PWD}/data/box`. Running Compose from `/root/LangBot/docker` puts this path under `/root`, so sandbox creation fails with `host_path ... is blocked for security`. Features that depend on the sandbox, such as stdio MCP, will not work.
|
||||
|
||||
**Use a dedicated absolute path, such as `/opt/langbot-box` or `/data/langbot-box`.** The LangBot project can stay under `/root`; only the sandbox data directory needs to be elsewhere. Add or update this entry in `LangBot/docker/.env`, keeping any existing settings:
|
||||
|
||||
```dotenv
|
||||
LANGBOT_BOX_ROOT=/opt/langbot-box
|
||||
```
|
||||
|
||||
Avoid protected directories such as `/root`, `/etc`, `/proc`, `/sys`, `/dev`, `/boot`, and `/run`, their subdirectories, and symlinks pointing into them.
|
||||
|
||||
If you already have sandbox data, stop the related services, back up and migrate the data first; changing the path does not move existing data. When ready, run from `LangBot/docker`:
|
||||
|
||||
```bash
|
||||
docker compose --profile all up -d --force-recreate langbot langbot_box
|
||||
```
|
||||
|
||||
Recreate both `langbot` and `langbot_box`: `restart` alone does not update environment variables or mounts. Compose environment variables override `config.yaml`, so editing that file alone will not help.
|
||||
|
||||
`langbot_box` creates sandbox containers through the host Docker socket, so the Box root path must be identical on the host and inside the container:
|
||||
|
||||
```yaml
|
||||
@@ -86,7 +110,7 @@ docker info
|
||||
If `docker info` works, restart LangBot.
|
||||
|
||||
<Warning>
|
||||
`langbot_box` does not read `LANGBOT_BOX_*` or `BOX__*` variables directly. Set `BOX__LOCAL__*` on `langbot`; LangBot forwards the effective Box config to Box Runtime through INIT RPC. To change the Box root, set `LANGBOT_BOX_ROOT` to an absolute path, for example `LANGBOT_BOX_ROOT=/var/lib/langbot/box docker compose --profile all up`.
|
||||
`langbot_box` does not read `LANGBOT_BOX_*` or `BOX__*` variables directly. LangBot reads `BOX__LOCAL__*` and forwards the effective Box config to Box Runtime through INIT RPC. Set `LANGBOT_BOX_ROOT` as described above rather than changing only the environment of `langbot_box`.
|
||||
</Warning>
|
||||
|
||||
The container maps port `5300` for WebUI access. You can visit `http://127.0.0.1:5300` to view the WebUI.\
|
||||
|
||||
@@ -20,6 +20,10 @@ git clone https://github.com/langbot-app/LangBot
|
||||
cd LangBot/docker
|
||||
```
|
||||
|
||||
<Warning>
|
||||
プロジェクトを `/root` 配下に置く場合は、起動前に下の「サンドボックスのデータディレクトリ」に従って `LANGBOT_BOX_ROOT` を設定してください。デフォルトのパスは安全規則により拒否されます。
|
||||
</Warning>
|
||||
|
||||
推奨の `all` profile でコンテナを起動します。これにより、サンドボックス、stdio MCP ホスティング、Skill の追加/編集など Box Runtime に依存する機能がデフォルトで有効になります:
|
||||
|
||||
```bash
|
||||
@@ -48,6 +52,26 @@ docker compose up
|
||||
|
||||
公式 Docker イメージにはオプションの SeekDB 依存関係がすでに含まれており、追加のビルド引数は不要です。コンテナは対応する Linux アーキテクチャの `pylibseekdb` wheel を使用するため、ホストの macOS バージョンはコンテナ内の組み込みモードを制限しません。SeekDB を使用しない場合は、デフォルトの `vdb.use: chroma` のまま使用できます。
|
||||
|
||||
## サンドボックスのデータディレクトリ
|
||||
|
||||
`all` または `box` profile を有効にすると、サンドボックスのデータはデフォルトで `${PWD}/data/box` に保存されます。`/root/LangBot/docker` で Compose を実行すると保存先も `/root` 配下になるため、サンドボックス作成時に `host_path ... is blocked for security` が発生し、stdio MCP などの機能が使えなくなります。
|
||||
|
||||
**`/opt/langbot-box` や `/data/langbot-box` など、専用の絶対パスを推奨します。** LangBot 本体は `/root` 配下のままで構いません。サンドボックスのデータだけを別の場所に置きます。`LangBot/docker/.env` の既存設定を残し、次の行を追加または変更してください：
|
||||
|
||||
```dotenv
|
||||
LANGBOT_BOX_ROOT=/opt/langbot-box
|
||||
```
|
||||
|
||||
`/root`、`/etc`、`/proc`、`/sys`、`/dev`、`/boot`、`/run` などの保護されたディレクトリとその配下、およびそれらを指すシンボリックリンクは使用しないでください。
|
||||
|
||||
既存のサンドボックスデータがある場合は、先に関連サービスを停止し、バックアップとデータ移行を済ませてください。パスを変更してもデータは自動で移動しません。準備ができたら、`LangBot/docker` で次を実行します：
|
||||
|
||||
```bash
|
||||
docker compose --profile all up -d --force-recreate langbot langbot_box
|
||||
```
|
||||
|
||||
`langbot` と `langbot_box` の両方を再作成する必要があります。`restart` だけでは環境変数やマウントは更新されません。また、Compose の環境変数が `config.yaml` より優先されるため、設定ファイルだけを編集しても反映されません。
|
||||
|
||||
`langbot_box` はホスト Docker socket 経由でサンドボックスコンテナを作成するため、Box root のホスト側パスとコンテナ内パスは同一である必要があります：
|
||||
|
||||
```yaml
|
||||
@@ -81,7 +105,7 @@ docker info
|
||||
`docker info` が正常に出力される場合は、LangBot を再起動してください。
|
||||
|
||||
<Warning>
|
||||
`langbot_box` は `LANGBOT_BOX_*` や `BOX__*` 環境変数を直接読み取りません。`BOX__LOCAL__*` は `langbot` に設定し、LangBot が INIT RPC 経由で Box Runtime に渡します。Box root を変更する場合は `LANGBOT_BOX_ROOT=/var/lib/langbot/box docker compose --profile all up` のように絶対パスを指定してください。
|
||||
`langbot_box` は `LANGBOT_BOX_*` や `BOX__*` 環境変数を直接読み取りません。LangBot が `BOX__LOCAL__*` を読み取り、INIT RPC 経由で Box Runtime に渡します。`langbot_box` の環境変数だけを変更せず、上記の手順で `LANGBOT_BOX_ROOT` を設定してください。
|
||||
</Warning>
|
||||
|
||||
コンテナはWebUIアクセス用にポート`5300`をマッピングします。`http://127.0.0.1:5300`にアクセスしてWebUIを表示できます。
|
||||
|
||||
@@ -21,6 +21,10 @@ git clone https://github.com/langbot-app/LangBot
|
||||
cd LangBot/docker
|
||||
```
|
||||
|
||||
<Warning>
|
||||
如果项目放在 `/root` 下，请先按下方「沙箱数据目录」设置 `LANGBOT_BOX_ROOT`，否则默认沙箱路径会被安全规则拒绝。
|
||||
</Warning>
|
||||
|
||||
启动容器（推荐启用 `all` profile，以默认启用沙箱、stdio MCP 托管、Skill 添加/编辑等依赖 Box Runtime 的功能）：
|
||||
|
||||
```bash
|
||||
@@ -49,6 +53,26 @@ docker compose up
|
||||
|
||||
官方 Docker 镜像已经包含可选的 SeekDB 依赖，无需额外构建参数。容器会使用对应 Linux 架构的 `pylibseekdb` wheel，因此宿主机的 macOS 版本不会限制容器内的 embedded 模式；不使用 SeekDB 时保持默认 `vdb.use: chroma` 即可。
|
||||
|
||||
## 沙箱数据目录
|
||||
|
||||
启用 `all` 或 `box` profile 时，沙箱数据默认放在 `${PWD}/data/box`。若在 `/root/LangBot/docker` 下运行 Compose，默认路径也会落在 `/root` 下，创建沙箱时会报 `host_path ... is blocked for security`，导致 stdio MCP 等依赖沙箱的功能不可用。
|
||||
|
||||
**建议使用独立的绝对路径，例如 `/opt/langbot-box` 或 `/data/langbot-box`。** LangBot 项目本身可以留在 `/root`，只需把沙箱数据目录放到外面。在 `LangBot/docker/.env` 中添加或修改（保留已有配置）：
|
||||
|
||||
```dotenv
|
||||
LANGBOT_BOX_ROOT=/opt/langbot-box
|
||||
```
|
||||
|
||||
不要使用 `/root`、`/etc`、`/proc`、`/sys`、`/dev`、`/boot`、`/run` 等受保护目录及其子目录，也不要通过符号链接指向这些目录。
|
||||
|
||||
已有沙箱数据时，请先停止相关服务、备份并迁移数据；更改路径不会自动搬迁旧数据。准备好后，在 `LangBot/docker` 目录执行：
|
||||
|
||||
```bash
|
||||
docker compose --profile all up -d --force-recreate langbot langbot_box
|
||||
```
|
||||
|
||||
需要同时重建 `langbot` 和 `langbot_box`，仅 `restart` 不会更新环境变量或挂载。Compose 环境变量会覆盖 `config.yaml`，因此只改配置文件无效。
|
||||
|
||||
`langbot_box` 通过主机 Docker socket 创建沙箱容器，因此 Box 根目录的宿主机路径和容器内路径必须一致：
|
||||
|
||||
```yaml
|
||||
@@ -82,7 +106,7 @@ docker info
|
||||
若 `docker info` 正常输出，请重启 LangBot。
|
||||
|
||||
<Warning>
|
||||
`langbot_box` 不直接读取 `LANGBOT_BOX_*` 或 `BOX__*` 环境变量；Box 配置由 `langbot` 读取 `BOX__LOCAL__*` 后通过 INIT RPC 传给 Box Runtime。若要改 Box 根目录，请使用绝对路径设置 `LANGBOT_BOX_ROOT`，例如 `LANGBOT_BOX_ROOT=/var/lib/langbot/box docker compose --profile all up`。
|
||||
`langbot_box` 不直接读取 `LANGBOT_BOX_*` 或 `BOX__*` 环境变量；Box 配置由 `langbot` 读取 `BOX__LOCAL__*` 后通过 INIT RPC 传给 Box Runtime。请按上文设置 `LANGBOT_BOX_ROOT`，不要只修改 `langbot_box` 的环境变量。
|
||||
</Warning>
|
||||
|
||||
<Info>
|
||||
|
||||
Reference in New Issue
Block a user