NewAPI Report

NewAPI Report is a Go single-binary MVP for a private NewAPI site-owner alliance. It runs in two modes:

• server: central reporting API, local persistence, public stats dashboard, admin-only site review, rule analysis, and webhook alerts.
• agent: site-side read-only collector that calls NewAPI admin HTTP APIs and reports snapshots to the central server.

The agent does not connect to a NewAPI database. It only uses the configured NewAPI base URL and admin token.

Build

go build ./cmd/newapi-report

If the default Go build cache is blocked on Windows, use a workspace cache:

$env:GOCACHE = (Join-Path (Get-Location) 'work\gocache')
go build ./cmd/newapi-report

Run the central server

newapi-report server --config examples/server.yaml

Open the public dashboard without a token:

http://127.0.0.1:8080/

The dashboard shows approved-site statistics publicly. Newly reporting sites are visible as pending, but they do not enter approved totals, user analysis, or cross-site analysis until approved.

Site review

List all sites, including pending sites, with the admin token:

Invoke-RestMethod `
  -Method Get `
  -Uri http://127.0.0.1:8080/api/sites `
  -Headers @{ Authorization = "Bearer change-me-admin-token" }

Approve a pending site:

$body = @{ site_id = "site-a" } | ConvertTo-Json
Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8080/api/sites/approve `
  -Headers @{ Authorization = "Bearer change-me-admin-token" } `
  -ContentType application/json `
  -Body $body

You can also pre-create an approved site without a reporting secret:

$body = @{ site_id = "site-a"; site_name = "Alpha NewAPI" } | ConvertTo-Json
Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8080/api/sites `
  -Headers @{ Authorization = "Bearer change-me-admin-token" } `
  -ContentType application/json `
  -Body $body

Run a site agent

examples/agent.yaml contains the site-side settings. The agent only needs the NewAPI URL and admin token for site identity; it uses newapi_url as the reported site ID. There is no required site_id, site_name, or report_secret; review happens on the central server.

Test collection without reporting:

newapi-report test-collect --config examples/agent.yaml

Run continuous reporting:

newapi-report agent --config examples/agent.yaml

The agent calls agent.collect_path with Authorization: Bearer <agent.admin_token>, automatically increments the p query parameter until an empty page is returned, normalizes users, and POSTs the full site snapshot to agent.report_url every agent.interval. Each accepted report replaces that site's previous user list.

Snapshot payload

Agents POST this shape to /api/report. No central-side site secret is required:

{
  "site_id": "https://newapi.example.com",
  "reported_at": "2026-06-14T12:00:00Z",
  "users": [
    { "username": "alice", "token_used": 1234, "balance": 120000, "referral_count": 3 }
  ]
}

This JSON endpoint also acts as the manual import fallback when a site cannot expose all fields through NewAPI APIs.

Analysis rules

The server recomputes and stores alerts after each report for approved sites:

• same username appears across multiple approved sites
• user token usage exceeds thresholds.heavy_token
• remaining token balance is below thresholds.low_balance
• referral count exceeds thresholds.referral
• latest approved site report is older than thresholds.stale_site

Webhook alerts are sent as JSON POST bodies to server.webhook_url when configured.

Storage note

The code keeps the OpenSQLite repository boundary so the persistence layer can be swapped for a real SQLite driver without changing server logic. In this sandbox, third-party SQLite checksum generation was blocked, so the MVP currently uses a local JSON file at the configured server.database path. The repository API and tests are structured to make replacing this with SQLite straightforward.

Debug NewAPI collection

If test-collect returns an empty users array, first inspect the raw NewAPI response shape:

./newapi-report-linux-amd64-v2 test-collect --config agent.yaml --debug

Useful agent options for real NewAPI deployments:

agent:
  collect_path: "/api/user/?p=1&size=1000" # p will auto-increment until an empty page
  auth_prefix: "Bearer"
  newapi_user_id: "1"

newapi_user_id is optional, but many NewAPI management tokens require the New-Api-User header. If the debug output shows a different list field, adjust collect_path or share the raw_preview after removing secrets.

Data replacement semantics

Every report is treated as a complete snapshot for that site. When a site reports again, the server removes the previous user list for that site and keeps only the newest uploaded list. balance means remaining token quota, not currency balance. Usernames are shown in clear text on the dashboard.

Dashboard behavior

• 用量 Top 默认每页 20 人，按已用 Token、拉人数量、剩余 Token 倒序排序。
• 跨站同名也按同一规则排序，并在首页合并展示已用 Token、剩余 Token、拉人数量。
• 用量 Top 和跨站同名里的三个数字字段都可以点击，进入该用户名在各站点的明细页。
• 告警接口仍保留，但首页暂不展示告警模块。

Agent site identity

站长侧不需要配置站点名或站点 ID。Agent 默认用 agent.newapi_url 去掉末尾 / 后作为 site_id 上报，中心端待审核列表也直接显示该 URL。旧配置里的 site_id / site_name 仍兼容，但不再推荐填写。

Site access guide page

The web dashboard includes a “站点接入教程” button linking to /guide. The guide points site owners to https://github.com/changeGood/newapi-report/releases for release downloads and shows the minimal agent.yaml and startup commands.