Langfuse 開源本地部署(Docker Compose)與提示詞版本管理(Prompt Management)從零上手教學

企業內網嚴禁業務日誌出境,又想免費擁有大模型調用鏈追蹤與不發版熱更新提示詞的能力?本文按 Langfuse 官方文檔整理 Docker Compose 本地一鍵啟動(含 ClickHouse 架構注意事項)、密鑰配置與 Prompt Management 標籤化版本管理全流程。

NNathaniel bigo··原創首發·AI 輔助撰寫
10 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 免費帳號 帳號

結論先說

  1. 官方提供開箱即用的 docker compose up 全棧編排:克隆官方倉庫後一條命令即可拉起 Web 控制檯、異步 Worker、PostgreSQL、ClickHouse、Redis 與 MinIO,無需註冊任何外部雲服務。
  2. 本機 Docker 至少預留 4GB 以上內存:新版架構依賴 ClickHouse 高速寫入海量調用鏈,內存太小會導致容器反覆重啟或健康檢查超時。
  3. 上生產前必須改掉預設密鑰:測試跑通後若要對團隊內網暴露,務必修改環境變量中的 NEXTAUTH_SECRET、SALT、ENCRYPTION_KEY 與數據庫預設密碼。
  4. 提示詞管理靠 production 標籤加客戶端內存緩存實現零延遲熱更新:運營或研發在網頁後台把新版本切到 production 標籤後,線上代碼在緩存過期(預設 60 秒)後自動生效,Langfuse 掛掉時 SDK 也會降級使用內存舊緩存不崩業務。
  5. AI 編程訂閱與團隊採購入口:部署與編寫後端工程可搭配高頻編程助手提效,國內免外幣卡開通可見本站 Claude Code 訂閱說明、ChatGPT Business 團隊定製 與 AI 會員充值中心。

Langfuse 本地部署核心容器職責

圖:本站根據 Langfuse 官方文檔:Local Deployment 整理的示意圖

本文根據 Langfuse 官方自託管文檔《Local Deployment (Docker Compose)》與《Prompt Management》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Langfuse 官方網站。

適用於誰

  • 有數據合規要求,希望把所有用戶對話 Trace、Token 帳單與評測數據完全留在公司自有伺服器或本機的開發團隊;
  • 厭倦了每次只改提示詞裏一句話都要走 Git 提交、CI 構建和重新發版流程的工程師;
  • 準備用 Docker Compose 在本地快速拉起 Langfuse v3 並跑通第一條提示詞熱加載的人。

一、Docker Compose 本地一鍵部署步驟與資源要求

在裝好 Docker Desktop(macOS / Windows WSL2)或 Linux Docker Engine 的機器上,確保 Docker 可用內存不低於 4GB(推薦 8GB),且本機 3000、5432、8123、9090 等端口未被佔用,按順序執行:

bash
# 1. 克隆官方倉庫並進入目錄
git clone https://github.com/langfuse/langfuse.git
cd langfuse

# 2. 後台啟動完整容器棧(首次拉取鏡像並初始化 ClickHouse 約需 2 至 3 分鐘)
docker compose up -d

# 3. 觀察 langfuse-web 容器日誌,看到 Ready 即可訪問
docker compose logs -f langfuse-web

看到服務就緒後,打開瀏覽器訪問 http://localhost:3000:

  1. 點擊 Sign up 在本地數據庫創建第一個管理員帳號(數據僅存本機 PostgreSQL,不聯網發送);
  2. 依次創建 Organization(組織)與 Project(項目);
  3. 進入項目左側 Settings > API Keys,點擊創建密鑰,複製儲存 pk-lf-...(公鑰)、sk-lf-...(私鑰)以及本地地址 http://localhost:3000。

內網長期運行必改項:官方示例編排文件裏硬編碼了演示用密碼與 # CHANGEME 標記。正式給團隊用之前,請用 openssl rand -hex 32 重新生成 NEXTAUTH_SECRET、SALT 與 ENCRYPTION_KEY,並將 NEXTAUTH_URL 改為內網真實訪問域名或 IP 端口。

二、提示詞版本管理(Prompt Management)實戰

Langfuse 部署與提示詞管理四步

圖:本站根據 Langfuse 官方文檔:Prompt Management 整理的示意圖

把提示詞硬編碼在 Python 代碼裏有兩大痛點:產品經理沒法幫忙調優措辭,而且線上追查 Bug 時不知道昨天下午那條錯答究竟用的是哪一版提示詞。Langfuse 的提示詞中心通過「不可變版本號 + 環境標籤(Labels)」解決這一問題:

  1. 在控制檯新建模板:點擊左側選單 Prompts > New prompt,名稱填 order-refund-assistant,類型選 Chat(對話消息列表)或 Text(純文本)。
  2. 使用雙花括號定義動態變量:在內容框寫入如下結構,勾選底部的 Set the "production" label 儲存為 Version 1:
text
你是企業售後客服助手。請嚴格依據以下制度回答,不要編造條款:
【制度片段】:{{policy_context}}
【用戶提問】:{{question}}
  1. Python 代碼拉取編譯並與調用鏈雙向綁定:安裝 pip install langfuse openai(首次調模型接口可參考 大模型 API 首次調用通用入門),寫入以下代碼:
python
import os
from langfuse import Langfuse
from langfuse.openai import OpenAI

os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-你的公鑰"
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-你的私鑰"
os.environ["LANGFUSE_HOST"] = "http://localhost:3000"

langfuse = Langfuse()
client = OpenAI()  # 使用 Langfuse 包裝版客戶端

# 預設拉取 label="production" 的版本,客戶端自動內存緩存 60 秒(0 網絡阻塞)
prompt = langfuse.get_prompt("order-refund-assistant", label="production", cache_ttl_seconds=60)
compiled_text = prompt.compile(
    policy_context="數碼產品拆封激活後無質素問題不支持七天無理由退貨。",
    question="剛激活的平板不喜歡能退嗎?",
)

# 將 langfuse_prompt 傳入請求,後台會自動按提示詞版本號彙總成功率與成本
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": compiled_text}],
    langfuse_prompt=prompt,
)
print(resp.choices[0].message.content)
langfuse.flush()

代碼上線後,如果發現某類邊界問題回答生硬,直接在 localhost:3000 網頁端編輯儲存為 Version 2,先打上 staging 標籤在測試環境驗證,確認無誤後把 production 標籤挪到 Version 2,線上服務無需重啟就會在 1 分鐘內平滑切換過去。

訂閱與帳號準備提示:在本地調試 Docker 編排報錯或編寫後端服務時,配合終端智能體可大幅減少查日誌時間(入門見 Claude Code 中文入門教學);國內開發者可在本站免外幣卡自助開通 Claude Pro 或大額度的 Claude Max。

三、成本核算與緩存架構聯動建議

Langfuse 內置了主流模型的公開價格表,也可以在控制檯 Models 頁添加企業私有化部署模型的自定義單價(官方公開價格速查見 AI 大模型 API 價格對比)。當你在管理十幾萬字長系統提示詞模板時,記得把固定規則放在 system 頂部、動態 {{question}} 放在末尾,避免破壞模型廠商的前綴提示詞緩存(原理見 RAG 與長上下文加提示詞緩存選型框架)。

常見問題

問:執行 docker compose up -d 後 langfuse-web 反覆報錯退出怎麼辦?

答:九成是 clickhouse 或 postgres 容器還沒初始化完畢,或者宿主機內存不足導致 ClickHouse 被系統 OOM 殺掉。運行 docker compose ps 檢查各依賴容器是否為 healthy,清理無用鏡像釋放內存後再執行 docker compose up -d。

問:萬一自建的 Langfuse 容器重啟維護,會導致線上業務調 get_prompt 全部報錯癱瘓嗎?

答:只要該進程啟動後成功拉取過一次提示詞,SDK 就算遇到後台網絡超時也會自動回退使用內存裏的舊緩存副本繼續服務;冷啟動防災還可在 get_prompt(..., fallback="兜底提示詞") 參數裏傳入本地硬編碼兜底文本。

問:後續怎麼安全升級本地 Docker 版本的 Langfuse?

答:先對 PostgreSQL 數據卷做一次 pg_dump 備份,再拉取最新倉庫配置或修改鏡像版本號執行 docker compose pull && docker compose up -d,容器啟動時會自動按序執行數據庫與 ClickHouse 表結構遷移腳本。

問:國內個人或研發團隊沒有外幣信用卡,怎麼訂閱 AI 編程會員或開具報銷發票?

答:可前往本站 AI 會員充值中心 自助兌換 Claude Pro 卡密、ChatGPT Plus 或諮詢團隊定製(自助卡密無需提供帳號密碼),支持支付寶、微信支付與 AlipayHK 付款並支持開具增值稅發票;實時價格與售後邊界(掉訂閱按剩餘天數折退,封號不在質保範圍)以頁面展示為準。

相關教學

參考資料

  • Langfuse 官方自託管文檔:Local Deployment (Docker Compose) — https://langfuse.com/self-hosting/local
  • Langfuse 官方文檔:Prompt Management Get Started — https://langfuse.com/docs/prompts/get-started
  • Langfuse 官方 GitHub 倉庫 — https://github.com/langfuse/langfuse

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同產品的其他教學

  1. 01

    用 ChatGPT 速讀英文產品手冊、開源文檔與 GitHub Issue 並沉澱團隊中文內訓手冊

    團隊引入海外 SaaS 工具或開源框架時,全英文文檔晦澀冗長、真正的坑全藏在幾十頁 GitHub Issue 討論裏。本文分享速讀拆解英文手冊、歸類 Issue 排障庫以及重構團隊中文內訓 SOP 的完整實戰流程。

    ChatGPT其他 AI 工具0
  2. 02

    用 ChatGPT 寫油猴腳本(Tampermonkey)與瀏覽器書籤小工具解決網頁繁瑣重複操作實戰

    每天在後台系統裏重複勾選幾十個複選框、手工複製網頁表格或清理遮擋閱讀的側邊欄,既枯燥又浪費時間。本文分享不會寫 JS 也能用 F12 配合 ChatGPT 寫出油猴腳本與書籤小工具的完整實戰流程。

    ChatGPT其他 AI 工具0
  3. 03

    用 ChatGPT 寫高質素 SQL 窗口函數(RANK / LAG / SUM OVER)做留存與漏斗分析實戰

    做用戶留存率、復購間隔與有序轉化漏斗時,多層自連接既難讀又拖垮數據庫,窗口函數則是高效解法。本文整理數據庫方言喂數規範、CTE 分層提示詞以及用內置沙盒先驗證再上線的完整實戰流程。

    ChatGPT其他 AI 工具0
  4. 04

    ChatGPT 連接 Canva、Figma、Linear、Jira、Dropbox 等第三方應用搜不到數據或授權失效怎麼辦

    在 ChatGPT 接入 Canva、Figma、Linear、Jira 或 Dropbox 後,明明顯示已連接卻搜不到文件工單,或老提示授權失效怎麼辦?本文拆解帳號錯綁、OAuth 範圍漏選、權限繼承與管理員攔截 5 步排障法。

    ChatGPT其他 AI 工具0
  5. 05

    Anthropic Contextual Retrieval(上下文增強檢索)是什麼、怎麼實現:給文檔塊自動補背景摘要結合緩存降失誤率

    長文檔切成小塊後丟了公司名、年份和主語指代導致 RAG 頻頻搜錯?本文按 Anthropic 官方技術文章詳解 Contextual Retrieval 原理、官方公開評測失誤率下降 49% 至 67% 的組合架構,以及用 Claude 提示詞緩存低成本批量生成切片背景的完整 Python 代碼。

    Claude其他 AI 工具0
  6. 06

    RAG 知識庫回答不準怎麼調優:切片大小(Chunking)、BM25 + 向量混合檢索與 Rerank 重排序三步排查法

    搭好的 RAG 企業知識庫一問具體型號、報錯碼或跨行表格就答非所問?本文按 OpenAI 與 Anthropic 官方檢索文檔,給出先隔離檢索與生成故障、再按結構化切片(Chunking)、BM25 加向量混合召回(RRF)與 Rerank 重排序逐層調優的三步法。

    Claude其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~