企业官网建设流程全解析

使用 Docker Compose 部署 Opik：Profile 画像体系、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-llm

Opik 是一个用于调试、评估和监控 LLM 应用、RAG 系统与 Agent 工作流的可观测性平台。本指南围绕仓库中 deployment/docker-compose/README.md 展开，系统讲解如何通过 Docker Compose 完成从单机基础设施到完整 Opik 套件（含 Guardrails 与 OpenTelemetry 可观测性）的部署，并结合 docker-compose.yaml、opik.sh 等仓库源码，深入剖析其 Profile 画像机制、端口管理逻辑与底层配置原理。读完本文，你将能够按需组合启动任意服务组合、自定义版本与端口、暴露数据库端口进行本地联调，并开启 Nginx 追踪与日志的 OTLP 采集链路。

安装前置条件

在开始之前，请确保宿主机已安装以下软件（详见原文档的安装指引）：

• Docker：用于运行容器。
• Docker Compose（V2 及以上）：用于编排多容器应用。仓库脚本统一使用docker compose命令（V2 插件形式），并在 opik.sh 中做了兼容检测，若 V2 不可用会自动回退到 V1 的docker-compose。

一、Compose Profile 画像体系：按需组合服务

Opik 的 Docker Compose 编排基于Compose Profiles实现不同开发场景的服务组合。理解这套画像体系是使用本部署方案的前提，其核心设计在 docker-compose.yaml 中通过每个 service 的profiles字段定义。

1.1 五类服务画像

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

启动后端 + Guardrails：

docker compose --profile backend --profile guardrails up -d

启动完整 Opik 套件 + Guardrails：

docker compose --profile opik --profile guardrails up -d

启动完整 Opik 套件 + OpenTelemetry：

docker compose --profile opik-otel up -d

1.4 基础设施服务速览（来自 compose 源码）

从 docker-compose.yaml 可以梳理出基础设施层各服务的镜像与关键配置，帮助理解整个栈的依赖关系：

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.sh（Windows 使用 opik.ps1）。它本质上是 Compose 命令的封装层，负责参数解析、端口计算、容器健康检查与状态横幅输出。

2.1 官方支持的选项

运行./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_ENABLED=false关闭）；当使用部分画像（非完整套件）时会自动禁用上报。

三、使用官方镜像运行：版本控制与基础部署

3.1 指定 Opik 版本

如需使用特定版本，先通过环境变量设置版本号：

export OPIK_VERSION=0.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（使用其 Dockerfile），frontend 对应 apps/opik-frontend，python-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_BAKE=true以加速镜像构建。

五、暴露数据库与后端端口：本地联调开发

默认情况下，业务容器之间的通信通过 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 -d

5.2 暴露到宿主机后的端口一览

这些映射在 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_PORT=5293 ./opik.sh

NGINX_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_OFFSET=N

该变量会被 scripts/worktree-utils.sh 的calculate_port_offset优先采用（若设置了OPIK_PORT_OFFSET则直接返回该值，不再按路径哈希计算），随后所有端口都以基础端口 + 偏移量的形式重新计算并导出给 docker-compose。

八、本地运行 Backend + Docker 运行其余组件

Opik 支持"本机直接运行后端代码、其余组件全部跑在 Docker"的混合开发模式，非常适合调试后端时快速热重载。

8.1 修改 Nginx 反向代理指向

在 nginx_default_local.conf 中，将后端上游地址替换为你的 localhost：

http://backend:8080

Mac/Windows（Docker Desktop）环境替换为：

http://host.docker.internal:8080

Linux 环境替换为 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 等端口）；
• Jaeger（UI 位于http://localhost:16686）。

从 docker-compose.yaml 可以看出，jaeger使用jaegertracing/all-in-one镜像并开放 16686（UI）、14317（OTLP gRPC）、14318（OTLP HTTP）端口；otel-collector使用otel/opentelemetry-collector-contrib:0.139.0，加载 otel-collector-config.yaml 作为配置，并依赖 jaeger 健康后才启动。

9.2 开启 Nginx 追踪与日志投递

默认情况下 Nginx 的追踪与日志采集是关闭的，需要显式开启：

# 在 Nginx 中启用 OpenTelemetry 追踪 export OTEL_TRACE=on # 配置 Nginx 通过 Syslog 将日志投递到 OpenTelemetry Collector export NGINX_EXTRA_ACCESS_LOG="access_log syslog:server=otel-collector:5140 logger-json;" export NGINX_EXTRA_ERROR_LOG="error_log syslog:server=otel-collector:5140 error;" # 使用对应画像启动 docker compose --profile opik-otel up -d

启用后：

• Nginx Traces：发送到 OTel Collector，并可在 Jaeger 中查看；
• Nginx Logs：通过 syslog 发送到 OTel Collector。

9.3 底层的采集链路解析

• Nginx 侧：OTEL_TRACE=on会渲染到 Nginx 的 OpenTelemetry 模块（见 20-otel.conf.template 中的otel_trace ${OTEL_TRACE};、otel_exporter与otel_service_name "opik-frontend"）；logger-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 定义了三条 pipeline：traces（接收 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 停止 Opik

docker 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