Penguin Statistics

Penguin Statistics - V3 后端

使用 Go 构建的重新设计版 Penguin Statistics v3 后端。

使用数据

掉落数据是公开的：

• REST API 位于 https://penguin-stats.io/PenguinStats/api/v2/：请参阅 开发者文档和 OpenAPI（Swagger 2.0）规范。

• 面向 AI 助手（Claude、ChatGPT、Cursor、VS Code、Cherry Studio 等）的 MCP 服务 位于 https://mcp.penguin-stats.io/mcp：Streamable HTTP，无需身份验证，只读。在 Claude Code 中：

  claude mcp add --transport http --scope user penguin-stats https://mcp.penguin-stats.io/mcp
  

  其他所有应用的配置步骤（英文和中文）请见 https://mcp.penguin-stats.io/。

• 面向编码 Agent 的 插件和技能：MCP 服务附带一项技能，用于读取、引用和查询数据： https://github.com/penguin-statistics/agent-skills

掉落数据采用 CC BY-NC 4.0 许可：仅限非商业用途，并须注明出处。请注明：Data: Penguin Statistics (penguin-stats.io), CC BY-NC 4.0。本仓库的代码采用 MIT 许可。

架构

这个 Go 项目主要使用：

• gofiber/fiber
• uber-go/fx
• uptrace/bun

本项目主要遵循 RESTful API 设计。

运维

报告死信流中的任务

当报告任务永远无法处理（它不是任务，或其中某个阶段不存在），或在 30 次投递中每次都失败时，报告工作器会将其从 penguin-reports 流移至 penguin-reports-dead（主题为 REPORT_DEAD.*）。这些投递的重试间隔总计约 97 分钟。每次移动都会以错误级别记录日志（reportwkr.malformed、reportwkr.parked 或 reportwkr.dead）。副本会保留发布时的负载，并带有以下标头：

• Penguin-Original-Subject：发布时使用的主题，例如 REPORT.SINGLE
• Penguin-Original-Sequence：该消息在 penguin-reports 中的序列号
• Penguin-Deliveries：消息移动时的投递次数
• Penguin-Last-Error：导致消息移动的错误

如果任务的负载接近最大大小，无法容纳这些标头，则移动时不会附带标头；它在 REPORT_DEAD.* 下的主题会标明原始主题；移动操作会记录为 reportwkr.dead.bare，并包含序列号和错误信息。

流中的消息不会过期。使用 nats CLI，在问题原因修复后：

# list the tasks, with their headers
nats stream view penguin-reports-dead
# show one, by its sequence in penguin-reports-dead
nats stream get penguin-reports-dead 42
# replay it under its original subject: the worker processes it as a new task
nats stream get penguin-reports-dead 42 --json | jq -r .data | base64 -d \
  | nats pub REPORT.SINGLE --force-stdin
# remove it once replayed
nats stream rmm penguin-reports-dead 42 -f

如果任务是在每次投递均失败后移动的，其中一次投递可能已将其存储，但提交结果未知（例如提交期间连接断开）；重放前，请在 drop_reports 中检查对应的账户和时间。

基准测试

报告消费者 CPU

internal/workers/reportwkr/consumerbench_test.go（构建标签 consumerbench）通过实际代码路径运行报告消费者：每个任务都会发布到独立的 JetStream 流中，随后被获取并交给 Worker.ingestPreprocess（BenchmarkConsumer/ingest），该函数会将任务存入 PostgreSQL，并在 Redis 中设置其召回键，同时使用与生产环境相同的日志记录和跟踪配置。BenchmarkConsumer/process 单独运行 Worker.process。除了耗时和内存分配，它还会报告每个任务的进程 CPU 时间（cpu-ns/op，通过 getrusage 获取用户态和系统态时间；共享机器对它的影响远小于对墙钟时间的影响），以及等待 PostgreSQL（pg-wait-ns/op、pg-wait-%）和 Redis 的时间。

这些任务（internal/workers/reportwkr/testdata/consumerbench/tasks.jsonl.gz）按照报告处理器发布它们时的格式编码，来源于近期生产报告中的阶段、服务器、时间、来源、版本和丢弃模式，并使用合成账号、IP 和任务 ID。

它需要一个临时数据库、Redis 和启用了 JetStream 的 NATS。临时数据库包含生产环境恢复副本（penguinprod，仅供读取）的架构和参考表，以及合成账号；基准测试会清空其中的 drop_reports 和 drop_report_extras：

scripts/consumerbench/setup-db.sh   # creates penguin_cpubench and the role cpubench on 127.0.0.1:5434
# regenerate the tasks, if needed: CONSUMERBENCH_TASKS, CONSUMERBENCH_BATCH_PERMILLE, CONSUMERBENCH_SEED
CONSUMERBENCH_GENERATE=1 go test -tags consumerbench -run TestConsumerBenchGenerate ./internal/workers/reportwkr/

默认配置指向 127.0.0.1:5434 上的 penguin_cpubench、127.0.0.1:16379 上 Redis 的 DB 14，以及 127.0.0.1:4222 上的 NATS（CONSUMERBENCH_POSTGRES_DSN、CONSUMERBENCH_REDIS_URL、CONSUMERBENCH_NATS_URL）。然后：

# one run
go test -tags consumerbench -run '^$' -bench BenchmarkConsumer -benchtime 2000x ./internal/workers/reportwkr/
# interleaved runs of variants, compared with benchstat: logging to a counting io.Discard (prod), to /dev/null
# (devnull), disabled (logoff); tracing as in production at 10% (prod), off (traceoff), at 100% (trace1); both off (off)
COUNT=10 scripts/consumerbench/run.sh bench prod logoff traceoff off devnull trace1
# CPU and allocation profiles of the ingestion, the top functions and the share of each part of the consumer
scripts/consumerbench/run.sh profile prod

输出写入 $OUT（默认为新建的临时目录）。每次运行都会将负载平均值和集群上其他会话正在执行的查询记录到 $OUT/runs.log。PostgreSQL 连接通过回环接口运行；在此情况下，写入系统调用也会承担接收端的 TCP 工作，因此与远程服务相比，系统调用占比更高。

维护者

本项目主要由以下贡献者维护（按字母顺序排列）：

• AlvISsReimu
• GalvinGao

Penguin Statistics 项目所有活跃贡献者的完整名单，请参阅网站上的 团队成员页面。

贡献者

本项目由以下贡献者共同打造。欢迎随时贡献！

许可证