docs: add Docker deployment guide

2026-10-26 02:04:37 +08:00 · 2026-07-22 09:59:50 +08:00
1 parent 5806a1fcb5
commit 48761d7fa3
@@ -7,6 +7,7 @@ const enSidebar: DefaultTheme.SidebarItem[] = [
    text: 'Usage',
    items: [
      { text: 'Quick Start', link: '/usage/quick-start' },
+      { text: 'Docker Deployment', link: '/usage/docker' },
      { text: 'Export Chat Records', link: '/usage/how-to-export' },
      { text: 'Import Chat Records', link: '/usage/how-to-import' },
      { text: 'Troubleshooting', link: '/usage/troubleshooting' },
@@ -41,6 +42,7 @@ const cnSidebar: DefaultTheme.SidebarItem[] = [
    text: '使用指南',
    items: [
      { text: '快速开始', link: '/cn/usage/quick-start' },
+      { text: 'Docker 部署', link: '/cn/usage/docker' },
      { text: '导出聊天记录', link: '/cn/usage/how-to-export' },
      { text: '导入聊天记录', link: '/cn/usage/how-to-import' },
      { text: '故障排查', link: '/cn/usage/troubleshooting' },
@@ -78,6 +80,7 @@ const twSidebar: DefaultTheme.SidebarItem[] = [
    text: '使用指南',
    items: [
      { text: '快速開始', link: '/tw/usage/quick-start' },
+      { text: 'Docker 部署', link: '/tw/usage/docker' },
      { text: '匯出聊天記錄', link: '/tw/usage/how-to-export' },
      { text: '匯入聊天記錄', link: '/tw/usage/how-to-import' },
      { text: '故障排除', link: '/tw/usage/troubleshooting' },
@@ -0,0 +1,136 @@
+---
+outline: deep
+---
+
+# Docker 部署
+
+ChatLab CLI 提供 `linux/amd64` 和 `linux/arm64` 两种架构的容器镜像：
+
+```text
+ghcr.io/chatlab/chatlab-cli
+```
+
+## 快速开始
+
+```bash
+docker run --name chatlab \
+  -p 3110:3110 \
+  -v chatlab-data:/data \
+  ghcr.io/chatlab/chatlab-cli:latest
+```
+
+容器启动后，打开 <http://127.0.0.1:3110/>。
+
+镜像使用非特权 `node` 用户运行，并将 ChatLab 数据保存在 `/data`。替换或升级容器时，请保留该数据卷。
+
+## 服务选项
+
+容器的默认命令是：
+
+```bash
+chatlab start --no-open --host 0.0.0.0
+```
+
+`chatlab start` 按 CLI 中的声明顺序支持以下选项：
+
+| 选项 | 说明 |
+| --- | --- |
+| `--port <port>` | 服务端口，默认为 `3110`。 |
+| `--host <host>` | 监听地址；在容器外运行时默认为 `127.0.0.1`。 |
+| `--token <token>` | 自定义 Bearer Token；省略时由 ChatLab 读取或生成。 |
+| `--headless` | 仅启动 API，不提供 Web UI。 |
+| `--require-auth` | 除 API 路由外，也要求 Web UI 路由使用 Bearer 认证。 |
+| `--no-open` | 不打开浏览器。 |
+| `--daemon` | 安装 macOS/Linux 常驻服务，不适用于容器。 |
+
+Docker 参数会替换完整的默认命令。添加服务选项时，需要按需重复 `start`、`--no-open` 和 `--host 0.0.0.0`：
+
+```bash
+docker run --rm \
+  -p 8080:8080 \
+  -v chatlab-data:/data \
+  ghcr.io/chatlab/chatlab-cli:latest \
+  start --port 8080 --host 0.0.0.0 --headless --no-open
+```
+
+也可以直接选择其他 CLI 命令：
+
+```bash
+docker run --rm ghcr.io/chatlab/chatlab-cli:latest --version
+docker run --rm ghcr.io/chatlab/chatlab-cli:latest formats
+docker run --rm -v chatlab-data:/data \
+  ghcr.io/chatlab/chatlab-cli:latest sessions --format json
+```
+
+## 环境变量
+
+对于配置字段，ChatLab 按以下优先级读取值：
+
+1. `CHATLAB_*` 环境变量
+2. `~/.chatlab/config.toml` 或 `~/.chatlab/config.json`
+3. 内置默认值
+
+配置环境变量按源码中的声明顺序如下：
+
+| 环境变量 | 说明 |
+| --- | --- |
+| `CHATLAB_DATA_DIR` | 覆盖 ChatLab 数据目录；镜像将其设置为 `/data`。 |
+| `CHATLAB_API_PORT` | 设置 `api.port`。`start` 命令会提供自身的默认值，因此请使用 `--port` 配置容器服务。 |
+| `CHATLAB_API_HOST` | 设置 `api.host`。`start` 命令会提供自身的默认值，因此请使用 `--host` 配置容器服务。 |
+| `CHATLAB_LLM_PROVIDER` | 设置 `llm.provider`。 |
+| `CHATLAB_LLM_MODEL` | 设置 `llm.model`。 |
+| `CHATLAB_LLM_BASE_URL` | 设置 `llm.base_url`。 |
+| `CHATLAB_LOCALE_LANG` | 设置 `locale.lang`。 |
+| `CHATLAB_CLI_ALLOW_RAW` | 设置为 `1` 或 `true`，允许查询命令输出未经隐私预处理的 `--raw` 结果。 |
+
+ChatLab 还会读取以下运行时变量：
+
+| 环境变量 | 说明 |
+| --- | --- |
+| `CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR` | 设置为 `1` 可绕过数据目录的最低运行时版本检查。此操作可能损坏数据，仅用于紧急恢复。 |
+| `CHATLAB_DISABLE_NATIVE_PERF` | 设置为 `1` 可禁用原生解析器加速。 |
+| `CHATLAB_LOG_LEVEL` | 将应用日志级别设置为 `DEBUG`、`INFO`、`WARN` 或 `ERROR`，默认为 `INFO`。 |
+| `CHATLAB_SKIP_UPDATE_CHECK` | 设置为任意非空值可禁用 CLI 更新检查。 |
+| `CHATLAB_TEMP_ROOT` | 覆盖临时工作区根目录。 |
+| `LANG` | 选择 CLI 查询预处理使用的默认语言。 |
+
+Bearer Token、无界面模式、Web UI 认证和浏览器打开行为通过对应的命令行选项配置。ChatLab 不为这些选项提供环境变量别名。
+
+## Docker Compose
+
+```yaml
+services:
+  chatlab:
+    image: ghcr.io/chatlab/chatlab-cli:latest
+    restart: unless-stopped
+    ports:
+      - "3110:3110"
+    volumes:
+      - chatlab-data:/data
+    command:
+      - start
+      - --port
+      - "3110"
+      - --host
+      - 0.0.0.0
+      - --token
+      - ${CHATLAB_TOKEN:?set CHATLAB_TOKEN in the Compose environment}
+      - --require-auth
+      - --no-open
+
+volumes:
+  chatlab-data:
+```
+
+`CHATLAB_TOKEN` 由 Docker Compose 插值后作为 `--token` 的值传给 ChatLab，并不是 ChatLab 环境变量。请将其保存在密钥存储或未跟踪的 `.env` 文件中。
+
+## 多架构镜像
+
+Docker 会自动选择与宿主机架构匹配的镜像。也可以显式选择平台：
+
+```bash
+docker pull --platform linux/amd64 ghcr.io/chatlab/chatlab-cli:latest
+docker pull --platform linux/arm64 ghcr.io/chatlab/chatlab-cli:latest
+```
+
+镜像索引还包含来源证明。镜像仓库界面可能将这些元数据清单显示为 `unknown/unknown`；它们不是可运行平台，也无需单独拉取。
@@ -0,0 +1,147 @@
+---
+outline: deep
+---
+
+# Docker Deployment
+
+ChatLab CLI is available as a multi-architecture container image for
+`linux/amd64` and `linux/arm64`:
+
+```text
+ghcr.io/chatlab/chatlab-cli
+```
+
+## Quick start
+
+```bash
+docker run --name chatlab \
+  -p 3110:3110 \
+  -v chatlab-data:/data \
+  ghcr.io/chatlab/chatlab-cli:latest
+```
+
+Open <http://127.0.0.1:3110/> after the container starts.
+
+The image runs as the unprivileged `node` user and stores ChatLab data in
+`/data`. Keep the volume when replacing or upgrading the container.
+
+## Server options
+
+The default container command is:
+
+```bash
+chatlab start --no-open --host 0.0.0.0
+```
+
+The `chatlab start` options, in CLI declaration order, are:
+
+| Option | Description |
+| --- | --- |
+| `--port <port>` | Server port. Defaults to `3110`. |
+| `--host <host>` | Listen address. Defaults to `127.0.0.1` outside the container. |
+| `--token <token>` | Custom Bearer token. ChatLab reads or generates one when omitted. |
+| `--headless` | Start the API without serving the Web UI. |
+| `--require-auth` | Require Bearer authentication for Web UI routes as well as API routes. |
+| `--no-open` | Do not open a browser. |
+| `--daemon` | Install a resident macOS/Linux service. This is not intended for containers. |
+
+Docker arguments replace the complete default command. Repeat `start`,
+`--no-open`, and `--host 0.0.0.0` when adding server options:
+
+```bash
+docker run --rm \
+  -p 8080:8080 \
+  -v chatlab-data:/data \
+  ghcr.io/chatlab/chatlab-cli:latest \
+  start --port 8080 --host 0.0.0.0 --headless --no-open
+```
+
+Other CLI commands can be selected directly:
+
+```bash
+docker run --rm ghcr.io/chatlab/chatlab-cli:latest --version
+docker run --rm ghcr.io/chatlab/chatlab-cli:latest formats
+docker run --rm -v chatlab-data:/data \
+  ghcr.io/chatlab/chatlab-cli:latest sessions --format json
+```
+
+## Environment variables
+
+For configuration fields, ChatLab applies values in this order, from highest
+to lowest priority:
+
+1. `CHATLAB_*` environment variables
+2. `~/.chatlab/config.toml` or `~/.chatlab/config.json`
+3. Built-in defaults
+
+The configuration environment variables, in source declaration order, are:
+
+| Variable | Description |
+| --- | --- |
+| `CHATLAB_DATA_DIR` | Override the ChatLab data directory. The image sets it to `/data`. |
+| `CHATLAB_API_PORT` | Set `api.port`. The `start` command supplies its own default, so use `--port` to configure the container server. |
+| `CHATLAB_API_HOST` | Set `api.host`. The `start` command supplies its own default, so use `--host` to configure the container server. |
+| `CHATLAB_LLM_PROVIDER` | Set `llm.provider`. |
+| `CHATLAB_LLM_MODEL` | Set `llm.model`. |
+| `CHATLAB_LLM_BASE_URL` | Set `llm.base_url`. |
+| `CHATLAB_LOCALE_LANG` | Set `locale.lang`. |
+| `CHATLAB_CLI_ALLOW_RAW` | Set to `1` or `true` to allow privacy-unprocessed `--raw` query output. |
+
+ChatLab also reads these runtime variables:
+
+| Variable | Description |
+| --- | --- |
+| `CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR` | Set to `1` to bypass the minimum-runtime data-directory check. This may corrupt data and should only be used for emergency recovery. |
+| `CHATLAB_DISABLE_NATIVE_PERF` | Set to `1` to disable native parser acceleration. |
+| `CHATLAB_LOG_LEVEL` | Set the application log threshold to `DEBUG`, `INFO`, `WARN`, or `ERROR`. Defaults to `INFO`. |
+| `CHATLAB_SKIP_UPDATE_CHECK` | Set to a non-empty value to disable CLI update checks. |
+| `CHATLAB_TEMP_ROOT` | Override the temporary workspace root. |
+| `LANG` | Select the default language used by CLI query preprocessing. |
+
+Bearer tokens, headless mode, Web UI authentication, and browser opening are
+configured with the corresponding command-line options. ChatLab does not
+provide environment-variable aliases for those options.
+
+## Docker Compose
+
+```yaml
+services:
+  chatlab:
+    image: ghcr.io/chatlab/chatlab-cli:latest
+    restart: unless-stopped
+    ports:
+      - "3110:3110"
+    volumes:
+      - chatlab-data:/data
+    command:
+      - start
+      - --port
+      - "3110"
+      - --host
+      - 0.0.0.0
+      - --token
+      - ${CHATLAB_TOKEN:?set CHATLAB_TOKEN in the Compose environment}
+      - --require-auth
+      - --no-open
+
+volumes:
+  chatlab-data:
+```
+
+`CHATLAB_TOKEN` is interpolated by Docker Compose and passed to ChatLab as the
+value of `--token`; it is not a ChatLab environment variable. Keep it in a
+secret store or an untracked `.env` file.
+
+## Multi-architecture images
+
+Docker selects the matching image for the host architecture automatically. To
+select a platform explicitly:
+
+```bash
+docker pull --platform linux/amd64 ghcr.io/chatlab/chatlab-cli:latest
+docker pull --platform linux/arm64 ghcr.io/chatlab/chatlab-cli:latest
+```
+
+The image index also contains provenance attestations. Registry interfaces may
+display these metadata manifests as `unknown/unknown`; they are not runnable
+platforms and do not need to be pulled separately.
@@ -0,0 +1,136 @@
+---
+outline: deep
+---
+
+# Docker 部署
+
+ChatLab CLI 提供 `linux/amd64` 與 `linux/arm64` 兩種架構的容器映像：
+
+```text
+ghcr.io/chatlab/chatlab-cli
+```
+
+## 快速開始
+
+```bash
+docker run --name chatlab \
+  -p 3110:3110 \
+  -v chatlab-data:/data \
+  ghcr.io/chatlab/chatlab-cli:latest
+```
+
+容器啟動後，開啟 <http://127.0.0.1:3110/>。
+
+映像使用非特權 `node` 使用者執行，並將 ChatLab 資料儲存在 `/data`。替換或升級容器時，請保留此資料卷。
+
+## 服務選項
+
+容器的預設命令是：
+
+```bash
+chatlab start --no-open --host 0.0.0.0
+```
+
+`chatlab start` 按照 CLI 中的宣告順序支援以下選項：
+
+| 選項 | 說明 |
+| --- | --- |
+| `--port <port>` | 服務連接埠，預設為 `3110`。 |
+| `--host <host>` | 監聽位址；在容器外執行時預設為 `127.0.0.1`。 |
+| `--token <token>` | 自訂 Bearer Token；省略時由 ChatLab 讀取或產生。 |
+| `--headless` | 僅啟動 API，不提供 Web UI。 |
+| `--require-auth` | 除 API 路由外，也要求 Web UI 路由使用 Bearer 驗證。 |
+| `--no-open` | 不開啟瀏覽器。 |
+| `--daemon` | 安裝 macOS/Linux 常駐服務，不適用於容器。 |
+
+Docker 參數會替換完整的預設命令。加入服務選項時，需要視需要重複 `start`、`--no-open` 與 `--host 0.0.0.0`：
+
+```bash
+docker run --rm \
+  -p 8080:8080 \
+  -v chatlab-data:/data \
+  ghcr.io/chatlab/chatlab-cli:latest \
+  start --port 8080 --host 0.0.0.0 --headless --no-open
+```
+
+也可以直接選擇其他 CLI 命令：
+
+```bash
+docker run --rm ghcr.io/chatlab/chatlab-cli:latest --version
+docker run --rm ghcr.io/chatlab/chatlab-cli:latest formats
+docker run --rm -v chatlab-data:/data \
+  ghcr.io/chatlab/chatlab-cli:latest sessions --format json
+```
+
+## 環境變數
+
+對於設定欄位，ChatLab 按照以下優先順序讀取值：
+
+1. `CHATLAB_*` 環境變數
+2. `~/.chatlab/config.toml` 或 `~/.chatlab/config.json`
+3. 內建預設值
+
+設定環境變數按照原始碼中的宣告順序如下：
+
+| 環境變數 | 說明 |
+| --- | --- |
+| `CHATLAB_DATA_DIR` | 覆寫 ChatLab 資料目錄；映像將其設定為 `/data`。 |
+| `CHATLAB_API_PORT` | 設定 `api.port`。`start` 命令會提供自己的預設值，因此請使用 `--port` 設定容器服務。 |
+| `CHATLAB_API_HOST` | 設定 `api.host`。`start` 命令會提供自己的預設值，因此請使用 `--host` 設定容器服務。 |
+| `CHATLAB_LLM_PROVIDER` | 設定 `llm.provider`。 |
+| `CHATLAB_LLM_MODEL` | 設定 `llm.model`。 |
+| `CHATLAB_LLM_BASE_URL` | 設定 `llm.base_url`。 |
+| `CHATLAB_LOCALE_LANG` | 設定 `locale.lang`。 |
+| `CHATLAB_CLI_ALLOW_RAW` | 設定為 `1` 或 `true`，允許查詢命令輸出未經隱私預處理的 `--raw` 結果。 |
+
+ChatLab 也會讀取以下執行階段變數：
+
+| 環境變數 | 說明 |
+| --- | --- |
+| `CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR` | 設定為 `1` 可略過資料目錄的最低執行階段版本檢查。此操作可能損壞資料，僅用於緊急復原。 |
+| `CHATLAB_DISABLE_NATIVE_PERF` | 設定為 `1` 可停用原生解析器加速。 |
+| `CHATLAB_LOG_LEVEL` | 將應用程式日誌層級設定為 `DEBUG`、`INFO`、`WARN` 或 `ERROR`，預設為 `INFO`。 |
+| `CHATLAB_SKIP_UPDATE_CHECK` | 設定為任意非空值可停用 CLI 更新檢查。 |
+| `CHATLAB_TEMP_ROOT` | 覆寫暫存工作區根目錄。 |
+| `LANG` | 選擇 CLI 查詢預處理使用的預設語言。 |
+
+Bearer Token、無介面模式、Web UI 驗證與瀏覽器開啟行為透過對應的命令列選項設定。ChatLab 不為這些選項提供環境變數別名。
+
+## Docker Compose
+
+```yaml
+services:
+  chatlab:
+    image: ghcr.io/chatlab/chatlab-cli:latest
+    restart: unless-stopped
+    ports:
+      - "3110:3110"
+    volumes:
+      - chatlab-data:/data
+    command:
+      - start
+      - --port
+      - "3110"
+      - --host
+      - 0.0.0.0
+      - --token
+      - ${CHATLAB_TOKEN:?set CHATLAB_TOKEN in the Compose environment}
+      - --require-auth
+      - --no-open
+
+volumes:
+  chatlab-data:
+```
+
+`CHATLAB_TOKEN` 由 Docker Compose 插值後作為 `--token` 的值傳給 ChatLab，並不是 ChatLab 環境變數。請將它儲存在密鑰儲存或未追蹤的 `.env` 檔案中。
+
+## 多架構映像
+
+Docker 會自動選擇與主機架構相符的映像。也可以明確選擇平台：
+
+```bash
+docker pull --platform linux/amd64 ghcr.io/chatlab/chatlab-cli:latest
+docker pull --platform linux/arm64 ghcr.io/chatlab/chatlab-cli:latest
+```
+
+映像索引也包含來源證明。映像倉庫介面可能將這些中繼資料資訊清單顯示為 `unknown/unknown`；它們不是可執行平台，也不需要單獨拉取。