内置文档 · 功能说明

• 配置 (Agent)　面板里创建的一套开机配置，核心是 agentId + agentToken；复制开机命令到服务器执行即可接入。
• 机器 (Server)　执行开机命令接入的云服务器，每台机器有自己的 bootId；Agent 上报后自动出现在「已对接服务器」，不需要手动添加。
• 凭证 (Credential)　集中保存的 API 密钥：阿里云 AccessKey、Cloudflare DNS。模块只引用凭证 ID，不会各自存一份密钥。
• 拨测节点 (Probe Node)　统一维护的测活来源（本机内置 / Globalping / 自建 Agent / HTTP 接口），供「TCP 拨测」模块和「GTM 健康模板」共同复用。
• GTM 实例　选若干「地址池」+ 一套策略，把结果输出为一条域名的智能解析（阿里云 AliDNS 或 Cloudflare）。
• 模板　按模块或整套配置可视化保存，新建/编辑配置时一键套用；单模块模板 = 只存一个功能项（如只存「TCP 拨测」的设置）。
• 接管模式　外部补机（默认，新机上报直接顶掉旧 active）／保守心跳（旧机超时未上报才被接管）／多活（多台在线机器同时作为 IP 池）。
• 有效在线　已被替换的机器不计入在线数，也不会进入 DDNS / GTM 的 IP 池。

控制面本体（这个面板自己）要装在什么样的服务器上。这一页你现在能看到，说明当前这台机器已经装成功了——这里留一份记录，方便你以后加第二台机器、或者转给同事按同样的标准选机器。

• 支持的系统　x86_64 或 aarch64、glibc ≥ 2.28 的 Linux 发行版：Ubuntu 20.04+ / Debian 10+ / RHEL·CentOS·Rocky Linux·AlmaLinux 8+ / Amazon Linux 2023+。
• 不支持的系统　CentOS 7 / RHEL 7 及更早（glibc 2.17）、Ubuntu 18.04 及更早（glibc 2.27）、Debian 9 及更早（glibc 2.24）、Amazon Linux 2（glibc 2.26）——都低于最低门槛，装了也跑不起来；这是官方 Node.js 24 Linux 构建本身的硬约束，不是安装脚本的限制。musl 系发行版（Alpine 等）完全不支持，官方 Node.js 不出 musl 构建。
• 装之前会先自己查　install.sh 会在真正动任何文件之前检测目标机器的 glibc 版本和 libc 类型，不满足会直接拒绝并说明原因和最低要求，不会让你等装完了才发现装不上。
• 业务服务器不受此限　这条系统要求只管控制面本体（这个面板）。「配置与脚本」页复制出来的探针安装命令是纯 shell 脚本，装在你的业务服务器上，不挑发行版，Alpine 也能装。
• 不确定这台机器够不够　在目标机器上跑 ldd --version，看第一行最后那个版本号，低于 2.28 就别装了。

  ldd --version

从拿到授权码到在浏览器里打开面板的这一整段。系统要求见上一节；这里讲的是「码放哪儿、脚本怎么跑、为什么装完直接用 IP 打开还是 404」。

• ① 授权码只能写进配置文件　授权码只能写进 /etc/keepalight/gtm/license.conf，命令行传参那种写法已经删掉了：写在命令行上的授权码会出现在 ps 的输出里、也会留在 shell 历史里，配置文件不会。文件里就这一行，键名是 LICENSE_CODE，不要加引号、不要在同一行写注释——整行被 # 注释掉、键名拼错、只写码没写 LICENSE_CODE= 是最常见的三种写错法。

  mkdir -p /etc/keepalight/gtm && chmod 0700 /etc/keepalight/gtm
  printf 'LICENSE_CODE=你的授权码\n' > /etc/keepalight/gtm/license.conf
  chmod 0600 /etc/keepalight/gtm/license.conf

• 没填码就跑安装脚本会怎样　⚠️ 没有授权码装不了：安装脚本会在真正动任何文件之前先读这个文件，读不到就原地停下、把购买页地址打给你，这一次一个文件都不会落地。不是「装完再补」——先在购买页拿到授权码，再去服务器上跑安装脚本。
• ② 装机命令　脚本依次做这些事：检测系统要求 → 读授权码（没有就在这里停下，什么都不装）→ 放可执行文件 → 自动生成一条随机面板路径和密钥 → 建数据目录 → 联网激活（拿授权码换一张授权票；这一步不成功就不往下装，而且会把刚才生成的东西全部清掉，机器回到装之前的状态，失败会说清楚是「授权码本身用不了」还是「联系不上授权服务器」）→ 装好 systemd 服务并等它真的起来 → 打印出一个首次配置地址。

  sudo ./install.sh

• 🔴 ③ 装完之后，面板只在你绑定的那个域名上开门　所以打开面板前必须先做完这三步（包括设管理员账号那一步，也要等域名能访问才做得了）：① 把绑定域名的 DNS 解析指到这台服务器；② 在这台机器上配好 HTTPS 反向代理，转到面板监听的地址（默认 127.0.0.1:8080）——反代必须透传 Host 请求头，域名锁只认这个请求头，不透传的话就算从正确的域名访问也一样是 404；同时要在 keepalight.env 里打开 TRUST_PROXY=true，并让反代同时传 X-Forwarded-For 和 X-Forwarded-Proto；③ 用浏览器打开安装完成时打印的那个首次配置地址，在页面上自己设管理员账号——安装脚本不会生成、也不会打印任何管理员口令。
• 用 IP 打不开不是故障　用服务器 IP、127.0.0.1、SSH 隧道或别的域名访问面板，一律返回和未知路径完全相同的 404，这不是故障。⚠️ 客户机器上的 Agent 完全不受这条限制：上报、配置下发、命令回执在任意域名或 IP 上都照常工作。
• ④ 面板路径是随机的，忘了怎么办　面板路径是安装时生成的一串随机字符，只在安装脚本的终端输出里打印这一次（服务端日志、系统日志里都不会出现，避免被贴进工单时泄漏）。忘了地址不要猜，在服务器上跑这条只读命令查，服务跑着也能查、不影响运行；要改路径去面板里改：「全局设置 → 管理员账号与访问路径」。

  DATA_DIR=/var/lib/keepalight/gtm /opt/keepalight/gtm/keepalight-gtm --show-panel-path

• ⑤ 卸载控制面（不是探针）　sudo ./install.sh --uninstall（默认）：数据目录和配置文件都保留，只删可以安全重新生成的二进制和服务定义；之后重新装会被自动识别成「升级」，账号 / 密钥 / 已存凭据全部原样接得上。sudo ./install.sh --uninstall --purge：连数据目录和 keepalight.env 一起永久删除，这是唯一不可逆的一步；交互式终端会先列出要删的东西再要求输入 yes 确认，非交互环境必须显式加 --yes，不给就拒绝执行、不删任何文件。⚠️ 业务服务器上那个探针的卸载是另一条命令，见「配置与脚本 · 上线流程」最后一步。

• 第 1 步 · 创建配置　在「配置与脚本」新建配置，按需填写基础 / 服务器·系统 / 解析·故障切换三个标签，保存后自动生成 agentId + agentToken。
• 第 2 步 · 复制开机命令　在配置卡片上点「复制开机命令」，得到一条一次性命令，会下载 /bootstrap/{agentId} 对应脚本并执行。
• 第 3 步 · 在服务器执行　粘贴到目标云服务器终端（root 或 sudo）执行；自动安装 curl / jq / openssl / ca-certificates，并固定安装 cron。文件统一放在 /opt/keepalight/gtm-agent/agent。
• 第 4 步 · Agent 上报　启动时强制上报一次，之后每 1 分钟上报一次公网 IP（及已开启模块产生的数据，如 root 口令版本编号、探测结果、命令执行结果——root 口令本身不由机器上报，见下方「root SSH 密码托管」），同时搭顺风车带回这台机器的探针指标：CPU / 内存 / 硬盘 / 网络速率 / 连接数 / 开机时长 / 累计流量 / IPv6，在「已对接服务器」的详情抽屉里看。
• 第 5 步 · 面板查看　机器出现在「已对接服务器」，可查看在线状态 / IP / SSH（若托管）/ 网页终端（若三层开关都开）/ 日志。
• 第 6 步 · 按需编辑　配置的三个标签随时可改；每个模块小节旁边都有「存为模板」，把当前小节另存，供下次新建配置直接套用。
• 第 7 步 · 卸载　装机时已经把卸载器写到机器本地，直接执行它即可（不再从网上下载，避免一个匿名可取的固定地址暴露本产品）；连 Nyanpass 一起卸载时在命令后追加 --with-nyanpass。

  sudo bash /opt/keepalight/gtm-agent/uninstall.sh

不是免责声明，是省你踩坑的时间。这几条都是刻意的设计或真实的边界，不是待修的缺陷。

• 不是 CDN，也不是硬件负载均衡器　不做内容加速或缓存，也不在你的机器和访客之间转发流量——它只负责「该把域名指向谁」这一个判断，实际流量仍然是访客直连你的服务器。
• 不承诺零停机，也不承诺 100% 可用　从「机器挂了」到「域名解析切过去」之间必然有健康检查间隔 + DNS 生效的时间差，秒到分钟级；具体多快取决于你设置的检查频率和 DNS 记录的 TTL，不取决于这套系统有多快。
• 网页终端需要 systemd　没有 systemd 的机器装不了、也用不了网页终端，而且开启之后也绝不会自动安装——必须有人到那台机器上手动执行一条命令。这台机器上其它功能（DNS 解析、健康检查、故障切换、心跳上报）完全不受影响。完整说明见「配置与脚本 · 服务器·系统标签」的「网页终端」。
• 没有免费试用期，也没有宽限期　装完没激活就是只读；到期当天就锁「改配置」这一件事。域名解析、健康检查、故障切换、Agent 上报永远不会因为授权状态而停一秒。这不是漏洞，是刻意的设计。
• 换一台机器没有一键搬家　可以用「全局设置 → 备份与恢复」把凭证 / 拨测节点 / GTM 实例 / 配置 / 模板 / 全局设置导出再导入（要用同一把 CREDENTIALS_SECRET 才解得开机密字段），但运行时数据（已对接服务器）不在备份范围内，探针要重新接入；授权也要在新机器上重新激活一次。没有「点一下就搬过去」的工具。
• 升级没有自动灰度 / 回滚编排　每台机器的升级命令都是你自己手动复制到服务器上执行的，节奏完全由你控制，但这不是产品提供的分批推送功能。

• 启用开关　关闭后机器仍会正常上报，但 Worker 不会执行 DDNS / GTM / TCP 相关动作。
• 分组　给配置打标签，方便在「配置与脚本」列表里按分组筛选。
• 接管模式　外部补机（默认）／保守心跳／多活，详见上方「整体关系速览」。
• Agent ID / Agent Token　ID 用来生成开机命令；Token 是机器请求 Worker 时的鉴权令牌，两者一起决定这台机器归属哪个配置。

这一标签里的模块都是「机器自己执行的动作」，不涉及 DNS 写入：root SSH 密码托管、允许下发 root 命令、网页终端、允许推送 Agent 更新、Nyanpass、BBR。

• root SSH 密码托管　默认关闭。开启后允许 root 登录 + 密码登录。口令**由控制面在保存这份配置时生成**（随机模式），或用你自己填的固定密码（固定模式）；机器装机时按控制面下发的那一把设上去，机器自己不生成、不保存、也不再把口令上报回来。同一份配置下的所有机器共用这份配置生成/填写的那一把，不是「每台机器各自一把」；「服务器·系统」标签里还有一个「换一把随机口令」按钮，换完立刻对控制面这边生效，但已经装好的机器要重跑一次安装命令才会真的换。口令可在「已对接服务器」的 SSH 面板按需查看 / 复制（要重新输入一次管理员密码）；关闭时完全不碰 SSH、不设置 root 密码，并会尽量把当初放通的改动还原。
• 允许下发 root 命令（高危）　默认关闭。它是一道纯开关，本身不提供任何输入框：它是**命令通道的总闸**，走这条通道的一共五件事——root 登录还原（关掉「root SSH 密码托管」时，把机器上被放通的那些改动改回去）；Nyanpass 的安装 / 卸载；BBR 的应用 / 还原；「TCP 端口拨测」判定「国内不可达」时那条「服务器命令」；Agent 自更新推送（手动触发：「已对接服务器」页点「推送 Agent 更新」）。关掉它，这五件事一条命令都发不出去。控制面不 SSH 到机器，而是把命令放进机器下次上报的响应里，机器收到后用 bash -lc 本地执行，结果随下一次上报带回。这个开关只是控制面这一侧的闸。机器那一侧还有一道只有 root 改得动、控制面写不到的放行文件（ROOT 下发控制器，allow_server_commands）：没装的机器一条命令都收不到，控制面因此**根本不给它入队**，也绝不会写一句"已下发"。装机时装机命令只会把要敲的那条打印出来（不会替你放行），已经装好的机器只能有人登上去执行一次 sudo /opt/keepalight/gtm-agent/agent/agent.sh --allow-server-commands。每台机器装没装，在「已对接服务器」页的「云端控制」那一列看得见（老 Agent 报不出来时显示「未知」，控制面一律按没装处理）。
• 网页终端（高危）　默认关闭。开启后，这份配置下的机器可以在面板上直接开一个 root 终端，敲什么就在机器上执行什么。⚠️ 这个开关拨一下立刻生效，不跟随「保存」（它不住在配置文档里，所以套模板、导入备份都打不开它）。它只是终端那几层闸里配置级的一层，只能收紧不能放松：控制面服务器上的 TERMINAL_ENABLED 没开的话，这里开了也一样开不出终端——那一层面板改不了，是有意的；另外被判定为「控制面宿主」的机器永远不许开，任何开关都覆盖不了。「已对接服务器」页的「终端设置」改的是同一个开关，改哪边都一样。⚠️ 网页终端需要 systemd，而且**装它必须有人真的到这台机器上、带着 SSH 凭据手动执行一条命令**——这是一个刻意的不对称设计「减权可以自动，增权必须到场」：关掉开关 → 自动卸载（下一轮上报，≤60 秒，不需要谁登机器）；打开开关 → 绝不自动安装，面板只给出一条命令 sudo /opt/keepalight/gtm-agent/agent/agent.sh --install-terminal，要有人拿着 SSH 凭据登上那台机器手动执行（避免「控制面被攻破 = 攻击者远程给自己开一个 root 终端」）。那条命令里没有任何凭据（用的是机器早就有的本机凭据），抄给别人也没用。没有 systemd 的机器上就是这一个功能装不了、用不了，这台机器上其它功能（DNS 解析、健康检查、故障切换、心跳上报）不受影响。
• 允许推送 Agent 更新（高危）　默认关闭。⚠️ 它是一张许可证，不是一个自动任务：控制面永远不会自己把 Agent 更新推给任何机器。开着它，你才可以到「已对接服务器」页对某一台点「推送 Agent 更新」，或者用「一键全部推送」把当前这一屏所有「旧版」的机器推一遍；被点到的机器会收到一条以 root 执行的安装命令把新版装上去。下载安装脚本时先核对 sha256（期望值由控制面现算，不采信任何外部输入），对不上就不装。关着它，连手动推都不许。⚠️ 开着它也不等于机器就会更新，还差三样，缺一样那台机器点了也推不动（面板会当场逐台告诉你缺的是哪一样、下一步该做什么）：① 有人到「已对接服务器」页手动点；② 这份配置的「允许下发 root 命令」也得开着（命令通道是它唯一的下发路，关着就一台都推不动）；③ 那台机器上要有人登上去执行过一次 sudo /opt/keepalight/gtm-agent/agent/agent.sh --allow-server-commands（控制面替不了它）。另外这几种情况点了也不会推，而且都会当场说明：机器离线、机器已被吊销、这份配置是停用状态、机器没上报脚本版本（Agent 太老）、机器已经是最新。同一台机器两次推送之间至少隔 30 分钟（防连点：一次推送就是那台机器以 root 重跑一整份装机脚本），同一个目标版本连推 8 次还没装上就停下来喊人。把这一项从「关」拨到「开」需要重新输入一次管理员密码（二次验证），拨回「关」不需要口令、立刻生效，并且会把已经排队、机器还没取走的那些自更新命令一并作废。它刻意不进模板系统——这种开关不该被套模板批量打开。想升级个别机器又不想动这些开关：登上去重跑一次安装命令，效果一样。
• Nyanpass / rel_nodeclient　默认关闭。执行的就是你粘贴进来的那条完整安装命令（面板不限定安装脚本域名，也没有「线路」这个选项，你从 Nyanpass 面板复制到什么就是什么）。⚠️ 不只在开机阶段跑一次：以后每次改动这个模块（改命令、开、关）保存后，都会向这份配置下的机器下发一条同步命令，先执行 /opt/nyanpass.uninstall.sh 卸掉旧的，开着的话再按新命令重装一遍。Worker 不参与节点连接。
• BBR　默认关闭。机器本机执行 BBR 优化脚本，默认使用 本机内置 bbrx.sh，也可以切换为外部脚本 URL；和 DDNS / GTM 写入没有直接关系。

这一标签管「要不要把机器 IP 写进解析、出问题时怎么办」：内置 DDNS、阿里云 GTM、TCP 端口拨测 / 失败动作。

• 内置 DDNS　默认关闭，新建配置不带任何域名。机器只负责上报公网 IP，域名解析由 Worker 完成：单 IP 模式更新当前 active 的解析；多 IP 模式同步所有「有效在线」的 IPv4。服务商支持阿里云 AliDNS 和 Cloudflare DNS，凭证从「凭证区」选，机器端不保存 DNS API 密钥。⚠️ 它跟 GTM 实例不是同一套东西：DDNS 完全不经过健康模板 / 地址池那套判定，只是把某条域名记录直接指向「当前判定为这个配置下活跃的那台机器」的最新公网 IP。适合只有一台 / 一组机器、不需要复杂调度策略的场景；需要多线路 / 多权重 / 多备份策略时，才需要建 GTM 实例。它也会被「TCP 端口拨测」判定「国内外都不通」时阻止本轮写入。
• 阿里云 GTM　默认关闭。这条路走的是阿里云官方的「全球流量管理」产品：解析由阿里云自己应答，本程序只负责把机器上报的 IP 写进你那个 GTM 地址。它和独立的「GTM」区域（自研 GTM）是两条并行的路，不是新旧关系，用哪条都可以——自研那条不用额外买阿里云的付费产品、功能更全（地址池 / 分线路 / 多种健康模板）；官方这条更稳一点，因为分流和故障转移是阿里云自己在跑，不依赖本程序一直在线，代价是要先在阿里云开通全球流量管理、而且只支持阿里云。两个模块互不干扰，也可以并存。机器不直接调用阿里云，只上报 IP，由控制面用「凭证区」的 AccessKey 调用阿里云 GTM API。GTM 3.0 / Cloud Address 只需填地址 ID；GTM 2.0 / Address Pool 需要地址池 ID + 匹配备注。多活模式下单地址不会随机写入，避免「最后上报的 IP 覆盖目标」。
• 阿里云 GTM · 按时间自动停用 / 启用　可选，默认关闭，只支持 GTM 3.0 / Cloud Address。粒度到「地址」级：一个配置一条排班，管的就是这个配置对接的那一个 GTM 地址。两种模式二选一（和自研 GTM 那边完全一样的口径）：「停用时段」= 列出来的时段停、其余时间开；「启用时段」= 只有列出来的时段开、其余时间全停。支持每天重复或按星期几（一行 = 星期几 + 一个时段）。⚠️ 时区是这份配置自己的，必须显式选一个（IANA 地区名，如 Asia/Shanghai）——不选就一分钟都不生效，我们绝不替你猜（猜一个就等于在你从没同意过的时刻停解析）。⚠️ 停用是真的去调阿里云接口把那个地址停掉，不是「我们不写了」；我们看不到你阿里云账号里的拓扑（只存了一个地址 ID），如果这是它所在地址池里唯一一个可用地址，停用窗口里那条线路在阿里云侧就没有可返回的地址了，请自己先确认池里还有别的地址。把排班关掉、把这份配置整个停用、或者删除这份配置时，如果它正被我们停着，都会先还原为启用；其中删除这条路更严格——还原失败会直接不让删、把原因告诉你，只有你在还原失败之后主动确认「就这么删」，那个地址才会留在停用状态，需要你自己到阿里云控制台改回启用。精度分钟级，生效时刻落在窗口边界之后的 0~59 秒。
• TCP 端口拨测　默认关闭，默认探测端口 22（可自定义）。国内和国外分别选择拨测节点（节点在「拨测节点区」维护，Globalping / HTTP 接口 / 自建 Agent 都可选），连续复测确认后才触发动作，减少网络波动误判。
• 拨测结果 → 动作　国内通 + 国外通：正常，不动作。国内不通 + 国外通：可调用 Worker HTTP 动作，也可下发服务器命令（需先开启「允许下发 root 命令」）。国内通 + 国外不通：只记录结果，不执行切 IP 动作。国内外都不通：判定可能死机 / 补机中，不误切 IP，并阻止本轮 DDNS / GTM 写入。
• Worker HTTP 动作　TCP 模块的子功能，触发条件同上（国内不通 + 国外通，且连续复测确认）。Worker 用 fetch 调用你填写的 HTTP/HTTPS API，适合调用「切换 AWS IP」之类的外部接口。可用变量：

  {{ip}} {{target}} {{port}} {{agentId}} {{agentName}} {{side}} {{location}}

• 怎么出现的　配置对应的机器执行开机命令后，Agent 上报即自动出现在这里，不需要手动添加。
• 状态判定　在线 → 疑似掉线 → 离线，三档时间阈值（在线判定超时 / 离线判定小时）在「全局设置」里配置，只影响状态显示，不影响实际写入逻辑。
• 角色　活跃写入（当前 active，会被写进 DDNS / GTM）／备用只记录／已被替换／多活有效（多活模式下所有在线机器都算有效）。
• SSH 面板　配置里开了「root SSH 密码托管」的机器，这里能看公网 IP / SSH 用户 / 密码（可切换显隐）/ 一键复制 SSH 命令或密码。
• 清理离线　「清理离线」按钮一键清理所有非在线记录（在线的不会被删）。⚠ 这是唯一真正把机器记录从存储里删掉的动作：「全局设置 → 自动清理」里那个天数只负责把超期的机器从列表里隐藏起来，它们不会自己消失。

• 两种类型　全量模板（保存整套配置：基础 + 服务器·系统 + 解析·故障切换所有模块）；单模块模板（只保存一个模块，如只存「TCP 拨测」或只存「内置 DDNS」的设置）。
• 怎么存　在配置编辑器里，每个模块小节旁边都有「存为模板」按钮，直接把当前填写内容另存；也可以在「模板」页新建 / 编辑。
• 怎么用　新建或编辑配置时，在对应标签选一个模板即可套用其内容（全量模板套整套配置，单模块模板只覆盖那一个模块，其余模块不受影响）。
• 列表范围　只显示当前账号自己保存的模板；新建配置默认选中「自定义」，切回自定义会恢复切换模板前手填的内容，不会丢失。

GTM 独立于开机配置，是「候选地址 → 健康检查 → 打包 → 策略 → 一条域名解析」的完整流水线，共 4 个标签：实例 / 健康模板 / 地址 / 地址池。

• 是什么　一次 TCP 探测的定义：端口、尝试次数、重试间隔（秒）、用哪些拨测节点。定义一次，可以被多个「地址」复用。
• 默认　新建 GTM 实例自带一个「TCP 22」健康模板，也可以在「GTM → 健康模板」标签单独新增/编辑，供多个地址共用。
• 达标比例（默认 50%）　本轮真正给出了结论的拨测节点里，测通的占比达到这个比例才算健康。⚠️ 分母不是「这个模板配置了几个节点」，而是「这一轮真正给出了结论的节点」——掉线、超期、探测器自己不可用的节点不进分母，所以一个坏掉的节点不会把一个活着的地址拖到阈值以下判死。另外多节点模板有防抖：要有两条说不通的上报才允许判死，一条反对票只能待定。

• 是什么　候选 IP / 域名的来源，加上「用哪个健康模板探测它」。三种来源模式：自定义 IP（手填一批 IP）、域名（手填一批域名）、引用配置在线 IP（取某个开机配置当前的在线 IP）。
• 「域名」这一档到底写出去什么　写出去的就是这个域名本身，作为 CNAME 记录 —— 控制面不会先把它解析成 IP 再写 A 记录。健康探测打的也是这个域名，所以「本机自带测活节点」测不了它（那个节点只能拨测公网 IP 字面量），要用自建 Agent / Globalping / HTTP 接口节点。另外 DNS 不允许同名混用 A 和 CNAME：同一条记录下 IP 和域名混在一起时，写入会丢弃其中一类并在运行历史里明确报出来，请把它们拆到不同的地址池。
• 手动状态　自动（按健康模板探测结果判定）／强制在线／强制离线，用于临时摘除或强推某个地址，不用等探测周期。
• 权重 / 优先级　同一个地址池内，多个地址按池内策略（轮询 / 权重 / 顺序）从这里取值参与计算。⚠️ 最终生效的权重是「这个地址在某个地址池里」的成员设置：地址自己那份只是默认值，池内成员权重会盖在它上面——所以同一个地址被两个池引用时，可以在两个池里各有各的权重。

• 是什么　把若干「地址」打包成一个池，池内按策略（轮询 / 权重 / 顺序）选值；「最小可用数」决定这个池要凑够多少个健康地址才判定为整体可用。
• 服务线路　分线路解析时，给每个池指定它负责哪些运营商线路（默认 / 电信 / 联通 / 移动 / 教育网 / 境外……可自定义输入）；没配线路的池在分线路模式下不会输出到任何线路。

按运营商 / 地域配置不同的解析结果——电信用户查到电信线路的结果、联通用户查到联通线路的结果。一句话版本：按地址池的排列顺序、逐条线路首匹配，匹配到但不够健康就顺延到下一个，「默认」线路永远兜底。

• 仅阿里云 DNS 支持　分线路解析仅阿里云 DNS 支持。Cloudflare 走的是另一条路：要靠 Cloudflare 负载均衡，而且非 Enterprise 套餐下按地域分流还需要额外加购 Traffic Steering，否则只提供「顺序兜底」和「权重」两种调度。
• ① 地址池是有序的　一个实例引用的地址池按序号排成一个有序列表，面板里可以用 ↑↓ 调整顺序。这个顺序就是下面「首匹配」的查找顺序。
• ② 一个池可以同时服务多条线路　「这个池在这个实例里服务哪些线路」是「实例 ↔ 地址池」这层引用关系的属性，不是地址池自己的属性——同一个池在另一个实例里可以服务另一组线路。
• ③ 首匹配　对每一条目标线路，系统按地址池的排列顺序从上到下找：找到第一个「配置为服务这条线路（或配置为『默认』兜底）」并且「健康成员数达到最少可用数」的地址池，就用它的输出——排在它之后的池哪怕更健康也不会再被看。
• ④ 不够健康就顺延　排在前面的池匹配了这条线路但健康成员不够，就跳过它，继续往后找下一个匹配这条线路的池——这就是分线路场景下的健康故障转移。地址池被排班停用时同样跳过、顺延到下一个。
• ⑤ 「默认」永远兜底　没有被任何具体线路覆盖到的访客，查到的是「默认」这条线路的结果。强烈建议在地址池列表里放一个服务「默认（全部）」的池垫底，否则冷门线路的访客可能什么都查不到。
• 池内部也是同一套规则　如果一个地址池自己的策略被设成「分线路解析」，它会对自己的成员地址做一次同样逻辑的嵌套匹配。

地址和地址池都能设「排班」：到点自动停用、过了自动回来，不用人守着。它和健康检查是两层独立的闸门——排班放行不代表健康，健康好也挡不住排班；一个地址真正进解析，两层都得过。

• 停用时段 / 启用时段，二选一　停用时段（默认）：列出来的时段关，其余时间开，适合「每天凌晨 2-5 点维护」。启用时段：列出来的时段开，其余时间全关，适合「只在 9:00-18:00 提供服务」。⚠️ 同一组时间在两种模式下含义正好相反（「08:00-09:00 停用」= 一天关 1 小时；「仅在 08:00-09:00 启用」= 一天关 23 小时），所以切换模式时面板会弹确认并告诉你切换后每天会关多少小时。选了「启用时段」却一个时段都不填 = 任何时候都不启用，保存会被拒绝，不会把它悄悄关光。
• 每天重复 / 按星期几　默认「每天重复」，整个星期列都不出现，不用勾任何星期。切到「按星期几」后，星期几是跟着每一行时段走的，不是整条规则共用一组星期——所以「周一 08:00-09:00、周二 13:00-14:00」写得出来：加两行、各勾各的天；同一天也可以有好几行。⚠️ 「按星期几」模式下每一行都必须至少勾一天，一天都不勾的那一行什么都不做，保存时会点名是第几行并报错。
• 时间窗怎么算　半开区间：设 08:00 至 09:00 = 08:00 起停用、09:00 整自动恢复。结束时间比开始时间小 = 跨午夜（23:00 至 01:00 = 今晚 23:00 到明早 01:00），跨午夜的时段锚定在它开始的那一天（勾「周一」+ 23:00 至 01:00 = 周一晚 23:00 到周二凌晨 01:00）。停一整天写 00:00 至 24:00。一条规则最多 24 行。
• 时区挂在 GTM 实例上　一个实例只能有一个时区，在实例编辑里设，这个实例下所有地址/地址池的排班都按它算。⚠️ 实例没设时区 = 这条排班完全不生效（不会拿浏览器时区或 UTC 去兜底——不知道你说的「8 点」是哪儿的 8 点，系统不会猜），面板会红字说明并给一个「去实例设置时区」的入口。只能选 Asia/Shanghai 这种地区名，不收 +08:00 这种固定偏移（它不含夏令时规则，一到切换日整体错一小时）。
• 设了排班的资源不许被不同时区的实例共用　地址和地址池是独立资源、按 id 被多个实例引用，而时区挂在实例上——同一个池在上海实例里正被停用、在伦敦实例里同一时刻可能正启用，面板不可能同时显示两种状态。所以保存时会拦下来，并点名是哪个资源、被哪几个实例用了哪几个时区。处置办法：把资源复制一份，两边各用各的（复制出来的是独立资源，改一份不会动到另一份）。没设排班的资源完全不受这条限制。
• 保存前会先演一遍，防止把某条线路排空　保存排班（以及调整地址池顺序）时，系统会把未来 7 天按分钟演一遍——7 天而不是 1 天，是为了让「只在周一停」这种排班在任何一天保存都能被检查到。如果这套排班会让某条线路在某一刻一个可用地址都不剩，保存会被拒绝，并告诉你是哪条线路、哪个时间段（带星期几）、被哪几个地址/地址池同时停掉的。处置办法通常是给这条线路留一个不参与排班的兜底资源，或者把几个停用时段错开。⚠️ 这个检查只管排班，不预测健康检查——健康那一层挂掉仍按原来的故障转移规则走。
• 停用之后长什么样　列表里「排班」和「健康」是分开的两列：被排班停的显示「排班停用中」（橙色），被健康检查判死的显示「不健康」（红色），查问题时一眼知道该看哪边。地址池被排班停用时，分线路解析会跳过这个池、顺延到下一个匹配这条线路的池（最后落到「默认」兜底），不是把这条线路变成没有解析结果。
• 精度　分钟级。同步每分钟跑一轮，实际生效落在整分之后的 0~59 秒内，不承诺秒级。

• 是什么　选若干「地址池」+ 一套策略，输出到 AliDNS 或 Cloudflare 上的一条域名；新实例只需要在「地址池」标签勾选池、在「策略」标签定策略、在「输出」标签选服务商 / 域名。
• 负载策略　轮询 / 权重 / 顺序 / 分线路解析（仅阿里云 DNS 支持，按运营商线路各解析各的池；Cloudflare 不支持分线路解析）。
• 策略标签（非分线路）　多池同时生效，或主备切换（选首选池 / 备用池，故障切换模式：自动 / 固定首选池 / 固定备用池）。要按运营商线路分别解析，要去「地址池」标签给每个池配服务线路，不是在这个标签配。
• 实时性　外部拨测节点上报结果会立即重算并改解析（实时）；只用内置探测时最坏约 1 分钟（cron 巡检）才发现变化。
• 预览（dry-run）　点「预览」按当前健康探测结果试算将写入的 DNS 记录，不会真正写入；确认无误后再点「立即运行」，也可以直接在预览弹窗里确认运行。
• 清空（drain）　点「清空」会强制按本次计算结果覆盖 DNS（即便结果为空），用于清理陈旧解析记录；这是唯一会主动写入「空结果」的操作，请谨慎点击。
• 兜底行为（不会误清空）　健康模板被删除 / 禁用导致地址探测不到结果时，保留上次已知解析，不会误判成「全部健康」而写入源 IP；实例计算结果为空但之前有输出时，同样保留上次输出，不会误删已有解析记录。
• 旧结构提示　早期实例把地址 / 池直接内嵌在实例里（旧「内嵌」结构）；编辑这类实例时面板会提示可一键「拆分到资源库并改为引用」，拆完就能像新实例一样只在「地址池」标签勾选。

产品里有两套各自独立的探测机制，共享同一个「拨测节点区」资源池，但服务的下游完全不同。查问题时先分清是哪一套在说话。

• GTM 健康模板　决定「一个地址算不算健康」，进而决定 GTM 实例最终输出的解析。实例策略选「顺序」时就是主备语义：主用的挂了，自动顶上备用的。细节见「GTM · 健康模板」。
• 配置里的「TCP 端口拨测」　决定的是「这台机器是不是不可达、要不要触发动作」，不参与 GTM 的健康判定。四种拨测结果各自对应什么动作，见「配置与脚本 · 解析·故障切换标签」的「拨测结果 → 动作」那一条；其中「国内外都不通」会阻止本轮 DDNS / GTM 写入，避免补机过程中误切。
• 兜底：不会误判成全部健康，也不会误删已有解析　找不到健康结果时保留上次已知解析，不会误判成「全部健康」写入源 IP；实例计算结果为空但之前有输出时，同样保留上次输出。唯一会主动写入「空结果」的是手动点「清空（drain）」。
• 多快能切过去　自建 Agent 型拨测节点一回传结果，控制面当场重算受影响的实例并改解析；其余几种跟着巡检走，最坏约 1 分钟。真正到访客那边还要再加上 DNS 记录 TTL 的生效时间——所以产品不承诺零停机，见「如实告诉你：这几件事目前做不到」。

• 当前支持的类型　只有两种：阿里云 AccessKey（AccessKey ID + Secret）、Cloudflare DNS（API Token）。旧版本的「动作 / HTTP 接口」凭证类型已下线——外部测活现在统一由「拨测节点区」负责，不再挂在凭证区下面。
• Cloudflare 为什么只收 API Token　账号级的「邮箱 + Global API Key」是一把钥匙开整个 Cloudflare 账号的全部权限（DNS、账单、域名转移都在内），一旦泄漏没有中间地带，Cloudflare 官方也已计划弃用它，所以这里不再提供这种鉴权方式。API Token 相反：可以只授一个站点、只授 DNS 编辑，能单独吊销、能设有效期，对你是更安全的一侧，不是少了个选项。
• API Token 去哪儿建、要勾什么权限　Cloudflare 控制台 →「我的个人资料 / My Profile」→「API 令牌 / API Tokens」→「创建令牌 / Create Token」，选「编辑区域 DNS / Edit zone DNS」模板，把「区域资源 / Zone Resources」限定到你要用的域名。若还要用 Cloudflare 负载均衡（分线路），再额外勾上账号级「Load Balancing: Monitors and Pools Write」和该站点的「Load Balancers Write」。
• 谁在用凭证　内置 DDNS、GTM 实例（阿里云 / Cloudflare 输出）、配置里的「阿里云 GTM」模块，都是选凭证 ID 引用，不会各自另存一份密钥。
• 安全存储　密钥加密存储；列表和摘要只显示掩码（如 AK 前后各 4 位），修改时才需要重新输入完整值。
• 删除影响　删除凭证后，已引用它的配置 / GTM 实例会失去这个引用，需要重新选择，请谨慎操作。

• 用途　统一维护所有「测活」来源，供「TCP 拨测」模块和「GTM 健康模板」共同复用，改一处、两边都生效。
• 内置节点　共三个：本机自带节点 + 两个 Globalping 预设节点（国内 / 境外），默认存在，不能删除、不能修改（列表里标「内置」），也不占授权的拨测节点名额。
• ⚠️ 自建部署上「本机自带节点」用不了　本机自带测活节点唯一的实现手段是 Cloudflare Worker 才有的 socket 接口，自建 / 二进制部署（也就是这台机器）上它永远给不出结论。健康模板里只挂它 = 健康判定永远判不出「不健康」= 故障切换形同虚设。系统不会静默吞掉这件事：它会作为「配置错误」在实例上明确报出来，请把这类模板里的节点换成自建 Agent 型节点。
• 四种可配置类型　自建 Agent（部署在你自己的机器上，主动拉取任务并回传结果）；Globalping（第三方多地探测网络，可指定 Location / 节点数 / 每节点包数）；HTTP 接口（自定义 URL + 方法 + Headers/Body，Worker 直接调用）；阿里云站点监控（付费，见下方单独一条）。
• 安装 / 回传方式　只有「自建 Agent」节点需要复制安装命令到目标机器执行；它每分钟拉取一次任务并回传结果。本机自带节点、Globalping、HTTP 接口、阿里云站点监控都由 Worker 即时发起调用，不需要安装。
• 实时性　只有「自建 Agent」是把结果推回来的：它一回传结果，控制面当场重算受影响的 GTM 实例并改解析，不用等下一轮巡检。其余几种（本机自带 / Globalping / HTTP 接口 / 阿里云站点监控）都是由控制面在巡检那一轮里现去调用或现去取结果，所以最快也是跟着巡检走，最坏约 1 分钟。
• 阿里云站点监控（付费，会花真金白银）　第三方视角的按次计费拨测，最快 1 分钟一次（默认 5 分钟，频率越高账单越高）。新建时必须选一个阿里云凭证 + 至少一个探测点（拉取探测点列表本身免费）；一个探测点都不选就不会建任何任务，也不会产生费用。批量启用这类节点、或单个节点预计月开销上涨超过阈值时，保存前会弹确认框把预计花费说清楚。
• 阿里云站点监控 · 计费与限制　按量计费没有免费额度（开通动作免费，第一次探测就开始算钱），也没有满一万次才计费的进位规则。单价按运营商 + 地域档位分档（移动端探测点比固网贵 36 倍），价格写死在程序里、阿里云调价不通知也不会自动更新——本页顶部「当前月开销」卡片只在存在这类节点时出现，展示的是按当前真实任务条数算出的估算金额，标注了取价日期与官网核对链接，实际花费以阿里云账单为准。任务条数和探测点数都没有上限，系统不会替你砍掉超出的部分——砍掉会让你在不知情的情况下失去故障切换，所以改成只把开销显示清楚。
• 阿里云站点监控 · 只挂它会怎样　健康模板里可以只挂阿里云站点监控，系统不拦你，但保存时会提示一次风险：它是付费的、有采集延迟，一旦欠费、被限流或阿里云侧延迟，这个模板下的地址会集体失去健康依据、停在「待拨测」；而 GTM 实例在有待拨测地址时不会改动解析——表现出来就是解析悄悄不再更新，而且哪儿都不报错。建议再搭一个自建 Agent 或内置节点兜底，搭了之后这条提示就不再出现。
• 阿里云站点监控 · AccessKey 权限建议　强烈建议单独建一把最小权限 AccessKey，不要用管 DNS 的那把：在 RAM 里新建一个用户，只授一条自定义策略（Action 仅 cms:CreateSiteMonitor、cms:ModifySiteMonitor、cms:DeleteSiteMonitors、cms:DescribeSiteMonitor*，Resource 可先用 *）。这样万一这把 key 泄漏，对方也只能动站点监控任务，动不了你的解析记录。

• 管理员账号与访问路径　改用户名 / 密码、改面板访问路径都在这里，改之前页面会先提示后果：改密码后，其它设备上已登录的会话全部失效需要重新登录，当前这个窗口不受影响；改面板路径后旧地址立刻打不开（面板和全部管理接口一起搬家），保存时会二次确认，保存后自动跳到新地址，记得更新书签。面板路径出厂就是安装时随机生成的一串（不是固定的 /gtmag），忘了地址不要来猜——在服务器上用 --show-panel-path 查当前真正生效的路径（用法见 README，仅自建部署适用）。Agent 上报和拨测节点回连走的是固定接口，不跟着面板路径走，改路径不会让已装探针失联。
• 会话安全 · 退出所有设备　怀疑面板登录状态被盗用时用这个按钮：一键让所有设备的登录立刻失效，需要重新输入用户名和密码。跟「改密码」不一样——改密码会保留你当前这个窗口不掉线，这个不会，⚠ 点下去之后你自己这个窗口也会被一起踢下线，需要重新登录一次。
• Agent 回调基础 URL　开机 / 安装命令里 Agent 回连 Worker 使用的域名，留空则用面板自身域名；非 localhost 必须使用 HTTPS，否则保存会被拒绝。⚠ 改这一项会影响已经装好的 Agent：它们每轮都会从控制面拉一次回连地址并按新值更新自己，所以新地址必须是这台控制面真实可达的域名——填成一个解析不到或证书不对的地址，探针会集体连不上。
• 在线判定超时（分钟）　超过该时间未上报，服务器从在线变为疑似掉线；只影响状态显示，取值范围 1-1440。
• 离线判定（小时）　超过该时间未上报，服务器从疑似掉线变为离线，取值范围 1-8760。
• 自动清理（天）　超过该时间未上报的机器，从「已对接服务器」列表里隐藏，不再显示、也不再进入 DDNS / GTM 的 IP 池；取值范围 1-3650。⚠ 隐藏不等于删除：那条记录仍然留在存储里（也仍然算进本月 KV 用量估算），真正把它删掉要在「已对接服务器」页点一次「清理离线」。把天数调大之后，先前被隐藏的机器会重新出现。
• 补机接管（秒）　只给「保守心跳」接管模式使用：旧 active 超过该时间未上报，新机器才接管；外部补机模式不等待此项，取值范围 30-3600。
• 备份与恢复　导出：把凭证 / 拨测节点 / GTM 实例 / 配置 / 模板 / 全局设置整体导出为一份 JSON 备份，机密字段以密文导出，授权本身不在导出范围内。导入：从备份文件恢复，同名条目会被覆盖，且需要与导出时相同的 CREDENTIALS_SECRET 才能解密机密字段；运行时数据（已对接服务器）不在备份范围内。授权有数量限制时，导入还要再过一道限额检查：恢复后 GTM 实例 / 配置与脚本 / 凭证 / 拨测节点这四类的数量都不许比恢复前更多，卡住任何一类就整份备份一个字节都不会写入。换一台全新机器（当前一个都没有）去恢复一份超过授权额度的备份，会被直接拒绝并提示升级套餐——这种场景不做例外，本机自己原地恢复自己刚导出的那份备份不受这条限制影响。

• 地址　Worker 域名下的 /health，公开访问，不需要登录。

  GET https://<你的Worker域名>/health

• 用途　给外部监控（如 UptimeRobot、云厂商健康检查）确认 Worker 本身在正常运行；不反映某台服务器或某个 GTM 实例的健康状态——那些要看「已对接服务器」和「GTM 实例」页面。

让你自己的程序直接调这套面板的接口：按权限项勾选，可选填 IP 白名单和有效期，随时可以单独吊销。没有「全权」这一档。

• 明文只显示一次　⚠ 令牌明文只在创建那一屏显示一次，关掉那一屏之后再也看不到——服务端只存哈希，我们自己也拿不回来。请当场复制到密码管理器或 CI 的机密变量里，弄丢了只能吊销重建，不能找回。
• 调用域名必须匹配　令牌调用也必须走授权绑定的那个域名（和面板同一把锁，令牌不豁免）：用服务器 IP、127.0.0.1、SSH 隧道或别的域名去调，一律返回和未知路径完全相同的 404——那不是「接口没了」，也不是令牌坏了。
• 做不到的事　看机器 root 密码、导入备份、保存一份会以 root 跑遍机群的配置——这几件事要求「有人坐在浏览器前」，令牌一律做不了，会被明确拒绝，请在面板里手工做。
• 吊销的传播延迟　自建 / 二进制部署吊销立刻生效；如果这套跑在 Cloudflare Worker 上，存储是最终一致的，最长可能有约 60 秒传播延迟。

授权对应的是自建部署的控制面本体——你自己一台服务器上跑的那个可执行文件。这一页管的就是它：还剩多少天、四类资源各用了几个、到期之后什么会被锁住、什么永远不会停。

• 没有试用期　没激活授权 = 从装完第一分钟起配置就是只读的，不会先给一段免费试用期；装机时联网会自动用激活码完成激活解锁，不需要装完再手动走一遍。
• 锁定只锁「改配置」　未授权 / 已过期 / 授权无效时，只有新增、修改、删除配置这类写操作会被拒绝。域名解析、健康检查、故障切换、Agent 上报、拨测回传、面板登录查看、导出备份都照常运行，不会中断——授权到期不是故障，只是欠费。
• 没有宽限期　到期当天配置立刻变只读，没有「过期后还能再改几天」的缓冲；到期前 14 天面板会开始提示剩余天数，别等到最后一刻才续费。续费或重新激活后，面板立即恢复可编辑，不需要重启。
• 四类数量限额　GTM 实例 / 配置与脚本 / 凭证 / 拨测节点，各自独立计数。某一类在授权里缺失该项、填了 null 或 0，都表示这一类不限量。内置的 本机自带拨测节点和 Globalping 预设节点不占拨测节点的名额。
• 「满了」只挡新建　用量正好等于上限时，只有「再新建一个」会被拒；已经建好的照常改、照常删，解析和故障切换完全不受影响。
• 「超了」会锁住这一类的「改」　降级套餐导致存量超过新上限时（用量 > 上限），这一整类资源的编辑会被暂时拒绝，直到你把它删回额度以内为止。存量不会被停用、不会被删除，解析和故障切换一秒都不停，锁的只是面板上的编辑动作。删除永远放行——那是唯一的恢复路径；删到用量等于上限（是「等于」就够，不用删到更少）这一类立刻自动解锁。拒绝提示会直接告诉你这一类现在几个、允许几个、还要删几个。四类各锁各的，GTM 实例超了不会连累凭证。
• 激活方式　正常路径是装机时联网自动完成：安装脚本会把买到的激活码发给授权服务器换回一份签好名的授权文件，换回来之后校验都在本机完成，不需要一直联网，客户第一次打开面板通常已经是「已激活」状态。「授权与购买」页上仍然留着一个「换码 / 重新激活」的入口，用来处理换了新激活码（续费/换套餐买到新码）或者需要在这台机器上重新激活这两种情况。授权页会自动周期性联网复核一次（快到期或已过期时更频繁），取回续费后的新授权；复核失败不影响当前授权是否有效——授权文件自带签名和到期时间，联不上服务器不代表授权失效。⚠️ 在线激活拿到的其实是一张有效期 45 天的「租约票」：客户端会在租约到期前自动联网续签，每次成功续签换回一张「从此刻起 45 天」的新票，正常联网使用完全感觉不到这条规则；只有**连续 45 天一次都没联上**面板才会因为票过期而变成只读。面板上显示的「到期时间 / 剩余天数」一律说的是**订阅**，不是这张租约票。
• 换机器 / 迁移　授权绑定的是「本机安装编号」（不是硬件或域名），换一台机器要在新机器上重新输入激活码完成迁移；如果检测到本机安装标识像是被重建过（比如手工删过部分数据后又恢复），重新激活会占用发证服务器上的一个安装名额，这种情况建议先联系供应商处理，不要自己反复重装重新激活。
• 购买 / 续费 / 加购　面板里不下单、不收款——「授权与购买」页只给一个「前往购买页」的按钮，跳到我们自己域名的购买页完成域名归属验证与人机验证，买到后拿到一张激活码，回到面板「换码 / 重新激活」填进去即可。购买页地址由供应商在后台配置，没配置时按钮会灰掉并说明「购买页尚未配置」，不会出现一个点了 404 的按钮。
• 出问题联系谁　授权到期、验签失败、账号被封禁……面板里几十处提示的落款都是「请联系供应商」，具体联系方式挂在左侧侧边栏底部（退出登录按钮上方），固定显示，不是只在出错那一刻才冒出来。这是供应商（分发者）装机时用 install.sh --support-contact= 写进服务器本地 keepalight.env 的一句话（邮箱 / 网址 / 群号都行），客户在面板里只能看，改不了。如果分发者当时没填，侧边栏会如实显示「未配置支持联系方式」——不会编一个打不开的邮箱地址糊弄人。