IP 守护面板
==============

作用
----
面板装在一台服务器上，定时检测源站 IP 的端口。

- 大陆能连上：不处理。
- 大陆连不上、海外能连上：判定被墙。连续失败达到次数后，POST 换 IP 网址，等专属域名解析出新 IP，再把这个 IP 写成 Cloudflare 的 A 记录。
- 大陆和海外都连不上：默认认为是服务自己没开，不换 IP，避免把 IP 换掉仍旧没用。

检测机器建议放在大陆。只有装在会被墙影响的网络里，检测结果才有意义。


一、上传到宝塔
--------------
1. 把 dist 目录里的「cf-ip-guard-宝塔上传.zip」上传到宝塔。
2. 解压到网站根目录：
   /www/wwwroot/api-cf.ladder-cat.com/
3. 解压后应能直接访问：
   https://api-cf.ladder-cat.com/
   https://api-cf.ladder-cat.com/install.sh
   https://api-cf.ladder-cat.com/cf-ip-guard.tar.gz
4. 这个目录只是安装包下载站，不要把面板 data 目录放进来。安装包里带有当前面板设置，包含换 IP 网址和 Cloudflare 密钥。
5. 如果站点开了防盗链或禁止下载 sh、gz，需要关掉，否则另一台机器拉不下来。


二、在另一台服务器安装
----------------------
用 root 登录要安装面板的 Linux 服务器，执行：

  cd /tmp
  curl -fL -o install.sh "https://api-cf.ladder-cat.com/install.sh"
  bash install.sh "https://api-cf.ladder-cat.com/cf-ip-guard.tar.gz"

没有 curl 时：

  wget -O install.sh "https://api-cf.ladder-cat.com/install.sh"
  wget -O cf-ip-guard.tar.gz "https://api-cf.ladder-cat.com/cf-ip-guard.tar.gz"
  bash install.sh ./cf-ip-guard.tar.gz

指定面板端口：

  bash install.sh --port 12580 "https://api-cf.ladder-cat.com/cf-ip-guard.tar.gz"

系统需要 Ubuntu 20.04、Debian 11 或更新的发行版。脚本会优先使用已经安装的 Node 18 及以上；没有的话会从国内镜像下载独立 Node，不改系统原来的 Node。

安装位置：
- 程序：/opt/cf-ip-guard
- 配置和密码：/opt/cf-ip-guard/data
- 端口配置：/etc/cf-ip-guard.env
- 服务名：cf-ip-guard

装好后放行端口：
- 云服务器安全组放行 12580/tcp
- 宝塔「安全」里也放行同样端口
- 浏览器打开 http://服务器IP:12580 ，默认管理员密码是 admin。登录后可以在设置里修改。

常用命令：
  systemctl status cf-ip-guard
  systemctl restart cf-ip-guard
  journalctl -u cf-ip-guard -f


三、面板里要填的内容
--------------------
1. 检测
   - 检测目标：源站 IP，或 VPS 面板里的专属域名。
   - 端口：只填真正对外的端口，例如 443。不要填本来就没开的端口。
   - 本机所在网络：面板装在大陆，保持「大陆」。超时只记录，不换 IP。大陆明确连不上才换 IP。
2. 更换 IP
   - 换 IP 网址：从 VPS 面板复制「换 IP 随机网址」。它等同密码。
   - 请求方式：按服务商说明，常见是 POST。
   - 专属域名：永远指向当前公网 IP 的那个域名。换 IP 后用它确认新地址。
3. Cloudflare 域名
   - API Token：在 Cloudflare 创建，权限至少包含 Zone 读取、Zone DNS 编辑。用这种时邮箱留空。
   - Global API Key：和注册邮箱一起填写。只填密钥、不填邮箱时，Cloudflare 不会接受。
   - Zone ID：可点「查找 Zone」。
   - 解析域名：一行一个，例如 vpn.example.com。根域名可填 @，但要先有 Zone ID。
   - 仅 DNS（灰云）：域名直接指向新 IP，适合客户端直连源站。
   - 已代理（橙云）：只更新源站地址，访客仍先访问 Cloudflare。
4. 先点「保存设置」。
5. 点「测试连接并读取解析」确认 Token 可用。
6. 点「把当前 IP 写入 CF」，先把域名指到现在的 IP。
7. 点「立即检测」看端口结果。
8. 确认无误后，打开右上角「自动换 IP」。

自动换 IP 默认连续失败 3 次才更换。平时约 15 秒检测一次；已经明确连不上时，约 8 秒再确认一次。换完冷却 10 分钟。
单次连接默认最多等 3 秒。超时只记录，不换 IP。
检测目标如果填的是 IP，换成功后会自动改成新 IP。填专属域名则不用改。
首页「记录」可以清除，换 IP 历史会保留。
这次的安装包带有当前面板设置。新机器第一次安装会直接用这些设置。如果 /opt/cf-ip-guard/data/settings.json 已经存在，安装不会覆盖它。


四、升级
--------
把新的上传包解压覆盖宝塔里的 cf-ip-guard 目录，然后在业务服务器重新执行安装命令。
/opt/cf-ip-guard/data 和 /etc/cf-ip-guard.env 会保留。


五、卸载
--------
安装包里的 uninstall.sh 可以单独执行：

  bash uninstall.sh

这会停掉服务并删除程序，但保留 data 目录。彻底删除：

  rm -rf /opt/cf-ip-guard /etc/cf-ip-guard.env


六、注意
--------
- 换 IP 网址、Cloudflare Token 和面板密码都只在业务服务器的 data 目录里。
- 不要把 data 目录同步到公开网站，也不要发给别人。
- VPS 面板里一旦刷新换 IP 网址，旧网址立刻失效，要回到本面板重新填写。
- 自动换 IP 会真实调用服务商接口并修改 Cloudflare 解析，请先手动检测和手动写入各成功一次。