快速上手

这一页带你 5 分钟内从零跑通 —— 起服务、接入 SDK、看到第一条事件。

1. 起一个实例

最快的方式是官方 Docker 镜像。镜像基于 scratch，多架构（amd64 + arm64），约 13 MB。

docker run -d \
  --name kestrel \
  -p 8080:8080 \
  -v kestrel-data:/data \
  ghcr.io/wearzdk/kestrel:latest

首次启动会生成一个临时管理员密码，写到容器日志和 /data/.admin_password 里。docker logs kestrel 拿一下，或者用 -e KESTREL_ADMIN_PASSWORD=... 自己指定。

不想用 Docker 的话，每次发布都附带 Linux / macOS / Windows 的静态二进制 —— 一个可执行文件，没有运行时依赖。

2. 登录 + 创建项目

打开 http://localhost:8080，用第 1 步的密码登录。新建一个项目（名字随便起），从一次性 modal 里复制 ingest token。马上保存 —— Kestrel 只存哈希，token 之后不会再显示。如果丢了，去 Settings 页轮换即可。

3. 发送第一条事件

挑一个匹配你技术栈的 SDK：

JavaScript

npm install kestrel-sdk

Python

pip install kestrel-sdk

Go

go get github.com/wearzdk/kestrel/sdks/go@latest

然后在进程入口处接入：

JavaScript

import { init } from 'kestrel-sdk'

init({
  endpoint: 'http://localhost:8080/api/v1/ingest',
  token: 'YOUR_PROJECT_TOKEN',
})
// `window.error` 和 `unhandledrejection` 现在会被自动捕获。

Python

import kestrel_sdk
kestrel_sdk.init(
    endpoint="http://localhost:8080/api/v1/ingest",
    token="YOUR_PROJECT_TOKEN",
)
# sys.excepthook 已挂好。

Go

import kestrel "github.com/wearzdk/kestrel/sdks/go"

if err := kestrel.Init(
    "http://localhost:8080",
    "YOUR_PROJECT_TOKEN",
); err != nil {
    panic(err)
}
defer kestrel.Recover(ctx) // 捕获 panic

在你的代码里触发一个异常，一秒内 Kestrel web UI 就能看到一条新 issue。

4. 把钥匙交给 AI

Kestrel 的核心卖点是内置的 MCP server。把它加到 Claude Code（或任何兼容 MCP 的客户端）的配置里，agent 就能自己读错误。HTTP 传输对 Docker 和二进制安装都通用：

// ~/.claude/mcp.json
{
  "mcpServers": {
    "kestrel": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer YOUR_PROJECT_TOKEN" }
    }
  }
}

之后 agent 就能调用 list_errors、get_error、mark_resolved、mark_ignored、get_trend —— 详见 MCP 概览（也包含本地 stdio 接入方式）。

接下来

• 自部署 —— Docker 配方、配置项、反代示例、TLS。
• 备份 —— kestrel backup 与恢复流程。
• 指标与健康检查 —— /metrics、/healthz、/healthz/ready。
• SDK 参考 —— 每个 SDK 实际捕获什么、怎么手动上报。