快速上手

本页从零开始，带你在 15 分钟内完成：部署服务端 → 打开后台 → 接入第一台 VPS。

不需要写代码，全程在浏览器和 SSH 终端里完成。

开始之前

你需要准备

需要	说明
Cloudflare 账号	免费注册即可；需要能开通 R2（见下方提示）
GitHub 账号	一键部署会把代码复制到你的仓库，后续更新也靠它
一台 VPS	Linux（Debian/Ubuntu/CentOS 等均可），有 root 或 sudo
15 分钟	部署 + 构建大约 5–10 分钟，接入节点 1–2 分钟

你会得到

• 一个属于你自己的状态页（公开可访问）和一个管理后台；
• 一台（或多台）VPS 的实时指标、在线状态、TCP Ping 与代理可用性数据；
• 自动更新：节点自动升级，服务端按计划跟随官方稳定版。

先认识 8 个名词（后面都会遇到，不用背）

名词	一句话解释
Worker	Cloudflare 上的服务端程序，负责接口、探测调度和页面
D1	Cloudflare 的数据库，保存配置、当前状态和 SLA 聚合
R2	Cloudflare 的对象存储，保存高频历史与归档（需先开通）
Durable Objects（DO）	Cloudflare 的有状态组件，承载实时缓冲与状态流
Agent	装在你的 VPS 上的探针程序（Rust 单文件），上报指标
Manager	Agent 的伴生进程，负责需要 root 的任务与自动更新
探测目标（Target）	被监控的对象：一台 VPS、一个网站或一个代理节点
Latency 节点	放在其他网络位置的测速节点，用来测不同地区的延迟

1. 部署服务端（一键部署）

打开公开仓库 README，点击 Deploy to Cloudflare，授权 GitHub 与 Cloudflare，然后填写：

变量	填什么
ADMIN_USERNAME	后台账号，自己定
ADMIN_PASSWORD	至少 9 位，包含大小写字母、数字与特殊符号
ADMIN_PATH	后台入口路径，例如 admin（等于把入口藏在这个路径下）
TOTP_ENCRYPTION_KEY	至少 32 位的独立随机值，长期保持不变

最容易卡住的一步：新账号需要先在 Cloudflare 控制台开通 R2（免费额度 10 GB 存储、每月 100 万 A 类与 1000 万 B 类操作；即使只用免费额度也需订阅 R2 并绑定付款方式），否则部署会停在「使用仅 R2 订阅提供的 R2，立即升级」。D1 与 R2 桶由部署流程自动创建并绑定。

构建完成后：

1. 打开 Worker 地址，访问 Worker 地址 + 后台路径 登录（不需要填 Agent Token）。
2. 每台 VPS 的 Token 会在后台首次生成部署命令时自动创建。

*.workers.dev 打不开？ 默认返回 Not Found 是安全策略（workers.dev 是平行入口，会绕过自定义域的限流与防护）。还没有自定义域名时，在该 Worker 的 Settings → Variables and Secrets 添加文本变量 ALLOW_WORKERS_DEV = true 并保存重新部署，即可用 workers.dev 地址访问；绑定自定义域之后建议删除该变量收紧入口。页面路径是 /（公共状态页），后台入口是你部署时填写的 ADMIN_PATH。

完成后你应该看到：后台能登录、公开页能打开、/api/health 返回 ok: true（见下一节命令）。

方式 B：命令行部署（可选）

适合自定义域名、CI 或本地预览：

git clone https://github.com/3257085208/NIE-SLA.git nie-sla && cd nie-sla
npm install
npx wrangler d1 create nie-sla-db           # 把返回的 database_id 写入 wrangler.jsonc
npx wrangler r2 bucket create nie-sla-archive
npx wrangler secret put ADMIN_USERNAME      # 再依次设置 ADMIN_PASSWORD / ADMIN_PATH / TOTP_ENCRYPTION_KEY / INTERNAL_CRON_SECRET
npm run build                               # 按 update-manifest.json 的固定版本下载资产到 dist-one-click
npm run deploy

手动/命令行部署必须自行设置 INTERNAL_CRON_SECRET（32 位以上随机串）：内部 Durable Object 调用在缺少该密钥时 fail-closed 返回 401，Agent 上报会直接失败。一键部署会在 Cloudflare 构建时自动生成并注入该密钥，无需手动设置。

绑定自定义域：Cloudflare Dashboard → Workers & Pages → 选择该 Worker → Settings → Domains & Routes → Add custom domain；然后在后台「设置 → Agent」把 Agent 连接域名改为该域名。

2. 部署后检查（30 秒）

curl -fsSL https://你的域名/api/health      # 期望：{"ok":true,...}
curl -fsSL https://你的域名/bin/VERSION     # 期望：当前版本号，例如 v1.1.93
curl -fsSL https://你的域名/bin/SHA256SUMS  # 期望：各架构二进制校验和清单

再确认三件事：

• 后台能登录，路径正确；
• 公开页正常显示；
• Cloudflare 后台能看到 Cron 每分钟有运行记录（Workers → 你的 Worker → Logs / Cron Events）。

3. 接入第一台 VPS

1. 后台进入「探针」，新增一个 TCP/VPS 目标，填写名称并保存。
2. 点击目标上的 部署 Agent，复制生成的命令。
3. 在 VPS 上以 root 执行该命令。

命令里包含这台节点专属的 scoped Token：不要把一台 VPS 的命令复制给另一台。

安装器会自动识别架构、校验 manifest 与二进制、验证版本，并安装 systemd 或 OpenRC 服务。

完成后你应该看到：几分钟内后台该目标显示 Agent 在线与版本号。

主遥测服务以低权限账户运行；1.0.44 起不再使用 ICMP，systemd 单元与 Agent 二进制都不再需要 CAP_NET_RAW。旧 icmp:// 探针行仍显示在列表中以便删除，但不会下发给 Agent。

在 VPS 上排查问题时：

sudo cftz status     # 服务状态
sudo cftz log 100    # 最近 100 行日志

4. 配置探测与告警

• 有公网地址的 VPS 添加 TCP 目标后，Cloudflare 会按周期主动探测；IPv6-only 节点见 IPv6 与 Cloudflare 探测（或文档站对应专题）。
• 既有 Ping 输入框用 host:port 或 tcp://host:port 表示 TCP，http:///https:// 表示 Agent 侧 HTTP。默认间隔 20 秒，可配置范围 5-300 秒；保存过的 1 秒旧值会回退到 20 秒。
• 后台运行 NodeQuality 时可选 HardwareQuality（y/f/v/n）、IPQuality（y/n）、NetQuality（y/l/n）与回程路由（y/n），结果以 NodeQuality 官方报告为准。
• 在「设置 → 报警通知」配置 Telegram 或邮件，先发一条测试通知，确认收到后再开启规则。
• 需要从其他网络位置测延迟时，添加 External Latency 节点并运行它生成的安装命令。

5. 在线更新

一键部署生成的仓库默认每 6 小时检查官方最新稳定版本。更新会保留部署仓库的 wrangler.jsonc，完成安全扫描、应用测试与 Wrangler dry-run 后再提交。

想立刻更新：打开部署仓库 → Actions → NIE-SLA Online Update → Run workflow，无需填写参数。

后台「设置 → 系统更新」显示当前版本、最新版本与站内更新日志。

官方更新清单遇到 429、5xx 或超时时，会自动使用六小时缓存或随部署打包的可信 manifest。「官方源暂时受限，使用当前部署版本/缓存结果」是降级成功，不代表 Worker 或 Agent 离线，无需连续刷新。

节点（Agent）还有一条独立通道：即使服务端版本暂时落后，节点也会直接跟随官方发布通道自动更新，不需要你手动干预。

6. 验证公开 API

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

第一条应包含 api_version: "v1"、stability: "stable" 与端点清单；第二条返回公开目标。API 不需要 Token；浏览器跨域调用需要配置 DEVELOPER_API_ORIGINS。

常见卡点速查

现象	原因与处理
部署停在「使用仅 R2 订阅提供的 R2」	R2 未开通：Cloudflare 控制台 → R2 → 开通（需绑定付款方式，仍可用免费额度）
*.workers.dev 返回 Not Found	默认安全策略；临时办法见第 1 节的 ALLOW_WORKERS_DEV
Agent 一直不上线	在 VPS 执行 sudo cftz status / sudo cftz log 100；确认命令是这台机器专属的
Cron 没有运行记录	检查 Worker 是否部署成功；重新部署一次并观察日志
更新没跑	仓库 Actions 未启用或缺少工作流：见 常见问题 的「后台显示有新版本但一直没有自动更新」
NodeQuality 报告里的图片加载不出来	属于 NQ 图片/图床/同源代理问题，见 常见问题 对应条目
密码忘了	用部署时设置的 ADMIN_PASSWORD；改密见 FAQ

上线检查清单

• 管理员账号可登录，密码未与其他服务复用。
• 启用 TOTP 的话，恢复方式已妥善保存。
• 公开页与后台入口均正常。
• VPS 显示 Agent 在线与版本。
• 公开页没有泄露不应公开的 IP、端口或 URL 凭据。
• Telegram 或邮件至少完成一次测试通知。
• Cloudflare Cron、D1、R2 与 Durable Objects 无持续错误。

下一步

• 想了解系统怎么组成、数据怎么流转：看项目架构。
• 想换前端、做集成：看公开 API 与集成实践。
• 想改主题、改源码：看主题系统 与二次开发。
• 遇到问题：先查常见问题，再看错误处理。
• 关心 Cloudflare 免费额度能撑多少台：看用量计算模型（默认配置下约 122 台，建议 ≤106 台）。