Phoenix Docker部署指南：快速搭建本地LLM可观测平台-优快云博客

Phoenix Docker部署指南：快速搭建本地LLM可观测平台

【免费下载链接】phoenix AI Observability & Evaluation 项目地址: https://gitcode.com/gh_mirrors/phoenix13/phoenix

为什么选择Docker部署Phoenix？

你是否在部署LLM可观测平台时遇到过环境依赖冲突、配置繁琐、服务启动失败等问题？作为AI Observability领域的核心工具，Phoenix需要处理大量LLM追踪数据和评估指标，其部署过程涉及前后端构建、数据库配置和网络端口管理等复杂步骤。本文将通过Docker容器化方案，帮助你在15分钟内完成生产级LLM可观测平台的本地部署，无需担心系统兼容性问题，同时提供完整的扩展配置指南。

读完本文后，你将获得：

一套开箱即用的Docker Compose配置文件
3种部署模式（单机版/完整集群/开发调试版）的实施步骤
性能优化与资源配置的最佳实践
常见故障排查与日志分析方法
数据持久化与备份策略

部署前准备

环境要求

组件	最低要求	推荐配置	作用
Docker Engine	20.10+	24.0+	容器运行时环境
Docker Compose	v2.0+	v2.20+	多容器编排工具
CPU	2核	4核+	处理LLM追踪数据解析
内存	4GB	8GB+	缓存频繁访问的评估指标
磁盘空间	20GB	100GB SSD	存储PostgreSQL数据库和追踪日志
网络	稳定互联网连接	100Mbps+	拉取容器镜像和依赖

软件安装

# Ubuntu/Debian系统安装Docker
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动Docker服务并设置开机自启
sudo systemctl enable --now docker

# 验证安装是否成功
docker --version && docker compose version

源码获取

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/phoenix13/phoenix
cd phoenix

三种部署模式详解

1. 快速启动模式（推荐新手）

此模式使用预配置的docker-compose.yml文件，自动启动Phoenix应用和PostgreSQL数据库，适合快速体验完整功能。

# docker-compose.yml核心内容解析
services:
  phoenix:
    build: .  # 使用当前目录Dockerfile构建镜像
    depends_on: [db]  # 确保数据库先启动
    ports:
      - "6006:6006"  # Web UI端口
      - "4317:4317"  # gRPC数据接收端口
    environment:
      - PHOENIX_SQL_DATABASE_URL=postgresql://postgres:postgres@db:5432/postgres
      
  db:
    image: postgres:16  # 使用官方PostgreSQL 16镜像
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=postgres
    volumes:
      - database_data:/var/lib/postgresql/data  # 数据持久化卷

volumes:
  database_data:  # 声明命名卷用于数据持久化

启动命令：

# 构建并启动服务（后台运行）
docker compose up -d

# 查看服务状态
docker compose ps

# 查看日志输出
docker compose logs -f phoenix

服务启动成功后，访问http://localhost:6006即可打开Phoenix Web界面，默认包含：

LLM追踪数据可视化面板
模型评估指标仪表盘
数据导出与分析工具
API访问管理界面

2. 生产优化模式（企业级部署）

针对生产环境，需要优化资源配置、启用安全认证和设置数据备份策略。创建docker-compose.prod.yml文件：

version: '3.8'

services:
  phoenix:
    build: 
      context: .
      args:
        - BASE_IMAGE=gcr.io/distroless/python3-debian12:nonroot  # 最小安全镜像
    depends_on: [db]
    ports:
      - "6006:6006"
      - "4317:4317"  # gRPC端口（OpenTelemetry协议）
      - "9090:9090"  # Prometheus监控端口
    environment:
      - PHOENIX_SQL_DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@db:5432/${DB_NAME}
      - PYTHONUNBUFFERED=1  # 实时日志输出
      - PHOENIX_BATCH_PROCESSING_ENABLED=true  # 启用批处理提高性能
      - PHOENIX_DATA_RETENTION_DAYS=30  # 数据保留30天
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '2'
          memory: 4G
    restart: unless-stopped  # 异常退出时自动重启

  db:
    image: postgres:16-alpine  # 轻量级Alpine版本
    environment:
      - POSTGRES_USER=${DB_USER:-phoenix}
      - POSTGRES_PASSWORD=${DB_PASSWORD:-secure_password_here}
      - POSTGRES_DB=${DB_NAME:-phoenix_prod}
    volumes:
      - database_data:/var/lib/postgresql/data
      - ./scripts/ddl:/docker-entrypoint-initdb.d  # 初始化SQL脚本
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

  # 添加Prometheus监控服务
  prometheus:
    image: prom/prometheus:v2.45.0
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.retention.time=15d'
    ports:
      - "9090:9090"

volumes:
  database_data:
  prometheus_data:

启动命令：

# 设置环境变量
export DB_USER=phoenix_admin
export DB_PASSWORD=$(openssl rand -hex 16)  # 生成随机密码
export DB_NAME=phoenix_production

# 使用生产配置文件启动
docker compose -f docker-compose.prod.yml up -d

# 验证服务健康状态
docker compose -f docker-compose.prod.yml exec db pg_isready -U $DB_USER

3. 开发调试模式（二次开发用）

开发模式使用本地代码挂载和热重载功能，适合修改Phoenix源码后实时测试效果：

# 构建调试镜像（包含完整shell环境）
docker build -t phoenix:debug --build-arg BASE_IMAGE=gcr.io/distroless/python3-debian12:debug .

# 启动开发容器并挂载本地代码
docker run -it --rm \
  -p 6006:6006 \
  -v $(pwd)/src:/phoenix/src \
  -v $(pwd)/app:/phoenix/app \
  --entrypoint=sh \
  phoenix:debug

# 在容器内启动开发服务器
cd /phoenix
pip install -e ".[dev, pg]"
phoenix server --reload

Dockerfile深度解析

Phoenix采用多阶段构建策略，在保证镜像安全性的同时最小化最终镜像体积。以下是关键构建阶段的说明：

# 阶段1: 前端构建（使用Node.js环境）
FROM node:22-slim AS frontend-builder
WORKDIR /phoenix/app/
COPY ./app .
RUN npm i -g corepack && corepack enable && corepack use pnpm
RUN pnpm install  # 安装前端依赖
RUN pnpm run build  # 构建React应用，生成静态文件

# 阶段2: 后端构建（Python环境）
FROM python:3.11-bullseye as backend-builder
WORKDIR /phoenix
COPY ./src ./src
COPY ./pyproject.toml .
COPY --from=frontend-builder /phoenix/app/dist /phoenix/src/phoenix/server/static
RUN pip install --target ./env ".[container, pg]"  # 安装后端依赖到独立目录

# 阶段3: 生产镜像（基于Distroless最小镜像）
FROM gcr.io/distroless/python3-debian12:nonroot
WORKDIR /phoenix
COPY --from=backend-builder /phoenix/env ./env
ENV PYTHONPATH="/phoenix/env:$PYTHONPATH"
EXPOSE 6006  # Web端口
EXPOSE 4317  # gRPC端口
EXPOSE 9090  # Prometheus端口
CMD ["-m", "phoenix.server.main", "serve"]  # 启动命令

多阶段构建的优势：

安全加固：最终镜像不含构建工具和临时文件，减少攻击面
体积优化：从基础镜像的1.2GB减少到最终的280MB左右
构建隔离：前后端依赖分开管理，避免版本冲突
架构适配：通过BASE_IMAGE参数可构建arm64架构镜像（适用于M1/M2 Mac）

性能调优与资源配置

内存分配策略

Phoenix性能瓶颈主要来自LLM追踪数据的处理和存储，建议按以下比例分配资源：

mermaid

批处理配置优化

在生产环境中启用批处理可显著提高数据处理效率：

# 在environment中添加以下配置
environment:
  - PHOENIX_BATCH_PROCESSING_ENABLED=true
  - PHOENIX_BATCH_MAX_QUEUE_SIZE=10000  # 最大批量大小
  - PHOENIX_BATCH_SCHEDULE_DELAY_MS=5000  # 批处理间隔
  - PHOENIX_BATCH_PROCESSING_WORKERS=4  # 处理线程数

数据库性能调优

为PostgreSQL添加性能优化配置，创建pg_custom.conf文件：

# PostgreSQL性能优化配置
max_connections = 100
shared_buffers = 1GB  # 通常设置为系统内存的1/4
effective_cache_size = 3GB  # 通常设置为系统内存的3/4
maintenance_work_mem = 256MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 10485kB
min_wal_size = 1GB
max_wal_size = 4GB

在docker-compose中挂载配置文件：

services:
  db:
    image: postgres:16
    volumes:
      - database_data:/var/lib/postgresql/data
      - ./pg_custom.conf:/etc/postgresql/postgresql.conf.d/custom.conf
    command: ["postgres", "-c", "config_file=/etc/postgresql/postgresql.conf.d/custom.conf"]

数据管理与备份策略

自动备份脚本

创建backup.sh定期备份PostgreSQL数据库：

#!/bin/bash
# 数据库备份脚本
BACKUP_DIR="/path/to/backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
CONTAINER_NAME="phoenix_db_1"
DB_USER="phoenix"
DB_NAME="phoenix_production"

# 创建备份目录
mkdir -p $BACKUP_DIR

# 执行备份
docker exec $CONTAINER_NAME pg_dump -U $DB_USER -d $DB_NAME -F c -f /tmp/backup_$TIMESTAMP.dump

# 复制到宿主机
docker cp $CONTAINER_NAME:/tmp/backup_$TIMESTAMP.dump $BACKUP_DIR/

# 删除容器内临时文件
docker exec $CONTAINER_NAME rm /tmp/backup_$TIMESTAMP.dump

# 保留最近30天备份
find $BACKUP_DIR -name "*.dump" -mtime +30 -delete

添加到crontab定时任务：

# 每天凌晨3点执行备份
echo "0 3 * * * /path/to/backup.sh >> /var/log/phoenix_backup.log 2>&1" | crontab -

数据恢复流程

# 列出所有备份文件
ls -lh /path/to/backups

# 恢复指定备份
docker cp /path/to/backups/backup_20250915_030000.dump phoenix_db_1:/tmp/
docker exec phoenix_db_1 pg_restore -U phoenix -d phoenix_production -c /tmp/backup_20250915_030000.dump

常见问题排查

服务启动失败

# 检查服务状态和最近日志
docker compose ps
docker compose logs --tail=100 phoenix

# 常见错误及解决方案：
# 1. 端口冲突：修改docker-compose.yml中的端口映射，如"6007:6006"
# 2. 数据库连接失败：检查DB服务是否正常启动，网络是否连通
# 3. 资源不足：增加Docker内存分配，至少4GB

性能问题诊断

使用Prometheus监控Phoenix性能指标，关键指标包括：

phoenix_span_processing_time_seconds：追踪数据处理耗时
phoenix_eval_queue_length：评估任务队列长度
phoenix_db_query_duration_seconds：数据库查询耗时

# prometheus.yml配置示例
scrape_configs:
  - job_name: 'phoenix'
    static_configs:
      - targets: ['phoenix:9090']
    metrics_path: '/metrics'
    scrape_interval: 5s

数据持久化问题

如果重启容器后数据丢失，检查以下配置：

确认使用了命名卷而非匿名卷
检查卷的挂载路径是否正确
验证宿主机卷目录权限：

# 查看卷存储位置
docker volume inspect phoenix_database_data

# 检查权限
ls -ld /var/lib/docker/volumes/phoenix_database_data/_data

部署后验证与功能测试

基础功能验证

# 1. 检查服务端口是否正常监听
netstat -tulpn | grep -E '6006|4317|5432'

# 2. 发送测试追踪数据
curl -X POST http://localhost:6006/api/traces -H "Content-Type: application/json" -d @examples/trace_samples/simple_llm_trace.json

# 3. 验证数据是否被正确接收
docker compose exec phoenix python -c "from phoenix.trace import get_traces; print(len(get_traces()))"

负载测试

使用Apache Bench进行简单的API负载测试：

# 测试追踪数据接收API的性能
ab -n 1000 -c 10 http://localhost:6006/api/health

总结与扩展建议

通过Docker容器化部署，我们成功解决了Phoenix在本地环境的安装复杂性问题，同时确保了部署的一致性和可重复性。对于需要进一步扩展的用户，建议：

水平扩展：使用Kubernetes替代Docker Compose，通过helm/目录下的Chart文件部署到K8s集群
高可用配置：设置PostgreSQL主从复制，使用docker-compose.ha.yml模板
监控集成：对接Grafana和Alertmanager，设置关键指标告警
数据同步：配置定时任务将生产数据同步到数据分析平台

随着LLM应用的普及，可观测性工具的重要性日益凸显。Phoenix作为开源AI Observability平台，其容器化部署方案为开发者提供了快速上手的途径，同时保持了生产环境所需的稳定性和安全性。立即部署并体验LLM追踪与评估的强大功能，为你的AI应用保驾护航！

如果本指南对你有帮助，请点赞收藏并关注后续发布的《Phoenix高级评估功能实战》系列文章。有任何部署问题，欢迎在项目仓库提交issue交流讨论。

【免费下载链接】phoenix AI Observability & Evaluation 项目地址: https://gitcode.com/gh_mirrors/phoenix13/phoenix

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考