Tracely-ai

把生产事故变成回归测试，合并前自动拦截 AI 故障

Tracely-ai 是一个面向 AI 代理（agent）的 CI/CD 原生可观测与评测工具，旨在解决 AI 应用在生产环境中出现故障后难以复现和回归测试的问题。它自动检测生产环境中的 agent 失败案例，进行聚类分析，并将这些失败冻结为封闭的回归测试用例，然后在 CI 流程中零成本重放，从而在代码合并前阻断问题。核心能力包括：自动故障检测与聚类、将生产事故转化为可复现的测试用例、与 CI/CD 流水线深度集成、基于 LLM-as-judge 的评测机制、以及使用 ClickHouse 存储可观测数据。项目采用 Python 编写，技术栈覆盖 agent 可观测性、LLM 评估和持续集成，旨在降低 AI 应用迭代中的回归风险，提升生产稳定性。

开源 freemium 评测安全

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1501

维护状态活跃

是否开源是

定价模式 freemium

项目预览

项目数据

分类评测安全

开发团队Jwuthri

所属国家

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

GitHubhttps://github.com/Jwuthri/Tracely-ai

定价模式freemium

价格说明开源自托管免费，云端服务可能付费，具体定价待确认

访问状态

是否开源是

开源协议MIT

主要语言Python

技术栈/模型agent,agent-observability,ai-agents,ci-cd,clickhouse,evals,evaluation,llm,llm-as-judge,llm-evaluation,llm-observability,llm-ops,llmops,mcp,monitoring,opentelemetry,python,self-hosted,tracing

GitHub 星标★ 1501

30天Star增速

HF 下载量

上线时间2026-06-03 00:00:00

代码更新—

仓库体积—

本站数据更新—

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-24

浏览次数13

Star 增长趋势

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

正在加载星标数据…

技术标签

使用教程

—

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

环境要求

Docker 与 Docker Compose（运行整套服务的前提）
本地开发额外需要 uv（Python 包管理器）
本地开发额外需要 Node 20+ 与 pnpm
可访问的 GitHub 网络环境以克隆仓库

安装与启动步骤

1克隆仓库

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

用 demo profile 拉起 ClickHouse、Postgres、Redis、MinIO 及 API/worker/前端，并自动执行迁移与种子数据。
```
docker compose --profile demo up -d --build --wait
```
3打开控制台

启动完成后访问 Web 界面，应能看到 traces、clusters、cases 和 gates 的示例数据，而不是空壳页面。
```
open http://localhost:3001
```
4停止或清空数据

停止所有容器；若想连数据卷一起清空，加上 -v 参数重新执行。
```
docker compose down
```
5改代码后重启服务

backend/worker/frontend 以源码卷挂载，多数改动只需重启对应服务；Celery worker 不支持热重载。
```
docker compose restart backend
```
6部署到云端(可选)

也可用 Railway 一键部署整套栈；提示时需设置 SESSION_SECRET 与 SECRETS_ENCRYPTION_KEY 两个密钥。
```
openssl rand -hex 32
```

关键配置

配置项	必填	说明	示例
`TRACELY_WEB_PORT`	否	前端 Web 服务对外暴露的宿主端口	`3001`
`TRACELY_BACKEND_PORT`	否	后端 API 对外暴露的宿主端口	`8000`
`SESSION_SECRET`	是	云端部署时的会话签名密钥，需自行生成	`openssl rand -hex 32 生成的值`
`SECRETS_ENCRYPTION_KEY`	是	云端部署时的密钥加密用密钥，需自行生成	`openssl rand -hex 32 生成的值`

如何确认成功

浏览器打开 http://localhost:3001，能看到已填充 traces、clusters、cases、gates 的工作区即启动成功。

常见问题

Q：默认的接入密钥是什么？

A：demo 种子会创建默认项目与 ingest key，值为 tracely_dev_key，可直接用它向本地实例发送 OTLP 追踪数据。

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

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

Q：改了代码需要重新 build 吗？

A：backend、worker、frontend 使用源码卷挂载，多数改动只需 docker compose restart ；但 Celery worker 不会热重载。

Q：怎么把演示数据全部清掉？

A：执行 docker compose down -v，-v 会连同数据卷一起删除，下次启动是干净环境。

Q：本地不用 Docker 开发需要什么？

A：除 Docker 外还需 uv，以及 Node 20+ 与 pnpm，README 中未给出更多本地裸机启动命令。

注意事项

demo profile 会自动执行迁移、种子默认项目与 ingest key，并填充 traces、clusters、cases、gates 示例数据。
生产/自托管部署参考 deploy/railway/README.md 与 .env.railway.example，硬化和备份流程见 guides/DEPLOY.md。
部署到 Railway 时需在提示处填入用 openssl rand -hex 32 生成的 SESSION_SECRET 和 SECRETS_ENCRYPTION_KEY。
首次执行 docker compose --profile demo up -d --build 需要构建镜像，耗时可能长于 15 分钟。

核心亮点

自动将生产失败案例聚类并转化为封闭测试，无需手动构造用例
与 CI/CD 深度集成，在 PR 阶段即可阻断回归，成本为零
基于 ClickHouse 存储，支持大规模 agent 行为追踪和回放

不足之处

文档/社区待观察
依赖特定 CI/CD 环境，集成配置可能有一定学习成本

适用场景

AI agent 应用上线后，快速定位并复现生产环境偶发故障
在 CI 流程中自动添加回归测试，防止旧问题随代码更新复发
团队需要统一管理 agent 行为日志和评测结果的场景

替代项目

LangSmith、Arize Phoenix、Helicone

项目介绍

Tracely-ai 是评测安全领域的开源项目，由 Jwuthri 开发，是 2026 年新上线的项目。

在全站 13,916 个收录项目中，它的 GitHub 星标数（1,501）位列前 30%，在评测安全分类中处于中上游。

近 44 天，它的 GitHub 星标从 1,039 增加到 1,500，净增 461。

项目目前处于活跃维护状态，最近一次代码更新于 2026-10-06。开源自托管免费，云端服务可能付费，具体定价。从国内网络环境看，可直接访问。

它主要面向的使用场景是：AIagent应用上线后，快速定位并复现生产环境偶发故障。同类可对比的替代方案包括 LangSmith、Arize Phoenix、Helicone。

上一篇：NiceEval

下一篇：Doberman-Core