使用 Docker Compose 部署 OpikProfile 画像体系、opik.sh 脚本与可观测性配置全指南【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llmOpik 是一个用于调试、评估和监控 LLM 应用、RAG 系统与 Agent 工作流的可观测性平台。本指南围绕仓库中 deployment/docker-compose/README.md 展开系统讲解如何通过 Docker Compose 完成从单机基础设施到完整 Opik 套件含 Guardrails 与 OpenTelemetry 可观测性的部署并结合 docker-compose.yaml、opik.sh 等仓库源码深入剖析其 Profile 画像机制、端口管理逻辑与底层配置原理。读完本文你将能够按需组合启动任意服务组合、自定义版本与端口、暴露数据库端口进行本地联调并开启 Nginx 追踪与日志的 OTLP 采集链路。安装前置条件在开始之前请确保宿主机已安装以下软件详见原文档的安装指引Docker用于运行容器。Docker ComposeV2 及以上用于编排多容器应用。仓库脚本统一使用docker compose命令V2 插件形式并在 opik.sh 中做了兼容检测若 V2 不可用会自动回退到 V1 的docker-compose。一、Compose Profile 画像体系按需组合服务Opik 的 Docker Compose 编排基于Compose Profiles实现不同开发场景的服务组合。理解这套画像体系是使用本部署方案的前提其核心设计在 docker-compose.yaml 中通过每个 service 的profiles字段定义。1.1 五类服务画像Profile包含内容说明默认无 Profile基础设施MySQL、Redis、ClickHouse、ZooKeeper、MinIO 等始终启用任何业务画像都自动依赖它backend基础设施自动 Backend、Python Backend 等后端服务层opik完整 Opik 套件全部基础设施 全部服务默认推荐的全功能组合不含GuardrailsguardrailsGuardrails 服务需与其他画像组合使用即使在全套件中默认也是可选的除非显式启用opik-otel完整 Opik 套件 Jaeger OpenTelemetry Collector面向可观测性场景1.2 画像的使用规则基础设施服务数据库、缓存、对象存储等默认总会启动这与 Compose 对无 Profile 服务的默认行为一致可参考 Docker 官方文档 Using profiles with Compose。任何业务画像backend、opik 等都自动包含基础设施无需显式叠加。多个 Profile 可以叠加使用例如--profile opik --profile guardrails。在 docker-compose.yaml 中可以看到backend、python-backend、frontend等服务的profiles声明与上述画像一一对应backend服务挂载backend、opik、opik-otel三个画像frontend服务挂载opik、local-be、opik-otel三个画像guardrails-backend与guardrails-backend-cpu分别挂载互斥的guardrails与guardrails-cpu画像两者共享guardrails主机名同一时刻只能运行一个。1.3 画像使用示例仅启动基础设施服务不指定 Profile 时的默认行为docker compose up -d启动基础设施 后端服务docker compose --profile backend up -d启动完整 Opik 套件所有基础设施和服务除 Guardrails 外docker compose --profile opik up -d启动后端 Guardrailsdocker compose --profile backend --profile guardrails up -d启动完整 Opik 套件 Guardrailsdocker compose --profile opik --profile guardrails up -d启动完整 Opik 套件 OpenTelemetrydocker compose --profile opik-otel up -d1.4 基础设施服务速览来自 compose 源码从 docker-compose.yaml 可以梳理出基础设施层各服务的镜像与关键配置帮助理解整个栈的依赖关系服务镜像关键配置mysqlmysql:8.4.2数据库opik用户/密码均为opik数据卷持久化到~/opik/mysqlredisredis:7.2.4-alpine3.19通过--requirepass opik设置密码数据卷redis-dataclickhouseclickhouse/clickhouse-server:26.3.16.16-alpine数据库/用户/密码均为opik开启 SQL 驱动的访问控制CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT1依赖 ZooKeeper 与clickhouse-init初始化容器zookeeperzookeeper:3.9.4数据目录使用/bitnami/zookeeper/data以兼容从 Bitnami 镜像升级的场景miniominio/minio:RELEASE.2025-03-12T18-04-18ZS3 兼容对象存储默认密钥可通过MINIO_ROOT_USER/MINIO_ROOT_PASSWORD覆盖mc容器负责创建public桶并设置为匿名下载clickhouse-initalpine:latest一次性初始化容器把 clickhouse_config 目录拷入配置卷并修正属主clickhouse依赖zookeeper与clickhouse-init而backend依次依赖 mysql、clickhouse、minio、redis 全部健康后才会启动整个启动链通过 Compose 的depends_on: condition: service_healthy与各服务的healthcheck严格编排。ClickHouse 的单节点集群定义remote_servers中的cluster与 Helm 部署保持一致见 clickhouse_config/additional_config.xml。二、opik.sh 一键安装脚本更高层的部署入口与其直接敲docker compose命令更推荐使用仓库根目录下的 opik.shWindows 使用 opik.ps1。它本质上是 Compose 命令的封装层负责参数解析、端口计算、容器健康检查与状态横幅输出。2.1 官方支持的选项选项说明--infra仅启动基础设施服务MySQL、Redis、ClickHouse、ZooKeeper、MinIO 等--backend启动基础设施 后端服务--guardrails启用 Guardrails可与其他启动选项组合--build启动前从源码构建镜像--verify检查所有容器是否健康--stop停止所有容器--clean停止所有容器并删除全部 Opik 数据卷警告所有 Opik 数据将丢失--help显示全部可用选项运行./opik.sh --help可查看完整选项列表。2.2 脚本中还存在但文档表格未列出的扩展选项从 opik.sh 源码print_usage函数可以看出脚本还支持以下选项--info仅当所有容器运行时显示欢迎横幅与系统状态--demo-data触发 demo 数据生成假设 backend、python-backend、frontend 等必要服务已在运行--debug开启调试模式输出详细日志--port-mapping通过加载 override 文件为所有容器开启端口映射可与其他选项组合--local-be启动除 backend 外的所有服务用于本地后端开发--local-be-fe仅启动基础设施 Python backend用于本地后端 前端联合开发--guardrails-cpu使用从源码构建的 CPU-only 镜像启用 Guardrails无需 GPU。其中--local-be与--local-be-fe会强制开启端口映射本地进程必须能直连基础设施分别对应 docker-compose.local-be.yaml 与 docker-compose.local-be-fe.yaml 两个 override 文件用于解除 frontend 对 backend 的依赖。此外--infra、--backend、--local-be、--local-be-fe四个画像选项互斥脚本会在同时传入多个时直接报错退出。2.3 脚本的底层行为机制Worktree 端口隔离脚本在启动时 source scripts/worktree-utils.sh 并调用init_worktree_ports。若当前目录位于 Git worktree 中会根据路径哈希计算一个 0~99 的端口偏移量PORT_OFFSET将所有端口整体平移同时设置COMPOSE_PROJECT_NAME形如opik-worktree_id实现多 worktree 并行开发互不冲突主仓库则偏移为 0保持向后兼容。用户也可通过OPIK_PORT_OFFSET手动指定偏移。Compose 命令构造get_docker_compose_cmd会根据所选模式拼装docker compose -p ${COMPOSE_PROJECT_NAME} -f deployment/docker-compose/docker-compose.yaml按需追加-f docker-compose.override.yaml--port-mapping以及对应的--profile参数。健康检查与自动补启start_missing_containers会先docker inspect检查目标容器状态只启动缺失的容器随后以 1 秒间隔轮询健康状态最多重试 60 次全部健康后自动生成~/.opik.config配置文件写入url_override http://localhost:5173/api/与workspace default方便后续 SDK 直接使用。匿名安装上报脚本默认发送匿名安装事件可通过OPIK_USAGE_REPORT_ENABLEDfalse关闭当使用部分画像非完整套件时会自动禁用上报。三、使用官方镜像运行版本控制与基础部署3.1 指定 Opik 版本如需使用特定版本先通过环境变量设置版本号export OPIK_VERSION0.1.10不设置时默认使用latest最新镜像。OPIK_VERSION会被注入所有业务镜像backend、python-backend、frontend、guardrails-backend的 tag例如 docker-compose.yaml 中的ghcr.io/comet-ml/opik/opik-backend:${OPIK_VERSION:-latest}。3.2 标准启动流程从项目根目录进入 compose 目录并启动cd deployment/docker-compose # 可选强制拉取最新镜像 docker compose --profile opik pull docker compose -f docker-compose.yaml --profile opik up -d启动完成后Opik UI 默认通过 Nginx 监听5173端口frontend服务的ports: ${NGINX_PORT:-5173}:${NGINX_PORT:-5173}访问http://localhost:5173即可打开控制台。四、从最新源码构建运行开发模式部署如果想使用仓库最新代码而非发布镜像在up时附加--build即可。Compose 会根据各服务的build.context指向的源码目录构建镜像例如 backend 的构建上下文是 apps/opik-backend使用其 Dockerfilefrontend 对应 apps/opik-frontendpython-backend 对应 apps/opik-python-backend。cd deployment/docker-compose # 可选强制拉取最新镜像 docker compose --profile opik pull # 构建镜像并启动 docker compose -f docker-compose.yaml --profile opik up -d --build # 或者强制拉取最新镜像 构建镜像 docker compose -f docker-compose.yaml --profile opik up -d --build --pull always提示使用./opik.sh --build也可以达到同样的构建启动效果脚本内部会优先探测 Docker Buildx 的 Bake 能力并导出COMPOSE_BAKEtrue以加速镜像构建。五、暴露数据库与后端端口本地联调开发默认情况下业务容器之间的通信通过 Compose 内部网络完成宿主机的 Docker Compose 只暴露了frontend的 5173 端口。若你是开发者需要在宿主机上直接访问数据库或后端端口进行本地测试、调试例如本地运行 SDK 直连 ClickHouse 或 MySQL可以使用仓库提供的 override 文件。5.1 使用 override 文件暴露端口# 可选强制拉取最新镜像 docker compose --profile opik pull docker compose -f docker-compose.yaml -f docker-compose.override.yaml --profile opik up -d5.2 暴露到宿主机后的端口一览服务端口用途Redis6379缓存 / 消息队列ClickHouse8123HTTP、9000Native Protocol分析型数据库ZooKeeper2181ClickHouse 协调服务MySQL3306关系型数据库元数据Backend8080HTTP、3003OpenAPI 规范主后端 APIPython Backend8000HTTPPython 评估执行后端Frontend5173前端 UI这些映射在 docker-compose.override.yaml 中均有定义且每个端口都支持环境变量覆盖例如${MYSQL_PORT:-3306}、${CLICKHOUSE_HTTP_PORT:-8123}、${OPIK_BACKEND_PORT:-8080}等。值得注意的是backend 的端口映射使用了!override标签Compose 合并语义用于显式替换而不是合并基础文件中的 ports 定义。六、限制端口绑定地址安全加固Docker Compose 默认将暴露的容器端口绑定到0.0.0.0这意味着宿主机任意网络接口都能访问这些端口。若要限制访问范围只需在ports段指定具体 IP例如127.0.0.1:8080:80仅允许本机访问。以 docker-compose.yaml 中的frontend服务为例frontend: ports: - 127.0.0.1:5173:5173 # Frontend server port对安全性敏感的自托管部署建议对 MySQL、Redis、ClickHouse 等数据组件同样加上127.0.0.1前缀避免数据库端口直接暴露到外部网络。七、修改前端端口NGINX_PORT 与 OPIK_PORT_OFFSET如果宿主机上的 5173 端口已被占用例如另一个 Vite dev server 或无法迁移的本地应用可以在启动前设置NGINX_PORT环境变量# UI 将可通过 http://localhost:5293 访问 NGINX_PORT5293 ./opik.shNGINX_PORT会被前端容器的端口映射、healthcheck、Nginx 配置以及后端内部反向代理 URL 共同使用具体可见 docker-compose.yaml 中 frontend 服务的ports、healthcheck与NGINX_PORT环境变量以及 Nginx 模板 10-log-formats.conf.template 相关的listen ${NGINX_PORT}渲染逻辑。如果你的目标是将所有 Opik 端口前端、后端、MySQL、Redis 等整体平移相同的增量则使用export OPIK_PORT_OFFSETN该变量会被 scripts/worktree-utils.sh 的calculate_port_offset优先采用若设置了OPIK_PORT_OFFSET则直接返回该值不再按路径哈希计算随后所有端口都以基础端口 偏移量的形式重新计算并导出给 docker-compose。八、本地运行 Backend Docker 运行其余组件Opik 支持本机直接运行后端代码、其余组件全部跑在 Docker的混合开发模式非常适合调试后端时快速热重载。8.1 修改 Nginx 反向代理指向在 nginx_default_local.conf 中将后端上游地址替换为你的 localhosthttp://backend:8080Mac/WindowsDocker Desktop环境替换为http://host.docker.internal:8080Linux 环境替换为 Docker 默认网桥网关地址http://172.17.0.1:8080该文件被 frontend 容器以只读方式挂载为 Nginx 模板见 docker-compose.yaml 中./nginx_${OPIK_FRONTEND_FLAVOR:-default}_local.conf的挂载配置其内部通过upstream backend { server backend:8080 resolve; }与location api { proxy_pass http://backend; }完成/api/前缀的请求转发并额外代理/oauth/、/.well-known/oauth-authorization-server等 OAuth 端点。8.2 启动容器并停掉容器化的 backend# 可选强制拉取最新镜像 docker compose --profile opik pull docker compose -f docker-compose.yaml -f docker-compose.override.yaml --profile opik up -d随后停止 backend 容器本地后端将接管 8080 端口即可在宿主机上直接运行、调试后端代码而前端、数据库、Python backend 等仍由 Docker 提供。九、OpenTelemetry 可观测性追踪与日志采集Opik 提供开箱即用的 OpenTelemetry 可观测性方案通过opik-otel画像同时启动 OpenTelemetry Collector 与 Jaeger用于采集和可视化 traces 与 logs。9.1 一键启动docker compose --profile opik-otel up -d该命令将启动Opik 全栈Frontend、Backend 等OpenTelemetry Collector暴露 4317、4318、5140/udp 等端口JaegerUI 位于http://localhost:16686。从 docker-compose.yaml 可以看出jaeger使用jaegertracing/all-in-one镜像并开放 16686UI、14317OTLP gRPC、14318OTLP HTTP端口otel-collector使用otel/opentelemetry-collector-contrib:0.139.0加载 otel-collector-config.yaml 作为配置并依赖 jaeger 健康后才启动。9.2 开启 Nginx 追踪与日志投递默认情况下 Nginx 的追踪与日志采集是关闭的需要显式开启# 在 Nginx 中启用 OpenTelemetry 追踪 export OTEL_TRACEon # 配置 Nginx 通过 Syslog 将日志投递到 OpenTelemetry Collector export NGINX_EXTRA_ACCESS_LOGaccess_log syslog:serverotel-collector:5140 logger-json; export NGINX_EXTRA_ERROR_LOGerror_log syslog:serverotel-collector:5140 error; # 使用对应画像启动 docker compose --profile opik-otel up -d启用后Nginx Traces发送到 OTel Collector并可在 Jaeger 中查看Nginx Logs通过 syslog 发送到 OTel Collector。9.3 底层的采集链路解析Nginx 侧OTEL_TRACEon会渲染到 Nginx 的 OpenTelemetry 模块见 20-otel.conf.template 中的otel_trace ${OTEL_TRACE};、otel_exporter与otel_service_name opik-frontendlogger-json日志格式定义了包含method、request、status、request_time、otel_trace_id、upstream_response_time等字段的 JSON 结构见 10-log-formats.conf.template其中otel_trace_id让每条日志都能与对应 trace 关联。Collector 侧otel-collector-config.yaml 定义了三条 pipelinetraces接收 OTLP/Jaeger/Zipkin导出到 debug 与otlp/jaeger、metrics接收 OTLP/Prometheus、logs接收 OTLP/syslog。syslog receiver 监听 UDP 5140 端口用正则解析 Nginx 的 access/error 日志并提取消息内容batchprocessor 负责批量发送traces 通过otlp/jaegerexporter 写入 Jaeger。应用侧backend 与 python-backend 容器默认已配置OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4317等环境变量应用自身的 trace 数据同样汇入 Collector。9.4 停止 Opikdocker compose --profile opik down # 若使用 otel 画像启动则 docker compose --profile opik-otel down十、部署方案小结按需组合利用 Compose Profile 机制默认基础设施 / backend / opik / guardrails / opik-otel自由组合服务且业务画像自动包含基础设施双重入口既可直接使用docker compose --profile xxx up -d也可使用 opik.sh 封装脚本获得健康检查、端口偏移、demo 数据生成等额外能力版本可控通过OPIK_VERSION环境变量固定镜像版本通过--build从源码构建最新代码联调友好override 文件可按需暴露 MySQL/ClickHouse/Redis/Backend 等端口NGINX_PORT与OPIK_PORT_OFFSET解决端口冲突与多 worktree 并行问题可观测性完备opik-otel画像集成 OpenTelemetry Collector 与 Jaeger支持应用 traces、Nginx 追踪与访问/错误日志的一体化采集与可视化。以上所有配置均以当前仓库实际文件为准进一步深入可查阅 docker-compose.yaml、docker-compose.override.yaml、opik.sh 与 otel-collector-config.yaml。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考