自部署

Kestrel 是一个二进制；整个部署面就是一个进程、一个 SQLite 文件、一个 sourcemap 目录。没有集群可建、没有依赖要装、没有消息队列要部署。

配置

配置按以下三个来源读取，优先级从高到低：

1. CLI flag —— --addr、--db、--retention-days 等。
2. 环境变量 —— KESTREL_ADDR、KESTREL_DB、KESTREL_RETENTION_DAYS、…
3. kestrel.toml —— 完整 schema 见 kestrel.example.toml。

没指定的项走内置默认值。TOML 里出现未知 key 会直接拒绝，避免拼写错误悄悄丢配置。

配置项	TOML	环境变量	Flag	默认值
HTTP 监听地址	addr	KESTREL_ADDR	--addr	:8080
SQLite 路径	db	KESTREL_DB	--db	data/kestrel.db
Sourcemap 目录	sourcemaps	KESTREL_SOURCEMAPS	--sourcemaps	data/sourcemaps
数据目录	data	KESTREL_DATA	--data	dirname(db)
保留天数	retention.days	KESTREL_RETENTION_DAYS	--retention-days	0（永远保留）
指标 token	metrics.token	KESTREL_METRICS_TOKEN	--metrics-token	（空 → 关闭）
管理员密码	—	KESTREL_ADMIN_PASSWORD	—	自动生成

Docker

docker run -d \
  --name kestrel \
  --restart unless-stopped \
  -p 8080:8080 \
  -v kestrel-data:/data \
  -e KESTREL_ADMIN_PASSWORD=replace-me-with-a-real-password \
  -e KESTREL_RETENTION_DAYS=90 \
  ghcr.io/wearzdk/kestrel:latest

镜像暴露 8080，所有数据都写在 /data（DB + sourcemap + 管理员密码文件 + session 密钥）。挂一个命名 volume 上去，容器本身就是无状态的。

Docker Hub 镜像：wearzdk/kestrel:latest（如果维护者已配置同步）。

反向代理 + TLS

Kestrel 自身不做 TLS 终端 —— 放在你已经信任的反向代理后面。Ingest 路径需要从你应用所在的网络可达；管理 UI 通常只需要从你自己的网络可达。

Caddy

kestrel.example.com {
    reverse_proxy localhost:8080
}

Nginx

server {
    listen 443 ssl http2;
    server_name kestrel.example.com;

    ssl_certificate     /etc/letsencrypt/live/kestrel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/kestrel.example.com/privkey.pem;

    # SDK envelope <= 256 KB，这里设 1m 留出余量。
    client_max_body_size 1m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Traefik (docker labels)

services:
  kestrel:
    image: ghcr.io/wearzdk/kestrel:latest
    volumes:
      - kestrel-data:/data
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.kestrel.rule=Host(`kestrel.example.com`)"
      - "traefik.http.routers.kestrel.entrypoints=websecure"
      - "traefik.http.routers.kestrel.tls.certresolver=letsencrypt"
      - "traefik.http.services.kestrel.loadbalancer.server.port=8080"

静态二进制

不想用 Docker 的话，每次发布都在 GitHub Releases 提供静态二进制。下载对应 OS / arch 的归档，解压后跑：

./kestrel serve --addr :8080 --db /var/lib/kestrel/k.db

需要开机自启就用 systemd 包一下；二进制本身正确处理 SIGINT / SIGTERM。

鉴权模型

Kestrel 内置两种认证：

• 管理员密码 —— 守 web UI 和所有 /api/v1/{projects,issues,events} 读写。通过 KESTREL_ADMIN_PASSWORD 设置；未设置时首次启动生成一个 24 字符的随机密码，写入 /<data>/.admin_password 并打到日志。
• 项目 token —— 守 SDK ingest、sourcemap 上传和 MCP。以 sha256 hash 存储；明文只在 create / rotate 时一次性返回。轮换会立刻让旧 token 失效。

没有第三类。匿名读取不是一个特性 —— 每条读取路径都需要管理员 cookie。