AgentOps 应用开发环境实战：用 Docker Compose、Supabase 与 ClickHouse 跑通本地全栈-迪斯科星球

AgentOps 应用开发环境实战：用 Docker Compose、Supabase 与 ClickHouse 跑通本地全栈

【免费下载链接】agentopsPython SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI项目地址: https://gitcode.com/GitHub_Trending/ag/agentops

本文基于 AgentOps 仓库中app/子项目的官方开发文档 app/README.md 整理并纵深展开：AgentOps 是一个面向 AI Agent 的可观测性平台，覆盖实时追踪、分布式链路、成本分析与计费管理。读完本文，你可以独立完成三种本地部署路径（Docker Compose 全栈、自托管 ClickHouse 的本地数据链路、纯本地原生开发），掌握 Supabase 与 ClickHouse 凭据的获取方式，理解 SDK 上报的 trace 如何经由 OpenTelemetry Collector 落入 ClickHouse 并被 Dashboard 查询，并熟悉项目自带的 just 命令、测试与代码质量工具链。

平台能力与仓库架构

AgentOps 定位为 AI Agent 与应用的可观测性平台，app/README.md 中列出的核心特性包括：

实时监测（Real-time Monitoring）：实时跟踪 AI Agent 的性能与行为；
分布式追踪（Distributed Tracing）：完整可视化多步 AI 工作流；
成本分析（Cost Analytics）：跨模型供应商监控与优化成本；
错误追踪（Error Tracking）：全面的错误监控与告警；
团队协作（Team Collaboration）：多用户仪表盘与基于角色的访问控制；
计费管理（Billing Management）：内置订阅制与按用量计费。

这是一个 monorepo，app/目录下的组成与职责如下（继承自原文档 Architecture 一节）：

组件	路径	说明
API Server	app/api	FastAPI 后端，负责认证、计费与数据处理
Dashboard	app/dashboard	Next.js 前端，用于可视化与管理
Landing Page	app/landing	官网落地页
ClickHouse	—	存储 trace 与指标的 OLAP 分析库
Supabase	—	认证与主数据库（PostgreSQL）
Docker Compose	app/compose.yaml	本地开发环境编排

从 app/api/agentops/app.py 的源码结构看，后端采用「父应用挂载子应用」的组织方式：单一 FastAPI 入口挂载/auth、/opsboard、/public、/deploy四个子应用，业务主 API 挂在根路径/，并通过自定义 OpenAPI schema 生成器把它们合并为一份「Combined API」文档。这也解释了为什么本地启动后能在http://localhost:8000/docs看到完整的合并 API 文档。

环境前置要求

开始之前，确认已安装以下工具（继承自原文档 Prerequisites 一节）：

Node.js18+（见徽章声明）；
Python3.12+；
Docker 与 Docker Compose；
Bun（推荐，用于 JS/TS 依赖管理）或 npm；
uv（推荐，用于 Python 依赖管理，配合根目录 app/uv.lock 保证版本一致）。

Docker Compose 快速开始（推荐路径）

这是官方推荐的本地部署方式，最可靠也最容易复现。

1. 创建环境文件

app/.env中的变量会被 app/compose.yaml 通过${VAR}插值注入两个服务。仓库提供了 app/.env.example 作为起点：

cp app/.env.example app/.env

最小必需变量分组（与原文档一致，并按 app/.env.example 补全了默认值语义）：

Supabase（认证与主库）
- NEXT_PUBLIC_SUPABASE_URL=https://YOUR_PROJECT_ID.supabase.co
- NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
- SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
- SUPABASE_PROJECT_ID=YOUR_PROJECT_ID
URL
- APP_URL=http://localhost:3000
- NEXT_PUBLIC_SITE_URL=http://localhost:3000
认证
- JWT_SECRET_KEY=replace-with-long-random-secret
ClickHouse
- CLICKHOUSE_HOST=your-clickhouse-host
- CLICKHOUSE_PORT=8443（云）或8123（本地）
- CLICKHOUSE_USER=default
- CLICKHOUSE_PASSWORD=your-clickhouse-password
- CLICKHOUSE_DATABASE=otel_2
- CLICKHOUSE_SECURE=true（云）/false（本地）
可选
- NEXT_PUBLIC_ENVIRONMENT_TYPE=development
- NEXT_PUBLIC_PLAYGROUND=true
- NEXT_PUBLIC_POSTHOG_KEY=、NEXT_PUBLIC_SENTRY_DSN=（留空即可）
- NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=、NEXT_STRIPE_SECRET_KEY=、NEXT_STRIPE_WEBHOOK_SECRET=（仅测试计费时需要）

从 app/.env.example 可以看到本地与云端的典型差异写法：本地自托管 ClickHouse 时使用CLICKHOUSE_HOST=127.0.0.1、CLICKHOUSE_PORT=8123、CLICKHOUSE_SECURE=false、CLICKHOUSE_PASSWORD=password；切换到 ClickHouse Cloud 时把端口改为8443并设置CLICKHOUSE_SECURE=true。此外该文件还包含 S3 日志桶（SUPABASE_S3_*）、REDIS_HOST/REDIS_PORT与DEMO_ORG_ID等可选项。

2. 启动并观察

cd app docker compose up -d docker compose ps docker compose logs -f api docker compose logs -f dashboard

关于编排细节，从 app/compose.yaml 的源码结构看有三点值得注意：

文件顶部通过include引入了 app/opentelemetry-collector/compose.yaml，因此up时会自动带上otelcollector（OTLP 接收端，映射4317/4318等端口）与本地clickhouse（clickhouse/clickhouse-server:24.12镜像，HTTP 端口8123）两个附加服务——这正是 SDK 本地上报 trace 的数据通路（见后文「端到端验证」）。
api服务由 app/api/Dockerfile 构建，映射8000:8000，使用network_mode: host并挂载./api卷用于热开发；从源码结构看，这意味着本地 compose 场景下 API 直接共享宿主机网络栈。
dashboard服务声明了profiles: ['dashboard']。可以推断，默认docker compose up -d主要拉起 api 与 collector/ClickHouse 相关服务，若要以容器方式运行 Next.js Dashboard，需显式带上该 profile（例如docker compose --profile dashboard up -d）；而日常开发更常见的做法是原生运行 Dashboard（见下文原生开发一节）。

3. 验证

API 文档：http://localhost:8000/docs（注意：从 app/api/agentops/app.py 看，docs 路由仅在API_DOMAIN包含localhost时开启，所以本地 compose 场景天然可见）；
Dashboard：http://localhost:3000。

原文档给出的 CORS 行为与源码吻合：只有当API_DOMAIN含localhost或127.0.0.1时才会注入 CORS 中间件并放行http://localhost:3000来源（见 app/api/agentops/app.py）。因此必须保证APP_URL=http://localhost:3000，否则 Dashboard 跨域请求会被拒绝。

4. Compose 故障排查（继承自原文档）

CORS：APP_URL必须为http://localhost:3000，API 才允许 Dashboard 来源；
Supabase：API 侧需要 service role key，anon key 只够 Dashboard 前端用；
ClickHouse：云实例用8443端口 +CLICKHOUSE_SECURE=true，并确保你的 IP 已加入 ClickHouse Cloud 白名单；
Stripe：仅计费测试需要；如需 Webhook，设置NEXT_STRIPE_WEBHOOK_SECRET并运行stripe listen；
端口占用：启动 compose 前停掉占用 3000/8000 的原生服务；
日志：优先看docker compose logs -f api与docker compose logs -f dashboard定位报错。

外部服务凭据获取

Supabase

在 Supabase 控制台创建项目；
Project URL（对应NEXT_PUBLIC_SUPABASE_URL）：Settings → API → Project URL；
Anon key（对应NEXT_PUBLIC_SUPABASE_ANON_KEY）：Settings → API → anon public；
Service role key（对应SUPABASE_SERVICE_ROLE_KEY，API 侧记为SUPABASE_KEY）：Settings → API → service_role secret；
Project ID（对应SUPABASE_PROJECT_ID）：即 Project URL 的子域，或 Settings → General → Reference ID；
API 直连数据库需要额外一组变量：SUPABASE_HOST、SUPABASE_PORT、SUPABASE_DATABASE、SUPABASE_USER、SUPABASE_PASSWORD。在 Settings → Database → Connection info 中获取，使用 pooled/primary 主机与5432端口，用户通常是postgres.<project_id>（与 app/.env.example 中SUPABASE_USER=postgres.YOUR_PROJECT_ID的写法一致）。

本地 Supabase 方案（Supabase CLI）：supabase init+supabase start后，用SUPABASE_URL=http://127.0.0.1:54321与启动输出中的 anon key 更新.env，再执行supabase db push跑迁移；Linux 环境 CLI 安装受限时，仓库提供了 docs/local_supabase_linux.md 的手动二进制安装与环境映射指引，另有 docs/local_clickhouse_setup.md 覆盖本地 ClickHouse 搭建。

ClickHouse Cloud

在 ClickHouse Cloud 创建服务；
主机与端口：CLICKHOUSE_HOST=<your-service-name>.region.clickhouse.cloud、CLICKHOUSE_PORT=8443、CLICKHOUSE_SECURE=true；
认证：CLICKHOUSE_USER（默认default或自建用户）、CLICKHOUSE_PASSWORD取自连接串；
数据库：CLICKHOUSE_DATABASE=otel_2（本仓库默认库名，可按需调整）；
网络：把本机 IP 加入 ClickHouse Cloud 的 IP 白名单。

端到端本地数据链路验证（OTel Collector + 自托管 ClickHouse）

app/README.md 开头一段「Restart local stack and verify」描述的是完整本地链路的重启与验证流程，配合「Local ClickHouse (self-hosted)」一节，构成不依赖云服务的离线验证方案。

1. 本地 ClickHouse 环境配置

在.env中设置：

CLICKHOUSE_HOST=127.0.0.1 CLICKHOUSE_PORT=8123 CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=password CLICKHOUSE_DATABASE=otel_2 CLICKHOUSE_SECURE=false CLICKHOUSE_ENDPOINT=http://clickhouse:8123 CLICKHOUSE_USERNAME=default

注意CLICKHOUSE_ENDPOINT是容器间地址：从 app/opentelemetry-collector/compose.yaml 看，collector 容器默认以http://clickhouse:8123访问 ClickHouse 容器，trace 写入TRACES_TABLE_NAME（默认otel_traces）表，CLICKHOUSE_TTL默认12h，JWT_SECRET复用JWT_SECRET_KEY。

2. 初始化 schema

启动服务（自动包含 otelcollector 与本地 ClickHouse）：

docker compose -f compose.yaml -f opentelemetry-collector/compose.yaml up -d

初始化数据库与表结构（迁移 SQL 位于 app/clickhouse/migrations，按序共 5 个文件，从建表到 UDF/定价、span 计数物化视图、模型成本种子数据）：

curl -u default:password 'http://localhost:8123/?query=CREATE%20DATABASE%20IF%20NOT%20EXISTS%20otel_2' curl --data-binary @app/clickhouse/migrations/0000_init.sql -u default:password 'http://localhost:8123/?query='

若成本统计与计费功能需要，可继续按序应用 0001_udfs_and_pricing.sql 至 0004_seed_model_costs_full.sql。

3. 重启与日志检查

docker compose -f compose.yaml -f opentelemetry-collector/compose.yaml down --remove-orphans docker compose -f compose.yaml -f opentelemetry-collector/compose.yaml up -d docker compose -f compose.yaml -f opentelemetry-collector/compose.yaml logs --since=90s api docker compose -f compose.yaml -f opentelemetry-collector/compose.yaml logs --since=90s dashboard docker compose -f compose.yaml -f opentelemetry-collector/compose.yaml logs --since=90s otelcollector docker compose -f compose.yaml -f opentelemetry-collector/compose.yaml logs --since=90s clickhouse

4. 产生一条 trace 并双向验证

用 AgentOps SDK 的 OpenAI 同步示例（examples/openai/openai_example_sync.py）通过本地 OTLP 端点上报：

AGENTOPS_API_KEY=<key> \ AGENTOPS_API_ENDPOINT=http://localhost:8000 \ AGENTOPS_APP_URL=http://localhost:3000 \ AGENTOPS_EXPORTER_ENDPOINT=http://localhost:4318/v1/traces \ OPENAI_API_KEY=<openai_key> \ python examples/openai/openai_example_sync.py

其中AGENTOPS_EXPORTER_ENDPOINT指向 collector 映射到宿主机的4318OTLP/HTTP 端口（见 app/opentelemetry-collector/compose.yaml）。随后在两端交叉验证同一TRACE_ID：

ClickHouse 侧：

curl -s -u default:password "http://localhost:8123/?query=SELECT%20count()%20FROM%20otel_2.otel_traces%20WHERE%20TraceId%20=%20'<TRACE_ID>'"

Dashboard 侧：http://localhost:3000/traces?trace_id=<TRACE_ID>（登录入口为http://localhost:3000/signin）。

这条链路即：SDK → OTLP(4318) → otelcollector → ClickHouse(otel_2.otel_traces) → API 查询 → Dashboard 展示。

原生本地开发（Beginner Quickstart）

若不用容器，可直接以原生进程运行 API 与 Dashboard。

1. 准备环境文件

API：app/api/.env
Dashboard：app/dashboard/.env.local
可选（供 Docker Compose 使用）：app/.env

API 最小环境变量（app/api/.env）：

# 核心 URL（决定 CORS 与 docs 行为） PROTOCOL=http API_DOMAIN=localhost:8000 APP_DOMAIN=localhost:3000 # 认证 JWT_SECRET_KEY=your-long-random-secret # Supabase 连接 SUPABASE_URL=https://your-project-id.supabase.co SUPABASE_KEY=your-service-role-key SUPABASE_HOST=your-supabase-pg-host SUPABASE_PORT=5432 SUPABASE_DATABASE=postgres SUPABASE_USER=postgres.your-project-id SUPABASE_PASSWORD=your-supabase-db-password # ClickHouse 连接 CLICKHOUSE_HOST=your-clickhouse-host CLICKHOUSE_PORT=8443 CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=your-clickhouse-password CLICKHOUSE_DATABASE=otel_2 # 可选 SQLALCHEMY_LOG_LEVEL=WARNING REDIS_HOST=localhost REDIS_PORT=6379 STRIPE_SECRET_KEY=sk_test_... STRIPE_SUBSCRIPTION_PRICE_ID=price_... STRIPE_TOKEN_PRICE_ID=price_... STRIPE_SPAN_PRICE_ID=price_...

要点：API 后端操作需要 Supabase service role key，anon key 不够；APP_DOMAIN/API_DOMAIN/PROTOCOL需解析为http://localhost:3000与http://localhost:8000才能通过 CORS。

Dashboard 最小环境变量（app/dashboard/.env.local）：

NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key SUPABASE_SERVICE_ROLE_KEY=your-service-role-key SUPABASE_PROJECT_ID=your-project-id NEXT_PUBLIC_API_URL=http://localhost:8000 NEXT_PUBLIC_APP_URL=http://localhost:3000 NEXT_PUBLIC_SITE_URL=http://localhost:3000 # 可选 NEXT_PUBLIC_ENVIRONMENT_TYPE=development NEXT_PUBLIC_PLAYGROUND=true NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_... NEXT_PUBLIC_POSTHOG_KEY= NEXT_PUBLIC_SENTRY_DSN=

2. 安装依赖

仓库根目录（即app/）下：

bun install # 根级 JS/TS 工具链 uv pip install -r requirements-dev.txt # Python 开发依赖（Ruff 等） cd api && uv pip install -e . && cd .. # API 以可编辑模式安装 cd dashboard && bun install && cd .. # Dashboard 依赖

3. 原生启动

终端 A（API）：

cd app/api uv run python run.py

从 app/api/run.py 的实现看，服务以 uvicorn 绑定0.0.0.0:8000并开启reload热重载；同时会启动一个每小时执行一次的update_token_costs异步任务，周期性刷新 token 成本数据——这解释了成本分析功能为何在本地跑起来后也能持续更新。验证地址：http://localhost:8000/redoc。

终端 B（Dashboard）：

cd app/dashboard bun run dev

然后打开http://localhost:3000。

4. 验证清单

API：http://localhost:8000/redoc可加载且无 5xx；
Dashboard：http://localhost:3000可加载，浏览器控制台无 CORS/网络错误；
如需计费流程：配置 Stripe 测试密钥，运行stripe listen --forward-to http://localhost:8000/v4/stripe-webhook，并把生成的 secret 写入app/api/.env的STRIPE_WEBHOOK_SECRET。

5. 本地开发的额外服务

Redis：可选，仅限流/会话缓存需要；不启用则留空REDIS_*即可；

Supabase CLI 本地模式：Postgres 直连端口是54322（与 Supabase API 的54321不同），同时设置POSTGRES_*与SUPABASE_*两组连接变量：

POSTGRES_HOST=127.0.0.1 POSTGRES_PORT=54322 POSTGRES_USER=postgres POSTGRES_PASSWORD=postgres POSTGRES_DATABASE=postgres SUPABASE_HOST=127.0.0.1 SUPABASE_PORT=54322 SUPABASE_USER=postgres SUPABASE_PASSWORD=postgres SUPABASE_DATABASE=postgres

just 命令与开发工作流

仓库根目录提供 app/justfile 作为开发便利入口，从文件内容看可用命令包括：

just # 查看全部命令 just setup # 复制三份 .env 模板 + 安装全部依赖（首次使用先跑这个） just install # 安装根级、Python、API、Dashboard 依赖 just api-native # 原生运行 API（开发最快） just api-build # 构建 API Docker 镜像 just api-run # 容器运行 API just api-test # 运行 API pytest just fe-run # 启动 Dashboard 开发服务器（bun install + bun run dev） just fe-build # 构建生产版 Dashboard just fe-test # 前端测试（bun test） just lint / just format # 全量 lint / 格式化（format 执行 ruff format） just up / just down / just logs # Docker Compose 启停与日志 just clean # down -v + docker system prune

注意 app/justfile 的setup会依次创建.env、api/.env、dashboard/.env.local（均以对应.example为模板），等价于原文档 Quick Start 一节的手动cp操作。

手动开发等价命令：

cd app/api && uv run python run.py # API cd app/dashboard && bun run dev # Dashboard cd app/landing && bun run dev # Landing（如需要）

测试与代码质量

cd app/api && pytest # API 测试 cd app/dashboard && bun test # 前端测试 bun run lint # 根级 lint bun run format # 根级格式化

monorepo 采用集中式 lint/格式化配置（继承自原文档 Development Setup 一节）：

JS/TS：ESLint（app/.eslintrc.json）+ Prettier（app/prettier.config.js），位于仓库根；子项目（如dashboard/）可用自己的.eslintrc.json继承并覆盖；
Python：Ruff（app/ruff.toml）；
Pre-commit：Husky 在 app/.husky/pre-commit 中对暂存的 JS/TS/Python 文件自动执行根级格式化与 lint；
手动检查：bun run lint:js、bun run lint:py、bun run format:js、bun run format:py、bun run lint、bun run format。

建议为 IDE 配置 ESLint、Prettier、Ruff 扩展以获得保存即格式化的体验。

生产部署要点

Docker Compose（自托管推荐）：docker-compose -f app/compose.yaml up -d；

生产环境变量示例：

PROTOCOL="https" API_DOMAIN="api.yourdomain.com" APP_DOMAIN="yourdomain.com" DEBUG="false" LOGGING_LEVEL="WARNING" NEXT_PUBLIC_ENVIRONMENT_TYPE="production" NEXT_PUBLIC_PLAYGROUND="false"

部署平台：Docker Compose（自托管推荐）、Kubernetes、AWS/GCP/Azure 等云平台，或前端 Vercel + 后端 Railway/Fly.io 的组合。
仓库在 app/fly.toml、app/deploy 等位置也保留了相应的部署配置，可作为对照参考。

常见问题排查（Troubleshooting）

登录成功后立即被重定向回登录页

通常是前后端 Cookie 配置问题：

确认 Dashboard 的NEXT_PUBLIC_API_URL指向 API（本地为http://localhost:8000）；
确认 API.env中JWT_SECRET_KEY已设置且长度足够（建议 32 字符以上）；
本地不同端口开发：API 会自动针对 localhost 调整 cookie 配置，无需手动干预；
生产或自定义域名：确保 API 与 Dashboard 共享同一根域名，否则 cookie 无法跨域写入。

SQLAlchemy 连接错误

确认api/.env中 Supabase 数据库变量齐全（本地 Supabase 示例）：

SUPABASE_HOST=127.0.0.1 SUPABASE_PORT=54322 # 注意：与 Supabase API 端口 54321 不同 SUPABASE_USER=postgres SUPABASE_PASSWORD=postgres SUPABASE_DATABASE=postgres

Supabase 种子数据问题

supabase start时出现重复键或缺表错误，可能是 app/supabase/seed.sql 存在冲突，可临时注释有问题的 insert，或检查 app/supabase/migrations 中的迁移是否缺失。

其他（继承自原文档）

401/403：API 校验 Supabase JWT，需先经 Dashboard 登录，使请求携带Authorization: Bearer <token>；
ClickHouse 连接超时/拒绝：确认 8443 端口、凭据与 Cloud IP 白名单；
Redis 未安装：开发环境可选，启用限流或会话缓存时才需要；
端口占用：确保 3000/8000 未被占用，或调整映射端口并同步修改相关 env URL。

贡献流程与代码规范

继承自原文档 Procedue 一节：

特性分支工作流：建分支 → 完成特性 → 提交 PR（附简要说明）→ 至少一人评审后合并进main；
PR 规则：不使用 squash commit；合并前至少一次评审；main分支受保护；紧急免评审合并需在 PR 中说明理由；PR 描述需符合模板；关闭 Linear 工单时引用（如Closes ENG-123）；
提交信息格式：type(service): description，例如feat(supabase): added user table、fix(app): spacing issue on dashboard、test(app): login component testing；
详细规范见 app/CONTRIBUTING.md 与根目录 CONTRIBUTING.md。

许可与支持

项目采用 Elastic License 2.0（见 app/LICENSE）：可免费使用、修改、分发，允许商业用途；但不允许向第三方提供托管/管理服务、不允许绕过许可证密钥机制、不允许移除许可声明；
子模块文档：app/api/README.md、app/dashboard/README.md；
本地环境辅助文档：docs/local_clickhouse_setup.md、docs/local_supabase_linux.md。

小结

AgentOps 的本地开发体系围绕三条主线组织：以 app/compose.yaml（含 OpenTelemetry Collector 与本地 ClickHouse）为核心的容器化全栈、以 SDK + OTLP 端点 + ClickHouse 校验构成的端到端数据链路验证、以及 just + uv + bun 工具链驱动的原生开发体验。按本文的顺序完成「凭据准备 → .env 配置 → 启动 → trace 上报 → 双向验证」，即可在不依赖任何云服务的前提下完整跑通 AgentOps 的可观测数据管道，并在此基础上开展 API 与 Dashboard 的二次开发。

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

企业官网建设流程全解析