ChatLab

繁體中文

English
简体中文

繁體中文

English
简体中文

Appearance

Docker 部署 ​

ChatLab CLI 提供 linux/amd64 與 linux/arm64 兩種架構的容器映像：

text
ghcr.io/chatlab/chatlab-cli

快速開始 ​

與 Desktop / 本機 CLI 共用資料（建議） ​

ChatLab Desktop、CLI 和 Docker 都可以使用主機的 ~/.chatlab。在本機執行 Docker 時，建議直接掛載此目錄：

macOS / Linux：

bash
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：

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：

bash
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 以外，還需要另外掛載該目錄，並讓環境變數指向對應的容器路徑：

bash
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 會透過相容性閘門拒絕啟動。

服務選項 ​

容器的預設命令是：

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 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 命令：

bash
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：

dotenv
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。

yaml
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 會自動選擇與主機架構相符的映像。也可以明確選擇平台：

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；它們不是可執行平台，也不需要單獨拉取。