docs: give Docker deployment a clear step-by-step flow (#128)

Co-authored-by: dadachann <[email protected]>
2026-11-01 21:35:25 +08:00 · 2026-09-08 02:21:58 +08:00
parent 9fe0eddf34
commit e55f402c70
4 changed files with 196 additions and 104 deletions
@@ -3,57 +3,72 @@ title: "Docker Deployment"
 description: "Deploy LangBot with Docker and Docker Compose. Run an open-source multi-platform AI chatbot for Discord, Telegram, WeChat and more in minutes."
 ---

-<Warning>
-  Before you start, you may learn about in advanced:
+## 1. Prepare your environment

-  - Usage of `Docker` and `Docker Compose`
-  - Docker container network communication configuration methods
-</Warning>
+Install Git, Docker, and Docker Compose, and make sure your account can run Docker commands.

-<Info>
-  - Please ensure Git, Docker, and Docker Compose are installed
-</Info>
+## 2. Download the project

-We recommend installing LangBot at `/opt/LangBot`. Avoid restricted directories such as `/root` and `/etc`, where security rules can block sandbox features. With an account that can write to `/opt`, run:
+We recommend `/opt/LangBot`. Avoid restricted directories such as `/root` and `/etc`, where security rules can block sandbox features. The example below uses `/opt`; you can choose another deployment directory that your account can write to.

 ```bash
-git clone https://github.com/langbot-app/LangBot /opt/LangBot && cd /opt/LangBot/docker && docker compose --profile all up -d
+cd /opt
+git clone https://github.com/langbot-app/LangBot
+cd LangBot/docker
 ```

-This enables the sandbox, stdio MCP, and Skill editing by default. No separate data directory configuration is needed.
+### Mainland China: optional image mirror

-## Runtime tokens for Internet-accessible deployments
+If pulling images from Docker Hub is slow, edit `docker-compose.yaml` in the current directory **before starting the services**. Replace every occurrence of `rockchin/langbot:latest` with:

-The open-source edition skips token verification only when **both LangBot and the corresponding Runtime leave the token unset**. If the deployment is accessible from the Internet, strongly protect Plugin Runtime and Box Runtime with separate strong tokens:
+```text
+docker.langbot.app/langbot-public/rockchin/langbot:latest
+```
+
+Save the file, then continue to the next step.
+
+## 3. Start the services
+
+<Accordion title="Public servers: set access tokens before starting">
+  On a public server, set access tokens for the supporting services and avoid exposing runtime ports directly to the Internet.
+
+  Run this command twice to generate two different random values:
+
+  ```bash
+  openssl rand -hex 32
+  ```
+
+  Add the following settings to `.env` in the current directory, replacing the placeholders with the generated values. If either setting already exists, update it instead:
+
+  ```dotenv
+  LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN=<first-random-value>
+  LANGBOT_BOX_CONTROL_TOKEN=<second-random-value>
+  ```
+
+  Compose passes the tokens to the matching services automatically; no other configuration changes are needed. Keep `.env` safe and do not commit it to a repository.
+</Accordion>
+
+Run from `LangBot/docker`:

 ```bash
-export LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN="$(openssl rand -hex 32)"
-export LANGBOT_BOX_CONTROL_TOKEN="$(openssl rand -hex 32)"
 docker compose --profile all up -d
 ```

-The official Compose file passes each variable to both ends of its connection. Setting only one end, using different values, or using a weak token causes the connection to be rejected. Store tokens in your deployment platform's secret manager and never commit them.
+This starts LangBot and its supporting services in the background, including sandbox, stdio MCP, and skill features.

-This starts `langbot`, `langbot_plugin_runtime`, and `langbot_box`. If you only need the basic services and do not want to enable Box Runtime, run:
+## 4. Open the dashboard
+
+Visit the appropriate address in your browser:
+
+- **Local installation**: `http://127.0.0.1:5300`
+- **Server installation**: `http://YOUR_SERVER_IP:5300`. Make sure the firewall allows your access to port `5300`.
+
+Follow the on-screen initialization steps, then add a [model](/en/usage/models/readme) and a [bot](/en/usage/platforms/readme).
+
+If the page does not open, check the startup logs from the deployment directory:

 ```bash
-docker compose up
+docker compose --profile all logs --tail=100
 ```

-## SeekDB support
-
-The official Docker image already includes the optional SeekDB dependencies;
-no additional build argument is required. The container uses the matching
-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.
-
-The container maps port `5300` for WebUI access. You can visit `http://127.0.0.1:5300` to view the WebUI.\
-It also maps ports `2280-2285` reserved for message platform adapters.
-
-After completing the LangBot deployment, please continue reading:
-
- [Bot Configuration Documentation](/en/usage/platforms/readme).
- [Model Configuration Documentation](/en/usage/models/readme).
- [Sandbox Documentation](/en/usage/sandbox/readme).
- [Skills Documentation](/en/usage/skills/readme).
+For further configuration, see the [sandbox](/en/usage/sandbox/readme) and [skills](/en/usage/skills/readme) guides.
@@ -3,52 +3,72 @@ title: "Dockerデプロイ"
 description: "Docker と Docker Compose で LangBot をデプロイ。Discord・Telegram・WeChat 対応のオープンソース AI チャットボットを数分で起動。"
 ---

-<Warning title="まず以下について学習することをお勧めします:">
+## 1. 環境を準備する

- - `Docker`と`Docker Compose`の使用方法
- - Dockerコンテナネットワーク通信の設定方法
-</Warning>
+Git、Docker、Docker Compose をインストールし、現在のアカウントで Docker コマンドを実行できることを確認してください。

-<Info>
- Git、Docker、Docker Composeがインストールされていることを確認してください
-</Info>
+## 2. プロジェクトをダウンロードする

-インストール先は `/opt/LangBot` を推奨します。`/root` や `/etc` などの制限されたディレクトリでは、安全規則によりサンドボックス機能が使えなくなるため避けてください。`/opt` に書き込めるアカウントで、次を実行します：
+インストール先は `/opt/LangBot` を推奨します。`/root` や `/etc` などの制限されたディレクトリでは、安全規則によりサンドボックス機能が使えなくなるため避けてください。以下は `/opt` を使う例です。書き込み権限のある別のデプロイ先に変更しても構いません。

 ```bash
-git clone https://github.com/langbot-app/LangBot /opt/LangBot && cd /opt/LangBot/docker && docker compose --profile all up -d
+cd /opt
+git clone https://github.com/langbot-app/LangBot
+cd LangBot/docker
 ```

-サンドボックス、stdio MCP、Skill の編集がデフォルトで有効になります。データディレクトリを別途設定する必要はありません。
+### 中国本土のネットワーク：任意のミラー設定

-## インターネット公開時の Runtime Token
+Docker Hub からのイメージ取得が遅い場合は、**サービスを起動する前に**現在のディレクトリの `docker-compose.yaml` を編集してください。すべての `rockchin/langbot:latest` を次の値に置き換えます：

-オープンソース版で Token 検証が省略されるのは、**LangBot と対応する Runtime の両方で Token が未設定の場合のみ**です。インターネットからアクセス可能な環境では、Plugin Runtime と Box Runtime にそれぞれ強力な Token を設定することを強く推奨します：
+```text
+docker.langbot.app/langbot-public/rockchin/langbot:latest
+```
+
+保存してから次の手順へ進んでください。
+
+## 3. サービスを起動する
+
+<Accordion title="公開サーバー：起動前にアクセストークンを設定する">
+  公開サーバーでは、関連サービスにアクセストークンを設定し、ランタイムのポートをインターネットへ直接公開しないでください。
+
+  次のコマンドを 2 回実行し、異なるランダムな値を 2 つ生成します：
+
+  ```bash
+  openssl rand -hex 32
+  ```
+
+  現在のディレクトリの `.env` に次の設定を追加し、プレースホルダーを生成した値に置き換えてください。同じ設定がすでにある場合は、既存の値を変更します：
+
+  ```dotenv
+  LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN=<1つ目のランダムな値>
+  LANGBOT_BOX_CONTROL_TOKEN=<2つ目のランダムな値>
+  ```
+
+  Compose が対応するサービスへ自動で渡すため、ほかの設定変更は不要です。`.env` は安全に保管し、リポジトリにコミットしないでください。
+</Accordion>
+
+`LangBot/docker` で次を実行します：

 ```bash
-export LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN="$(openssl rand -hex 32)"
-export LANGBOT_BOX_CONTROL_TOKEN="$(openssl rand -hex 32)"
 docker compose --profile all up -d
 ```

-公式 Compose ファイルは、各変数を対応する接続の両端に渡します。片側だけの設定、値の不一致、または強度不足の Token は接続拒否の原因になります。Token はデプロイ環境の Secret 管理に保存し、リポジトリへコミットしないでください。
+LangBot と関連サービスがバックグラウンドで起動し、サンドボックス、stdio MCP、スキル機能が有効になります。

-これにより `langbot`、`langbot_plugin_runtime`、`langbot_box` が起動します。Box Runtime を有効にせず、基本サービスのみを使う場合は次を実行します：
+## 4. 管理画面を開く
+
+ブラウザーで次の URL にアクセスします：
+
+- **ローカルにインストールした場合**：`http://127.0.0.1:5300`
+- **サーバーにインストールした場合**：`http://サーバーのIP:5300`。ファイアウォールで自分からポート `5300` へのアクセスが許可されていることを確認してください。
+
+画面の案内に従って初期設定を完了し、[モデル](/ja/usage/models/readme)と[ボット](/ja/usage/platforms/readme)を追加してください。
+
+ページが開かない場合は、デプロイ先のディレクトリで起動ログを確認します：

 ```bash
-docker compose up
+docker compose --profile all logs --tail=100
 ```

-## SeekDB サポート
-
-公式 Docker イメージにはオプションの SeekDB 依存関係がすでに含まれており、追加のビルド引数は不要です。コンテナは対応する Linux アーキテクチャの `pylibseekdb` wheel を使用するため、ホストの macOS バージョンはコンテナ内の組み込みモードを制限しません。SeekDB を使用しない場合は、デフォルトの `vdb.use: chroma` のまま使用できます。
-
-コンテナはWebUIアクセス用にポート`5300`をマッピングします。`http://127.0.0.1:5300`にアクセスしてWebUIを表示できます。
-また、メッセージプラットフォームアダプター用に予約されたポート`2280-2285`もマッピングします。
-
-LangBotのデプロイ完了後、引き続き以下をお読みください:
-
- [ボット設定ドキュメント](/ja/usage/platforms/readme)
- [モデル設定ドキュメント](/ja/usage/models/readme)
- [サンドボックスドキュメント](/ja/usage/sandbox/readme)
- [Skills ドキュメント](/ja/usage/skills/readme)
+追加の設定が必要になったら、[サンドボックス](/ja/usage/sandbox/readme)と[スキル](/ja/usage/skills/readme)のドキュメントを参照してください。
@@ -0,0 +1,46 @@
+"""Keep the beginner Docker guide ordered and actionable in every locale."""
+import re
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class DockerDeploymentFlowTests(unittest.TestCase):
+    def test_all_locales_follow_one_setup_path(self):
+        for locale in ("zh", "en", "ja"):
+            with self.subTest(locale=locale):
+                text = (ROOT / locale / "deploy/langbot/docker.mdx").read_text()
+                headings = re.findall(r"^## (\d+)\. .+$", text, re.MULTILINE)
+                self.assertEqual(headings, ["1", "2", "3", "4"])
+                download = "cd /opt\ngit clone https://github.com/langbot-app/LangBot\ncd LangBot/docker"
+                start = "docker compose --profile all up -d"
+                mirror = "docker.langbot.app/langbot-public/rockchin/langbot:latest"
+                self.assertIn(download, text)
+                self.assertNotIn("&&", text)
+                self.assertEqual(text.count(start), 1)
+                self.assertLess(text.index(download), text.index(mirror))
+                self.assertLess(text.index(mirror), text.index(start))
+                self.assertLess(text.index(start), text.index("http://127.0.0.1:5300"))
+                self.assertIn("`/root`", text)
+                self.assertIn("`/etc`", text)
+                self.assertNotIn("seekdb", text.lower())
+                self.assertNotIn("LANGBOT_BOX_ROOT", text)
+
+    def test_optional_security_precedes_start_without_extra_start_commands(self):
+        for locale in ("zh", "en", "ja"):
+            with self.subTest(locale=locale):
+                text = (ROOT / locale / "deploy/langbot/docker.mdx").read_text()
+                accordion = re.search(r"<Accordion\b[^>]*>(.*?)</Accordion>", text, re.DOTALL)
+                assert accordion is not None, f"{locale}: missing optional security section"
+                content = accordion.group(1)
+                for value in (".env", "openssl rand -hex 32", "LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN", "LANGBOT_BOX_CONTROL_TOKEN"):
+                    self.assertIn(value, content)
+                self.assertNotIn("docker compose", content)
+                self.assertLess(accordion.end(), text.index("docker compose --profile all up -d"))
+                for target in ("usage/models/readme", "usage/platforms/readme"):
+                    self.assertIn(f"/{locale}/{target}", text)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -3,61 +3,72 @@ title: "Docker部署"
 description: "使用 Docker 和 Docker Compose 部署 LangBot，几分钟内运行支持 Discord、Telegram、微信等多平台的开源 AI 聊天机器人。"
 ---

-<Warning>
-  您需要提前了解：
+## 1. 准备环境

-  - `Docker` 和 `Docker Compose` 的使用
-  - Docker 容器间网络通信配置方式
-</Warning>
+请先安装 Git、Docker 和 Docker Compose，并确保当前账号可以运行 Docker 命令。

-<Info>
-  - 推荐使用[阿里云，服务器价格低至 38 元一年，更可以享受8折优惠](https://www.aliyun.com/minisite/goods?userCode=ys4ad8gs)
-</Info>
+## 2. 下载项目

-建议将 LangBot 安装到 `/opt/LangBot`，避免 `/root`、`/etc` 等受限制目录，以免沙箱功能被安全规则拦截。使用有 `/opt` 写入权限的账号，执行以下命令即可启动：
+建议安装到 `/opt/LangBot`，避免 `/root`、`/etc` 等受限制目录，以免沙箱功能被安全规则拦截。下面以 `/opt` 为例，你可以换成其他有写入权限的部署目录。

 ```bash
-git clone https://github.com/langbot-app/LangBot /opt/LangBot && cd /opt/LangBot/docker && docker compose --profile all up -d
+cd /opt
+git clone https://github.com/langbot-app/LangBot
+cd LangBot/docker
 ```

-默认启用沙箱、stdio MCP 和 Skill 编辑等功能，无需单独配置数据目录。
+### 中国大陆网络：可选镜像源

-## 公网部署的 Runtime Token
+如果拉取 Docker Hub 镜像较慢，**请在启动前**编辑当前目录下的 `docker-compose.yaml`，将所有 `rockchin/langbot:latest` 替换为：

-开源版仅在 LangBot 与对应 Runtime **两端都未设置 Token** 时跳过 Token 校验。若部署环境可从公网访问，强烈建议为 Plugin Runtime 和 Box Runtime 设置独立的强 Token：
+```text
+docker.langbot.app/langbot-public/rockchin/langbot:latest
+```
+
+保存文件后，继续下一步。
+
+## 3. 启动服务
+
+<Accordion title="公网服务器：启动前设置访问令牌">
+  如果部署在公网服务器上，建议先为配套服务设置访问令牌，不要直接向公网开放运行时端口。
+
+  运行两次以下命令，生成两个不同的随机值：
+
+  ```bash
+  openssl rand -hex 32
+  ```
+
+  在当前目录的 `.env` 文件中添加以下配置，将占位内容替换为生成的值；如已有同名配置，请修改原值：
+
+  ```dotenv
+  LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN=<第一个随机值>
+  LANGBOT_BOX_CONTROL_TOKEN=<第二个随机值>
+  ```
+
+  Compose 会自动将令牌传给对应服务，无需修改其他配置。请妥善保存 `.env`，不要提交到仓库。
+</Accordion>
+
+在 `LangBot/docker` 目录执行：

 ```bash
-export LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN="$(openssl rand -hex 32)"
-export LANGBOT_BOX_CONTROL_TOKEN="$(openssl rand -hex 32)"
 docker compose --profile all up -d
 ```

-官方 Compose 文件会把每个变量传给对应连接的两端。只设置一端、两端值不一致或 Token 强度不足都会导致连接被拒绝。请把 Token 保存在部署平台的 Secret 管理中，不要提交到仓库。
+这会在后台启动 LangBot 及配套服务，包含沙箱、stdio MCP 和技能功能。

-这会启动 `langbot`、`langbot_plugin_runtime` 和 `langbot_box`。如果只需要基础服务，不启用 Box Runtime，可以使用：
+## 4. 打开管理页面
+
+在浏览器中访问：
+
+- **本机部署**：`http://127.0.0.1:5300`
+- **服务器部署**：`http://你的服务器IP:5300`，并确保防火墙允许你访问 `5300` 端口。
+
+按照页面提示完成初始化，然后添加[模型](/zh/usage/models/readme)和[机器人](/zh/usage/platforms/readme)。
+
+如果页面无法打开，可在部署目录查看启动日志：

 ```bash
-docker compose up
+docker compose --profile all logs --tail=100
 ```

-## SeekDB 支持
-
-官方 Docker 镜像已经包含可选的 SeekDB 依赖，无需额外构建参数。容器会使用对应 Linux 架构的 `pylibseekdb` wheel，因此宿主机的 macOS 版本不会限制容器内的 embedded 模式；不使用 SeekDB 时保持默认 `vdb.use: chroma` 即可。
-
-<Info>
-  - 如果你的主机位于中国大陆，可以考虑把 `docker-compose.yaml` 文件中的镜像名称改为`docker.langbot.app/langbot-public/rockchin/langbot:latest`以使用我们提供的镜像源。
-  - 推荐[设置 Docker 容器代理](https://docker.github.net.cn/network/proxy/)，以便保证 LangBot 在运行期间的网络访问通畅。
-  - 如果需要禁用或强制沙箱后端，请参考[沙箱配置](/zh/usage/sandbox/config)。
-</Info>
-
-首次启动会输出创建配置文件的提示，请继续按照文件配置。
-
-容器会映射`5300`端口供 WebUI 使用，您可以访问`http://127.0.0.1:5300`查看 WebUI。\
-还会映射`2280-2285`端口供使用 OneBot 协议的消息平台适配器反向连接。
-
-完成 LangBot 部署后，请继续阅读：
-
- [配置机器人文档](/zh/usage/platforms/readme)。
- [配置模型文档](/zh/usage/models/readme)。
- [沙箱文档](/zh/usage/sandbox/readme)。
- [技能系统文档](/zh/usage/skills/readme)。
+需要进一步配置时，再查看[沙箱](/zh/usage/sandbox/readme)和[技能系统](/zh/usage/skills/readme)文档。