---

📋 目录

• 快速开始
• 概述
• 工作原理
• 前提条件
• 详细安装
• 配置
• 使用与验证
• 故障排除
• 卸载
• 许可证

---

🚀 快速开始

第 1 步：获取 API 令牌

在 tip.qfeeds.com 获取免费 API 密钥。

第 2 步：下载脚本

git clone https://github.com/Q-Feeds/NFtables-IPtables-integration-script.git
cd NFtables-IPtables-integration-script
chmod +x qfeeds-installer.sh qfeeds-uninstaller.sh

步骤 3：以 root 身份运行安装程序

sudo ./qfeeds-installer.sh

安装程序将：

1. 自动检测你的防火墙后端（nftables 或 iptables）
2. 提示你输入 API 令牌、拦截选项以及可选的白名单
3. 安装所有依赖项、更新脚本和 cron 任务
4. 立即执行首次完整同步

第 4 步：完成

你的服务器现已受到保护。cron 任务每 20 分钟检查一次更新（可配置），并且仅在许可证允许时才会实际调用 API。

---

📖 概述

此解决方案会定期从 Q-Feeds 下载最新的威胁情报源，并将其应用为防火墙规则（分步指南：NFtables/IPtables 设置），使你能够：

• ✅ 拦截来自已知恶意 IP 的入站连接
• ✅ 拦截发往已知恶意 IP 的出站连接
• ✅ 将你自己的 IP/CIDR 加入白名单，以免将自己锁在外面
• ✅ 基于你的 Q-Feeds 许可证自动调度
• ✅ 增量更新，通过基于差异的同步实现最低资源占用

为什么采用这种方法？

• ✅ 自动检测后端 — 无需手动选择即可在 nftables 或 iptables+ipset 上运行
• ✅ 快速 — 使用优化的哈希集合（nftables）或 ipset（iptables），几秒内加载 40 万+ IP
• ✅ 安全 — 使用专用表/集合 — 绝不触碰你现有的防火墙规则
• ✅ 高效 — 基于差异的更新仅处理变更部分，而非完整列表
• ✅ 可靠 — 自愈：检测到本地集合为空或不完整（例如重启后）时会重建它，并在差异同步失败时自动回退到完整同步
• ✅ 灵活 — 可选择入站/出站拦截，以及可选白名单

---

🔧 工作原理

后端检测

安装程序会自动检测可用的防火墙后端：

优先级	检测方式	后端
第 1	找到 nft 命令	nftables
第 2	找到 iptables 命令	iptables+ipset
—	两者均未找到	错误（退出）

检测到的后端会存储在配置文件中。更新脚本和卸载脚本会使用它来运行正确的防火墙命令。

架构：两种集合类型

两种后端都使用相同的拆分集合策略以实现最大性能：

nftables 后端：

┌─────────────────────────────────────────────────────────┐
│  table ip qfeeds                                        │
│                                                         │
│  ┌─────────────────────────┐  ┌───────────────────────┐ │
│  │ qfeeds_blacklist_v4     │  │ qfeeds_blacklist_v4   │ │
│  │ (hash set)              │  │ _nets (interval set)  │ │
│  │                         │  │                       │ │
│  │ Individual IPs          │  │ CIDR ranges           │ │
│  │ ~99% of entries         │  │ ~1% of entries        │ │
│  │ O(1) lookup & insert    │  │ O(log n) lookup       │ │
│  └─────────────────────────┘  └───────────────────────┘ │
│                                                         │
│  ┌─────────────────────────┐                            │
│  │ qfeeds_whitelist_v4     │                            │
│  │ (interval set)          │                            │
│  │ Your allowed IPs/CIDRs  │                            │
│  └─────────────────────────┘                            │
│                                                         │
│  chain input-chain (hook input, priority 0, accept)     │
│    → ip saddr @qfeeds_whitelist_v4 accept               │
│    → ip saddr @qfeeds_blacklist_v4 drop                 │
│    → ip saddr @qfeeds_blacklist_v4_nets drop            │
│                                                         │
│  chain output-chain (if enabled)                        │
│    → ip daddr @qfeeds_whitelist_v4 accept               │
│    → ip daddr @qfeeds_blacklist_v4 drop                 │
│    → ip daddr @qfeeds_blacklist_v4_nets drop            │
└─────────────────────────────────────────────────────────┘

iptables+ipset 后端：

┌──────────────────────────────────────────────────────────┐
│  ipset sets                                              │
│                                                          │
│  ┌─────────────────────────┐  ┌────────────────────────┐ │
│  │ qfeeds_blacklist_v4     │  │ qfeeds_blacklist_v4    │ │
│  │ (hash:ip)               │  │ _nets (hash:net)       │ │
│  │ maxelem 1000000         │  │ maxelem 65536          │ │
│  │                         │  │                        │ │
│  │ Individual IPs          │  │ CIDR ranges            │ │
│  └─────────────────────────┘  └────────────────────────┘ │
│                                                          │
│  ┌─────────────────────────┐                             │
│  │ qfeeds_whitelist_v4     │                             │
│  │ (hash:net)              │                             │
│  └─────────────────────────┘                             │
│                                                          │
│  iptables: INPUT/OUTPUT jump to a dedicated chain        │
│  (jump rule tagged -m comment "qfeeds"):                 │
│                                                          │
│  chain QFEEDS_INPUT (rebuilt each run, in order):        │
│    -m set --match-set whitelist_v4 src -j ACCEPT         │
│    -m set --match-set blacklist_v4 src -j DROP           │
│    -m set --match-set blacklist_v4_nets src -j DROP      │
│    (QFEEDS_OUTPUT mirrors this with dst, if enabled)     │
└──────────────────────────────────────────────────────────┘

IPv6 也存在相同的结构（ip6 qfeeds 表或 ip6tables + family inet6 ipsets）。

为什么有两种集合类型？

• 哈希集合存储单个 IP，插入和查找为 O(1) —— 加载 40 万+ IP 只需几秒
• 网络/区间集合仅用于 feed 中少量的 CIDR 范围
• 这避免了代价高昂的合并操作，否则会拖慢包含数十万条目的单个集合

更新流程

┌──────────────────────────────────────────────────────┐
│  1. Check license schedule (licenses.php API)        │
│     → Skip run if not yet time for next update       │
│  2. Determine sync mode (full or diff)               │
│  3. Fetch IPv4 feed (ipv6=0) and IPv6 feed           │
│     (ipv6=only) separately                           │
│  4. Separate IPs from CIDRs in awk                   │
│  5. Batch-load into hash set (IPs) and net/interval  │
│     set (CIDRs)                                      │
│  6. Update whitelist sets from config                 │
│  7. Persist rules                                    │
└──────────────────────────────────────────────────────┘

全量同步与差异同步

模式	适用时机	功能说明
全量同步	首次运行、强制更新、差异同步失败后、本地集合丢失基线（为空或远小于预期）时，或上次同步时间超过 FULL_SYNC_MAX_AGE（默认 24 小时）	先获取并验证每个数据源，然后清空并重新加载黑名单集合。只有在获取到有效数据后才会清空集合，因此获取失败绝不会导致您失去保护
差异同步	后续运行（仅限 malware_ip 数据源）且本地集合状态健康时	仅获取自上次拉取以来的新增（+）和删除（-）条目

差异同步是按 API 密钥进行的——API 会跟踪您上次成功拉取的时间，并仅返回此后的变更。如果差异同步失败，脚本会自动回退到全量同步。

自愈机制： 差异更新仅修补现有集合。如果该集合丢失或被截断——例如重启后防火墙规则未持久化、手动清空或之前的部分同步——更新程序会检测到缺失的基线（实时元素计数为 0 或远低于上次记录的计数），并强制进行全量重建，而不是在空集合上进行差异同步。作为额外的安全网，它还会强制进行定期全量同步（默认每 24 小时一次，通过 FULL_SYNC_MAX_AGE 控制）。

基于许可证的调度

更新程序在每次运行前都会检查 Q-Feeds 许可证 API（licenses.php）。如果您的许可证的 next_update 时间戳尚未到达，脚本会提前退出，避免不必要的 API 调用。cron 任务运行频繁（默认每 20 分钟一次），但实际更新仅在您的许可证允许时才会执行。

---

✅ 前提条件

安装前，请确保您具备：

• Linux 服务器，支持 nftables 或 iptables（Debian、Ubuntu、CentOS、Fedora、Arch、Alpine）
• Root 权限——安装程序和更新程序必须以 root 身份运行
• Q-Feeds API 令牌——在 tip.qfeeds.com 免费获取
• 互联网访问——服务器需要能够访问 api.qfeeds.com

安装程序将自动安装所需的依赖项：

• nftables 后端：nftables、curl、jq、util-linux
• iptables 后端：iptables、ipset、curl、jq、util-linux

---

📝 详细安装指南

1. 获取您的 API 令牌

访问 tip.qfeeds.com 获取您免费的 Q-Feeds API 令牌。

2. 下载并运行

git clone https://github.com/Q-Feeds/NFtables-IPtables-integration-script.git
cd NFtables-IPtables-integration-script
chmod +x qfeeds-installer.sh qfeeds-uninstaller.sh
sudo ./qfeeds-installer.sh

3. 安装程序提示

安装程序将询问以下问题：

API 令牌（必填）

Enter your Q-Feeds API Token:

来自 tip.qfeeds.com 的令牌。如果为空，安装程序将拒绝继续。

订阅源类型

Enter feed type [default: malware_ip]: