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 条评论

登录 后参与评论

还没有评论,来抢沙发~