企业官网建设流程全解析

• 数据分析
• 人工智能
• AI 应用
• AI Agent
• 桌面应用
• CLI
• MCP 服务
• AI 技能

ChatLab 是一套「本地優先」的 AI 聊天記錄分析工具，安裝方式分為 Desktop 桌面版、CLI 命令列與 Docker 容器三種，分別對應圖形化使用、腳本 / AI Agent 自動化與伺服器常駐部署三類場景。本文以官方安裝文檔 docs/tw/usage/installation.md 為主體，結合倉庫內 CLI 與配置模組的實際原始碼，完整說明每一種安裝方式的環境要求、操作步驟、啟動選項與安全注意事項，讀完即可在個人電腦或伺服器上把 ChatLab 跑起來。

三種安裝方式總覽

三種方式使用同一套使用者資料（預設位於主機的~/.chatlab），因此可以在不同方式之間切換，不需要複製資料，具體做法見下文 Docker 小節。

Desktop：圖形化安裝

前往 ChatLab 官網或 GitHub Releases 頁面下載對應作業系統的安裝程式，執行安裝即可。安裝完成後直接啟動應用，即可在首頁拖入聊天記錄檔案開始使用。

需要特別注意的硬體限制：macOS 桌面版目前僅支援搭載 Apple 晶片（M 系列）的 Mac。Intel Mac 使用者可以改用下方的 CLI Web 方式——CLI 在 Intel Mac 上照常執行，透過瀏覽器獲得與桌面版一致的 Web UI 體驗。

從倉庫結構看，桌面端是基於 Electron 構建的應用（見 apps/desktop/package.json），內部依賴electron-builder進行各平台打包；其本體與 CLI 共用同一套@openchatlab/*核心套件，這也解釋了為何不同安裝方式可以讀取同一份使用者資料。

CLI：Node.js 環境與 npm 全域安裝

CLI 安裝包名為chatlab-cli，需要Node.js 22.19 或更新版本——這與倉庫內 apps/cli/package.json 中宣告的"engines": { "node": ">=22.19.0" }完全一致，低於此版本的 Node 將無法安裝或運行。

npm install --global chatlab-cli

安裝完成後，系統會同時提供兩個命令名稱。查看 apps/cli/package.json 的bin欄位可以確認：

"bin": { "chatlab": "bin/chatlab.mjs", "clb": "bin/chatlab.mjs" }

官方建議使用更短的clb；舊的chatlab命令仍會保留，以相容既有腳本與使用習慣。可以先用clb --version確認安裝成功（該選項在 apps/cli/src/cli.ts 中註冊，同時支援-v）。

啟動 API + Web UI：clb web 的三種模式

CLI 的核心啟動命令是clb web（別名start），根據參數可以呈現三種運行模式：

clb web # 啟動 API + Web UI，並在瀏覽器中開啟 clb web --no-open # 啟動 API + Web UI，但不自動開啟瀏覽器 clb web --headless # 僅啟動 API，不提供 Web UI（供腳本 / AI Agent 呼叫）

這些選項的實際實現在 apps/cli/src/cli.ts 的web命令定義中：預設會先檢查dist-cli-web/目錄是否存在以決定是否提供 Web UI；--headless時直接跳過 Web UI 靜態資源的掛載，只啟動 HTTP API。啟動成功後終端會輸出 Web UI / API 位址與自動產生的 Bearer Token，例如：

ChatLab v0.x.x Web UI: http://127.0.0.1:3110/ API: http://127.0.0.1:3110 Token: <自動產生的令牌>

常用啟動選項

其中--port的預設值直接來自配置套件匯出的DEFAULT_API_PORT，--host的預設值為127.0.0.1（見 apps/cli/src/cli.ts）。啟動前 CLI 會先對端口做預檢，若被佔用會輸出明確的EADDRINUSE提示並快速失敗，避免初始化到一半才報錯。

進階：Unix Socket 監聽與反向代理

在 macOS 和 Linux 上，可以讓 ChatLab 不佔用 TCP 連接埠，改用 Unix 網域通訊端：

clb web --socket /tmp/chatlab.sock --no-open

啟動後可使用curl直接透過通訊端存取（請將YOUR_TOKEN替換為啟動時顯示的令牌）：

curl --unix-socket /tmp/chatlab.sock -H "Authorization: Bearer YOUR_TOKEN" http://localhost/api/v1/status

也可以在其前方設定反向代理，把 HTTP 請求轉發到該通訊端，再由代理對外提供標準 HTTP 介面。需要留意兩點：

1. 通訊端權限：若反向代理以另一個 Unix 使用者執行，請在 ChatLab 啟動後為代理所屬群組授予通訊端存取權限：

   sudo chgrp <代理群組> /tmp/chatlab.sock && sudo chmod 660 /tmp/chatlab.sock

   由於每次重新啟動都會重建通訊端，權限設定也需要每次重新套用，建議使用服務管理器的啟動後掛鉤（post-start hook）自動完成。ChatLab 與代理以相同使用者執行時通常不需要修改權限。

2. Web UI 驗證：如果代理可從本機信任環境之外存取，請使用--require-auth啟動 ChatLab（或在代理層強制驗證身分），避免 Web UI 路由和權杖設定公開暴露。

從原始碼看，--require-auth的機制位於 apps/cli/src/http/auth.ts：/api/開頭的路由始終要求 Bearer Token；而/_web/開頭的 Web UI 靜態路由，只有開啟requireAuthEnabled時才要求驗證。換句話說，--require-auth是專門為「Web UI 可能暴露在非本機環境」設計的安全開關。

常駐服務：clb web --daemon / clb status / clb stop

若要讓服務常駐後台、登入時自動啟動，可以使用常駐服務模式（僅 macOS / Linux）：

clb web --daemon # 註冊為系統服務，登入時自動啟動（macOS / Linux） clb status # 查看常駐狀態 clb stop # 停止並移除系統服務

從 apps/cli/src/daemon/service.ts 的實作可以看到底層機制：

• macOS：寫入~/Library/LaunchAgents/fun.chatlab.daemon.plist，透過 launchd 的RunAtLoad+KeepAlive實現登入自啟與崩潰重啟；
• Linux：寫入~/.config/systemd/user/chatlab.service，透過 systemd 使用者單元（systemctl --user enable --now）實現同樣效果，並帶有Restart=always；
• 服務日誌寫入~/.chatlab/logs/daemon.log，安裝資訊記錄在~/.chatlab/daemon.json；
• clb status會顯示服務是否安裝、是否運行、監聽位址與自動啟動狀態（與 apps/cli/src/cli.ts 中的status命令相對應）；
• Windows 目前不支援 daemon 模式，原始碼中會直接提示改用clb web前台運行；另外--daemon與--socket也不能同時使用，原始碼會在組合使用時直接報錯退出。

Docker：容器化部署速覽

需要容器部署時，請查看完整的 Docker 部署文檔。官方映像為ghcr.io/chatlab/chatlab-cli，提供linux/amd64與linux/arm64兩種架構，容器預設以clb web --no-open --host 0.0.0.0啟動，並已內建本地向量模型與簡體中文斷詞詞典所需的執行元件，首次啟動無需下載額外的 Node 相依套件或詞典。

資料共用的關鍵：ChatLab Desktop、CLI 和 Docker 都使用主機的~/.chatlab。在本機運行 Docker 時，建議掛載此目錄，這樣無論是先 Docker 後 Desktop / CLI，還是先 Desktop / CLI 後 Docker，都能直接讀取原有的設定、聊天資料庫和 AI 資料，完全不需要複製資料。推薦的掛載方式是：

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

這組命令的細節值得展開：映像預設使用非特權node使用者（UID/GID 1000）執行，--user讓容器程序使用主機目前使用者的 UID/GID，HOME確保系統目錄仍是/home/node/.chatlab，而CHATLAB_DATA_DIR將使用者資料固定到容器可存取的/home/node/.chatlab/data，避免主機config.toml中的絕對路徑在容器內失效。Windows PowerShell 使用者去掉--user與--mount語法差異後即可直接使用。容器啟動後，開啟 http://127.0.0.1:3110/ 即可。

如果是在伺服器上部署、明確不想與主機共用資料，則改用 Docker named volume（-v chatlab-data:/home/node/.chatlab），但要注意 Desktop 和主機 CLI不會自動看到其中的資料，升級容器時務必保留該資料卷。文檔中也提供了透過環境變數自訂使用者資料目錄、以start --port ... --headless --no-open覆寫容器預設命令、以及 Docker Compose 一鍵部署等進階方案，均收錄於 docs/tw/usage/docker.md。

安裝後的資料與配置要點

安裝完成後的第一步

安裝完成後，建議繼續閱讀 快速開始指南：把第三方工具匯出的聊天記錄檔案直接拖入 ChatLab 首頁（匯出方式見 如何匯出聊天記錄，匯入細節見 匯入聊天記錄指南），然後在設定中接入 AI 模型，即可透過自然語言探索聊天歷史。

配置優先順序與環境變數

ChatLab 對配置欄位的讀取遵循以下優先順序（實現在 packages/config/src/loader.ts）：

1. CHATLAB_*環境變數
2. ~/.chatlab/config.toml（或相容的config.json）
3. 內建預設值

常用設定環境變數與其對應的配置欄位如下（映射規則同樣見 packages/config/src/loader.ts）：

此外還有幾個運行時環境變數值得留意：CHATLAB_LOG_LEVEL（日誌層級，預設INFO）、CHATLAB_SKIP_UPDATE_CHECK（停用 CLI 更新檢查）、CHATLAB_DISABLE_NATIVE_PERF（停用原生解析器加速）等。而 Bearer Token、無介面模式、Web UI 驗證與瀏覽器開啟行為則只能透過對應的命令列選項設定，ChatLab 不為這些選項提供環境變數別名——這也解釋了 Docker 部署中為何要用--token而非環境變數來傳遞令牌。

總結

ChatLab 的三種安裝方式覆蓋了從普通使用者到伺服器運維的完整需求：Desktop 適合圖形化日常使用（注意 macOS 僅支援 Apple 晶片）；CLI 依賴 Node.js 22.19+，一條npm install --global chatlab-cli即可獲得clb web的 API + Web UI 組合，並可用--socket、--require-auth與--daemon構建安全的常駐服務；Docker 則提供多架構官方映像，透過掛載主機~/.chatlab實現與 Desktop / CLI 的無縫資料共用。三種方式共用同一套使用者資料與配置體系，安裝完成後即可匯入聊天記錄並接入 AI，開始用自然語言探索你的聊天歷史。

• 数据分析
• 人工智能
• AI 应用
• AI Agent
• 桌面应用
• CLI
• MCP 服务
• AI 技能