企业官网建设流程全解析

ChatLab 官方提供基于ghcr.io/chatlab/chatlab-cli的 Docker 镜像，覆盖linux/amd64与linux/arm64两种架构，可在一行命令内启动完整的 Web UI 与 HTTP API。本文以官方文档（docs/cn/usage/docker.md）为骨架，结合仓库源码深入讲解三种数据挂载方案、clb web服务选项、配置环境变量的优先级与映射规则，以及 Docker Compose 的完整部署配置，帮助你完成从本机试用、数据共享到服务器常驻部署的全过程。

镜像总览：预置本地向量模型与 NLP 词典

ChatLab CLI 容器镜像名为：

ghcr.io/chatlab/chatlab-cli

镜像同时发布linux/amd64和linux/arm64两个平台，Docker 会自动选择与宿主机架构匹配的镜像（也可通过--platform显式指定，见下文“多架构镜像”）。

与通用 Node 镜像相比，官方镜像有两个关键预置：

• 内置本地向量模型所需的运行组件：启用本地语义索引时，只需按界面提示下载所选模型文件即可，不会在容器启动后再次安装约 370 MB 的 Node 依赖，显著加快首次启动与启用语义索引的流程。
• 预置简体中文分词词典：镜像将默认的简体中文分词词典存放在/opt/chatlab/nlp，并通过CHATLAB_NLP_DICT_DIR环境变量指向该路径，首次启动时无需联网下载；挂载的 ChatLab 目录中已有的词典会被保留。该变量在源码中作为bundledNlpDictDir传入共享路由注册逻辑（见 apps/cli/src/http/routes/web/index.ts），是分词能力在容器内“开箱即用”的实现基础。

快速开始：三种数据存放方式

ChatLab 的 Desktop、CLI 与 Docker 三者共享同一套数据目录设计：系统目录默认位于~/.chatlab，用户数据（聊天数据库、向量索引、AI 数据等）默认位于其中的data子目录。Docker 部署的核心就是决定“数据放哪里、如何挂进容器”。

方式一：与 Desktop / 本地 CLI 共用数据（推荐）

宿主机本机运行 Docker 时，建议直接把宿主机的~/.chatlab挂载进容器，这样 Docker 与 Desktop、本地 CLI 读取的是同一份配置、聊天数据库与 AI 数据，无需任何拷贝即可双向切换。

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 "$(id -u):$(id -g)"让容器进程使用宿主机当前用户的 UID/GID；HOME=/home/node则确保 ChatLab 的系统目录仍然是/home/node/.chatlab。对于当前用户 UID/GID 不是 1000 的 Linux 主机，这两个参数是必需的，否则容器进程无法读写挂载的宿主目录。
• 目录映射：宿主机~/.chatlab对应容器内/home/node/.chatlab；~/Downloads对应容器内可写的下载/导出目录（导出文件、截图会落到这里）。
• 固定用户数据目录：CHATLAB_DATA_DIR=/home/node/.chatlab/data将默认用户数据固定到容器可访问的路径。这一点很关键——宿主机~/.chatlab/config.toml中如果记录了绝对路径（例如 Desktop 修改过数据目录），直接挂载会导致容器内按宿主机绝对路径找不到数据；显式设置CHATLAB_DATA_DIR可避免宿主机配置中的绝对路径在容器内失效（源码层面，环境变量优先级高于配置文件，见 packages/config/src/loader.ts）。

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

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

方式二：使用独立 Docker 数据（named volume）

在服务器上部署，或明确不想与宿主机上的 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数据卷（--rm运行不会影响已有数据卷，但删除容器时不要顺手-v删除它）。

方式三：自定义用户数据目录

如果 Desktop / CLI 已将聊天数据库移动到~/.chatlab之外（即配置文件data.user_data_dir指向了别的路径），还需要额外挂载该目录，并让环境变量指向对应的容器路径：

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 的数据目录应通过挂载和环境变量调整，而不是在存储管理页面中切换。在源码中，该变量同样禁止了运行时通过存储管理界面切换数据目录（canSetDataDir: !process.env.CHATLAB_DATA_DIR，见 apps/cli/src/http/routes/web/index.ts）。

数据共享与兼容性提醒

同一版本的 Desktop、CLI 和 Docker 可以共享数据库。切换数据目录、执行迁移或跨版本使用前，建议先停止其他 ChatLab 实例。ChatLab 在启动时会检查数据目录的最低运行时版本要求：如果旧版本无法安全读取已经升级的数据目录，会通过兼容门禁拒绝启动，并提示所需的最低版本（实现见 apps/cli/src/runtime-compat.ts）。

服务选项：clb web的参数与容器命令覆盖

容器的默认命令是：

clb web --no-open --host 0.0.0.0

clb web（别名start）按 CLI 中的声明顺序支持以下选项（源码定义见 apps/cli/src/cli.ts）：

Token 的生成与读取逻辑在 HTTP 服务启动时完成：优先使用命令行传入的 token，否则读取配置中的api.token，都不存在时自动生成clb_前缀的随机 token 并尽力写回配置（见 apps/cli/src/http/index.ts）。--require-auth会设置 Web 路由的认证要求（见 apps/cli/src/http/index.ts）。

重要：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

上面的命令在 8080 端口以 API-only 模式（--headless）启动，适合只暴露 API 给其他客户端消费的场景。

容器内也可以直接执行其他 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

--version查看版本；formats列出所有受支持的聊天记录导入格式（命令实现在 apps/cli/src/cli.ts）；sessions list --format json以 JSON 输出会话列表，适合脚本化消费。注意执行需要访问数据的命令时同样要带上数据挂载参数。

环境变量：优先级、配置映射与运行时变量

配置优先级

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

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

这一优先级在配置加载器中实现：先读取文件配置，再读取环境变量配置，最后用 Zod Schema 的默认值兜底，三者逐层合并（见 packages/config/src/loader.ts）。因此，通过-e传入的环境变量可以覆盖宿主配置文件中的任何同名字段，这也是前文“自定义用户数据目录”方案能够生效的根本原因。

配置环境变量

配置环境变量按源码中的声明顺序如下（映射逻辑见 packages/config/src/loader.ts）：

关于CHATLAB_API_PORT/CHATLAB_API_HOST与--port/--host的关系需要特别注意：start（web）命令本身会提供默认值（端口默认3110、host 默认127.0.0.1，定义见 packages/config/src/schema.ts），且命令选项优先于环境变量，因此在容器中应使用--port/--host配置服务端口与监听地址，环境变量主要用于其他非 CLI 启动场景。同理，CHATLAB_DATA_DIR会设置data.user_data_dir；而 API 的api.token、api.require_auth及浏览器打开行为等没有对应的环境变量别名，只能通过命令行选项配置（见 docs/cn/usage/docker.md）。

运行时变量

ChatLab 还会读取以下运行时变量：

其中CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR在仓库测试中用于验证兼容门禁的绕过路径（见 apps/cli/src/runtime-compat-startup.test.ts），CHATLAB_SKIP_UPDATE_CHECK在更新检查器中直接短路（见 apps/cli/src/update-checker.ts）。这些变量应在确有需要时才设置，尤其是数据兼容绕过类变量，仅用于紧急恢复。

Docker Compose：服务化部署配置

在生产或常驻场景，推荐使用 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。

然后创建docker-compose.yml：

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

几点说明：

• restart: unless-stopped保证容器在宿主机重启或进程崩溃后自动拉起。
• 端口仅绑定到127.0.0.1，避免服务直接暴露到公网。
• CHATLAB_TOKEN由 Docker Compose 插值后作为--token的值传给 ChatLab，它并不是 ChatLab 环境变量；请将其保存在密钥存储或未跟踪的.env文件中，并通过--require-auth让 Web UI 路由也要求 Bearer 认证。
• ${VAR:?error message}语法会在变量缺失时直接报错拒绝启动，避免误用默认值。
• 如果需要完全独立的服务器数据（不读取宿主机的~/.chatlab），请改用上文“使用独立 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

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

小结

ChatLab 的 Docker 部署整体遵循“镜像预置运行时组件、数据目录通过挂载与环境变量控制”的设计：本机试用以~/.chatlab双向绑定为主，服务器独立部署用 named volume，自定义数据目录场景则叠加CHATLAB_DATA_DIR固定容器路径。启动 Web 服务时牢记容器参数会整体替换默认命令，务必重复start、--host 0.0.0.0与--no-open；配置读写遵循“环境变量 > 配置文件 > 内置默认值”的优先级，CHATLAB_DATA_DIR是其中优先级最高、也最常用于容器场景的配置项。更完整的 CLI 命令与配置说明，可进一步参考 apps/cli/src/cli.ts 与 packages/config/src/schema.ts。