Tracely-ai

把线上 agent 失败轨迹变成 CI 回归测试，退化就拦 PR

开源 🏷️定价信息待确认 ⏳ 访问状态待核验评测安全 🍴 复刻 146 🐛 待处理 22 👀 关注 3

访问官网 ↗ GitHub ↗

GitHub 星标 ★ 1166

维护状态活跃

是否开源开源

定价模式 🏷️定价信息待确认

项目预览

项目数据

分类评测安全

开发团队jwuthri-cloud

官网地址https://tracely-ai.com

GitHubhttps://github.com/jwuthri-cloud/Tracely-ai

定价模式🏷️定价信息待确认

价格说明定价信息待确认，支持自托管

访问状态⏳ 访问状态待核验

是否开源是

开源协议MIT

主要语言Python

技术栈/模型agent-evaluation,ai-agents,ai-testing,ci-cd,clickhouse,developer-tools,llm-evaluation,llm-observability,llmops,mcp,observability,python,regression-testing,self-hosted,tracing

GitHub 星标★ 1166

上线时间2026-10-11 00:00:00

代码更新2026-10-19

仓库体积19.8 MB

本站数据更新2026-10-22

维护状态活跃

收录时间2026-10-22

浏览次数0

项目介绍

Tracely-ai 是一个面向 AI Agent 的 trace 原生 CI/CD 工具，把生产环境中的 agent 调用轨迹当作一等公民来治理。它解决的核心问题是：AI agent 上线后行为难以回归验证，失败案例散落在日志里无法沉淀为测试。项目能接入生产 trace，按质量维度打分，自动聚类失败模式，再把典型失败冻结成可回放的回归测试用例，最后在 CI 中运行这些用例，一旦 PR 导致 agent 行为退化就阻断合并。技术上基于 Python，使用 ClickHouse 存储和查询大规模 trace 数据，支持自托管部署，适合已有 agent 产品、需要建立质量门禁的团队。整体定位是把传统软件工程的 CI/CD 与回归测试理念迁移到 LLM agent 场景，让 agent 的迭代从凭感觉变成有数据、有门禁、可回放。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-10-22 · 当前星标 ★ 1166

技术标签

agent-evaluation ai-agents ai-testing ci-cd clickhouse

使用教程

难度：入门约 15 分钟部署方式：Docker 5 步

环境要求

已安装 Docker 与 Docker Compose
本机 3001（前端）和 8000（后端）端口空闲
首次启动需拉取镜像并构建，需可访问 GitHub 与 Docker 仓库的网络
如需本地二次开发，另需 uv 与 Node 20+ / pnpm

安装与启动步骤

1克隆仓库

把项目源码拉到本地并进入目录，后续所有命令都在该目录下执行。
```
git clone https://github.com/jwuthri-cloud/Tracely-ai && cd Tracely
```
2一键启动全栈

用 demo profile 拉起 ClickHouse、Postgres、Redis、MinIO 及 API、worker、前端，并自动跑迁移、写入演示数据。
```
docker compose --profile demo up -d --build --wait
```
3打开界面

浏览器访问前端端口，此时应已能看到预置的 traces、clusters、cases 和 gates，而不是空页面。
```
open http://localhost:3001
```
4停止或清空

普通停止用 down；加 -v 会连同数据卷一起删除，演示数据也会被清空。
```
docker compose down
docker compose down -v
```
5生成部署密钥

若走 Railway 等方式自行部署，需为会话与密钥加密各生成一个 32 字节十六进制串。
```
openssl rand -hex 32
```

关键配置

配置项	必填	说明	示例
`TRACELY_WEB_PORT`	否	前端映射到宿主机的端口，默认 3001	`3001`
`TRACELY_BACKEND_PORT`	否	后端 API 映射到宿主机的端口，默认 8000	`8000`
`SESSION_SECRET`	否	Railway 等自建部署时的会话签名密钥	`3f9a1c7d8b2e4f60a1c3d5e7f9012345678abcdef0123456789abcdef012`
`SECRETS_ENCRYPTION_KEY`	否	自建部署时用于加密存储敏感配置的密钥	`9b1d3f5a7c9e0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e`

如何确认成功

执行 up 后等 --wait 返回，浏览器打开 http://localhost:3001 能看到已填充的 traces、clusters、cases 和 gates 即成功。

常见问题

Q：启动后页面是空的怎么办？

A：确认使用了 --profile demo 并等待 --wait 完成；该模式会自动执行迁移、创建默认项目与 ingest key，并写入演示数据。

Q：端口 3001 或 8000 被占用怎么办？

A：通过环境变量 TRACELY_WEB_PORT 和 TRACELY_BACKEND_PORT 重映射宿主机端口后重新启动。

Q：改了源码为什么不生效？

A：backend、worker、frontend 走源码卷挂载，多数改动执行 docker compose restart 即可，但 Celery worker 不支持热重载，需要重启容器。

Q：如何彻底重置环境？

A：执行 docker compose down -v 删除数据卷，再重新用 demo profile 启动即可回到初始演示状态。

Q：默认的接入 key 是什么？

A：演示环境会 seed 默认项目和接入 key tracely_dev_key，仅用于本地演示，正式部署请自行更换。

注意事项

demo profile 会自动跑迁移、seed 默认项目与接入 key（tracely_dev_key）并填充演示数据，适合首次体验。
docker compose down -v 会删除数据卷，本地数据不可恢复，慎用。
自托管到 Railway / EKS 前请阅读 deploy/railway/README.md、deploy/eks/README.md 与 guides/DEPLOY.md 生产加固手册。
本地开发需要 uv 和 Node 20+ / pnpm，仅用 Docker 体验则不需要。