单 IP 防护接入

策略覆盖范围

「封海外，不封港澳台」放行中国大陆和港澳台的来源网段。「封海外，含港澳台」仅放行中国大陆来源。两种模式均放行本地配置的可信网段，未归类来源会被丢弃。
「封入站 UDP」丢弃外部发起且指向此 IP 的 UDP 流量，包括 UDP DNS、QUIC 和游戏协议。由业务 IP 主动发起的 UDP 会话，其回包仍由原有防火墙处理。
HTTP CC 在 Nginx 上按来源 IP 限制 HTTP/HTTPS 请求，支持请求速率和突发额度，超额返回 429。每个目标 IP 可独立配置。

网关规则覆盖经本节点及指定入口接口、已启用连接跟踪的流量。目标填节点在 INPUT 或 FORWARD 链看见的目的 IP。若流量在此之前做了 DNAT，填转换后的 IP。多个公网 IP 转换到同一个内部 IP 时，这个执行点无法区分它们。允许的地区仍须通过原有防火墙规则。

注册与配置

在中央平台点击「添加宿主机」，类型选择「IP 防护节点」。把项目中的 Agent 文件复制到实际流量入口的 Linux 节点。节点需要 Python 3.8 或更高版本。使用封海外或封 UDP 时安装 nftables。启用 CC 时需有正在运行的 Nginx HTTP/HTTPS 入口。

sudo install -d -m 700 /etc/vm-ip-guard
sudoedit /etc/vm-ip-guard/config.json
sudo chmod 600 /etc/vm-ip-guard/config.json
sudo install -D -m 644 agents/edge.py /opt/vm-bandwidth/edge.py
sudo install -m 644 agents/vm-ip-guard.service /etc/systemd/system/

下面的 IP、接口名、网段文件路径和令牌为示例。将目标替换为节点能直接匹配的 IP。每个目标可以独立开启防火墙能力或映射到 Nginx 站点。

{
  "url": "https://vm.example.com",
  "token": "该防护节点的独立令牌",
  "ingress": ["eth0"],
  "targets": [
    {"ip": "203.0.113.20", "firewall": true, "site": "web20"},
    {"ip": "2001:db8::20", "firewall": true}
  ],
  "cidr_files": {
    "CN": "/etc/vm-ip-guard/CN.cidr",
    "HK": "/etc/vm-ip-guard/HK.cidr",
    "MO": "/etc/vm-ip-guard/MO.cidr",
    "TW": "/etc/vm-ip-guard/TW.cidr"
  },
  "trusted": [],
  "nginx": "/usr/sbin/nginx"
}

从你选用的 IP 地理库导出四份 CIDR 文件，每行写一个 IPv4 或 IPv6 网段，可用 # 注释。每个所选地区必须有对应目标地址族的数据。文件缺失、格式错误或该地址族为空时，平台会收到失败回执，原有防火墙规则继续工作。UDP 单独启用时无需地理网段文件。地理封禁的准确度取决于所选地理库及其更新频率。

配置 Nginx 入口

仅使用防火墙时，省略目标的 site，可跳过本节。要启用 CC，先创建空文件并添加 include。宝塔 Nginx 的可执行文件路径按面板实际安装位置填写，例如 /www/server/nginx/sbin/nginx。使用自定义主配置时可添加 nginx_config。

sudo install -d -m 755 /etc/vm-ip-guard/nginx
sudo touch /etc/vm-ip-guard/nginx/http.conf /etc/vm-ip-guard/nginx/site-web20.conf

在主配置的 http 块添加下面这一行。

include /etc/vm-ip-guard/nginx/http.conf;

在服务目标 IP 的 server 块添加对应文件。为每个需要保护的 HTTP 或 HTTPS 入口配置 include。若某个 location 已单独定义 limit_req，Nginx 会以该层的规则为准，需在实际流量所经层级核对规则。一个虚拟主机同时服务多个目标 IP 时，应使用独立的监听和 server 配置来获得各 IP 独立策略。

include /etc/vm-ip-guard/nginx/site-web20.conf;

先用实际 Nginx 二进制执行 nginx -t 并重载。前置 CDN 或代理场景下，应按其可信源地址配置 Nginx Real IP，避免以代理地址对所有访客计数。网关封海外仍按网络层看见的源地址匹配。

Nginx 请求限速文档 · Nginx Real IP 文档

启动、验收与撤销

sudo systemctl daemon-reload
sudo systemctl enable --now vm-ip-guard
sudo journalctl -u vm-ip-guard -n 50 --no-pager

升级已运行的节点时，覆盖 Agent 和服务文件后执行 sudo systemctl daemon-reload 和 sudo systemctl restart vm-ip-guard。等节点完成一次同步后，再做离线重启测试。

在中央平台「IP 防护」找到节点上报的目标 IP，选择策略并等待回执。先使用测试 IP，确认入口接口、路由和目标地址匹配。
使用分别位于大陆、港澳台和其他地区的实际来源验证两种海外模式，再验证同节点的其他目标不受影响。用外部 UDP 请求验证封禁，并使用 sudo nft list table inet vm_ip_guard 检查丢弃计数。
从同一客户端向目标 HTTP 服务发出高于配置速率的请求，检查超额请求是否返回 429。CC 回执代表配置检查通过且重载命令已提交，实际流量需用请求和 Nginx 日志验证。
测试网关离线重启。先确认平台收到策略回执，再暂时断开测试网关到平台的连接并重启网关。Agent 会从 /var/lib/vm-ip-guard/firewall.json 恢复最近一次核对成功的 nftables 规则。重新连上平台后会继续同步最新策略。首次同步前，或平台地址、入口接口、受保护的目标 IP 变更后，需要连接平台生成新快照。
移除目标或停用节点前，先把海外、UDP、CC 全部关闭并等待回执。防火墙只管理独立的 vm_ip_guard 表。紧急解除本机网关规则时，先执行 sudo systemctl stop vm-ip-guard，再执行 sudo nft delete table inet vm_ip_guard 和 sudo rm -f /var/lib/vm-ip-guard/firewall.json。重启 Agent 前还要撤销平台上的对应策略。

nftables 规则文档