常见问题

按“先确认版本，再确认数据源，最后检查凭据与缓存”的顺序排查。错误信息包含密码、Session、Agent 部署命令或第三方 Secret 时，不要贴到公开 Issue。

按场景速查

不确定该看哪一条时，先按你遇到的场景找到对应条目：

首次部署与访问

场景	看这里
部署完 `*.workers.dev` 打不开	关于 `*.workers.dev` 访问
改了后台入口路径后 404	修改后台入口后返回 404
服务器连不上 Cloudflare / Fastly / Akamai，装不上 Agent	节点无法访问 Cloudflare / Fastly / Akamai 时如何安装
安装命令提示不再接受 `--token`	安装脚本不再接受 `--token`（1.1.65 起）
BusyBox 系统执行 NQ/IP 报 setpriv 参数错误	BusyBox 节点运行 NQ/IP 提示 setpriv 参数错误

节点离线或不上报

场景	看这里
Agent 已发布，但节点版本/状态没变	Agent 已发布但节点版本没有立即变化
只有 IPv6 的节点探测不到	IPv6 与 Cloudflare 探测
External Latency 节点一直“尚未上报”	External Latency 节点显示“尚未上报”
代理检测一直离线或超时	代理检测一直离线或超时

更新相关

场景	看这里
系统更新显示 HTTP 429	系统更新显示 HTTP 429
后台提示有新版本，但一直没自动更新	后台显示有新版本但一直没有自动更新
实例版本落后，节点还会更新吗	实例落后时节点仍会跟上官方版本

显示、数据与容量

场景	看这里
NQ 图片不显示或显示旧数据	NQ 图片不显示或显示旧数据
磁盘容量数字看起来不对	磁盘容量显示
想换主题 / 用 Canvas 主题	主题与 Canvas 主题
想知道免费额度够不够用	免费额度

安全、备份与集成

场景	看这里
备份与恢复数据	后台备份恢复相关
浏览器调用公开 API 报 CORS	浏览器请求公开 API 报 CORS 错误

系统更新显示 HTTP 429

这是 Worker 读取官方 GitHub Raw 更新清单时遇到上游限流，不是 Agent 故障。自 1.0.38 起，更新检查使用六小时成功缓存、并发请求合并与十五分钟失败退避；官方源不可用时使用最近成功缓存，冷启动使用随部署打包的可信 manifest。

“使用当前部署版本/使用缓存结果”属于安全降级。
不要连续刷新或自行增加重试频率。
检查 /api/health、/update-manifest.json 与 /bin/VERSION 是否为同一版本。
自部署更新由部署仓库的 NIE-SLA Online Update workflow 完成，不需要 GitHub Token 输入框。

修改后台入口后返回 404

ADMIN_PATH 保存成功后旧入口立即失效，这是预期行为。用“Worker 地址 + 新路径”重新打开。路径不是身份认证，安全边界仍是账号密码、短期 Session 与可选 TOTP。

关于 `*.workers.dev` 访问

自托管部署默认可以直接用 *.workers.dev 地址访问——一键部署的新账号通常还没有域名，它是主要入口。绑定自定义域后如果不希望保留这个平行入口（它会绕过自定义域的限流与防护），在 Worker → Settings → Variables and Secrets 添加文本变量 ALLOW_WORKERS_DEV = false 并保存部署即可；官方生产站还会在配置层直接关闭 workers.dev 路由。另外确认访问路径：公共状态页是 /，后台是部署时填写的 ADMIN_PATH（不是 /admin）。

Agent 已发布但节点版本没有立即变化

Agent 按更新策略轮询，不会在 Release 创建瞬间全部升级。先检查后台显示的 agent_version、在线状态与 Manager 状态，再在节点执行：

bash

sudo cftz status
sudo cftz log 100

极旧版本可能没有当前 Manager 或完整校验更新链，需要重新执行后台为该节点生成的最新部署命令。不要复用其他节点命令，其中的 Token 只对一个节点有效。

BusyBox 节点运行 NQ/IP 提示 setpriv 参数错误

1.0.49 到 1.0.50 曾把 GNU setpriv --reuid/--regid 参数交给 BusyBox，导致脚本启动失败；后续直接降权解决了启动问题，却让 NQ 的 raw socket、延迟与路由探测失去权限，出现“任务成功但延迟全为 0、回程全是 NoData”。升级 Agent 到 v1.0.58+：NQ 与 IP 解锁由强制 root 的 Manager 直接执行，不再使用 nstatus-task、no_new_privs 或 user namespace。普通指标采集仍由低权限 nstatus 服务运行；Manager 只接受两个固定 action，并校验脚本 SHA-256、私有目录、无符号链接、固定 PATH、超时与输出上限。

v1.0.59 把 NodeQuality 深度检测上限从 30 分钟提高到 60 分钟，避免低配置或慢盘 VPS 在 HardwareQuality 硬盘阶段提前退出；IP 解锁保持 10 分钟上限。

v1.0.64 起后台运行 NQ 时可分别选择 HardwareQuality（y/f/v/n）、IPQuality（y/n）、NetQuality（y/l/n）与回程路由（y/n），单机与批量任务都随请求提交；NQ 任务不再设置外部超时，排队过期保留 7 天宽限。

v1.0.66 修复批量 NQ 在旧 Agent 上约 600 秒被 exit 124 终止：Worker 对旧 Agent 重新下发 3600 秒兼容上限，v1.0.64+ Agent 仍无外部超时。

v1.0.67 修复后台批量运行 NQ/IP 解锁时“确认排队”后弹窗不退出、右下角无提示、刷新后部分 VPS 未开始的问题：批量创建改为每批 5 台并发，前端立即关闭弹窗并显示排队中提示，批量请求超时提升到 60 秒。

v1.1.0 切换为十进制版本号并直接发布 1.1.0：备份预览/恢复增加低频 D1 限流，任务请求超时提示补充“请求可能仍在服务端继续执行，请稍后刷新查看”。

v1.1.1 为 NQ/IP 解锁任务增加强制停止：排队中的任务立即取消，运行中任务由新 Agent 检测到取消标记后按脚本整个进程组结束；表格与详情弹窗显示“强制停止”按钮与“正在停止”状态。

v1.1.2 起公开页与后台的解锁信息也以 NodeQuality 报告为准，NQ 完全解锁时不再被旧 IP.Check.Place 失败覆盖；中国 显示为红色，锁定/失败/会员限定等状态显示在红色徽标内。

v1.1.3 修复腾讯云等网络环境无法从 GitHub 下载 NQ 组件的问题：静态脚本保留官方源，下载失败自动回退实测加速镜像并强制校验 SHA-256；Agent 任务 Runner 增加实例归属与 30 分钟心跳兜底，同时修复重复的 /api/agent/tasks GET 路由。

v1.1.4 在 NQ 弹窗增加加速源（auto / EdgeOne 中国 / Cloudflare 海外）。审核过的脚本优先使用公开 NIE-Proxy 加速服务，自动回退官方源与镜像；SHA-256 校验不变。

v1.1.5 起 HardwareQuality 内部下载的 Geekbench 5 包也走所选 NIE-Proxy 加速路径，白名单增加 cdn.geekbench.com。

v1.1.6 从 NQ 弹窗移除 EdgeOne，只保留“默认”与“Cloudflare 海外”；历史 eo 任务自动回退默认。

v1.1.7 起上传 API 在解析正文前先完成认证；当时的静态预算测试只覆盖基础流量，后续生产数据证明它低估了探测、Durable Object 和调度执行时长，不能再用来保证 100 台容量。

v1.1.8 修复包含 & 等特殊字符的目标 ID：Worker 按原始 ID、规范化 ID 与扫描匹配三层解析目标，metrics、pings、config、location 都能落到原始目标。

v1.1.9 修复前端快速切换时间范围时指标与 Ping 偶发串图，TCP Ping 与 Latency 曲线改为丢包断线，并重新排版后台探针列表。

v1.1.10 图表工具栏新增“端点连续”开关：Latency 与 TCP Ping 默认在丢包或失败处断开，打开后跨空值连线，选择保存在本机浏览器。

v1.1.11 后台探针列表恢复原有表格版式，移除上一版过宽的监控块与行内补白，目标信息密度与操作区布局回到 1.1.8 之前。

v1.1.12 探测策略整体降频：单次超时降至 3 秒，状态快照改为每 2 分钟刷新，区域延迟数据每 3 分钟更新，连续失败的目标自动降频为 10 分钟一次；NQ 报告图片接入边缘缓存；Agent 任务取消轮询从固定 2 秒改为 5~10 秒退避，D1 汇总缓存与新索引上线。

v1.1.18 已发布 300 秒体验、WS 复用、按小时 R2 缓冲与缓存/304；v1.1.22 又新增批量 Ping 接口，使公开面板可一次读取全量 VPS 的 Ping 历史。实际能力仍以目标部署的 Manifest 和发布记录为准。

IPv6 与 Cloudflare 探测

“Agent 在线但 CF Latency 失败”通常是方向问题：Agent 上报只证明 VPS 有出站网络，Cloudflare 能否连接 VPS 端口是另一条链路。要点：

后台主机字段填 IPv6 时不要带 []，端口填在端口字段。
直接填 IPv6 字面地址可能被 Cloudflare 拒绝，尝试为同一地址创建 DNS-only AAAA 域名。
不要开橙云（代理）：AAAA 会返回 Cloudflare 代理地址，Workers TCP Socket 禁止连接 Cloudflare IP。
从另一条公网 IPv6 用 nc -6 -vz 域名端口 验证监听与防火墙。

完整排查见文档站的 IPv6 专题。

NQ 图片不显示或显示旧数据

网络质量与回程路由图片由 Worker 渲染并上传；图床失败时前端回退文本报告，任务不判失败。
公开图片地址是同源代理，不暴露上游图床。
图床链路由官方公益 Broker 承担，普通部署不需要、也不能配置自己的 NQ_IMGBED_URL/NQ_IMGBED_TOKEN。
只处理配置生效后的新报告，旧报告不自动补传。

External Latency 节点显示“尚未上报”

节点记录创建不等于部署成功。检查：是否在正确机器执行了该节点最新完整命令；安装输出是否出现 accepted；服务是否 active；日志是否有 401/403/TLS/DNS 错误。旧版节点重新执行完整安装命令，不要只重启服务。

浏览器请求公开 API 报 CORS 错误

命令行成功但浏览器失败：Origin 未加入 DEVELOPER_API_ORIGINS。填入完整 Origin（https://status.example.com），不能带路径、不能是 *。生产必须 HTTPS，HTTP 只允许本机开发地址。

后台备份恢复相关

恢复前必须先预览并输入确认词；支持合并与替换。
恢复前 Worker 自动保存 R2 快照；失败时先保留快照并查日志，不要反复点击。
敏感备份的 Agent Token 在恢复时重新封装，跨账号迁移后原节点可继续认证。
普通备份不含 Token；高频历史不在 JSON 中，迁移优先复用原 R2。

磁盘容量显示

agent_metrics.vps_info.total_disk_gb 表示系统根文件系统容量，不是所有挂载点之和。同设备绑定挂载不重复计入。

主题与 Canvas 主题

当前版本只开放主题包，不提供插件运行时。只调配色与间距用 CSS 主题；需要重写公开页布局、交互或图表时用 Canvas 主题，它运行在无同源权限的 sandbox iframe 中，只能通过消息协议读取公开状态，不能直接联网或读取宿主页面。

主题上传后默认停用，管理员核对 SHA-256 后手动启用；停用立即恢复原版界面。
不要分发 type: "plugin" 的 ZIP；旧教程里的插件上传与插件消息协议从未作为当前生产能力开放。
独立面板走公开 v1 API，部署到独立域名，并配置精确的 DEVELOPER_API_ORIGINS。

免费额度

经济模式默认让健康目标每 15 分钟探测、故障目标约每 2 分钟重试；Agent 指标每 15 分钟批量上报，任务每 10 分钟领取，普通升级检查每天一次。这样 100 台 VPS 的入口请求和 Unbound 压力显著低于旧的 5 分钟模型，但指标最多延迟约 15 分钟，故障恢复仍保持短间隔。上线后仍应在 Dashboard 对 Workers、Durable Objects、D1 rows 与 R2 操作设置告警；接近 80% 时先确认是否存在旧版本 Agent，再降低频率或切换 Workers Paid。详细调度参数见架构说明。

现状（1.1.93）：Agent 遥测缓冲与探测历史都已并入共享 Durable Object 实例，D1 写入只在缓冲失败时回退；在 5 分钟上报的实际规模下，Workers、Durable Objects、D1 与 R2 都保持在免费额度内（D1 读行是最紧的一项）。精确占比请用用量计算模型与目标部署的 Cloudflare 账单复核，不要用旧的静态预算结论推算 100 台。

节点无法访问 Cloudflare / Fastly / Akamai 时如何安装

少数网络环境的 VPS 无法直接访问 Cloudflare 等 CDN，安装、上报与自动更新都会失败。可以在任意一台能访问站点的机器上做纯 TCP 中转（TLS/SNI/Host 原样透传，不需要域名、证书或备案）：

在中转机上（该机器需能执行 curl -fsS https://sla.niekaixiang.com/api/health）：

bash

sudo apt install -y socat
sudo systemd-run --unit=nie-sla-relay socat TCP-LISTEN:443,fork,reuseaddr TCP:sla.niekaixiang.com:443

用防火墙只放行被中转节点的 IP；重启后可用同样的 systemd-run 命令或开机脚本恢复。然后在受限节点上把两个官方域名指向中转机 IP，照常执行后台生成的部署命令：

bash

echo "<中转机IP> sla.niekaixiang.com api-sla.niekaixiang.com" | sudo tee -a /etc/hosts
curl -fsS https://sla.niekaixiang.com/api/health

TLS 校验、Host 与更新下载地址仍然全部是官方域名，因此上报、任务、WebSocket 与自动更新都走中转。若只是 IPv6 或备用端口可达，可先测试 curl -6 -fsS https://域名/api/health 或 curl -fsS https://域名:8443/api/health。

安装脚本不再接受 `--token`（1.1.65 起）

为避免密钥出现在 ps 与 Shell 历史中，setup.sh、install-mac.sh 与 quick-install.sh 会拒绝 --token 参数并提示改用环境变量或交互输入：

bash

NIE_SLA_AGENT_TOKEN='...' sudo -E bash setup.sh --non-interactive

后台生成的一键命令使用环境变量与一次性凭据，不受影响。

代理检测一直离线或超时

先确认该代理目标「执行 Agent」的版本。1.1.53 及更早版本缺少 1.1.57 的 Reality 握手缓冲修复，Reality 节点会固定 5 秒超时并显示 stage=connect / timeout，握手与首字节时间保持 -。处理方式：把执行节点升级到 v1.1.57+（直接重跑后台生成的部署命令），或在代理目标里把「执行 Agent」换成一台已升级的节点。替换后若仍然全部失败，再检查分享链接与参数是否完整（Reality 公钥与短 ID 必填）。

后台显示有新版本但一直没有自动更新

一键部署的在线更新由部署仓库里的 GitHub Actions 工作流（NIE-SLA Online Update）执行，每 6 小时检查一次官方稳定版；它不在 Worker 内运行，Worker 无法替自己升级。后台「系统更新」卡片只显示当前版本与官方最新版本，发现新版本并不代表升级已经执行。

如果 Actions 页面是「Get started with GitHub Actions」（完全没有工作流），说明一键部署没有把工作流复制进仓库。在浏览器里补装一次即可（更新逻辑始终由官方仓库维护，以后不用再动）：

打开部署仓库的 Actions 页 → 点击 set up a workflow yourself；
粘贴下面这段并点 Commit changes；
之后在左侧选择 NIE-SLA Online Update → Run workflow。

yaml

name: NIE-SLA Online Update
on:
  workflow_dispatch:
  schedule:
    - cron: "17 */6 * * *"
permissions:
  contents: write
jobs:
  update:
    uses: 3257085208/NIE-SLA/.github/workflows/nie-sla-update.yml@main

长时间没有升级时，按顺序检查：

仓库是否启用 Actions：部署仓库 → Settings → Actions → General，选择允许运行工作流（新建或复刻的仓库默认可能关闭）。
是否有运行记录：仓库 Actions 页面应能看到「NIE-SLA Online Update」的定期运行。完全没有记录时按上面的补装步骤处理；已安装时点击 Run workflow 可以立即触发一次。
查看失败日志：打开失败运行的最后一步：
- no online-update baseline：仓库内容与官方当前版本基线不一致，需要先手动同步一次；
- Deployment files differ from the official … baselines：仓库里有官方版本之外的改动（只有 wrangler.jsonc 允许不同）；
- 依赖或构建错误：用最新分支重新触发一次。
等待 Cloudflare 构建：工作流推送成功后，Cloudflare Workers Builds 还需要约 1–3 分钟完成构建；强制刷新后台页面再点「检查更新」。

不使用 GitHub Actions 时也可以手动更新：把仓库同步到官方最新版本后执行 npm run deploy，或直接用最新模板重新一键部署（可同时获得最新的 Durable Object 绑定与内部密钥配置）。

实例落后时节点仍会跟上官方版本（v1.1.90+）

上面的工作流管的是实例（Worker/静态资产）。执行节点（Agent）本身还有一条独立通道：从 v1.1.90 起，当实例发布的版本已经落后于官方最新版时，节点会直接跟随官方发布通道（https://sla.niekaixiang.com 的 update-manifest.json 与 bin/SHA256SUMS）完成校验并自更新，不再被实例版本卡住。规则：

只有在实例的「自动更新」开启（后台开关 auto_update）时才会走这条回退通道；实例明确关闭自动更新时，节点保持现状。
实例只要发布了比节点更新的版本，仍以实例为准（自建分发优先）。
可用环境变量关闭或改写：NIE_SLA_OFFICIAL_UPDATE=0 关闭回退；NIE_SLA_OFFICIAL_UPDATE_BASE=https://… 指向自建镜像。
检查节奏：实例未显式配置时默认每 1 小时检查一次（AGENT_UPDATE_CHECK_SEC，可设 900–86400 秒）；实例策略里的间隔优先。

因此即使实例的部署流水线暂时停摆，节点也会继续获得官方修复；实例自身的升级仍需上面的工作流（或手动部署）完成。

常见问题 ​

按场景速查 ​

系统更新显示 HTTP 429 ​

修改后台入口后返回 404 ​

关于 *.workers.dev 访问 ​

Agent 已发布但节点版本没有立即变化 ​

BusyBox 节点运行 NQ/IP 提示 setpriv 参数错误 ​

IPv6 与 Cloudflare 探测 ​

NQ 图片不显示或显示旧数据 ​

External Latency 节点显示“尚未上报” ​

浏览器请求公开 API 报 CORS 错误 ​

后台备份恢复相关 ​

磁盘容量显示 ​

主题与 Canvas 主题 ​

免费额度 ​

节点无法访问 Cloudflare / Fastly / Akamai 时如何安装 ​

安装脚本不再接受 --token（1.1.65 起） ​

代理检测一直离线或超时 ​

后台显示有新版本但一直没有自动更新 ​

实例落后时节点仍会跟上官方版本（v1.1.90+） ​

常见问题

按场景速查

系统更新显示 HTTP 429

修改后台入口后返回 404

关于 `*.workers.dev` 访问

Agent 已发布但节点版本没有立即变化

BusyBox 节点运行 NQ/IP 提示 setpriv 参数错误

IPv6 与 Cloudflare 探测

NQ 图片不显示或显示旧数据

External Latency 节点显示“尚未上报”

浏览器请求公开 API 报 CORS 错误

后台备份恢复相关

磁盘容量显示

主题与 Canvas 主题

免费额度

节点无法访问 Cloudflare / Fastly / Akamai 时如何安装

安装脚本不再接受 `--token`（1.1.65 起）

代理检测一直离线或超时

后台显示有新版本但一直没有自动更新

实例落后时节点仍会跟上官方版本（v1.1.90+）