ChatLab/docs/cn/usage/docker.md

outline

outline
deep

Docker 部署

ChatLab CLI 提供 linux/amd64 和 linux/arm64 两种架构的容器镜像：

ghcr.io/chatlab/chatlab-cli

官方镜像已内置本地向量模型所需的运行组件。启用本地语义索引时，只需按界面提示下载所选模型文件，不会在容器启动后再安装约 370 MB 的 Node 依赖。

镜像还将默认的简体中文分词词典存放在 /opt/chatlab/nlp，并通过 CHATLAB_NLP_DICT_DIR 指向该路径，因此首次启动时无需下载。挂载的 ChatLab 目录中已有的词典会被保留。

快速开始

与 Desktop / 本地 CLI 共用数据（推荐）

ChatLab 的 Desktop、CLI 和 Docker 都可以使用宿主机的 ~/.chatlab。本机运行 Docker 时，建议直接挂载这个目录：

macOS / Linux：

mkdir -p "$HOME/.chatlab" "$HOME/Downloads"

docker run --name chatlab \
  -p 127.0.0.1:3110:3110 \
  --user "$(id -u):$(id -g)" \
  --mount type=bind,source="$HOME/.chatlab",target=/home/node/.chatlab \
  --mount type=bind,source="$HOME/Downloads",target=/home/node/Downloads \
  -e HOME=/home/node \
  -e CHATLAB_DATA_DIR=/home/node/.chatlab/data \
  ghcr.io/chatlab/chatlab-cli:latest

Windows PowerShell：

New-Item -ItemType Directory -Force "$HOME/.chatlab" | Out-Null

docker run --name chatlab `
  -p 127.0.0.1:3110:3110 `
  --mount "type=bind,source=$HOME/.chatlab,target=/home/node/.chatlab" `
  -e CHATLAB_DATA_DIR=/home/node/.chatlab/data `
  ghcr.io/chatlab/chatlab-cli:latest

容器启动后，打开 http://127.0.0.1:3110/。

镜像默认使用非特权 node 用户（UID/GID 1000）运行。在 macOS 和 Linux 上，--user 会让容器进程使用宿主机当前用户的 UID/GID，HOME 则确保 ChatLab 的系统目录仍是 /home/node/.chatlab。对于当前用户 UID/GID 不是 1000 的 Linux 主机，这两个参数是必需的。宿主机的 ~/.chatlab 对应容器内的 /home/node/.chatlab，~/Downloads 对应容器内可写的下载目录；CHATLAB_DATA_DIR 将默认用户数据固定到容器可访问的 /home/node/.chatlab/data，避免宿主机 config.toml 中的绝对路径在容器内失效。

使用这组命令后，两种切换都不需要复制数据：

• 先使用 Docker，之后安装 Desktop 或本地 CLI：Desktop / CLI 会继续读取宿主机 ~/.chatlab。
• 已经使用 Desktop 或本地 CLI，之后启动 Docker：Docker 会直接读取原有的配置、聊天数据库和 AI 数据。

使用独立 Docker 数据

在服务器上部署，或者明确不想与宿主机上的 ChatLab 共用数据时，可以使用 Docker named volume：

docker run --name chatlab \
  -p 127.0.0.1:3110:3110 \
  -v chatlab-data:/home/node/.chatlab \
  ghcr.io/chatlab/chatlab-cli:latest

该数据卷会保留容器内的系统状态和用户数据，但 Desktop 和宿主机 CLI 不会自动看到其中的数据。替换或升级容器时，请保留 chatlab-data 数据卷。

自定义用户数据目录

如果 Desktop / CLI 已将聊天数据库移动到 ~/.chatlab 之外，还需要挂载该目录，并让环境变量指向对应的容器路径：

docker run --name chatlab \
  -p 127.0.0.1:3110:3110 \
  --user "$(id -u):$(id -g)" \
  --mount type=bind,source="$HOME/.chatlab",target=/home/node/.chatlab \
  --mount type=bind,source="$HOME/Downloads",target=/home/node/Downloads \
  --mount type=bind,source="/absolute/path/to/chatlab-data",target=/chatlab-data \
  -e HOME=/home/node \
  -e CHATLAB_DATA_DIR=/chatlab-data \
  ghcr.io/chatlab/chatlab-cli:latest

请将 /absolute/path/to/chatlab-data 替换为宿主机上的真实用户数据目录。系统数据仍通过 ~/.chatlab 挂载。由于 CHATLAB_DATA_DIR 的优先级最高，Docker 的数据目录应通过挂载和环境变量调整，而不是在存储管理页面中切换。

同一版本的 Desktop、CLI 和 Docker 可以共享数据库。切换数据目录、执行迁移或跨版本使用前，建议先停止其他 ChatLab 实例；如果旧版本无法安全读取已经升级的数据目录，ChatLab 会通过兼容门禁拒绝启动。

服务选项

容器的默认命令是：

clb web --no-open --host 0.0.0.0

clb web 按 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：

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  --user "$(id -u):$(id -g)" \
  --mount type=bind,source="$HOME/.chatlab",target=/home/node/.chatlab \
  --mount type=bind,source="$HOME/Downloads",target=/home/node/Downloads \
  -e HOME=/home/node \
  -e CHATLAB_DATA_DIR=/home/node/.chatlab/data \
  ghcr.io/chatlab/chatlab-cli:latest \
  start --port 8080 --host 0.0.0.0 --headless --no-open

也可以直接选择其他 CLI 命令：

docker run --rm ghcr.io/chatlab/chatlab-cli:latest --version
docker run --rm ghcr.io/chatlab/chatlab-cli:latest formats
docker run --rm \
  --user "$(id -u):$(id -g)" \
  --mount type=bind,source="$HOME/.chatlab",target=/home/node/.chatlab \
  --mount type=bind,source="$HOME/Downloads",target=/home/node/Downloads \
  -e HOME=/home/node \
  -e CHATLAB_DATA_DIR=/home/node/.chatlab/data \
  ghcr.io/chatlab/chatlab-cli:latest sessions list --format json

环境变量

对于配置字段，ChatLab 按以下优先级读取值：

1. CHATLAB_* 环境变量
2. ~/.chatlab/config.toml 或 ~/.chatlab/config.json
3. 内置默认值

配置环境变量按源码中的声明顺序如下：

环境变量	说明
CHATLAB_DATA_DIR	覆盖 ChatLab 用户数据目录。设置后，请另外挂载所选目录。
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

先在 Compose 文件旁创建未跟踪的 .env：

CHATLAB_HOST_DIR=/absolute/path/to/.chatlab
CHATLAB_DOWNLOADS_DIR=/absolute/path/to/Downloads
CHATLAB_UID=1000
CHATLAB_GID=1000
CHATLAB_TOKEN=replace-with-a-secret-token

将 CHATLAB_HOST_DIR 替换为宿主机的 ~/.chatlab 绝对路径，并将 CHATLAB_DOWNLOADS_DIR 设置为一个已存在且可写的导出和截图目录，例如宿主机的 ~/Downloads。在 macOS 和 Linux 上，还需要将 CHATLAB_UID、CHATLAB_GID 分别替换为 id -u、id -g 的输出；Windows Docker Desktop 可以保留 1000。

services:
  chatlab:
    image: ghcr.io/chatlab/chatlab-cli:latest
    restart: unless-stopped
    user: "${CHATLAB_UID:-1000}:${CHATLAB_GID:-1000}"
    ports:
      - "127.0.0.1:3110:3110"
    environment:
      HOME: /home/node
      CHATLAB_DATA_DIR: /home/node/.chatlab/data
    volumes:
      - "${CHATLAB_HOST_DIR:?set CHATLAB_HOST_DIR in the Compose environment}:/home/node/.chatlab"
      - "${CHATLAB_DOWNLOADS_DIR:?set CHATLAB_DOWNLOADS_DIR in the Compose environment}:/home/node/Downloads"
    command:
      - start
      - --port
      - "3110"
      - --host
      - 0.0.0.0
      - --token
      - ${CHATLAB_TOKEN:?set CHATLAB_TOKEN in the Compose environment}
      - --require-auth
      - --no-open

CHATLAB_TOKEN 由 Docker Compose 插值后作为 --token 的值传给 ChatLab，并不是 ChatLab 环境变量。请将其保存在密钥存储或未跟踪的 .env 文件中。如果需要完全独立的服务器数据，请改用上文“使用独立 Docker 数据”中的 named volume。

多架构镜像

Docker 会自动选择与宿主机架构匹配的镜像。也可以显式选择平台：

docker pull --platform linux/amd64 ghcr.io/chatlab/chatlab-cli:latest
docker pull --platform linux/arm64 ghcr.io/chatlab/chatlab-cli:latest

镜像索引还包含来源证明。镜像仓库界面可能将这些元数据清单显示为 unknown/unknown；它们不是可运行平台，也无需单独拉取。