使用Trapfall收集个人项目错误
内容提要
作者为个人微信小程序寻找轻量错误监控方案，因Sentry组件多、资源占用高，改用Rust单二进制加SQLite的TrapFall。文中介绍FastAPI通过sentry-sdk接入并上报422与5xx错误、源码编译与Systemd部署、Caddy限制访问、前端配置DSN、触发验证，以及用中间Rust服务把Webhook转发到飞书或钉钉告警；也提到rules接口有删改bug，需直接改数据库。
延伸解读
轻量错误监控的取舍
作者因Sentry组件多、资源占用高，转向Rust单二进制加SQLite的TrapFall。这种方案适合个人项目或低流量场景，部署简单、资源消耗低，但功能与生态不如Sentry完善。选择时需权衡：若需要完整错误追踪、性能监控和团队协作，Sentry仍是更成熟的选择；若追求轻量和自主可控，TrapFall这类工具值得考虑。
422错误的捕获要点
FastAPI的422错误由内置异常处理器在路由函数执行前抛出，普通日志难以获取原始请求体。通过sentry-sdk集成时，需在Starlette和FastAPI集成中显式设置failed_request_status_codes包含422，才能上报校验失败详情。这提醒开发者：默认配置可能遗漏客户端错误，需根据业务需求调整上报状态码范围。
部署与访问控制实践
作者采用源码编译后传输二进制到服务器，用Systemd管理并限制内存和CPU，避免污染服务器环境。前端面板通过Caddy反向代理并限制仅家庭IP访问，DSN使用内网地址减少外网暴露。这些做法体现了个人项目在资源有限下的安全与运维平衡，但需注意规则接口存在删改bug，需直接操作数据库，适合不频繁变更规则的场景。
告警链路的中间层设计
TrapFall默认支持Webhook，但国内常用飞书、钉钉等IM的Webhook格式不兼容，需中间服务转换。作者用Rust编写翻译服务，将TrapFall的告警封装为飞书机器人要求的格式，形成TrapFall→中间服务→IM的链路。这种设计虽增加一层，但灵活适配不同通知渠道，且中间服务可复用。需注意Webhook URL应指向中间服务而非直接填IM地址。
Q&A
为什么作者选择TrapFall而不是Sentry来监控个人项目的错误？
Sentry组件多（包括PostgreSQL、Redis、Kafka等），资源占用高（最低8G内存、4核CPU），运维成本高，不适合个人业余项目的低配服务器。TrapFall是Rust单二进制加SQLite，内存占用极低，部署简单，更适合个人项目。
如何将FastAPI项目接入TrapFall来捕获422和5xx错误？
使用sentry-sdk，在初始化时配置StarletteIntegration和FastApiIntegration，并将failed_request_status_codes设置为{422, *range(500, 599)}，即可上报422和5xx错误。DSN使用TrapFall提供的地址。
TrapFall的部署步骤是怎样的？
先编译前端（cd web && npm ci && npm run build），然后编译Rust后端（cargo run --release -p trapfalld -- --db trapfall.db serve --listen 0.0.0.0:9090），生成二进制文件后，通过Systemd管理，配置环境变量如TRAPFALL_LISTEN、TRAPFALL_DATABASE_URL等，并设置资源限制防止OOM。
如何限制TrapFall Web面板的访问以提高安全性？
使用Caddy反向代理，通过client_ip匹配只允许家庭公网IP访问，其他IP返回403。配置示例中使用了@allowed匹配器，handle块内反向代理到127.0.0.1:9090。
TrapFall如何配置告警到飞书或钉钉？
TrapFall支持Webhook，但需要中间服务转换格式。作者用Rust编写了一个翻译服务，接收TrapFall的Webhook，转换成飞书机器人要求的格式再发送。链路为：TrapFall → 中间Rust服务 → 飞书机器人。
TrapFall的rules接口有什么问题？如何解决？
rules接口有bug，经常删不掉条目，也无法修改。作者直接去SQLite数据库中删除或修改rules，因为rules不经常改动，勉强可接受。
