内容
# TrapFall
自托管错误捕获引擎 — Rust + SvelteKit 5. Sentry SDK 兼容（直接替换 DSN）。
比 Sentry 更轻量级的替代方案。从任何 Sentry SDK 捕获错误，在实时仪表盘中查看，并获取 webhook 警报。单个二进制文件，SQLite 或 Postgres，**6MB Docker 镜像**。
## 功能
- **Sentry 兼容性摄入** — 直接替换 DSN，与任何 Sentry SDK（Rust、Python、JS、Flutter 等）兼容
- **多项目支持** — Web、移动、API — 每个项目都有自己的 DSN 和隔离的错误
- **项目管理** — 存档、取消存档、重命名、旋转 DSN、永久删除
- **实时仪表盘** — SvelteKit 5 + Tailwind v4 + shadcn-svelte
- **问题搜索 + 过滤** — 按标题/罪魁祸首搜索，按状态和级别过滤，分页
- **WebSocket 更新** — 实时问题动态，无需刷新
- **Blake3 指纹识别** — 自动错误分组和去重
- **警报规则** — 按项目条件触发的 webhook，带有冷却时间
- **全文搜索** — LIKE + sqlite_trigram 子字符串搜索
- **OpenAPI 文档** — `/api/docs` 处的 Swagger UI
- **MCP 服务器** — 通过 stdio JSON-RPC 的 12 个 AI 代理工具
- **小型 Docker 镜像** — 5.75MB（scratch + MUSL 静态二进制文件 + rustls）
- **多后端数据库** — SQLite（默认，零配置）或 Postgres（内置，无需额外标志）
- **一键部署** — 带有持久卷的 Docker Compose
## 快速开始
### Docker（推荐）
```bash
docker pull ghcr.io/codecoradev/trapfall:latest
docker run -p 9090:9090 -v trapfall-data:/data ghcr.io/codecoradev/trapfall:latest
```
或使用 Docker Compose：
```bash
# 克隆并运行
git clone https://github.com/codecoradev/trapfall.git
cd trapfall
docker compose up -d
# 打开 http://localhost:9090 → 设置向导
```
### 从二进制文件
从 [GitHub Releases](https://github.com/codecoradev/trapfall/releases/latest) 下载：
```bash
# Linux (x86_64)
tar xzf trapfall-x86_64-unknown-linux-gnu-v0.0.5.tar.gz
./trapfall --db trapfall.db serve --listen 0.0.0.0:9090
```
### 从源码
```bash
# 构建前端
cd web && npm ci && npm run build && cd ..
# 构建 + 运行
cargo run --release -p trapfalld -- --db trapfall.db serve --listen 0.0.0.0:9090
```
## 设置向导
1. 打开 `http://localhost:9090` → 首次运行显示设置向导
2. 创建管理员帐户（电子邮件、姓名、密码）
3. 默认项目自动创建，带有 DSN
4. 复制 DSN → 与您的应用程序集成
## 多项目设置
为每个应用程序/服务创建单独的项目：
1. 仪表盘 → **项目** → **"+ 添加项目"**
2. 命名（例如，“Web 应用程序”，“移动应用程序”，“后端 API”）
3. 每个项目都获得一个唯一的 DSN
4. 将每个 SDK 指向其自己的 DSN — 错误按项目隔离
### 管理项目
- **重命名**：点击 ⋮ 菜单 → 重命名
- **旋转 DSN**：点击 ⋮ 菜单 → 旋转 DSN（旧密钥立即吊销）
- **存档**：点击 ⋮ 菜单 → 存档（从主视图隐藏，保留数据）
- **删除**：首先存档，然后永久删除已存档的选项卡
- **取消存档**：从已存档的选项卡恢复已存档的项目
## SDK 集成
与任何 Sentry SDK 兼容 — 只需将 DSN 替换为指向您的 TrapFall 服务器：
### Rust
```rust
sentry::init(("https://<key>@your-server:9090/<project_id>", sentry::ClientOptions::default()));
```
### Python
```python
import sentry_sdk
sentry_sdk.init(dsn="https://<key>@your-server:9090/<project_id>")
```
### JavaScript / Node.js
```js
Sentry.init({ dsn: "https://<key>@your-server:9090/<project_id>" });
```
### Flutter / Dart
```dart
await SentryFlutter.init((options) => {
options.dsn = "https://<key>@your-server:9090/<project_id>",
});
```
## CLI 命令
```bash
trapfall serve # 启动 HTTP 服务器（默认）
trapfall project add "My App" # 创建项目（CLI）
trapfall project add "Mobile" mobile # 创建项目，自定义 slug
trapfall project list # 列出项目
trapfall project rotate-dsn app # 旋转 DSN 密钥
trapfall healthcheck # Docker 健康检查
trapfall mcp # 启动 MCP 服务器（stdio）
```
## 配置
| 环境变量 | 默认值 | 描述 |
| --- | --- | --- |
| `TRAPFALL_DATABASE_URL` | `sqlite:trapfall.db` | 数据库 URL（`sqlite:` 或 `postgres://`，回退到 `--db`） |
| `TRAPFALL_LISTEN` | `0.0.0.0:9090` | HTTP 监听地址（Docker 默认） |
| `TRAPFALL_SECURE_COOKIE` | `true` | 设置为 `false` 以进行 HTTP 本地开发 |
| `TRAPFALL_CORS_ORIGINS` | *（空 = 允许所有）* | 生产环境中用逗号分隔的来源 |
| `RUST_LOG` | `info` | 日志级别（`debug` 表示详细） |
参见 [.env.example](.env.example) 以获取完整参考。
## API 端点
### 摄入（公开，DSN 密钥身份验证）
- `POST /api/{project_id}/envelope/` — Sentry SDK 信封
### 仪表盘（Cookie 身份验证）
- `POST /api/0/setup` — 首次运行设置向导
- `POST /api/0/auth/login` — 登录
- `POST /api/0/auth/logout` — 注销
- `GET /api/0/auth/me` — 当前用户
- `POST /api/0/auth/change-password` — 修改密码
- `GET /api/0/projects` — 列出项目
- `POST /api/0/projects` — 创建项目
- `GET /api/0/projects/{slug}` — 获取项目
- `PATCH /api/0/projects/{slug}` — 重命名项目
- `DELETE /api/0/projects/{slug}` — 删除项目（仅存档）
- `POST /api/0/projects/{slug}/archive` — 存档项目
- `DELETE /api/0/projects/{slug}/archive` — 取消存档项目
- `POST /api/0/projects/{slug}/rotate-dsn` — 旋转 DSN 密钥
- `GET /api/0/projects/{slug}/issues` — 列出问题（带有过滤器 + 分页）
- `GET /api/0/projects/{slug}/search?q=...` — 搜索问题
- `GET /api/0/issues/{id}` — 获取问题详情
- `POST /api/0/issues/{id}/status` — 设置问题状态（已解决/未解决/忽略）
- `GET /api/0/issues/{id}/events` — 列出事件
- `GET /api/0/ws` — WebSocket 实时更新
- `GET /api/0/projects/{slug}/rules` — 警报规则
- `POST /api/0/projects/{slug}/rules` — 创建警报规则
- `DELETE /api/0/rules/{id}` — 删除警报规则
- `POST /api/0/rules/{id}/toggle` — 启用/禁用规则
- `GET /api/docs` — Swagger UI
- `GET /api/docs/openapi.yaml` — OpenAPI 规范
### 系统
- `GET /health` — 健康检查
- `GET /metrics` — Prometheus 指标
## MCP 工具
通过 stdio JSON-RPC 2.0 为 AI 代理提供 12 种工具：
`list_issues`, `get_issue`, `get_event`, `set_status`, `search_issues`, `list_projects`, `get_project`, `get_project_stats`, `list_alert_rules`, `list_events`, `rotate_dsn`, `healthcheck`
## 技术栈
| 层 | 技术 |
| --- | --- |
| 后端 | Rust, Axum 0.8, SQLite + Postgres (sqlx), tokio |
| 前端 | SvelteKit 5, Tailwind v4, shadcn-svelte |
| TLS | rustls（纯 Rust，无 OpenSSL） |
| 指纹识别 | blake3 |
| 构建 | Cargo 工作区，npm，Docker 多阶段（scratch + MUSL） |
| CI | GitHub Actions（10 个检查，包括 Cora Review, Trivy, Cargo Audit） |
## 架构
```
HTTP → mpsc(256) → digest(batch=16) → broadcast(64) + webhook(64)
↓
SQLite (WAL, single-writer)
```
带有嵌入式 SPA 的单个二进制文件，通过 `rust-embed` 实现。单个写入器的 SQLite 以 WAL 模式运行，`synchronous=NORMAL`。Docker 镜像在 `scratch` 上构建，带有静态链接的 MUSL 二进制文件 — 无 OS 层，攻击面最小。
## 文档
[docs/](docs/) 处的完整文档（VitePress）：
- [快速入门](docs/guide/getting-started.md)
- [Docker 部署](docs/guide/docker.md)
- [多项目管理](docs/guide/multi-project.md)
- [SDK 集成](docs/guide/sdk-integration.md)
- [搜索和过滤](docs/guide/search.md)
- [警报规则](docs/guide/alerts.md)
- [API 参考](docs/guide/api.md)
- [配置](docs/guide/configuration.md)
- [安全](docs/guide/security.md)
- [MCP 服务器](docs/guide/mcp.md)
## 许可证
Apache-2.0
