本页提纲
用自托管 GlitchTip 把错误告警唤醒 Holon
GlitchTip 是 Sentry 兼容的开源错误追踪(后端与前端仓库均为 MIT)。Holon 不需要专门的 GlitchTip 适配:项目告警的通用 webhook recipient 把错误摘要 POST 到 Holon 的 wake callback,agent 再用项目 API token 拉取 issue 和事件详情。
本文只覆盖这条路径。它不是 OIDC,也不替代应用自己的 SDK 接入。
实测版本与结论
2026-11-16 在隔离 Docker Compose 环境实测通过,不需要修改 Holon 运行时代码。
- GlitchTip 镜像
glitchtip/glitchtip:latest,digestsha256:c245745b4179667da3aebd73fb8d4f1fd918f7d68ba07d1fd73ea688933b6e01(镜像创建时间 2026-11-09)。投递请求的 User-Agent 为GlitchTip/7.0.0。 - Holon
0.59.0(33e2fcb4b)。 - 正向:
POST /api/{project_id}/store/?sentry_key=<DSN public key>摄入一条错误后,约一个告警周期内 webhook 到达,HolonPOST /api/callbacks/wake/<token>返回 200。RESTGET /api/0/issues/1/的title与 webhookattachments[0].title一致(本次均为ProbeError: glitchtip webhook verification)。GET /api/0/issues/1/events/的event_id与摄入响应一致。 - 反向:无 token 或无效 Bearer token 均为
401 {"detail":"Unauthorized"}。quantity高于窗口内事件数时不投递、也不唤醒。无效 recipient URL 不会打到 Holon。
前置条件
- 能跑 Docker 的机器。GlitchTip 只监听测试网或本机,不要把 8080 暴露到公网。
- Holon 已有一个
wake_hintcallback URL。该 URL 是 capability secret,只填进 GlitchTip 的 recipient,不要写入文档、计划、日志或截图。 - 若 callback 主机是内网、回环或 tailscale 的
100.64.0.0/10,必须打开GLITCHTIP_ALLOW_PRIVATE_IPS。GlitchTip 把 CGNAT 段视为不可投递地址;不打开时,创建 recipient 会被拒绝,或在发送时被 SSRF 防护丢掉。
第 1 步:部署
当前 latest 镜像是单进程架构:./bin/start.sh 同时提供 HTTP、消费任务队列,并在启动时初始化数据库。不要再按旧文档拆 migrate / worker 服务;镜像里的 bin/run-worker.sh 会直接拒绝运行。
队列变量以 VALKEY_URL 为准,REDIS_URL 只是兼容回退。redis:7 协议兼容,可直接使用。HTTP 端口由 PORT 控制,下面映射到本机 127.0.0.1:8080。
services:
postgres:
image: postgres:16-alpine
environment:
POSTGRES_DB: glitchtip
POSTGRES_USER: glitchtip
POSTGRES_PASSWORD: "<数据库密码>"
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U glitchtip -d glitchtip"]
interval: 5s
retries: 20
redis:
image: redis:7-alpine
web:
image: glitchtip/glitchtip:latest
ports:
- "127.0.0.1:8080:8080"
environment:
DATABASE_URL: "postgres://glitchtip:<数据库密码>@postgres:5432/glitchtip"
VALKEY_URL: "redis://redis:6379/0"
SECRET_KEY: "<随机长密钥>"
PORT: "8080"
GLITCHTIP_DOMAIN: "http://glitchtip.example.com:8080"
ENABLE_ORGANIZATION_CREATION: "true"
GLITCHTIP_ALLOW_PRIVATE_IPS: "true"
depends_on:
postgres:
condition: service_healthy
volumes:
pgdata:
GLITCHTIP_DOMAIN 必须是人和 agent 最终访问的地址。不设置时 webhook 里的 title_link 和 API 的 permalink 会落成默认的 http://localhost:8000/...,本次实测就是这个默认值。只在 callback 确实指向内网时才保留 GLITCHTIP_ALLOW_PRIVATE_IPS=true。
健康检查:GET /_health/ 返回 200。
第 2 步:建用户、项目和 API token
当前镜像 HEADLESS_CLIENTS 只有 browser,没有 app token 客户端。注册走 headless browser API,需要先取 CSRF cookie:
GET /_allauth/browser/v1/configPOST /_allauth/browser/v1/auth/signup,JSON 为{"email","password"},带头X-CSRFToken和Referer。默认未配置邮件时ACCOUNT_EMAIL_VERIFICATION为none,注册即登录并下发sessionid。- 用同一 session:
POST /api/0/organizations/{"name":"..."},POST /api/0/organizations/{org}/teams/{"slug":"..."},POST /api/0/teams/{org}/{team}/projects/{"name":"...","platform":"python"}。 POST /api/0/api-tokens/,session 鉴权,body 示例:{"label":"holon","scopes":["project:read","project:write","event:read","event:write","org:read"]}。响应里的token只出现这一次,当作 secret。GET /api/0/projects/{org}/{project}/keys/读取 DSN。public字段是 UUID;摄入时去掉连字符,作为sentry_key。
之后的查询用 Authorization: Bearer <token>,不再依赖 session。
第 3 步:配置告警 recipient
POST /api/0/projects/{org}/{project}/alerts/:
{
"name": "holon-error-alert",
"timespanMinutes": 60,
"quantity": 1,
"uptime": false,
"alertRecipients": [
{"recipientType": "webhook", "url": "http://<holon-host>:<port>/api/callbacks/wake/<token>"}
]
}
recipientType 必须是 webhook(通用 webhook)。quantity 是窗口内事件数阈值,timespanMinutes 是窗口。两者都要有值,否则这条告警不会被周期任务选中。默认检查间隔是 ALERT_NOTIFICATION_INTERVAL 秒,未设置时为 60。
第 4 步:摄入一条错误
curl -sS -X POST "http://127.0.0.1:8080/api/1/store/?sentry_key=<dsn-public-key>" -H 'Content-Type: application/json' -d '{"event_id":"<uuid>","message":"probe","level":"error","platform":"python","exception":{"values":[{"type":"ProbeError","value":"glitchtip webhook verification"}]}}'
成功返回 {"event_id":"..."}。issue 由队列异步生成,告警在下一个周期发出。
webhook 与 API 的对应关系
通用 webhook 不是原始 Sentry 事件,而是摘要:
{
"text": "GlitchTip Alert",
"attachments": [
{
"title": "ProbeError: glitchtip webhook verification",
"title_link": "http://glitchtip.example.com:8080/holon-test/issues/1",
"fields": [{"title": "Project", "value": "holon-probe", "short": true}]
}
]
}
Holon wake callback 是 wake_hint:HTTP 200 只表示 runtime 接受了唤醒,请求体不会被当成 operator 指令。agent 被唤醒后应自己查 API:
GET /api/0/issues/{id}/:title对齐 webhook 的attachments[].title,metadata.type/metadata.value对齐异常。GET /api/0/issues/{id}/events/:event_id对齐摄入响应,entries里有 exception 和 message。
webhook 里没有 event_id。要对单条事件,用 issue id 再查 events,不要假设 webhook 体就是完整事件。
反向用例与限制
- 不带
Authorization,或 Bearer token 无效:401 {"detail":"Unauthorized"}。 - 窗口内事件数小于
quantity:不投递、不唤醒。本次quantity=5且只有 1 条事件,下一个 60 秒周期没有第二次 webhook,也没有第二次 callback。 - 无效 recipient(关闭的端口)不会唤醒 Holon。但 GlitchTip 7 的
POST .../alerts/{id}/test/仍返回status: sent,连接失败在_post里被吞掉且不写日志。不能用测试接口的sent或实例日志判断投递成功;以 Holon access log 的 200 和本机捕获为准。 - 创建 recipient 时如果 URL 指向被拦截的地址,API 会直接拒绝。内网 callback 忘记开
GLITCHTIP_ALLOW_PRIVATE_IPS会卡在这一步,而不是运行后静默失败。
清理
docker compose down -v 会删除数据库、项目、token 和 recipient。不要把 callback URL 留在已停止但未删卷的库里。
未覆盖
- 邮件、Discord、Slack 等其他 recipient。
- 去抖之外的重复告警策略,以及 uptime monitor 告警。
- 浏览器 UI 建项目。本次全部走 HTTP API,没有使用 UI。
