云计算百科
云计算领域专业知识百科平台
当前位置：网硕互联帮助中心 > 服务器百科 > 正文

ChatLab CLI Docker 部署指南：数据共享、服务器选项与环境变量全解

2026-10-01 分类：服务器百科 阅读(5) 评论(0)

【免费下载链接】ChatLab

Local-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具

项目地址：
https://gitcode.com/gh_mirrors/cha/ChatLab

点击查看 免费下载

导读

本文是 ChatLab 本地优先 AI 聊天记录分析工具官方 Docker 部署指南的完整技术文档（源文档位于 docs/en/usage/docker.md）。ChatLab CLI 以多架构容器镜像形式发布，支持 linux/amd64 与 linux/arm64，官方镜像名为 ghcr.io/chatlab/chatlab-cli。读完本文，你将掌握：如何用 bind mount 让 Docker、桌面端与本机 CLI 共享 ~/.chatlab 数据；如何使用命名卷隔离服务器数据；如何通过 clb web 的 –port/–host/–token/–headless/–require-auth 等参数定制容器服务；如何使用 Compose 一键部署并配合 Bearer Token 鉴权；以及 CHATLAB_* 环境变量的优先级与完整映射关系。

镜像特性：开箱即用的运行时与分词词典

官方镜像针对容器化场景做了三项关键预置，避免首次启动时的大规模下载与初始化延迟：

  • 内置本地嵌入模型运行时：镜像已包含本地语义索引所需运行时，启用本地语义索引时只会下载所选模型文件，而不会在容器启动后再安装约 370 MB 的 Node 依赖。
  • 预置简体中文分词词典：镜像将默认简体中文分词词典存放于 /opt/chatlab/nlp，并通过 CHATLAB_NLP_DICT_DIR 环境变量指向该路径，首次启动无需下载词典。分词由 @openchatlab/node-runtime 中的 jieba-nlp-provider.ts 基于 @node-rs/jieba 实现，词典目录通过该环境变量注入运行时。
  • 保留已挂载词典：若挂载的 ChatLab 目录中已存在词典，则以现有词典为准，不会被覆盖。

    • 快速开始

    方案一：与桌面端、本机 CLI 共享 ~/.chatlab（推荐）

    ChatLab 桌面端、CLI 与 Docker 容器都可以使用宿主机上的 ~/.chatlab 目录。在本地运行 Docker 时，直接将该目录以 bind mount 方式挂载进容器即可实现双向数据共享。

    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/ 即可访问 Web UI。

    几个关键参数的原理解析
    • –user "$(id -u):$(id -g)"：镜像默认以非特权 node 用户（UID/GID 1000）运行。在 macOS/Linux 上，–user 将容器进程的用户映射为 bind mount 宿主目录的属主，而 HOME 保持 ChatLab 系统目录位于 /home/node/.chatlab。当宿主机用户的 UID/GID 不是 1000 时（绝大多数 Linux 主机都如此），这一参数是必需的；否则容器内 node 用户无法读写挂载进来的 ~/.chatlab。
    • 挂载映射：宿主机的 ~/.chatlab 映射为容器内 /home/node/.chatlab，宿主机的 ~/Downloads 映射为容器内可写的 Downloads 目录（用于导出与截图输出）。
    • CHATLAB_DATA_DIR=/home/node/.chatlab/data：该变量将默认用户数据固定到容器可访问的 /home/node/.chatlab/data，从而保证宿主 config.toml 中记录的绝对路径在容器内不会失效。这正是 CHATLAB_DATA_DIR 在配置优先级中最高（见下文"环境变量"小节）的实际应用。
    双向免拷贝的数据共享

    采用此方案后，两个方向都不需要手工拷贝数据：

    • 先用 Docker，再安装桌面端或本机 CLI：桌面端与 CLI 继续读取宿主 ~/.chatlab；
    • 先用桌面端或本机 CLI，再运行 Docker：Docker 直接读取已有的配置、聊天数据库与 AI 数据。

    方案二：仅使用 Docker 内部数据（命名卷）

    适用于服务器部署，或希望数据与宿主上的 ChatLab 完全隔离的场景：

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

    该命名卷在 Docker 内部保留系统状态与用户数据，桌面端与本机 CLI 不会自动看到这些数据。替换或升级容器时请保留 chatlab-data 卷，否则数据会丢失。

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

    若桌面端或 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 的数据目录，而不是在 Web 的 Storage 设置页面中修改（源码中 canSetDataDir: !process.env.CHATLAB_DATA_DIR 的逻辑表明，一旦设置了该环境变量，Web 界面便不允许再修改数据目录，见 apps/cli/src/http/routes/web/index.ts）。

    版本兼容与数据安全

    同版本的桌面端、CLI 与 Docker 可以共享数据库。在更改数据目录、执行迁移或在不同版本间切换之前，请先停止其他 ChatLab 实例。若旧版本无法安全读取已升级的数据目录，ChatLab 的兼容性门禁会阻止其启动——这正是 data-dir-compat.ts 中 assertDataDirCompatible 的实现逻辑：数据目录元信息中记录了 minRuntimeVersion，当前运行时低于该版本时抛出 DATA_DIR_REQUIRES_NEWER_RUNTIME 错误并阻止启动（data-dir-compat.ts#L107-L131）。

    服务器配置选项

    默认容器命令

    clb web –no-open –host 0.0.0.0

    clb web 的选项（按 CLI 声明顺序，见 apps/cli/src/cli.ts）：

    选项说明
    –port <port> 服务器端口，默认 3110。
    –host <host> 监听地址，容器外默认 127.0.0.1。
    –token <token> 自定义 Bearer Token；省略时 ChatLab 会读取已有配置或自动生成一个。
    –headless 仅启动 API，不提供 Web UI。
    –require-auth 对 Web UI 路由与 API 路由都要求 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

    示例中把端口改为 8080 并以 –headless 启动纯 API 模式。start 是 web 命令的别名（源码中 program.command('web').alias('start')），两者等价。

    直接运行其他 CLI 子命令

    Docker 镜像同样可以执行 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

    注意：查询型命令（如 sessions list）需要读写数据目录，必须携带与启动服务器时一致的挂载与 CHATLAB_DATA_DIR 配置。

    环境变量

    配置优先级

    对于配置字段，ChatLab 按以下顺序取值（从高到低）：

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

    • 这一优先级在 packages/config/src/loader.ts 中实现：loadEnvConfig 将环境变量映射到配置节字段后与配置文件、默认值做深度合并（loader.ts#L85-L108），环境变量覆盖文件配置，文件配置覆盖内置默认值。

    配置类环境变量

    以下变量对应具体配置字段（按源码声明顺序）：

    变量说明
    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 查询输出。

    源码中完整的映射关系为（loader.ts#L88-L97）：CHATLAB_DATA_DIR → data.user_data_dir、CHATLAB_API_PORT → api.port（经 parseInt 转换）、CHATLAB_API_HOST → api.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 → cli.allow_raw（'1' 或 'true' 启用）。

    运行时类环境变量

    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 查询预处理使用的默认语言。

    其中 CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR 的绕过路径可在 data-dir-compat.ts#L109-L118 中看到：设置后仅打印警告并放行，否则抛出版本门禁错误。CHATLAB_SKIP_UPDATE_CHECK 在 update-checker.ts 中生效，返回 true 即跳过更新检查。

    无环境变量别名的选项

    Bearer Token、headless 模式、Web UI 鉴权与浏览器打开行为，均通过对应的命令行选项配置；ChatLab 不为这些选项提供环境变量别名。因此在容器中请始终使用 –token、–headless、–require-auth、–no-open 来配置。

    Docker Compose 部署

    创建 .env 文件

    在 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 即可。

    编写 Compose 文件

    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 文件中；
    • 😕 语法用于强制校验：未设置对应变量时 Compose 会直接报错退出，避免因漏配而静默使用不安全默认值；
    • –require-auth 确保 Web UI 与 API 路由都需要 Bearer 鉴权，配合 –no-open 适合无头服务器场景；
    • 若需要完全隔离的服务器数据，请改用上文"方案二"中的命名卷方式。

    多架构镜像与来源验证

    Docker 会自动选择与宿主架构匹配的镜像。如需显式指定平台：

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

    镜像索引中还包含 provenance 来源证明（provenance attestations）。注册表界面可能将这些元数据清单显示为 unknown/unknown，它们不是可运行平台，无需单独拉取。

    小结

    Docker 部署的核心决策在于数据路径：共享 ~/.chatlab 实现桌面端/CLI/容器三端互通，命名卷实现服务器数据隔离，自定义 CHATLAB_DATA_DIR 适配非默认数据布局。搭配 start –port –host –headless –require-auth –no-open 与 CHATLAB_* 环境变量，即可在容器中复刻桌面端完全一致的配置、AI 数据与查询能力。官方镜像内置的本地嵌入模型运行时与简体中文分词词典，则保证了容器启动后即可直接使用本地语义索引，无需再安装数百 MB 依赖。

    延伸阅读

    • 命令行查询与 AI 使用：docs/en/usage/cli-query.md、docs/en/ai/cli-query.md
    • 配置与导入导出：docs/en/standard/chatlab-api.md、docs/en/usage/how-to-import.md、docs/en/usage/how-to-export.md
    • 安装与故障排查：docs/en/usage/installation.md、docs/en/usage/troubleshooting.md
    • 相关源码：apps/cli/src/cli.ts（clb web/start 命令定义）、packages/config/src/loader.ts（环境变量映射）、packages/node-runtime/src/data-dir-compat.ts（数据目录兼容性门禁）

    赞

    分享

    【免费下载链接】ChatLab

    Local-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具

    项目地址：
    https://gitcode.com/gh_mirrors/cha/ChatLab

    点击查看 免费下载

    相关推荐

    • ChatLab CLI 容器化部署完全指南：Docker 镜像、数据共享与环境变量详解

      ChatLab CLI 容器化部署完全指南：Docker 镜像、数据共享与环境变量详解 ChatLab 是本地优先的 AI 聊天记录分析工具，其 CLI 提供了

      数据分析
      人工智能
      AI 应用
      AI Agent
      桌面应用
      CLI
      MCP 服务
      AI 技能
      本地部署

    • ChatLab Docker 部署完全指南：镜像选择、数据共享策略、环境变量与 Compose 实战

      ChatLab Docker 部署完全指南：镜像选择、数据共享策略、环境变量与 Compose 实战 ChatLab 是本地优先的 AI 聊天记录分析工具，官方

      数据分析
      人工智能
      AI 应用
      AI Agent
      桌面应用
      CLI
      MCP 服务
      AI 技能
      本地部署

    • 如何选择适合的PHP设计模式？DesignPatternsPHP完整决策指南

      如何选择适合的PHP设计模式？DesignPatternsPHP完整决策指南 DesignPatternsPHP是一个专注于PHP 8.x设计模式实现的开源项目

    上一篇：
    DynamicCow终极教程：在iOS 16设备上解锁灵动岛完整指南

    下一篇：
    Markdownify MCP：终极文件格式转换神器

    创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

    赞(0)
    未经允许不得转载：网硕互联帮助中心 » ChatLab CLI Docker 部署指南：数据共享、服务器选项与环境变量全解
    分享到： 更多 (0)

    相关推荐

    评论 抢沙发

    评论前必须登录！

     

    热门标签

    服务器(6110)运维(4011)人工智能(3553)linux(2078)java(1619)开发语言(1562)python(1418)网络(1244)c++(1035)数据库(981)算法(976)前端(854)大数据(750)学习(618)ai(610)安全(566)深度学习(492)spring boot(484)笔记(466)后端(464)windows(437)C语言(433)架构(420)机器学习(395)ubuntu(386)docker(364)嵌入式硬件(350)经验分享(336)单片机(323)tcp/ip(314)

    置顶推荐

    热门文章

    最新文章