A small TCP ping API that tells you whether ip:port is reachable from the server it runs on. Run it
on a server inside mainland China and point NeXT-Panel's GFW detection at it.
netstatus-api-go [--config <file or directory>]
Without --config, config.json is searched in /etc/netstatus-api-go/ and the working directory.
If neither has one, the defaults below are used.
Images for linux/amd64, linux/arm64 and linux/riscv64 are published to GHCR. latest and X.Y.Z
follow releases, edge follows main.
docker run -d --name netstatus-api-go --restart unless-stopped -p 8080:8080 \ -v /etc/netstatus-api-go:/etc/netstatus-api-go:ro \ ghcr.io/the-next-project/netstatus-api-go:latest
To also push to Docker Hub, set the DOCKERHUB_USERNAME repository variable and the
DOCKERHUB_TOKEN secret. DOCKERHUB_IMAGE overrides the image name, which defaults to
<DOCKERHUB_USERNAME>/netstatus-api-go.
GET /v1/tcping?ip=<ip>&port=<port>[&token=<token>]
| Response | Meaning |
|---|---|
200 {"status":"true","time":42,"message":"TCP connection successful"} |
Reachable, time is the connect latency in ms |
200 {"status":"false","message":"TCP connection failed"} |
Unreachable after every attempt |
4xx/5xx {"status":"error","message":"..."} |
No verdict: bad input (400), bad token (401), non-public target (403), timed out (504) |
429 |
Rate limited |
ip must be a literal IPv4 or IPv6 address. Hostnames are not resolved.
| Key | Default | Description |
|---|---|---|
port |
8080 |
Listen port |
api_timeout |
3000 |
Time limit for a whole request, in ms |
tcping_timeout |
1000 |
Time limit for one connection attempt, in ms |
tcping_attempts |
1 |
Attempts before reporting unreachable. tcping_attempts × tcping_timeout must not exceed api_timeout |
rate_limit |
60 |
Requests per minute per client IP, 0 disables it |
trust_proxy |
false |
Take the client IP from X-Forwarded-For / X-Real-IP. Only enable this behind a reverse proxy |
allow_private |
false |
Allow probing loopback, private, link-local and CGNAT addresses |
token |
"" |
If set, requests must pass it as the token query parameter |
Set the detection API URL in the panel's cron settings, adding the token if you configured one:
https://probe.example.com/v1/tcping?ip={ip}&port={port}&token=<token>
- The panel probes nodes one after another from a single IP. If you have more nodes than
rate_limitallows per minute, the rest get429and are skipped. Raiserate_limit, or set atokenand use0. - The panel only marks a node as blocked on a
200with"status":"false". Every other response, including timeouts, leaves the node's state unchanged. - One lost SYN is enough to mark a node as blocked and notify users. Use
tcping_attemptsof2or3to reduce false alarms, and raiseapi_timeoutto match. The panel waits up to 10 s per probe.