1. 项目背景与核心价值
在AI技术快速发展的当下,大模型的可观测性成为企业落地的关键瓶颈。Langfuse作为一款开源的大模型可观测性平台,能够完整记录和分析大模型应用的输入输出、延迟、成本等关键指标,帮助开发者快速定位问题、优化性能。但在实际企业应用中,由于数据安全和网络环境的限制,很多团队需要将Langfuse部署在内网环境或离线服务器上。
我最近为一个金融客户成功实施了Langfuse的离线部署方案,过程中踩了不少坑,也总结出一套可靠的部署方法。与官方文档不同的是,这套方案特别针对国内网络环境和企业级安全要求进行了优化,解决了依赖下载、容器配置、数据持久化等关键问题。
2. 环境准备与依赖处理
2.1 硬件与系统要求
对于生产环境部署,建议配置:
- 至少4核CPU/16GB内存(实测8核32GB可支撑日均百万级请求)
- 100GB以上SSD存储空间(用于日志和追踪数据存储)
- Ubuntu 20.04/22.04 LTS或CentOS 7/8(已测试兼容性最佳)
注意:避免使用Windows Server作为宿主系统,我们在测试中发现Docker性能损耗高达30%
2.2 离线依赖包下载
由于是离线部署,需要提前下载所有依赖:
- Docker离线安装包(包含docker-ce, docker-compose-plugin)
- Langfuse官方镜像包(langfuse/langfuse:latest)
- PostgreSQL 15容器镜像(用于元数据存储)
- Redis 7容器镜像(用于队列和缓存)
下载技巧:
bash复制# 在有网络的环境先拉取镜像
docker pull langfuse/langfuse:latest
docker pull postgres:15
docker pull redis:7
# 保存为离线包
docker save -o langfuse.tar langfuse/langfuse:latest
docker save -o postgres15.tar postgres:15
docker save -o redis7.tar redis:7
2.3 证书与安全配置
企业内网通常需要自签名证书:
bash复制# 生成CA根证书(有效期10年)
openssl req -x509 -newkey rsa:4096 -keyout ca-key.pem -out ca-cert.pem -days 3650 -nodes -subj "/CN=Langfuse Internal CA"
# 生成服务器证书
openssl req -newkey rsa:4096 -keyout server-key.pem -out server-req.pem -nodes -subj "/CN=langfuse.internal"
openssl x509 -req -in server-req.pem -CA ca-cert.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 3650
3. 容器化部署实战
3.1 基础架构设计
我们采用三容器方案:
- 主服务容器:运行Langfuse核心服务
- PostgreSQL容器:存储项目配置和元数据
- Redis容器:处理异步任务队列
网络拓扑建议:
code复制[客户端] → [Nginx反向代理] → [Langfuse主服务]
↘
[PostgreSQL]
[Redis]
3.2 docker-compose配置
创建docker-compose.yml文件:
yaml复制version: '3.8'
services:
postgres:
image: postgres:15
volumes:
- pg_data:/var/lib/postgresql/data
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: langfuse
POSTGRES_DB: langfuse
restart: unless-stopped
redis:
image: redis:7
command: redis-server --requirepass ${REDIS_PASSWORD}
volumes:
- redis_data:/data
restart: unless-stopped
langfuse:
image: langfuse/langfuse:latest
depends_on:
- postgres
- redis
environment:
DATABASE_URL: postgresql://langfuse:${DB_PASSWORD}@postgres:5432/langfuse
REDIS_HOST: redis
REDIS_PASSWORD: ${REDIS_PASSWORD}
NEXTAUTH_SECRET: ${AUTH_SECRET}
NEXTAUTH_URL: https://${DOMAIN}
S3_ENDPOINT: ${S3_ENDPOINT}
S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY}
S3_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}
S3_BUCKET_NAME: ${S3_BUCKET}
ports:
- "3000:3000"
restart: unless-stopped
volumes:
pg_data:
redis_data:
关键参数说明:
${DB_PASSWORD}:PostgreSQL密码(建议16位随机字符串)${REDIS_PASSWORD}:Redis访问密码${AUTH_SECRET}:用于会话加密的密钥(可通过openssl rand -base64 32生成)${DOMAIN}:内网访问域名(如langfuse.internal)
3.3 持久化存储方案
对于生产环境,建议配置S3兼容存储:
- MinIO(内网部署版)
- 阿里云OSS(通过专线连接)
- 华为云OBS(金融区部署)
配置示例(MinIO):
yaml复制environment:
S3_ENDPOINT: http://minio:9000
S3_ACCESS_KEY_ID: minioadmin
S3_SECRET_ACCESS_KEY: minioadmin
S3_BUCKET_NAME: langfuse
4. 配置调优与性能优化
4.1 数据库性能参数
修改PostgreSQL配置(postgresql.conf):
ini复制shared_buffers = 4GB # 25% of total RAM
effective_cache_size = 12GB # 75% of total RAM
maintenance_work_mem = 1GB # for large DBs
work_mem = 128MB # per-operation memory
random_page_cost = 1.1 # SSD storage
max_worker_processes = 8 # CPU cores
max_parallel_workers_per_gather = 4 # 50% of workers
4.2 Langfuse工作线程配置
通过环境变量调整:
yaml复制environment:
WORKER_CONCURRENCY: "8" # CPU核心数×2
TASK_QUEUE_CONCURRENCY: "4" # 每个worker的并发数
TRACE_QUEUE_LIMIT: "10000" # 队列积压阈值
4.3 监控指标采集
建议部署Prometheus监控:
yaml复制# 在docker-compose中添加
monitoring:
image: prom/prometheus
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
示例prometheus.yml配置:
yaml复制scrape_configs:
- job_name: 'langfuse'
static_configs:
- targets: ['langfuse:3000']
- job_name: 'postgres'
static_configs:
- targets: ['postgres:9187']
5. 常见问题排查指南
5.1 容器启动失败排查
典型错误1:数据库连接超时
log复制Error: connect ECONNREFUSED postgres:5432
解决方案:
- 检查PostgreSQL容器日志:
docker logs langfuse_postgres_1 - 验证网络连通性:
docker exec langfuse ping postgres - 检查环境变量:
docker exec langfuse env | grep DATABASE_URL
5.2 性能瓶颈分析
现象:API响应缓慢
排查步骤:
- 检查Redis队列积压:
bash复制docker exec langfuse_redis_1 redis-cli -a ${REDIS_PASSWORD} LLEN bull:langfuse:queue - 分析慢查询:
sql复制SELECT * FROM pg_stat_activity WHERE state = 'active' AND now() - query_start > interval '5 seconds';
5.3 数据持久化验证
确保S3存储正常工作:
- 上传测试文件:
bash复制docker exec langfuse curl -X PUT -T /etc/hosts http://minio:9000/langfuse/testfile - 检查MinIO控制台:
bash复制docker exec langfuse_minio_1 mc ls minio/langfuse
6. 安全加固措施
6.1 网络隔离方案
推荐配置:
yaml复制networks:
langfuse_net:
driver: bridge
internal: true # 禁止外部访问
6.2 定期备份策略
PostgreSQL备份脚本示例:
bash复制#!/bin/bash
BACKUP_DIR=/backups
DATE=$(date +%Y%m%d)
docker exec langfuse_postgres_1 pg_dump -U langfuse -Fc langfuse > $BACKUP_DIR/langfuse_$DATE.dump
6.3 访问控制配置
Nginx反向代理示例:
nginx复制server {
listen 443 ssl;
server_name langfuse.internal;
ssl_certificate /etc/ssl/server-cert.pem;
ssl_certificate_key /etc/ssl/server-key.pem;
location / {
proxy_pass http://langfuse:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# 限制访问IP段
allow 10.0.0.0/8;
deny all;
}
}
7. 升级与维护方案
7.1 版本升级流程
- 下载新版本镜像到测试环境
- 执行数据库迁移:
bash复制docker run --rm -e DATABASE_URL=postgresql://langfuse:${DB_PASSWORD}@postgres:5432/langfuse langfuse/langfuse:latest npx prisma migrate deploy - 验证无误后更新生产环境
7.2 日常维护任务
建议的crontab任务:
bash复制0 3 * * * /usr/bin/docker system prune -f --filter "until=72h"
0 4 * * * /backup/postgres_backup.sh
30 4 * * * /usr/bin/docker exec langfuse_redis_1 redis-cli -a ${REDIS_PASSWORD} BGSAVE
这套方案在某金融机构的生产环境已稳定运行6个月,日均处理大模型调用日志超过50万条。最关键的经验是:一定要在部署前做好存储规划,我们最初低估了数据增长量,导致不得不中途扩容存储。另外,定期执行VACUUM ANALYZE可以保持PostgreSQL性能稳定。