SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

Langfuse 自架部署:VPS 資源、TLS 與備份

在自己的 VPS 執行 Langfuse,了解實際最低資源、固定 image tag、TLS 設定,以及 ClickHouse retention 和可還原的備份方式,避免磁碟填滿。

為什麼要追蹤 AI agent

自行架設 Langfuse,可查看 agent 在一次執行期間實際做了什麼。Langfuse 是開放原始碼的 LLM(大型語言模型)可觀測性工具。它會記錄每個提示、每個模型回應、每次工具呼叫及每個 token,然後將這些資料歸入一個可開啟和閱讀的 trace。在自己的 VPS 上執行 Langfuse,這些提示就不會離開你控制的伺服器。

需要這麼做的原因很直接。看不見成本問題或品質問題,就無法修正。供應商帳單只能告訴你,星期二的費用是星期一的 4 倍。trace 則會告訴你是哪次 agent 執行造成這個結果、哪個提示增加到 40,000 個 token,以及哪個重試迴圈在放棄前執行了 9 次。帳單提供數字,trace 則提供產生這個數字的程式執行脈絡。

本指南會使用 3 個術語。trace 是 agent 的一次端到端執行。observation 是該次執行中的一個步驟:一般程式碼使用 span,呼叫模型則使用 generation。score 是附加在 trace 上的數值,來源可以是人工審查或自動評估器。Langfuse 支援 OpenTelemetry(OTel),這是與供應商無關的分散式追蹤標準,因此你現有的 instrumentation 可以指向 Langfuse。

自架 Langfuse 的實際執行架構

Langfuse v4 並非單一容器,而是由兩個應用程式容器與四個儲存服務組成。在單一 VPS 上,這六個元件皆會同時執行。

  • langfuse-web 提供網頁介面與資料匯入 API。
  • langfuse-worker 在背景處理佇列。它負責解析匯入批次、計算成本並執行每日保留作業。
  • Postgres 儲存交易資料,例如使用者、組織、專案、API 金鑰與提示詞(prompts)。
  • ClickHouse 儲存追蹤資料本身,即觀察結果與評分。這是一種專為分析查詢設計的列式儲存資料庫,因此即便處理上億筆資料,儀表板仍能快速回應。
  • Redis 作為網頁與背景處理器之間的佇列與快取。
  • MinIO 提供與 S3 相容的物件儲存服務。它儲存所有原始傳入事件以及您附加的任何媒體檔案。

Langfuse 公布了各元件的最低資源需求。下表顯示了三個主要運算元件的需求。

圖表Langfuse published minimum resources per component
此圖表背後的資料
[
  {
    "label": "ClickHouse",
    "cpu_cores": 2,
    "memory_gib": 8
  },
  {
    "label": "Langfuse web",
    "cpu_cores": 2,
    "memory_gib": 4
  },
  {
    "label": "Langfuse worker",
    "cpu_cores": 2,
    "memory_gib": 4
  }
]

僅 ClickHouse 就需要 8 GiB 記憶體。網頁容器與背景處理器各需 4 GiB。這些是表中 3 個元件的最低門檻。同一頁面列出 Postgres 需 4 GiB、Redis 或 Valkey 需 1.5 GiB,而 MinIO 需 4 GiB,因此這六個元件的總需求為 25.5 GiB。該專案的 Docker Compose 指南建議單機至少配置 4 核心、16 GiB 記憶體與約 100 GiB 儲存空間。此建議值低於各元件最低需求總和,因此請將 16 GiB 視為共享 Compose 環境的絕對下限,而非充裕的空間。

請勿嘗試在 2 GiB 的方案上執行。ClickHouse 啟動後雖能短暫接受寫入,但在背景合併(merge)時會崩潰,因為合併過程會將大量資料表載入記憶體。此時您會看到 docker compose ps 回報 clickhouse 容器狀態為 restarting,dmesg 顯示類似 Out of memory: Killed process 1234 (clickhouse-serv) 的訊息,且所有 Langfuse 儀表板皆會回傳 500 錯誤。在負載較輕的情況下,ClickHouse 則會拒絕查詢並記錄 DB::Exception: Memory limit (total) exceeded。規劃時請以 16 GiB 為基準。若該 VPS 還需執行其他服務,請額外預留資源,因為即使是像 自架 AFFiNE 工作區 這種相對輕量的堆疊也需要專屬的記憶體空間,而 ClickHouse 不會釋放任何已佔用的資源。

使用 Docker Compose 部署 Langfuse

複製儲存庫。堆疊、連接方式與預設環境設定皆位於其 docker-compose.yml 中。

git clone https://github.com/langfuse/langfuse.git
cd langfuse

該檔案中所有必須修改的值皆標記為 # CHANGEME。請先產生三個應用程式密鑰。

openssl rand -base64 32   # NEXTAUTH_SECRET
openssl rand -base64 32   # SALT
openssl rand -hex 32      # ENCRYPTION_KEY

ENCRYPTION_KEY 必須為 256 位元,並以 64 個十六進位字元表示,這正是 openssl rand -hex 32 輸出的格式。它用於加密儲存於執行個體中的敏感值,包含您儲存的任何 LLM 提供者金鑰。若在已有資料後變更此值,將導致這些資料列無法解密,因此請將其視為首次啟動後即永久固定的設定。SALT 用於雜湊您的 Langfuse API 金鑰,因此變更此值將使代理程式目前使用的所有金鑰失效。

接著設定 POSTGRES_PASSWORD、CLICKHOUSE_PASSWORD、REDIS_AUTH 與 MINIO_ROOT_PASSWORD。MinIO 密碼需出現在四個位置:分別為 MINIO_ROOT_PASSWORD、LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY、LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY 與 LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY。若遺漏其中一處,MinIO 將以 SignatureDoesNotMatch 拒絕該用戶端連線,此錯誤會出現在 worker 日誌中,而網頁介面看起來仍運作正常。將這些值保留在 env 檔案中而非直接寫入受版本控制的 compose 檔案,是 Docker Compose 環境變數檔案與密鑰 所涵蓋的模式。

在啟動前鎖定映像檔標籤

提供的檔案使用 docker.langfuse.com/langfuse/langfuse:4 與 docker.langfuse.com/langfuse/langfuse-worker:4。這些標籤會隨時間變動。Langfuse 會在啟動時自動執行 Postgres 與 ClickHouse 的遷移作業,因此數個月後執行例行性的 docker compose pull,可能會導致資料庫在未經當日備份的情況下進行非預期的結構遷移。請將兩者鎖定在特定版本並寫入 docker-compose.override.yml,Compose 會將其合併至原始檔案之上,確保後續的 git pull 不會覆蓋您的編輯。相同的映像檔亦發布於 Docker Hub,下方覆寫設定即從該處拉取。

services:
  langfuse-web:
    image: docker.io/langfuse/langfuse:4.72.0
  langfuse-worker:
    image: docker.io/langfuse/langfuse-worker:4.72.0

截至 2026 年 8 月,4.3.1 為當時的 4.3 版本。此後發布頻繁,截至 2026 年 10 月 11 日,GitHub 上最新版本為 v4.56.0。上述覆寫設定使用 v4.72.0,即截至 2026 年 10 月 31 日 GitHub 上的最新版本。請查閱專案的 GitHub 發布頁面,在部署當日鎖定最新版本,並謹慎更新該數值。原始檔案中的部分儲存映像檔也應比照辦理,因為其標籤同樣會變動。postgres:17(POSTGRES_VERSION 變數的預設值)與 redis:7 均遵循主版本號。原始檔案目前針對 docker.io/clickhouse/clickhouse-server 使用確切的版本標籤,以鎖定特定的 ClickHouse 版本。此規則不限於 Langfuse:自架 openGym 健身追蹤器 僅執行此堆疊的一小部分,但仍要求指定 git 標籤,因為任何會在啟動時遷移資料庫的程式,都可能將例行性的 pull 變成結構變更。

啟動服務。

docker compose up -d
docker compose ps
docker compose logs -f langfuse-worker

首次啟動會執行遷移作業,請等待兩到三分鐘再進行存取。網頁容器在啟動後會記錄 Ready。docker compose ps 應列出六個狀態為 running 的服務。若容器陷入重啟迴圈,請查看其日誌以找出原因。ClickHouse 遷移作業於網頁容器啟動時執行,因此錯誤的 CLICKHOUSE_MIGRATION_URL 會顯示在 docker compose logs langfuse-web 中,而非您正在監控的 worker 日誌。該變數使用連接埠 9000 的 ClickHouse 原生協定,而非 HTTP 連接埠 8123;若指向 8123 將導致網頁容器啟動遷移失敗。Worker 執行的是較慢的背景遷移,因此相關報告會出現在其日誌中。

從伺服器本身檢查健康狀態。

curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/ready

單純呼叫 /api/public/health 僅能證明 API 程序存活,因為預設情況下它不會檢查資料庫。failIfDatabaseUnavailable=true 格式才適合用於監控,若資料庫無法連線,它會回傳 503。/api/public/ready 在網頁容器準備好接收流量時回傳 200,在接收到關閉指令後回傳 500。兩者皆為標準 HTTP 檢查,因此 Uptime Kuma 狀態頁面 可以監控它們,並在您的代理程式發現問題前,先通知您堆疊已離線。

部署 TLS 並關閉額外連接埠

隨附的 compose 檔案將 3000:3000 發布給 web 容器,並將 9090:9000 發布給 MinIO。兩者皆綁定於所有介面。若伺服器擁有公開 IP,代表任何掃描 3000 埠的人都能連上註冊頁面,而掃描 9090 埠的人則能直接存取儲存原始提示詞的儲存桶。

單靠防火牆規則無法關閉這些連接埠。Docker 會將自身的 DNAT 規則寫入 nat 表,這些規則會在 ufw 的 filter 規則處理封包前先行評估,因此 ufw deny 3000 會導致發布的連接埠維持開放。此問題相當常見,已有專屬指南說明:為何 Docker 發布的連接埠會繞過 ufw。請改在 override 檔案中綁定 loopback。若使用 Docker Compose 2.24.4 或更新版本,請使用 !override 來取代原有的發布連接埠;若僅使用一般列表,則會與原始綁定合併。

services:
  langfuse-web:
    ports: !override
      - "127.0.0.1:3000:3000"
    environment:
      NEXTAUTH_URL: https://langfuse.example.com
  minio:
    ports: !override
      - "127.0.0.1:9090:9000"
      - "127.0.0.1:9091:9001"

NEXTAUTH_URL 必須設定為包含協定的完整公開位址,因為登入流程會依此值建立回呼 URL。若將其保留為 http://localhost:3000 並置於 HTTPS 代理後方,登入的往返請求會將瀏覽器導向無法存取的位置。

現在,將反向代理指向 127.0.0.1:3000 並由其處理憑證。若在同一個 Compose 專案中使用 Traefik,請透過 Compose 網路將請求路由至 langfuse-web:3000,並參考 在單一 Traefik 反向代理後方執行多個應用程式 中介紹的標籤設定。若伺服器僅執行 Langfuse,Caddy 只需兩行設定即可完成相同任務。請使用 curl -sI https://langfuse.example.com/api/public/ready 進行驗證,並從另一台機器確認 curl http://YOUR_IP:3000 無法連線。

關於 MinIO 有一點需注意。Langfuse 會發送指向該 S3 端點的預簽章 URL (presigned URLs),供上傳媒體的 SDK 及載入媒體的瀏覽器使用。因此,若您使用包含圖片或音訊的多模態追蹤 (multi-modal traces),僅綁定 loopback 的 MinIO 將導致這些附件無法從其他機器上傳,或無法在瀏覽器中載入。在進行代理設定前,請先閱讀 blob 儲存設定頁面,因為寫入預簽章 URL 的端點 LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT 必須與您發布的位址一致。純文字追蹤則不受影響。

首次造訪時請建立您的帳號,隨後應確保執行個體僅供您使用。在帳號建立完成後,請設定 AUTH_DISABLE_SIGNUP=true,以防止陌生人連上頁面並進行註冊。Langfuse 亦提供 LANGFUSE_ALLOWED_ORGANIZATION_CREATORS 功能以限制組織建立權限,但此為企業版功能,需搭配授權金鑰方可生效。若您已執行 Authentik 作為您的身分識別提供者,Langfuse 支援標準 OIDC 連線,帳號管理將可與其他應用程式整合,無須僅依賴此伺服器上的密碼清單。

發送您的第一個追蹤

在網頁介面中建立專案,並從專案設定中複製其公開金鑰與私密金鑰。Python SDK 會讀取三個環境變數。

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://langfuse.example.com"

LANGFUSE_BASE_URL 是 SDK v4 中的變數名稱,該版本於 2026 年 3 月發布。舊版程式碼與舊版指南使用 LANGFUSE_HOST。若您的追蹤資料被送往 Langfuse Cloud 而非您的伺服器,原因在於未設定 base URL,因為預設值會指向託管實例。

目前的 Python SDK v5 要求 Python 3.11 或更新版本,以及 Langfuse v4.59.0 或更新版本的自架環境,上述鎖定版本的伺服器皆已滿足此需求。

pip install langfuse opentelemetry-instrumentation-anthropic anthropic
import os
from anthropic import Anthropic
from langfuse import get_client, observe
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor

AnthropicInstrumentor().instrument()
langfuse = get_client()
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

@observe(as_type="tool")
def lookup_order(order_id: str) -> str:
    return f"order {order_id}: shipped"

@observe()
def handle_request(question: str) -> str:
    context = lookup_order("A-1042")
    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=512,
        messages=[{"role": "user", "content": f"{context}\n\n{question}"}],
    )
    return message.content[0].text

if __name__ == "__main__":
    assert langfuse.auth_check()
    print(handle_request("Where is my order?"))
    langfuse.flush()

@observe 裝飾器會在函式周圍開啟一個觀察(observation),擷取其參數與回傳值,並將其嵌套在任何已啟動的觀察之下。AnthropicInstrumentor 是針對 Anthropic 客戶端的 OpenTelemetry 檢測工具,它會將每個 messages.create 呼叫轉換為包含模型名稱、Token 使用量與延遲的生成(generation),且無需修改呼叫端的程式碼。

兩個呼叫可為您執行檢查。langfuse.auth_check() 在金鑰錯誤或 base URL 不正確時會回傳 False,這比納悶為何儀表板是空的要快得多。langfuse.flush() 會阻塞直到佇列中的 span 發送完畢;短生命週期的處理程序需要此功能,因為 SDK 會在背景進行批次處理,若指令稿立即結束,未發送的批次資料將會遺失。若整個團隊都在發送追蹤而非僅單一指令稿,請將這三個變數統一設定在所有人代理程式皆會通過的閘道器中,而非設定在每個人的 shell 內;這正是 自架 OneCLI 測試工具 如何在金鑰集中管理的情況下,確保每位同事的執行過程皆被檢測的方法。

為什麼 ClickHouse 的磁碟佔用持續增加?

追蹤資料(Traces)是大多數自架服務中成長最快的資料類型。代理程式(Agent)每執行一個步驟就會寫入一列資料,且輸入與輸出內容會被完整儲存;因此,一個頻繁互動且提示詞(Prompt)冗長的代理程式,其產生的資料量遠大於它所監控的應用程式。若不加管理,ClickHouse 會填滿磁碟,而磁碟空間耗盡會導致資料寫入直接停止,而非僅是變慢。

此問題源於兩個獨立的成長因素,需分別處理。

首先是您自己的追蹤資料,解決方法是設定保留期限(Retention)。在自架實例中,資料保留功能屬於 Enterprise Edition 特性,需要授權金鑰。若無授權,Langfuse 會無限期保留追蹤、觀察(Observations)、評分與媒體檔案,因此請依此規劃磁碟空間,並參考本節末尾的磁碟警報設定。若擁有授權,專案擁有者與管理員可在專案設定中指定資料保留天數。Langfuse 最短支援保留 3 天。系統會執行夜間任務,刪除超過該期限的追蹤、觀察、評分與媒體資產(已儲存資料集項目關聯的媒體除外),並同時從 ClickHouse 與物件儲存(Blob storage)中移除。該任務需要對儲存桶具備 DeleteObject 權限,預設 compose 檔案中的 MinIO root 憑證已具備此權限。刪除動作是永久性的,若需長期保存歷史資料,請先設定物件儲存匯出。請勿手動為 Langfuse 的資料表編寫 TTL 語句:保留任務是確保 ClickHouse 與儲存桶資料同步的關鍵,手動設定 TTL 只會刪除其中一側的資料。

請根據實際使用需求選擇保留期限。成本與品質審查通常針對幾天內的資料,而非數月前的資料。對於小型團隊,30 天是合理的起點;若僅在發生故障時才查看追蹤,14 天已足夠。

第二個因素是 ClickHouse 自身的系統日誌表,這常令使用者感到意外,因為即使設定了保留期限,磁碟空間仍持續增加。ClickHouse 會寫入 trace_log、text_log、opentelemetry_span_log、metric_log、asynchronous_metric_log 與 latency_log 用於自身診斷,這些表預設沒有 TTL,且 Langfuse 從不讀取它們。請先確認磁碟空間的實際佔用來源。

SELECT table, formatReadableSize(size) AS size, rows FROM (
    SELECT table, database, sum(bytes) AS size, sum(rows) AS rows
    FROM system.parts
    WHERE active
    GROUP BY table, database
    ORDER BY size DESC
)

使用 docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD" 執行上述指令。若系統表佔用空間名列前茅,請透過設定覆寫(Config overlay)將其關閉,因為 ClickHouse 在啟動時會將 /etc/clickhouse-server/config.d/ 中的每個檔案合併至主設定檔中。

<clickhouse>
    <trace_log remove="1"/>
    <text_log remove="1"/>
    <opentelemetry_span_log remove="1"/>
    <asynchronous_metric_log remove="1"/>
    <metric_log remove="1"/>
    <latency_log remove="1"/>
</clickhouse>

掛載該檔案並重新啟動 ClickHouse。

services:
  clickhouse:
    volumes:
      - ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:ro

這會停止新的寫入。已存在於磁碟上的資料列仍會保留,請使用 DROP TABLE IF EXISTS system.trace_log 明確回收空間,對每個移除的資料表執行相同操作。若您希望保留診斷資料,另一種選擇是為每個資料表設定積極的 TTL,而非使用 remove="1",詳細說明請參閱 Langfuse 擴充文件。這些 TTL 指令僅在建立系統表時生效,因此若為現有安裝,請參考同一份文件中的資料表調整步驟。

另有一個值得注意的資料表:blob_storage_file_log,它會追蹤上傳至儲存桶的事件檔案。若您同時為儲存桶設定了生命週期政策,請為該資料表設定對應的 TTL,以確保兩者保持同步。

ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;

請務必為資料磁碟設定基礎的 df -h 警報。追蹤資料的成長並非線性,通常在您部署新代理程式當天會激增,您應在資料寫入失敗前就收到警報。

備份 Postgres 與 ClickHouse

Langfuse 的備份包含三個部分。Postgres 儲存使用者、組織、專案與 API 金鑰;ClickHouse 儲存追蹤紀錄(traces);MinIO 則儲存原始事件資料。若僅還原 Postgres,您將能登入但無法查看歷史紀錄;若僅還原 ClickHouse,則會擁有歷史紀錄但無人能登入查看。這種架構並非 Langfuse 獨有,自架 Chatwoot 客服系統 亦具備相同特性,若備份 Postgres 時未同步備份上傳目錄,還原後的對話紀錄將會遺失所有附件。

Postgres 備份可使用標準的 pg_dump,這也是 Langfuse 官方文件針對 Docker 安裝所建議的方式。

docker compose exec -T postgres pg_dump -U postgres postgres \
  | gzip > langfuse-pg-$(date +%F).sql.gz

ClickHouse 的備份則需更謹慎,因為在合併(merges)執行期間直接複製資料目錄,無法確保備份的一致性。在單機環境下,最簡單的做法是停止容器並封存 volume。

docker compose stop clickhouse
docker volume ls | grep clickhouse
docker run --rm -v langfuse_langfuse_clickhouse_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/langfuse-ch-$(date +%F).tar.gz -C /data .
docker compose start clickhouse

請務必使用 docker volume ls 顯示的 volume 名稱,而非 YAML 檔案中定義的名稱。檔案中宣告的是 langfuse_clickhouse_data,但 Docker Compose 會加上專案名稱作為前綴,因此若在名為 langfuse 的目錄中執行,實際名稱會變成 langfuse_langfuse_clickhouse_data。若名稱錯誤,docker run 會在不發出警告的情況下建立一個新的空 volume,導致您的封存檔內空無一物。

Langfuse 會在每次接收請求時將原始事件資料上傳至 bucket,並在失敗時重新讀取以重試任務,因此短暫停止 ClickHouse 通常只會導致 worker 在恢復後進行重試。請選擇離峰時段執行並縮短停機時間。對於負載較高的執行個體,可使用 ClickHouse 的 BACKUP DATABASE default TO S3(...) 指令,在不停止伺服器的情況下建立一致的備份。MinIO 是第三個部分,可使用 mc mirror 或將 MinIO 複製到外部 bucket 來處理。無論產出何種備份,請務必將其移出伺服器,這正是 在 VPS 上使用加密 restic 備份 的目的。

Redis 負責儲存佇列與快取。遺失 Redis 將導致佇列中的任務被捨棄,即使原始事件檔案仍存在於 bucket 中亦然。

一致性問題確實存在且必須明確說明。由於 Postgres 與 ClickHouse 的備份時間點不同,還原後可能會出現「專案資料存在但無追蹤紀錄」,或「追蹤紀錄所屬的專案已不存在」的情況。Langfuse 對此具有容錯能力,但請盡量在低流量時段連續執行兩者的備份。事件 bucket 是真正的安全防護網,因為 Langfuse 會在每次接收請求時將原始事件資料上傳至該處。

請務必至少在測試環境中執行一次還原演練。這能讓您在平時就發現 volume 名稱錯誤等問題,而非等到服務中斷時才發現。

首先應查看的項目

以下4項值得在第一週優先檢查。

  • 每筆 trace 的成本。 Langfuse 會根據模型名稱與 token 用量計算成本,因此請依成本排序 trace,從頭到尾閱讀成本最高的一筆。問題通常出在不斷膨脹的 prompt:將整份文件貼入 context,或未刪減的對話歷史。看清楚問題後,控制 AI agent 的成本 就會成為工程工作,而不是猜測。
  • 依 input 與 output 拆分的 token 用量。 input token 數量多且便宜,output token 數量少但昂貴,而 cached input 更便宜。Claude Code 如何計算 token 用量 會進一步說明相同的計算方式;這也適用於自行撰寫的任何 agent。
  • 延遲百分位數。 中位數會掩蓋問題。p95 與 p99 是 timeout 發生的區間;在 agent loop 中,p95 的慢速 tool call 會隨迭代次數累積。
  • 失敗的 tool call。 依層級 ERROR 篩選 observation。某個 tool 若有 5% 的失敗率,在整體成功率中可能不明顯,但在 trace 中十分明顯;你會看到模型重試,接著消耗 token 來避開問題。

設定 retention window,並選定一個每週部署當天都要查看的 dashboard。沒有人開啟的 observability tool,最後只會成為填滿磁碟的資料庫。

FAQ

自架 Langfuse 需要多少記憶體?

建議規劃 4 核心 CPU 與 16 GiB 記憶體,這是 Langfuse Docker Compose 指南針對單一虛擬機的建議配置,另需約 100 GiB 儲存空間。官方發布的各組件最低需求為 ClickHouse 需 8 GiB,Web 與 Worker 容器各需 4 GiB。同一頁面列出 Postgres 需 4 GiB、Redis 需 1.5 GiB 以及 MinIO 需 4 GiB,總計為 25.5 GiB,高於 Compose 建議的 16 GiB。

為何設定資料保留期限後,ClickHouse 磁碟空間仍持續耗盡?

保留設定僅涵蓋 Langfuse 自身的資料。ClickHouse 會另外寫入診斷資料表 trace_log、text_log、opentelemetry_span_log、metric_log、asynchronous_metric_log 與 latency_log,這些資料表預設沒有 TTL。請執行 system.parts 並依資料表分組,以查看佔用空間最大的項目,接著在 /etc/clickhouse-server/config.d/ 目錄下的檔案中加入 remove="1" 設定以停用不必要的資料表,重啟 ClickHouse,最後刪除現有資料表以回收已使用的空間。

Langfuse 的最短資料保留期限為何?

三天。保留期限可在專案設定中針對各專案進行設定,或透過 Organization Management API 調整。系統會執行每日例行任務,刪除 ClickHouse 與 Blob 儲存中超過該期限的追蹤紀錄(traces)、觀察紀錄(observations)、評分(scores)與媒體資源,但與已儲存資料集項目相關的媒體除外。在自架實例中,此功能屬於 Enterprise Edition,需要授權金鑰。若無金鑰,資料將永久保留。刪除動作無法復原,若需保留該期限以外的歷史資料,請務必先設定 Blob 儲存匯出。

我必須同時備份 Postgres 與 ClickHouse 嗎?

是的,因為兩者儲存的內容不同。Postgres 儲存使用者、組織、專案與 API 金鑰,而 ClickHouse 儲存追蹤資料本身。若僅還原 Postgres,您將得到一個可登入但內容為空的實例。請同時備份 MinIO bucket,因為它儲存了 Langfuse 接收時持久化的原始事件,這是此技術堆疊中最接近原始資料來源的項目。

我可以將現有的 OpenTelemetry 設定指向自架的 Langfuse 嗎?

可以。Langfuse v4 及其目前的 SDK 是基於 OpenTelemetry 建構的,Anthropic 與 OpenAI 的 OTel 檢測(instrumentations)可直接匯出至此。在 Python 中,請執行 pip install langfuse opentelemetry-instrumentation-anthropic,在啟動時呼叫一次 AnthropicInstrumentor().instrument(),並將 LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY 與 LANGFUSE_BASE_URL 設定為您自己的主機位址。在排查儀表板資料缺失前,請先以 langfuse.auth_check() 確認連線狀態。

這篇文章對您有幫助嗎?