Quick start

From zero to a working deployment in 15 minutes: deploy the server, open the admin panel, connect your first VPS.

No coding required — everything happens in a browser and an SSH terminal.

Before you start

What you need

Item	Notes
Cloudflare account	Free signup is fine; R2 must be enabled (see the note below)
GitHub account	One-click deploy copies the code into your repository and drives updates
One VPS	Linux (Debian/Ubuntu/CentOS and friends), with root or sudo
15 minutes	Deploy + build takes about 5–10 minutes, connecting a node 1–2 minutes

What you get

• Your own public status page and an admin panel;
• Live metrics, online state, TCP pings and proxy availability for one or many VPS;
• Automatic updates: nodes upgrade themselves, the server follows the official stable release on a schedule.

Eight terms you will meet (no need to memorise)

Term	One-line explanation
Worker	The server program on Cloudflare: APIs, probe scheduling and pages
D1	Cloudflare's database: configuration, current state and SLA aggregates
R2	Cloudflare object storage: high-frequency history and archives (enable first)
Durable Objects (DO)	Cloudflare's stateful building blocks for realtime buffers and status streams
Agent	The probe program installed on your VPS (single Rust binary) that reports metrics
Manager	The Agent's companion process for root-level tasks and automatic updates
Target	The thing being monitored: a VPS, a website or a proxy endpoint
Latency node	A measuring node in another network location, used for regional latency

1. Deploy the server (one-click)

Open the public repository README, click Deploy to Cloudflare, authorize GitHub and Cloudflare, then fill in:

Variable	What to enter
ADMIN_USERNAME	Admin account name, your choice
ADMIN_PASSWORD	At least 9 characters with upper/lowercase, digits and symbols
ADMIN_PATH	Admin entry path, for example admin
TOTP_ENCRYPTION_KEY	Independent random value of at least 32 characters, kept stable forever

The step people get stuck on: a new account must enable R2 in the Cloudflare dashboard first (free tier: 10 GB storage, 1M Class A and 10M Class B operations per month; R2 still requires an R2 subscription with a payment method even on the free tier), otherwise the deploy stops at "uses R2, which is available with an R2 subscription". D1 and the R2 bucket are created and bound automatically.

After the build finishes:

1. Open the Worker URL and visit WORKER-URL + admin path to log in (no Agent token needed).
2. Each VPS token is created when the admin panel first generates an install command.

*.workers.dev shows Not Found? That is deliberate hardening: workers.dev is a parallel entry point that would bypass your custom-domain rate limits and protections. Without a custom domain, add the text variable ALLOW_WORKERS_DEV = true under the Worker's Settings → Variables and Secrets and redeploy to use the workers.dev URL; remove it after binding a custom domain. The public status page lives at /; the admin entry is the ADMIN_PATH you chose.

When this step is done you should see: the admin panel logs in, the public page opens, and /api/health returns ok: true (commands in the next section).

Option B: command line (optional)

For a custom domain, CI, or a local preview:

git clone https://github.com/3257085208/NIE-SLA.git nie-sla && cd nie-sla
npm install
npx wrangler d1 create nie-sla-db           # paste the returned database_id into wrangler.jsonc
npx wrangler r2 bucket create nie-sla-archive
npx wrangler secret put ADMIN_USERNAME      # then ADMIN_PASSWORD / ADMIN_PATH / TOTP_ENCRYPTION_KEY / INTERNAL_CRON_SECRET
npm run build                               # download assets pinned by update-manifest.json into dist-one-click
npm run deploy

Manual/CLI deployments must set INTERNAL_CRON_SECRET themselves (32+ random characters): internal Durable Object calls fail closed with 401 without it, and Agent telemetry fails immediately. One-click deployments generate and inject this secret during the Cloudflare build, so nothing is required there.

Custom domain: Cloudflare Dashboard → Workers & Pages → your Worker → Settings → Domains & Routes → Add custom domain; then set the Agent connection domain under "Settings → Agent" in the admin panel.

2. Post-deploy checks (30 seconds)

curl -fsSL https://YOUR-DOMAIN/api/health      # expect: {"ok":true,...}
curl -fsSL https://YOUR-DOMAIN/bin/VERSION     # expect: the current version, e.g. v1.1.93
curl -fsSL https://YOUR-DOMAIN/bin/SHA256SUMS  # expect: per-architecture checksums

Then confirm three things:

• the admin panel logs in at the right path;
• the public page renders;
• the Cloudflare dashboard shows a Cron run every minute (Workers → your Worker → Logs / Cron Events).

3. Connect your first VPS

1. In the admin panel open "Probes" and add a TCP/VPS target with a name, then save.
2. Click Deploy Agent on that target and copy the generated command.
3. Run it on the VPS as root.

The command contains a scoped token for this node: never reuse one VPS command on another machine.

The installer detects the architecture, verifies the manifest and binary, checks the version, and installs a systemd or OpenRC service.

When this step is done you should see: within a few minutes the target shows Agent online with its version.

The telemetry service runs as an unprivileged user; since 1.0.44 ICMP is no longer used, so neither the systemd unit nor the binary needs CAP_NET_RAW. Legacy icmp:// probe rows stay visible so you can delete them, but they are no longer sent to agents.

On the VPS, for troubleshooting:

sudo cftz status     # service state
sudo cftz log 100    # last 100 log lines

4. Configure probes and alerts

• After adding a TCP target with a public address, Cloudflare probes it on a schedule; for IPv6-only nodes see IPv6 and Cloudflare probing (or the matching topic in your language).
• In the Ping field, host:port or tcp://host:port means TCP, while http:///https:// means an Agent-side HTTP probe. The default interval is 20 seconds (range 5-300); legacy saved 1-second values fall back to 20.
• NodeQuality offers HardwareQuality (y/f/v/n), IPQuality (y/n), NetQuality (y/l/n) and backroute (y/n); results follow the official NodeQuality report.
• Configure Telegram or email under "Settings → Alerts" and send a test notification first before enabling rules.
• To measure latency from other network locations, add an External Latency node and run its install command.

5. Online updates

The one-click repository checks the official stable release every 6 hours. Updates keep your deployment's wrangler.jsonc, run the security scan, application tests and a Wrangler dry-run before committing.

Update immediately: open the deployment repository → Actions → NIE-SLA Online Update → Run workflow, no inputs required.

"Settings → System update" in the admin panel shows the current version, the latest version and the changelog.

If the official manifest hits 429, 5xx or a timeout, the workflow falls back to a six-hour cache or the trusted manifest shipped with the deployment. "Official source limited, using the current deployment/cached result" is a successful degradation, not an outage — no need to refresh repeatedly.

Nodes (Agents) have their own independent channel: even if the server version lags, nodes follow the official release channel and update themselves without manual work.

6. Verify the public API

curl -fsSL https://YOUR-API/api/v1
curl -fsSL 'https://YOUR-API/api/v1/status?days=30&lite=1'

The first should contain api_version: "v1", stability: "stable" and the endpoint list; the second returns public targets. No token is needed; browser cross-origin calls require DEVELOPER_API_ORIGINS.

Common blockers

Symptom	Cause and fix
Deploy stops at "available with an R2 subscription"	R2 is not enabled: Cloudflare dashboard → R2 → enable (a payment method is required; the free tier still applies)
*.workers.dev returns Not Found	Deliberate hardening; temporary fix via ALLOW_WORKERS_DEV in section 1
Agent never comes online	On the VPS run sudo cftz status / sudo cftz log 100; make sure the command belongs to this machine
No Cron runs	Check that the Worker deployed; redeploy once and watch the logs
Updates never run	Repository Actions disabled or the workflow missing: see FAQ "The panel shows a new version but nothing ever updates"
NodeQuality report images fail to load	NQ image / image-host / same-origin proxy topic, see the matching FAQ entry
Forgot the password	Use the ADMIN_PASSWORD you set at deploy time; see the FAQ for changing it

Go-live checklist

• The admin account logs in and its password is not reused elsewhere.
• If TOTP is enabled, recovery material is stored safely.
• The public page and the admin entry both work.
• The VPS shows Agent online with a version.
• The public page exposes no private IPs, ports or URL credentials.
• At least one Telegram or email test notification arrived.
• Cloudflare Cron, D1, R2 and Durable Objects show no persistent errors.

Next steps

• Understand how the system fits together and how data flows: Architecture.
• Replace the frontend or integrate: Public API and Integration.
• Build themes or change the source: Theme system and Development.
• Stuck: check the FAQ first, then Error handling.
• Curious how many machines the Cloudflare free tier supports: Usage model (about 122 with defaults; stay at or below 106).