Claude Code + n8n + Langfuse 三件套实战

Claude Code 调用本地模型时，Token 消耗不透明、延迟波动找不到原因、错误率无法归因——这些问题在切换到本地 Ollama 后尤为突出。本文搭建 Claude Code + n8n + Langfuse 三件套，用 Langfuse 的 OTEL Trace 打通从 Prompt 输入到工作流执行的完整链路，让每次 Claude Code 调用都有迹可循。

架构概览

三件套数据流：

Claude Code (Prompt 输入)
  ↓ HTTP (OpenAI-compatible API)
Ollama (本地 LLM)
  ↓ OTEL Trace
Langfuse (自托管，5000 端口)
  ↓ Trigger
n8n (监听 Langfuse Webhook)
  ↓ Action
工作流执行 (Slack 通知 / 记录到 Notion / 触发 CI)

• **Claude Code**：通过 `OLLAMA_BASE_URL=http://localhost:11434/v1` + `OPENAI_API_KEY=anything` 绑定 Ollama
• **n8n**：接收 Langfuse webhook，触发后续工作流
• **Langfuse**：记录每次 LLM 调用的 Token 消耗、延迟、错误率，支持自托管

前置准备

• **系统**：Ubuntu 22.04 LTS，RAM 16GB+
• **软件**：Docker 26.x, Docker Compose v2, Ollama 0.5.x
• **模型**：Ollama 默认模型 (如 llama3.2:3b)
• **验证命令**：`docker --version && ollama --version && curl -s http://localhost:3000/api/public/health`

步骤一：部署 Langfuse 自托管

Langfuse 提供官方 Docker Compose 模板，比 Vercel 部署更可控（数据不出境）。

mkdir -p ~/langfuse && cd ~/langfuse
# 下载官方模板
curl -fsSL https://langfuse.com/self-hosting/docker -o docker-compose.yml
# 修改环境变量
export SECRET_KEY=local-dev-secret-change-in-prod
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/langfuse
export NEXTAUTH_SECRET=local-auth-secret
# 启动
docker compose up -d
# 验证
curl -s http://localhost:3000/api/public/health | python3 -m json.tool

输出示例：

{"status":"ok","version":"3.14.2"}

Langfuse 仪表板：http://your-server:3000，默认注册第一个用户为管理员。

步骤二：配置 Claude Code 连接 Ollama

Claude Code 通过 OpenAI-compatible API 连接 Ollama，无需插件。

# 设置环境变量（建议写入 ~/.bashrc）
export OLLAMA_BASE_URL=http://localhost:11434/v1
export OPENAI_API_KEY=local-dev
export MODEL=llama3.2:3b

# 在 Claude Code 中验证
claude "What is 2+2?" --output-format stream

如果报错 Connection refused，检查 Ollama 服务：

# 确认 Ollama 在监听 11434
curl http://localhost:11434/api/tags

步骤三：Langfuse Python SDK 注入 Trace

在 Claude Code 调用的脚本中注入 Langfuse SDK：

# my_script.py
from langfuse import Langfuse
import os

langfuse = Langfuse(
    public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
    secret_key=os.environ["LANGFUSE_SECRET_KEY"],
    host="http://your-langfuse-server:3000"
)

def call_llm(prompt):
    with langfuse.start_span(name="ollama-call") as span:
        span.input = prompt
        # 这里实际调用 Ollama（通过 OpenAI SDK）
        response = openai.ChatCompletion.create(
            model=os.environ["MODEL"],
            messages=[{"role":"user","content":prompt}],
            api_base=os.environ["OLLAMA_BASE_URL"],
            api_key=os.environ["OPENAI_API_KEY"]
        )
        span.output = response["choices"][0]["message"]["content"]
        return response["choices"][0]["message"]["content"]

步骤四：n8n 监听 Langfuse Webhook

Langfuse 支持 webhook 回调，n8n 接收后触发后续动作（Slack 通知、写入 Notion、触发 CI）。

# n8n 自托管（接 6/15 n8n + Langfuse 实战）
mkdir -p ~/n8n && cd ~/n8n
curl -fsSL https://raw.githubusercontent.com/n8n-io/n8n/master/docker-compose.yml -o docker-compose.yml
# 添加 Langfuse Webhook Node
# n8n 管理面板 → Workflows → New → Webhook (langfuse-events)
# Trigger URL: https://your-langfuse.com/api/public/ingestion

n8n workflow 示例：当 Langfuse 记录一次 LLM 调用 latency > 5000ms，自动发 Slack 告警：

[Webhook Trigger] → [IF: trace.latency > 5000] → [Slack Node: @here 高延迟告警]

💣 踩坑录

坑一：Ollama 端口 11434 未监听所有接口

**报错**：ECONNREFUSED 127.0.0.1:11434

**原因**：Ollama 默认只监听 127.0.0.1，Docker 容器内无法访问宿主机 Ollama。

**修复**：设置 OLLAMA_HOST=0.0.0.0：

# 编辑 systemd 服务
sudo systemctl edit ollama
# 添加：
[Service]
Environment="OLLAMA_HOST=0.0.0.0"
# 重载
sudo systemctl daemon-reload && sudo systemctl restart ollama

坑二：Langfuse 5000 端口被 Docker 占用的默认冲突

**报错**：port is already allocated

原因：某些 Docker 镜像默认占用 5000 端口（Flask/Remnia 等）。

修复：

# 方法 1：修改 Langfuse 端口
# docker-compose.yml 中添加：
services:
  langfuse:
    ports:
      - "3000:3000"
      - "3001:3001"
# 改 DATABASE_URL 为 5432（PostgreSQL 默认）

# 方法 2：查占端口进程
sudo lsof -i :5000

坑三：Langfuse Python SDK 与 Ollama 的 model name 不匹配

**现象**：Langfuse Dashboard 显示 trace，但 model name 显示 unknown

**原因**：Ollama 返回的 model 名称格式是 llama3.2:3b，而 Langfuse SDK 默认用 openai 填充。

修复：在 span 设置时显式传递 model：

with langfuse.start_span(
    name="ollama-call",
    metadata={"model": os.environ["MODEL"]}
) as span:
    ...

坑四：n8n Webhook 超时（Langfuse 默认 30s timeout）

**报错**：RequestTimeoutError: Webhook request timeout

原因：Langfuse webhook 默认 timeout 30s，但复杂 n8n workflow 超过此时间。

修复：在 Langfuse dashboard → Settings → Webhooks → increase timeout，或将 webhook 改为异步触发：

[Webhook] → [Node: Delay 0] → [Node: HTTP Request (Langfuse ACK)]

坑五：Langfuse PostgreSQL 连接池耗尽（高频调用）

**报错**：remaining connection slots are reserved

**原因**：Langfuse 自托管默认 max_connections=20，高频 Claude Code 调用（每分钟 100+ 次）迅速耗尽。

修复：

# 在 docker-compose.yml 的 PostgreSQL 部分添加：
environment:
  POSTGRES_MAX_CONNECTIONS: 100
# 或直接修改：
ALTER SYSTEM SET max_connections = 100;
sudo systemctl restart postgresql

效果对比

总结

Claude Code + n8n + Langfuse 三件套将本地 LLM 的调用黑盒打开成透明链路：Langfuse 记录每次调用，n8n 根据 Trace 结果触发后续工作流，形成「LLM 调用 → 可观测性追踪 → 自动化响应」的完整闭环。

如果你在本地跑大模型，建议从 Langfuse 自托管开始（30 分钟可完成），再逐步接入 n8n 做告警和工作流。

延伸阅读：

👉 Join MiniMax Token Plan: AI coding acceleration for businesses

👉 Join Zhipu Coding Plan: GLM-4.6/GLM-5 coding packages, China-stable, pay-per-token unlimited

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews