大模型可观测平台langfuse服务器离线部署方法

在无网络（离线）环境的服务器上，该如何部署 Langfuse离线部署的关键是「先在有网的机器上把所有依赖资源下载好 → 传输到离线服务器 → 离线加载并部署」，主要包括 3 类资源：

1. Langfuse 仓库的源码（docker-compose.yml 核心配置）
2. 所有需要的 Docker 镜像（langfuse、postgres、redis 等）
3. 如果服务器连内网仓库都没有，还需要确保 Docker 能离线加载镜像
   

分步离线部署方案

第一步：在有网机器上准备所有资源

这一步在能联网的电脑/服务器上操作，把需要的东西都下载下来。

1. 下载 Langfuse 源码

# 克隆仓库（有网环境）
git clone https://github.com/langfuse/langfuse.git
cd langfuse

# （可选）如果只需要 docker-compose.yml，也可以直接下载这个文件，不用克隆整个仓库
# curl -O https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml

2. 下载所有需要的 Docker 镜像

先查看 docker-compose.yml 里用到的镜像，然后逐个拉取、保存为压缩包：

# 拉取所有镜像（按配置里的镜像名）
docker pull docker.io/langfuse/langfuse-worker:3
docker pull docker.io/langfuse/langfuse:3
docker pull docker.io/clickhouse/clickhouse-server
docker pull cgr.dev/chainguard/minio
docker pull docker.io/redis:7
docker pull docker.io/postgres:17

# 将镜像保存为 tar 压缩包（方便传输）
docker save docker.io/langfuse/langfuse-worker:3 -o langfuse-worker.tar
docker save docker.io/langfuse/langfuse:3 -o langfuse-web.tar
docker save docker.io/clickhouse/clickhouse-server -o clickhouse.tar
docker save cgr.dev/chainguard/minio -o minio.tar
docker save docker.io/redis:7 -o redis.tar
docker save docker.io/postgres:17 -o postgres.tar

3. 打包资源

把源码和镜像包放到一个文件夹，方便传输到离线服务器：

# 创建总文件夹
mkdir langfuse-offline-deploy
# 复制源码（至少包含 docker-compose.yml）
cp -r langfuse/* langfuse-offline-deploy/
# 复制所有镜像包
mv *.tar langfuse-offline-deploy/

# （可选）打包成压缩包，传输更方便
tar -zcvf langfuse-offline-deploy.tar.gz langfuse-offline-deploy/

第二步：传输资源到离线服务器

用 U 盘、内网网盘、SCP（如果服务器能连内网）等方式，把 langfuse-offline-deploy.tar.gz（或文件夹）传到离线服务器的某个目录（比如 /opt/）。

第三步：在离线服务器上部署

1. 解压资源

# 进入服务器目录
cd /opt/
# 解压（如果传的是压缩包）
tar -zxvf langfuse-offline-deploy.tar.gz
cd langfuse-offline-deploy

2. 加载 Docker 镜像

把第一步保存的镜像包加载到服务器的 Docker 里：

# 逐个加载镜像
docker load -i langfuse-worker.tar
docker load -i langfuse-web.tar
docker load -i clickhouse.tar
docker load -i minio.tar
docker load -i redis.tar
docker load -i postgres.tar

# 验证镜像是否加载成功（能看到所有镜像即可）
docker images

3. 修改配置（关键！）

离线部署前，先修改 docker-compose.yml 里的配置（和在线部署一样，改密码/密钥）：

# 编辑配置文件
vim docker-compose.yml

重点修改这些标了 # CHANGEME 的内容：

• PostgreSQL 密码（POSTGRES_PASSWORD）
• Redis 密码（REDIS_AUTH）
• MinIO 密码（MINIO_ROOT_PASSWORD）
• ClickHouse 密码（CLICKHOUSE_PASSWORD）
• 加密密钥（ENCRYPTION_KEY，可在有网机器上用 openssl rand -hex 32 生成后复制过来）
• S3/MinIO 相关的密钥（LANGFUSE_S3_*_SECRET_ACCESS_KEY）

4. 启动 Langfuse

# 启动所有服务（后台运行加 -d）
docker compose up -d

# 查看启动状态（确认所有容器都是 Up 状态）
docker compose ps

# 查看日志（如果启动失败，看日志排查）
docker compose logs -f

第四步：验证部署

离线服务器上访问 Langfuse 前端：

# 本地访问（服务器上）
curl http://localhost:3000

# 如果服务器有浏览器，直接打开 http://服务器IP:3000

能看到 Langfuse 的登录页面，就说明部署成功了。

额外注意事项

1. Docker 环境：离线服务器必须提前安装 Docker 和 Docker Compose（如果也没网，需要先离线安装 Docker：下载 Docker 的 rpm/deb 包，传到服务器安装）。
2. 端口开放：确保服务器的 3000 端口（前端）、9090 端口（MinIO）对外开放（如果需要外部访问）。
3. 数据持久化：离线部署后，数据会存在服务器的 Docker 卷里，和在线部署一样，重启容器不会丢数据。
4. 版本一致性：拉取镜像时要确保版本和 docker-compose.yml 里的一致（比如 langfuse:3、postgres:17），避免版本不兼容。

总结

1. 离线部署的核心是「有网机下载资源 → 传离线机 → 离线加载部署」，关键是提前下载所有 Docker 镜像和 Langfuse 配置文件。
2. 必须修改 docker-compose.yml 里的密码/密钥，确保部署安全。
3. 部署后验证 3000 端口可访问，即可确认 Langfuse 正常运行。