给 AI 装上＂黑匣子＂,差点翻车:在鲲鹏服务器上部署 Langfuse v3 的完整踩坑记

大家在使用或者开发大模型的过程中，一定会遇到一个问题，就是相对复杂一点的流程，大模型就是个黑箱，他究竟是如何运作的，你看不到，也摸不清，所以心里特别没底。

那怎么办呢？其实可以借鉴飞机的“黑匣子”思想，记录大模型在运行过程中的一举一动，市面上较火的项目有两个，一个是Langsmith,功能强，效果好，但这个是需要你将数据提交到他的云上，所以不是特别放心；另外一个 就是今天我要写的主角：Langfuse.

但这次部署过程比我想象的要难得多。难到什么程度呢？我花了将近3天，中间数次想放弃，最后是靠翻 GitHub issue 找到了一条别人踩出来的路，才勉强走通。

这篇文章就是完整记录。不是那种"三步搞定"的教程，而是一个真实的、充满死胡同和意外发现的踩坑过程。

一、Langfuse 是什么

Langfuse，：Langfuse（开源 LLM Engineering Platform），

简单说，Langfuse 就是大模型应用的"黑匣子"。你给代码加几行 SDK，它能帮你记录每次调用大模型的输入输出、Token 用量、延迟、错误率，还能做 prompt 版本管理和链路追踪。

• 定位
  LLM 应用的可观测 + 调试 + 评估 + 管理一体化平台
• 对标
  LangSmith（功能高度一致，但开源、可私有化、免费额度友好）
• 本质
  给大模型应用做 “监控 + 日志 + 质检 + 版本管理” 的工程化工具

对于做 AI 应用的人来说，这东西就像你给 Web 应用加的 Sentry。没有它的时候觉得无所谓，有了之后你会发现——之前那些"感觉效果不好"的模糊判断，现在全都有数据支撑了。

我之前装过 v2，很简单，一个 Docker 容器加一个 PostgreSQL，五分钟搞定。但 v3 变了——架构从 1 个容器变成了 5 个：

为什么要加 ClickHouse？因为 v3 把分析查询从 PostgreSQL 搬到了 ClickHouse。道理我都懂，但看着这 5 个容器，我有种不好的预感。

二、第一个坑：CPU 架构

我的服务器是华为鲲鹏 920，ARM64 架构。这颗 CPU 跑日常业务没问题，但跑某些软件会踩坑。

Langfuse v3 需要 ClickHouse。我信心满满地拉了最新版：

docker pull clickhouse/clickhouse-server:24.8-alpine

    启动，ClickHouse 容器秒退。退出码 132——SIGILL，非法指令。

什么意思？ClickHouse 用了鲲鹏 920 不支持的 CPU 指令。鲲鹏 920 是 ARMv8.2 架构，不支持 ARMv9 的 SVE 扩展和 LRCpc 指令集，但新版 ClickHouse 的官方二进制编译时默认开启了这些指令。

好，降版本。23.8？还是 选哪一个，尝试了下，选23.3，能跑了。

那一刻我还挺高兴的——总算找到一个能用的版本。

我不知道的是，麻烦才刚刚开始。

三、第二个坑：dateDiff('millisecond')

ClickHouse 23.3 启动成功，所有容器都起来了，Web 返回 HTTP 200，health check 正常。405 条数据库迁移跑完，11 张 ClickHouse 表创建成功。

我打开浏览器，登录 Langfuse Dashboard，点击"Home"页面——

白屏。

浏览器控制台报了 500 错误。后端日志里刷出来一条：

Error: Function dateDiff does not support 'millisecond' unit.tRPC route failed on dashboard.executeQuery

什么意思？Langfuse 的 Dashboard 查询用了 dateDiff('millisecond', ...) 这个 ClickHouse 函数，计算两个时间戳之间的毫秒差。但 ClickHouse 23.3 不支持 millisecond 这个时间单位——它是在 ClickHouse 23.4+ 才加上的。

这就尴尬了：

• ClickHouse 23.4+
  ：支持 dateDiff('millisecond')，但在鲲鹏 920 上启动就崩（SIGILL）
• ClickHouse 23.3
  ：能在鲲鹏 920 上跑，但不支 dateDiff('millisecond')

一个要 23.4，一个只能跑 23.3。差一个版本，卡死了。

四、为了修改我走过的弯路

弯路一：改 JS 文件

我的第一个想法是：既然 dateDiff('millisecond') 不支持，那我把代码里的 millisecond 改成 second，然后结果乘以 1000 不就行了？

Langfuse 是 Next.js 应用，编译后的 JS 文件在容器的 /app/web/.next/server/chunks/ 目录下。我 grep 了一下，找到了 5 个包含 dateDiff('millisecond') 的文件。

用 sed 全部替换成 dateDiff('second', ...) * 1000，然后 docker commit 保存为新镜像，防止重启丢失。

重启容器，Dashboard 的一些基础查询确实不报错了。但 Home 页面的延迟统计图表还是 500。

查 ClickHouse 的查询日志，发现实际发送到 ClickHouse 的查询仍然包含 dateDiff('millisecond')。

我反复检查——容器里的 JS 文件确实已经改了，grep 不到 millisecond 了。但查询里还有。

为什么？

因为 Dashboard 的查询不是写死在代码里的。它是通过一个叫 QueryBuilder 的类运行时动态拼接的。'millisecond' 作为参数传入查询构建器，藏在编译后的模块深处，不在那些我能改到的 JS 文件里。

这条路走不通。

弯路二：加 HTTP 代理

第二个想法：在 Langfuse 和 ClickHouse 之间加一层 HTTP 代理，拦截所有查询，把 millisecond 替换成 second。

我写了一个 Python 代理脚本，部署到 Docker 网络里。但这个方案太脆弱了——不仅要替换查询里的关键字，还要修改返回结果里的延迟值（乘以 1000），而且不同的查询格式不同，替换逻辑很容易出错。

这条路也走不通。

弯路三：降级 Langfuse

第三个想法：找一个不依赖 dateDiff('millisecond') 的旧版 Langfuse v3。

查了一下 GitHub，Langfuse 在 2025 年 1 月的 PR #4894 修过一次 dateDiff 兼容性问题——把 'milliseconds'（复数）改成了 'millisecond'（单数），说是 ClickHouse 23.x 兼容。

但问题是，v3.185.0 已经包含了这个修复。'millisecond'（单数）就是当前的写法。而 ClickHouse 23.3 连单数都不支持——这个参数是 23.4+ 才加的。

也就是说，Langfuse v3 的所有版本，只要用了 ClickHouse Dashboard 功能，最低都需要 ClickHouse 23.4。

三条路全堵死了。

五、山穷水尽疑无路

说实话，这个时候我是真的想放弃了。

ClickHouse 23.3 能跑但功能不全，23.4+ 功能全但跑不了。这不是配置问题，不是代码 bug，而是硬件架构和软件版本之间的根本性矛盾。

我甚至想过去编译 ClickHouse——从源码编译一个禁用 SVE 指令的版本。但 ClickHouse 的代码仓库有几十个 G，编译一次要好几个小时，而且不确定禁用 SVE 后还有没有其他问题。

也想过换回 Langfuse v2。但 v2 的功能确实差一截，而且我之前已经花了一整天把 v3 的架构搭好了，就这么放弃实在不甘心。

六、柳暗花明又一村

转折发生在一次 GitHub issue 搜索。

我抱着试一试的心态，在 ClickHouse 的 GitHub 仓库搜了一下 Kunpeng 920 Illegal instruction。

搜到了一个 issue：#102357。

标题一模一样："Illegal instruction (core dumped) on Huawei Kunpeng 920 (ARMv8.2-A) since ClickHouse v23.5+"

这个 issue 的提问者遇到的跟我完全一样——鲲鹏 920，ARMv8.2-A，没有 SVE，没有 LRCpc，ClickHouse 23.5+ 启动就崩。

而 ClickHouse 官方人员的回复里，有一句话让我眼前一亮：

curl https://clickhouse.com/ | sh should get you a compatible build.

All commits in CI have a Build (arm_v80compat) build you could use too.

arm_v80compat？兼容版本？

我赶紧去看 ClickHouse 的安装脚本。脚本里对 aarch64 架构的判断逻辑是这样的：

HAS_ARMV82=$(grep -m 1 'Features' /proc/cpuinfo | awk '/asimd/ && /sha1/ && /aes/ && /atomics/ && /lrcpc/')if [ "${HAS_ARMV82}" ]then    DIR="aarch64"else    DIR="aarch64v80compat"fi

它检查 CPU 是否有 lrcpc 指令。如果有，就下载标准版本；如果没有，就下载 aarch64v80compat 兼容版本——这个版本是专门为 ARMv8.0 基线编译的，不依赖 SVE 和 LRCpc。

而我们的鲲鹏 920，恰好没有 lrcpc。

我立刻在服务器上执行：

curl -sL https://builds.clickhouse.com/master/aarch64v80compat/clickhouse \  -o /tmp/clickhouse_compat && chmod +x /tmp/clickhouse_compat

154MB，下载完成。测试：

./clickhouse_compat local -q "SELECT version()"# 输出: 26.6.1.734

能跑了！

再测关键的 dateDiff('millisecond')：

echo"SELECT dateDiff('millisecond', toDateTime('2024-01-01'), toDateTime('2024-01-02'))" | ./clickhouse_compat local -q "$(cat)"# 输出: 86400000

完全正确！一天的毫秒数，86400000。

那一刻我的心情……怎么说呢，就像在沙漠里走了三天，突然看到一片绿洲。

七、从二进制到 Docker 镜像

拿到了能跑的 ClickHouse 二进制，下一步是把它集成到 Langfuse 的 Docker 架构里。

最直接的方案：用这个二进制打包一个自定义 Docker 镜像，替换掉原来的 ClickHouse 镜像。

Dockerfile 很简单，基于 Ubuntu 22.04：

FROM ubuntu:22.04# 安装最小依赖RUN apt-get update && apt-get install -y --no-install-recommends \    ca-certificates locales tzdata# 创建 clickhouse 用户（UID 101，跟旧镜像一致）RUN groupadd -r -g 101 clickhouse && \    useradd -r -g clickhouse -u 101 -d /var/lib/clickhouse -s /bin/bash clickhouse# 放入 v80compat 二进制，创建 symlinksCOPY clickhouse_compat /usr/bin/clickhouseRUNln -sf /usr/bin/clickhouse /usr/bin/clickhouse-server && \ln -sf /usr/bin/clickhouse /usr/bin/clickhouse-client# 配置文件，监听 0.0.0.0# ...（省略 XML 配置）USER clickhouseENTRYPOINT ["clickhouse-server", "--config-file=/etc/clickhouse-server/config.xml"]

踩坑：容器启动失败

第一次 build 完，启动容器——报错：

exec: "clickhouse-server": executable file not found in $PATH

原因：我们的二进制叫 clickhouse，但 Dockerfile 的 ENTRYPOINT 写的是 clickhouse-server。官方镜像里 clickhouse-server 是一个 symlink，我们的镜像没有。

修复：加了 

ln -sf /usr/bin/clickhouse /usr/bin/clickhouse-server

踩坑：数据目录权限

第二次启动——报错：

Effective user of the process (root) does not match the owner of the data (101)

旧的 ClickHouse Alpine 镜像用 UID 101 的用户运行，数据卷里的文件 owner 是 101。我们的镜像默认以 root 运行，ClickHouse 检测到不匹配就拒绝启动。

修复：在 Dockerfile 里用 

groupadd -r -g 101 和 useradd -r -g clickhouse -u 101

创建同 UID 的用户，并加 USER clickhouse。

踩坑：端口只绑定了 localhost

第三次启动——容器起来了，但 Langfuse 的数据库迁移报错：

dial tcp 172.21.0.4:9000: connect: connection refused

ClickHouse 的原生协议端口（9000）只监听了 127.0.0.1，容器之间通过 Docker 网络访问不到。

修复：在 config.xml 里加了 <listen_host>0.0.0.0</listen_host>。

踩坑：健康检查用错用户

第四次启动——ClickHouse 容器反复重启，日志里报认证失败。docker-compose 的健康检查用的是 clickhouse-client --query "SELECT 1"，默认以 default 用户连接。但环境变量 CLICKHOUSE_USER: clickhouse 和 CLICKHOUSE_PASSWORD: clickhouse 是给官方镜像的 entrypoint 脚本用的，我们的自定义镜像不会自动处理这些环境变量。

修复：在 config.xml 里显式添加了 clickhouse 用户和密码。

四次 build，四次踩坑，第五次终于全部绿灯。

八、最后一步：去掉补丁

之前为了绕过 dateDiff('millisecond') 问题，我给 Langfuse Web 容器打了补丁（替换 JS 文件里的关键字），保存为 langfuse:3-patched 镜像。

现在 ClickHouse 已经原生支持 millisecond 了，这些补丁不需要了。把 docker-compose 里的镜像改回官方的 langfuse:3，重启——

打开浏览器，登录，点击 Dashboard。

图表出来了。

延迟分布、Token 消耗、调用次数——所有数据一目了然。没有 500 错误，没有白屏，没有控制台报错。

搞定了。

九、最终架构

加上已有的 PostgreSQL，一共 6 个组件。

十、复盘：我学到了什么

1. 先搜 GitHub Issue，再动手

这次最大的教训是：遇到问题先搜 GitHub Issue，别急着自己想办法。

我花了两天时间尝试改 JS 文件、加代理、降级版本，全失败了。最后搜了一下 ClickHouse 的 issue，发现别人早就踩过同样的坑，而且官方已经提供了兼容版本。

如果我一开始就搜 Kunpeng 920 ClickHouse，可能半小时就搞定了。

2. "能跑"不等于"能用"

ClickHouse 23.3 能启动，所有容器都是绿色的，health check 通过——看起来一切正常。但 Dashboard 的核心功能其实坏了。

只看容器状态不够，要实际点进去用一下。 这跟写代码一样——编译通过不代表没 bug，得跑起来测过才知道。

3. 编译参数决定兼容性

ClickHouse 官方的 Docker 镜像和二进制，编译时默认开启了最新的 CPU 指令（SVE、LRCpc 等）。这些指令在新硬件上能加速运算，但在旧硬件上直接崩。

aarch64v80compat 这个名字的意思是：为 ARMv8.0 基线编译的兼容版本。 它不用 SVE，不用 LRCpc，只用最基础的 NEON 指令集，所以能在鲲鹏 920 上跑。

这个知识不是 ClickHouse 文档里写的，是翻 issue 翻出来的。

4. 自定义 Docker 镜像没那么难

之前我觉得"自定义 Docker 镜像"是很高级的操作，需要深入理解 Docker 内部机制。实际上就是一个 Dockerfile，把二进制文件放进去，写好配置文件，指定用户和入口命令。

真正的难点不在 Docker 本身，而在那些"踩一次才知道"的细节——UID 要匹配、端口要绑定 0.0.0.0、symlink 要手动创建、环境变量要自己处理。

5. 山穷水尽的时候，换个方向找答案

这次最深的体会是：当一条路走不通的时候，不要在原地死磕。

改 JS 文件、加代理、降级版本——这三条路我都试了，都失败了。如果我继续在这些方向上深挖（比如更仔细地分析 QueryBuilder 的代码、写更复杂的代理逻辑），可能还要花更多时间，最后还是死路。

真正的突破来自于换了一个完全不同的搜索方向——不是搜 Langfuse 的代码，而是搜 ClickHouse 的硬件兼容性。答案不在 Langfuse 仓库里，而在 ClickHouse 的 issue 里。

这就像迷路的时候，与其在原地转圈，不如爬到高处看一看——也许你要找的路，就在你完全没想到的方向。

总结一句话：在鲲鹏 920 上部署 Langfuse v3 的关键，不是 Langfuse 本身，而是找到 ClickHouse 的 aarch64v80compat 兼容版本。 这个版本不在 Docker Hub 的官方标签里，不在 Langfuse 的文档里，只在一个 ClickHouse issue 的评论区里。

如果你也在国产 ARM 服务器上遇到了类似的问题，希望这篇文章能帮你少走一些弯路。

最后放一张部署成果如下：

我是AI易用君，在此公众号分享探索、学习、使用AI的经验，让我们一起来学AI，用AI，AI（爱）让生活更美好。如果你觉得我说的对，欢迎点赞收藏。