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内置订阅制与按用量计费。这是一个 monorepoapp/目录下的组成与职责如下继承自原文档 Architecture 一节组件路径说明API Serverapp/apiFastAPI 后端负责认证、计费与数据处理Dashboardapp/dashboardNext.js 前端用于可视化与管理Landing Pageapp/landing官网落地页ClickHouse—存储 trace 与指标的 OLAP 分析库Supabase—认证与主数据库PostgreSQLDocker Composeapp/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.12Docker 与 Docker ComposeBun推荐用于 JS/TS 依赖管理或 npmuv推荐用于 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_URLhttps://YOUR_PROJECT_ID.supabase.coNEXT_PUBLIC_SUPABASE_ANON_KEYyour-anon-keySUPABASE_SERVICE_ROLE_KEYyour-service-role-keySUPABASE_PROJECT_IDYOUR_PROJECT_IDURLAPP_URLhttp://localhost:3000NEXT_PUBLIC_SITE_URLhttp://localhost:3000认证JWT_SECRET_KEYreplace-with-long-random-secretClickHouseCLICKHOUSE_HOSTyour-clickhouse-hostCLICKHOUSE_PORT8443云或8123本地CLICKHOUSE_USERdefaultCLICKHOUSE_PASSWORDyour-clickhouse-passwordCLICKHOUSE_DATABASEotel_2CLICKHOUSE_SECUREtrue云/false本地可选NEXT_PUBLIC_ENVIRONMENT_TYPEdevelopmentNEXT_PUBLIC_PLAYGROUNDtrueNEXT_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_HOST127.0.0.1、CLICKHOUSE_PORT8123、CLICKHOUSE_SECUREfalse、CLICKHOUSE_PASSWORDpassword切换到 ClickHouse Cloud 时把端口改为8443并设置CLICKHOUSE_SECUREtrue。此外该文件还包含 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时会自动带上otelcollectorOTLP 接收端映射4317/4318等端口与本地clickhouseclickhouse/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 场景天然可见Dashboardhttp://localhost:3000。原文档给出的 CORS 行为与源码吻合只有当API_DOMAIN含localhost或127.0.0.1时才会注入 CORS 中间件并放行http://localhost:3000来源见 app/api/agentops/app.py。因此必须保证APP_URLhttp://localhost:3000否则 Dashboard 跨域请求会被拒绝。4. Compose 故障排查继承自原文档CORSAPP_URL必须为http://localhost:3000API 才允许 Dashboard 来源SupabaseAPI 侧需要 service role keyanon key 只够 Dashboard 前端用ClickHouse云实例用8443端口 CLICKHOUSE_SECUREtrue并确保你的 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_URLSettings → API → Project URLAnon key对应NEXT_PUBLIC_SUPABASE_ANON_KEYSettings → API → anon publicService role key对应SUPABASE_SERVICE_ROLE_KEYAPI 侧记为SUPABASE_KEYSettings → API → service_role secretProject ID对应SUPABASE_PROJECT_ID即 Project URL 的子域或 Settings → General → Reference IDAPI 直连数据库需要额外一组变量SUPABASE_HOST、SUPABASE_PORT、SUPABASE_DATABASE、SUPABASE_USER、SUPABASE_PASSWORD。在 Settings → Database → Connection info 中获取使用 pooled/primary 主机与5432端口用户通常是postgres.project_id与 app/.env.example 中SUPABASE_USERpostgres.YOUR_PROJECT_ID的写法一致。本地 Supabase 方案Supabase CLIsupabase initsupabase start后用SUPABASE_URLhttp://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_HOSTyour-service-name.region.clickhouse.cloud、CLICKHOUSE_PORT8443、CLICKHOUSE_SECUREtrue认证CLICKHOUSE_USER默认default或自建用户、CLICKHOUSE_PASSWORD取自连接串数据库CLICKHOUSE_DATABASEotel_2本仓库默认库名可按需调整网络把本机 IP 加入 ClickHouse Cloud 的 IP 白名单。端到端本地数据链路验证OTel Collector 自托管 ClickHouseapp/README.md 开头一段「Restart local stack and verify」描述的是完整本地链路的重启与验证流程配合「Local ClickHouse (self-hosted)」一节构成不依赖云服务的离线验证方案。1. 本地 ClickHouse 环境配置在.env中设置CLICKHOUSE_HOST127.0.0.1 CLICKHOUSE_PORT8123 CLICKHOUSE_USERdefault CLICKHOUSE_PASSWORDpassword CLICKHOUSE_DATABASEotel_2 CLICKHOUSE_SECUREfalse CLICKHOUSE_ENDPOINThttp://clickhouse:8123 CLICKHOUSE_USERNAMEdefault注意CLICKHOUSE_ENDPOINT是容器间地址从 app/opentelemetry-collector/compose.yaml 看collector 容器默认以http://clickhouse:8123访问 ClickHouse 容器trace 写入TRACES_TABLE_NAME默认otel_traces表CLICKHOUSE_TTL默认12hJWT_SECRET复用JWT_SECRET_KEY。2. 初始化 schema启动服务自动包含 otelcollector 与本地 ClickHousedocker 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/?queryCREATE%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 --since90s api docker compose -f compose.yaml -f opentelemetry-collector/compose.yaml logs --since90s dashboard docker compose -f compose.yaml -f opentelemetry-collector/compose.yaml logs --since90s otelcollector docker compose -f compose.yaml -f opentelemetry-collector/compose.yaml logs --since90s clickhouse4. 产生一条 trace 并双向验证用 AgentOps SDK 的 OpenAI 同步示例examples/openai/openai_example_sync.py通过本地 OTLP 端点上报AGENTOPS_API_KEYkey \ AGENTOPS_API_ENDPOINThttp://localhost:8000 \ AGENTOPS_APP_URLhttp://localhost:3000 \ AGENTOPS_EXPORTER_ENDPOINThttp://localhost:4318/v1/traces \ OPENAI_API_KEYopenai_key \ python examples/openai/openai_example_sync.py其中AGENTOPS_EXPORTER_ENDPOINT指向 collector 映射到宿主机的4318OTLP/HTTP 端口见 app/opentelemetry-collector/compose.yaml。随后在两端交叉验证同一TRACE_IDClickHouse 侧curl -s -u default:password http://localhost:8123/?querySELECT%20count()%20FROM%20otel_2.otel_traces%20WHERE%20TraceId%20%20TRACE_IDDashboard 侧http://localhost:3000/traces?trace_idTRACE_ID登录入口为http://localhost:3000/signin。这条链路即SDK → OTLP(4318) → otelcollector → ClickHouse(otel_2.otel_traces) → API 查询 → Dashboard 展示。原生本地开发Beginner Quickstart若不用容器可直接以原生进程运行 API 与 Dashboard。1. 准备环境文件APIapp/api/.envDashboardapp/dashboard/.env.local可选供 Docker Compose 使用app/.envAPI 最小环境变量app/api/.env# 核心 URL决定 CORS 与 docs 行为 PROTOCOLhttp API_DOMAINlocalhost:8000 APP_DOMAINlocalhost:3000 # 认证 JWT_SECRET_KEYyour-long-random-secret # Supabase 连接 SUPABASE_URLhttps://your-project-id.supabase.co SUPABASE_KEYyour-service-role-key SUPABASE_HOSTyour-supabase-pg-host SUPABASE_PORT5432 SUPABASE_DATABASEpostgres SUPABASE_USERpostgres.your-project-id SUPABASE_PASSWORDyour-supabase-db-password # ClickHouse 连接 CLICKHOUSE_HOSTyour-clickhouse-host CLICKHOUSE_PORT8443 CLICKHOUSE_USERdefault CLICKHOUSE_PASSWORDyour-clickhouse-password CLICKHOUSE_DATABASEotel_2 # 可选 SQLALCHEMY_LOG_LEVELWARNING REDIS_HOSTlocalhost REDIS_PORT6379 STRIPE_SECRET_KEYsk_test_... STRIPE_SUBSCRIPTION_PRICE_IDprice_... STRIPE_TOKEN_PRICE_IDprice_... STRIPE_SPAN_PRICE_IDprice_...要点API 后端操作需要 Supabase service role keyanon key 不够APP_DOMAIN/API_DOMAIN/PROTOCOL需解析为http://localhost:3000与http://localhost:8000才能通过 CORS。Dashboard 最小环境变量app/dashboard/.env.localNEXT_PUBLIC_SUPABASE_URLhttps://your-project-id.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEYyour-anon-key SUPABASE_SERVICE_ROLE_KEYyour-service-role-key SUPABASE_PROJECT_IDyour-project-id NEXT_PUBLIC_API_URLhttp://localhost:8000 NEXT_PUBLIC_APP_URLhttp://localhost:3000 NEXT_PUBLIC_SITE_URLhttp://localhost:3000 # 可选 NEXT_PUBLIC_ENVIRONMENT_TYPEdevelopment NEXT_PUBLIC_PLAYGROUNDtrue NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYpk_test_... NEXT_PUBLIC_POSTHOG_KEY NEXT_PUBLIC_SENTRY_DSN2. 安装依赖仓库根目录即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. 原生启动终端 AAPIcd 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。终端 BDashboardcd app/dashboard bun run dev然后打开http://localhost:3000。4. 验证清单APIhttp://localhost:8000/redoc可加载且无 5xxDashboardhttp://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_HOST127.0.0.1 POSTGRES_PORT54322 POSTGRES_USERpostgres POSTGRES_PASSWORDpostgres POSTGRES_DATABASEpostgres SUPABASE_HOST127.0.0.1 SUPABASE_PORT54322 SUPABASE_USERpostgres SUPABASE_PASSWORDpostgres SUPABASE_DATABASEpostgresjust 命令与开发工作流仓库根目录提供 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/TSESLintapp/.eslintrc.json Prettierapp/prettier.config.js位于仓库根子项目如dashboard/可用自己的.eslintrc.json继承并覆盖PythonRuffapp/ruff.tomlPre-commitHusky 在 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生产环境变量示例PROTOCOLhttps API_DOMAINapi.yourdomain.com APP_DOMAINyourdomain.com DEBUGfalse LOGGING_LEVELWARNING NEXT_PUBLIC_ENVIRONMENT_TYPEproduction NEXT_PUBLIC_PLAYGROUNDfalse部署平台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_HOST127.0.0.1 SUPABASE_PORT54322 # 注意与 Supabase API 端口 54321 不同 SUPABASE_USERpostgres SUPABASE_PASSWORDpostgres SUPABASE_DATABASEpostgresSupabase 种子数据问题supabase start时出现重复键或缺表错误可能是 app/supabase/seed.sql 存在冲突可临时注释有问题的 insert或检查 app/supabase/migrations 中的迁移是否缺失。其他继承自原文档401/403API 校验 Supabase JWT需先经 Dashboard 登录使请求携带Authorization: Bearer tokenClickHouse 连接超时/拒绝确认 8443 端口、凭据与 Cloud IP 白名单Redis 未安装开发环境可选启用限流或会话缓存时才需要端口占用确保 3000/8000 未被占用或调整映射端口并同步修改相关 env URL。贡献流程与代码规范继承自原文档 Procedue 一节特性分支工作流建分支 → 完成特性 → 提交 PR附简要说明→ 至少一人评审后合并进mainPR 规则不使用 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 的二次开发。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考