Cursor/Codex CLI插件开发指南：plugin.json配置与failed to load plugins排查
2026/10/4 3:35:03
先纠正一个很多人都会踩的误区：iptables-restore并不是用来“把规则导出到文件”的，它的职责正好相反——从文件里读取规则，恢复进内核里的防火墙。真正负责导出的是它的搭档iptables-save。这两个命令一个存、一个取，合在一起才是 Linux 防火墙规则持久化的完整闭环。
很多人学 Linux 防火墙时，习惯用iptables -A一条条加规则，加完发现重启服务器规则全没了，又不知道怎么把当前规则完整备份出来，更不敢在生产环境批量恢复。这篇文章就把这套“保存-恢复”机制讲透：从命令用法、规则文件格式，到生产环境备份/回滚/批量部署的完整套路，最后再分享几个我实际踩过的坑。
内容偏向实操，Linux 运维、搞网络安全、自学系统管理的人都能用得上。容器环境排查网络问题的人也别划走，后面有一小节专门讲iptables v1.8.9 (legacy): can't initialize iptables table 'nat'这个高频报错。
1. 先弄清 iptables-restore 的定位：别被名字带偏了
1.1 它的真实职责与那对“黄金搭档”的关系
iptables-restore从标准输入（stdin）读取规则文件，解析后把规则写入内核的 netfilter 框架。也就是说，数据流向是“文件 -> 内核”，这是一个导入操作。我们平时敲iptables -A INPUT -p tcp --dport 22 -j ACCEPT也是在往内核里写规则，但iptables-restore真正强的地方在于：它能把一整份规则文件一次性恢复进去，而不是一条一条敲。
反过来，iptables-save是从内核里把当前所有规则导出来，打印到标准输出（stdout）。要存成文件，用重定向就行：
iptables-save > /etc/iptables.rules这两个命令是配套的。你可以理解为打游戏存档：iptables命令负责“玩”，iptables-save负责“存档”，iptables-restore负责“读档”。没有存档，重启系统等于游戏进度清零。
| 命令 | 数据方向 | 典型用法 | 核心用途 |
|---|---|---|---|
iptables -A/-D/-I | 用户 -> 内核 | iptables -A INPUT -j DROP | 单条增删改查 |
iptables-save | 内核 -> stdout | iptables-save > rules.txt | 导出当前完整规则集 |
iptables-restore | 文件/stdin -> 内核 | iptables-restore < rules.txt | 从文件批量恢复规则集 |
记住这个关系，后面读任何文档都不容易晕。
1.2 为什么规则会“丢”：内存态规则的宿命
初学 iptables 的人有个很大的困惑：规则明明用iptables -A加进去了，用iptables -L -n也能看到，为什么重启服务器就没了？
因为 iptables 规则只存在于内核内存中。它不像你编辑/etc/hosts、/etc/resolv.conf那样写进了磁盘文件，重启后文件还在。iptables命令本身没有提供任何“自动把规则保存到磁盘”的机制——这不是设计缺陷，而是有意为之：规则属于运行时状态，内核只负责执行，不负责持久化。
这就像你往路由器里临时改了条静态路由，没点“保存配置”，一断电就还原。Linux 服务器的防火墙规则也是这个道理。生产环境里配置一次规则容易，但规则往往几十条、上百条，分布在 filter、nat、mangle 多张表里，靠人工重新敲一遍不现实，而且极容易漏。所以必须依赖iptables-save和iptables-restore这对工具来完成落盘和恢复。
1.3 在哪些场景下能真正救你
把这两个命令的价值放到实际场景里，你会更直观地感受到：
- 修改前备份：生产服务器的防火墙规则，动之前必须
iptables-save > /backup/iptables-$(date +%F).rules。规则改炸了，一条iptables-restore < 备份文件就能还原，比逐条敲回去不知道快多少倍。 - 批量部署：一套规则在测试环境验证通过后，需要发到几十台服务器上。人工挨个敲命令不现实，把规则文件分发过去，每台机器执行一次
iptables-restore < rules.txt就全部对齐了。 - 版本管理与审计：规则文件是纯文本，天然适合放进 Git 仓库。谁改了什么、加了哪条放行规则、删了哪个端口，
git diff一目了然。 - 应急回滚：最近一次规则更新导致业务异常，直接恢复到上一个版本的规则文件，把故障时间控制在分钟级别。
2. 从导出到恢复的完整实操流程
2.1 导出规则：iptables-save 的正确用法
先看看最常用的几种导出方式：
# 导出所有表的所有规则（默认行为） iptables-save # 导出到文件 iptables-save > /etc/iptables.rules # 只导出 nat 表 iptables-save -t nat # 带计数器导出（默认就带，这里显式写出来） iptables-save -c > /etc/iptables.rules-c（--counters）这个参数值得解释一下。iptables 每条规则都跟着两个计数器：匹配了多少个数据包（packets）和多少字节（bytes）。iptables-save默认就会把计数器带进输出文件里，这也是为什么文件里每条规则末尾有个[123:4567]这样的字段。
计数器有什么用？主要在两个场景：一是做流量统计和排障，看看某条放行规则实际命中多少流量；二是用iptables-restore -c恢复时，能把计数器的值也还原回去，保证恢复前后状态完全一致。如果不关心计数，恢复时可以不用-c，让计数器从零开始。
2.2 看懂规则文件：一行一行拆给你看
用iptables-save导出的文件格式，看起来像脚本但并不是脚本。它由若干“表区块”组成，每个表以*表名开头、以COMMIT结束。一段典型的输出长这样：
# Generated by iptables-save v1.8.7 on Mon Jan 1 00:00:00 2024 *filter :INPUT DROP [0:0] :FORWARD DROP [0:0] :OUTPUT ACCEPT [0:0] -A INPUT -i lo -j ACCEPT -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT -A INPUT -p tcp -m tcp --dport 22 -j ACCEPT COMMIT # Completed on Mon Jan 1 00:00:00 2024逐段拆解：
# Generated by ...和# Completed on ...是注释，由iptables-save自动生成，恢复时iptables-restore会忽略它们。*filter声明当前要操作的是 filter 表。后面可能还有*nat、*mangle，取决于内核里有没有加载对应表。:INPUT DROP [0:0]是链定义。冒号开头，格式是:链名 默认策略 [数据包计数:字节计数]。这行的意思是：把 INPUT 链的默认策略设为 DROP，当前计数器为零。默认策略极其关键，它决定了没有匹配到任何规则的数据包最终是放行还是丢弃。-A INPUT -i lo -j ACCEPT是规则行，含义和命令行下敲的iptables -A INPUT -i lo -j ACCEPT完全一致：追加一条规则到 INPUT 链，匹配来自环回接口（lo）的数据包并放行。COMMIT表示这张表的规则到此为止，iptables-restore在读到 COMMIT 后才把这些规则真正提交到内核。
给新手提个醒：规则文件里不要把COMMIT漏了。漏掉 COMMIT，iptables-restore会认为这张表的规则还没定义完，报语法错误，整张表的规则都不会加载。这个错误通常被日志忽略掉，等你发现规则没生效时已经过了一段时间。
2.3 恢复规则：iptables-restore 的三类用法
恢复操作的核心命令只有一句：
iptables-restore < /etc/iptables.rules注意：iptables-restore不接受把文件名作为参数直接传，它只从文件描述符读。所以重定向符号<是不能省的，也可以用管道：
cat /etc/iptables.rules | iptables-restore但没人这么写，直接用重定向最直观、最不容易出错。
完整参数参考：
| 参数 | 作用 | 典型场景 |
|---|---|---|
| 无参数 | 清空已有规则后，把文件里的规则完整加载 | 标准化部署、规则回滚 |
-n | 不刷新（flush）现有规则，只把文件里的规则追加进去 | 增量追加、临时加载部分规则 |
-c | 连计数器一起恢复 | 排障时需要保留原始命中数据 |
--test | 只解析和校验文件，不真正修改内核规则 | 上线前语法检查 |
-t | 只恢复指定的表（如-t nat） | 只处理某一张表时 |
实际工作中用得最多的是无参数和--test。我个人的习惯是：任何规则文件在正式恢复之前，先跑一次--test：
iptables-restore --test < /etc/iptables.rules如果规则文件里有语法错误或者引用了不存在的表/链，它会直接报错。测试通过再真正恢复，能帮你挡掉一大半低级失误。
2.4 开机自动加载：规则不落地等于白配
上面讲的都是手动恢复，但生产环境里服务器重启后必须自动把规则加载回来。这里提供三种方案，从推荐到备选排序。
方案一：systemd 服务（适用所有主流发行版）
创建/etc/systemd/system/iptables-restore.service：
[Unit] Description=Restore iptables rules Before=network-pre.target Wants=network-pre.target [Service] Type=oneshot ExecStart=/usr/sbin/iptables-restore /etc/iptables.rules ExecReload=/usr/sbin/iptables-restore /etc/iptables.rules RemainAfterExit=yes [Install] WantedBy=multi-user.target注意：systemd 服务里的ExecStart=/usr/sbin/iptables-restore /etc/iptables.rules，这里的写法其实等价于iptables-restore < /etc/iptables.rules，iptables-restore自己会处理文件参数并打开读取（需要校验你的 iptables 版本是否支持，v1.8.x 支持）。如果版本老，就写成ExecStart=/bin/sh -c '/usr/sbin/iptables-restore < /etc/iptables.rules'。
启用服务：
systemctl enable iptables-restore.service方案二：iptables-persistent（Debian/Ubuntu 系）
apt install iptables-persistent netfilter-persistent save netfilter-persistent reload安装后，规则默认保存到/etc/iptables/rules.v4和/etc/iptables/rules.v6，开机自动加载，省心。Ubuntu 系服务器我很推荐这个方案。
方案三：rc.local（老系统备选）
CentOS 6 或一些老环境里，把加载命令写进/etc/rc.local：
/usr/sbin/iptables-restore < /etc/iptables.rules需要给rc.local加上执行权限才能生效。
不管用哪种方案，核心思想都一样：把规则文件放到固定位置，系统启动时执行一次恢复。规则文件哪来的？当然是用iptables-save导出的。
3. 参数、文件格式与底层逻辑：把每个“为什么”说清楚
3.1 为什么恢复要用“整文件”而不是一条条敲
有人会问：既然iptables -A能加规则，为什么还要多此一举搞个iptables-restore？
最直接的理由是效率。几十上百条规则，用iptables -A一条条敲或者写个 for 循环去执行，每条命令都要走一遍用户态到内核态，慢不说，中间任何一个步骤出了问题，规则集就处于一个“只加载了一半”的混乱状态。比如你敲了前 10 条放行规则，还没敲第 11 条默认拒绝规则，这时候防火墙对业务来说就是不可控的。
iptables-restore就不一样。它读取整个规则文件，把每张表的规则一次性解析，再统一提交到内核。更重要的是，不带-n参数时，iptables-restore会先把现有的规则清空，再按文件内容逐个加载。这意味着文件里的内容就成了规则的“最终目标状态”，不会出现“旧规则还在、新规则又插入”的叠加混乱。
用一句话概括：iptables -A是程序化地修改状态，iptables-restore是声明式地把规则集对齐到文件内容。这也是为什么很多自动化运维工具里，最终落地的都是 save/restore 组合。
3.2 默认策略、规则顺序与计数器：文件里的三个隐藏陷阱
再聊深一点文件内容的三个细节，每一个都能让你少踩一次坑。
默认策略。链定义行:INPUT DROP [0:0]里写的是链的默认策略。当数据包经过链时，如果所有规则都不匹配，就走默认策略。生产环境里最常见的默认策略组合是 INPUT 链 DROP、FORWARD 链 DROP、OUTPUT 链 ACCEPT。恢复这样的文件后，任何新的入站连接都会被拒绝，除非有显式放行规则。
规则顺序。iptables 规则的匹配是按文件里的顺序从上到下进行的，命中一条就执行动作，不再继续往下匹配。所以，放行规则必须写在拒绝规则之前。比如：
-A INPUT -p tcp --dport 22 -j ACCEPT写在前面- 最后再写
-A INPUT -j DROP
如果顺序反了，DROP 把 SSH 连接全丢了，后面的 ACCEPT 永远不会被执行，这就是经典的“规则顺序坑”。
计数器。[0:0]不是随便写的装饰品。iptables-restore在加载规则时会保留这些计数器的初始值。恢复时若想保留中断前的精确计数，用-c；若想清零重来，就别用-c。这在小流量环境没什么感觉，但在高流量生产环境，计数器是排障时判断“规则到底有没有生效”的重要依据。
3.3 我推荐的“改规则工作流”：一套标准化流程
基于上面这些原理，我整理了一套自己在生产环境用的改规则流程，步骤固定、出错率低：
- 备份现状：
iptables-save > /backup/iptables-$(date +%F-%H%M).rules - 修改规则文件：复制备份文件为工作文件，编辑它。别直接改系统里正在生效的规则，要通过改“文件”来间接改规则。
- 语法校验：
iptables-restore --test < 工作文件 - 先测后上：条件允许的话，先在测试机恢复这个文件，验证业务端口连通性。
- 生产恢复：
iptables-restore < 工作文件 - 即时验证：立刻检查业务端口、SSH 是否正常，看
iptables-save的实际输出和文件是否一致。 - 重新保存：验证通过后，把已生效的规则再次
iptables-save > /etc/iptables.rules，保持持久化文件是“当前生效版本”。
这套流程的核心理念是：永远不要在线上服务器上直接敲 iptables 命令去试，一切改动先沉淀成文件，再通过 restore 加载。
3.4 高频报错：iptables v1.8.9 (legacy) 初始化 nat 表失败
部署 iptables-restore 时最常遇到的一个报错，热词里也出现了：
iptables v1.8.9 (legacy): can't initialize iptables table `nat': table does not exist这个报错我在 Docker 容器里见过最多，其次是没有加载 netfilter 相关模块的轻量级云服务器。拆解一下原因。
报错里的(legacy)指明 iptables 用的是 legacy 后端，走的是老式ip_tables内核模块接口。而内核里如果没有加载iptable_nat之类的模块，nat表就不存在，自然无法初始化。
排查步骤：
# 1. 确认内核是否有 ip_tables 相关模块 lsmod | grep -E 'iptable|ip_tables|nf_tables' # 2. 手动加载 nat 表模块 modprobe iptable_nat # 3. 再执行导出/恢复 iptables-save -t nat如果modprobe报错或者没有权限（比如容器里），那就换个思路：
- 容器环境：确认容器是否具备 CAP_NET_ADMIN 权限。用 docker 的话，启动时加
--cap-add=NET_ADMIN；K8s 里可能需要调整 securityContext。 - 宿主机环境：检查
/proc/net/ip_tables_names是否存在，如果不存在说明ip_tables模块没加载。 - 还有一个思路：把 iptables 切换到 nft 后端，有些发行版上用
update-alternatives --config iptables切换，或者直接用iptables-nft命令。nft 后端走的是 nf_tables 框架，很多以前 legacy 模式下报的“表不存在”问题在 nft 模式下直接消失。
这里多说一句：报错里的 legacy 和 nft 指的是 iptables 命令的两种后端实现。新内核普遍推荐 nft 模式，但老脚本和老思路还停留在 legacy，所以实际环境里两种模式并存。排障时先看清楚自己的发行版默认走的是哪个后端，再决定排查方向。
4. 生产环境实战：备份、批量部署与应急回滚
4.1 定时备份规则脚本
既然规则这么容易丢，定时备份就是最基本的“保险”。把下面脚本放进 crontab，每天凌晨备份一次：
#!/bin/bash # /usr/local/bin/backup-iptables.sh BACKUP_DIR="/backup/iptables" mkdir -p "${BACKUP_DIR}" iptables-save > "${BACKUP_DIR}/iptables-$(date +%Y%m%d-%H%M%S).rules" find "${BACKUP_DIR}" -name "iptables-*.rules" -mtime +30 -deletecrontab 里加一行：
0 2 * * * /usr/local/bin/backup-iptables.sh这样至少保留最近 30 天的规则快照。就算某天规则被改得面目全非，也能从历史快照里找到回退版本。
4.2 多台机器批量部署
规则文件一旦定型，批量部署就很省事。最简单的思路：把文件分发到目标机器，然后执行iptables-restore。
用 shell 循环：
for host in 192.168.1.10 192.168.1.11 192.168.1.12; do scp /etc/iptables.rules root@${host}:/etc/iptables.rules ssh root@${host} "iptables-restore < /etc/iptables.rules && iptables-save > /etc/iptables.rules" done用 Ansible 更规范：
- name: 部署 iptables 规则 hosts: all tasks: - name: 分发规则文件 copy: src: files/iptables.rules dest: /etc/iptables.rules - name: 恢复规则 shell: iptables-restore < /etc/iptables.rules - name: 持久化规则 shell: iptables-save > /etc/iptables.rules不管用哪种方式，恢复完成之后的iptables-save > /etc/iptables.rules别省。它能在恢复成功的基础上，把“当前生效规则”重新固化为持久化文件，避免文件里写的和内核实际加载的有细微出入。
4.3 回滚策略：别把自己关在门外
远程管理服务器防火墙，最恐怖的事情就是：你恢复了新规则，默认策略是 DROP，而新规则里又忘了放行 SSH 端口，结果当前连接被切断，你再也登不进去。这种情况我遇到过，当时后背一凉。
两个习惯可以避免这个问题：
第一，恢复前先把 SSH 端口放行规则放到文件最顶部。无论如何，-A INPUT -p tcp --dport 22 -j ACCEPT这种保命规则必须先写，确保恢复过程中不会断连。
第二，用定时自动回滚兜底。如果你在改一批高风险规则，担心恢复后误伤业务，可以用一个带超时的回滚脚本：
# 先保存旧规则 iptables-save > /backup/rules.bak # 启动一个 60 秒后自动回滚的定时任务 (sleep 60; iptables-restore < /backup/rules.bak) & # 再恢复新规则，然后立刻验证 iptables-restore < /etc/iptables.rules.new echo "恢复成功，检查服务连通性..."如果 60 秒内验证发现新规则有问题，等它自动回滚到旧规则就行；如果验证没问题，就把后台那个定时任务 kill 掉：
pkill -f 'sleep 60'这个“超时自动回滚”的思路还可以再封装成更完整的脚本，加上端口探测等验证逻辑。核心就是要给自己留一条物理上的回退路径，别一口气把旧规则全冲了。
4.4 顺带说一句：屏蔽“某个程序连网”与 iptables 的边界
有热词提到“先去防火墙建立出入站规则屏蔽 acrobat.exe 联网”，这是 Windows 防火墙的用法，按程序路径（exe）直接屏蔽。Linux 下用 iptables 做不到按完整程序路径屏蔽，它本质上是基于 IP、协议、端口的网络层过滤。
但也不是完全没有对应方案。Linux 下要限制某个进程联网，可以用 iptables 的owner模块：
# 屏蔽 UID 为 1001 的用户进程出站流量 iptables -A OUTPUT -m owner --uid-owner 1001 -j DROP # 屏蔽具体命令名（cmd-owner，注意仅对本地生成的数据包有效） iptables -A OUTPUT -m owner --cmd-owner acrobat -j DROP--cmd-owner有一定局限性：命令名字匹配有长度限制，而且只有 root 能看到所有进程的 owner 信息。所以生产环境里，更常见的做法是：先定位程序要访问的 IP/域名/IP 段，再按目的地址去封禁。比如：
# 禁止访问某个远程 IP 段，注意先放行已建立的连接，否则会误伤正常出站 iptables -A OUTPUT -m conntrack --ctstate ESTABLISHED -j ACCEPT iptables -A OUTPUT -d 203.0.113.0/24 -j DROP顺序上一定要把 ESTABLISHED 放行规则写在前面，否则你自己的正常出站连接也会被掐断。这种思路在服务端限制出站、防数据外传的场景里很常用。
5. 常见问题与避坑实录
5.1 高频坑：我从实际环境里踩过来的
总结几个高频坑，每一个我都亲眼见过，有的还亲手踩过。
坑 1：恢复后 SSH 立刻断开。原因九成是默认策略被设成了 DROP，或者放行 SSH 的规则没有覆盖当前连接的网卡/来源 IP。解决办法就是 4.3 节那套“保命规则”+“自动回滚”。
坑 2：规则文件漏了 COMMIT。语法校验时容易忽略这种静默失败。恢复命令不报错，但表里的规则一条都没进去。使用--test能不能查出来？分情况，--test能发现明显的语法错误，但漏 COMMIT 的情况不同版本行为有差异。最稳的验证方式：恢复完立刻iptables-save，和原文件对比。
坑 3：规则顺序反了。放行规则写在了拒绝规则后面。比如先写-A INPUT -j DROP再写-A INPUT -p tcp --dport 80 -j ACCEPT，那 80 端口永远通不了。iptables 匹配是“命中即停”，规则顺序就是优先级顺序。
坑 4：脚本里反复iptables -A导致规则叠加。有些初始化脚本每次启动都执行同样的-A命令，重启几次以后规则列表里出现好几条相同的规则，计数器和性能都会受影响。解决方式：要么先iptables -F清空再添加，要么干脆用iptables-restore加载固定文件。
坑 5：nat 表规则恢复失败。就是 3.4 节那个table does not exist。常见于未加载iptable_nat模块的容器或精简内核环境。注意，不仅是 nat 表，mangle、raw表也有各自的模块依赖，恢复前可以先确认/proc/net/ip_tables_names里列出了哪些表。
5.2 一套可靠的测试与上线流程
综合前面所有内容，我建议你把下面这套流程固化下来，每次变更防火墙规则都这么走：
- 在测试环境先
iptables-restore < 新规则文件，模拟线上流量做一次连通性验证。 - 对正式规则文件执行
iptables-restore --test，确保语法层面无问题。 - 恢复前看一眼规则文件头部：SSH 放行规则在不在？当前业务端口放行规则在不在？
- 执行恢复，恢复后立即检查两个点：当前 SSH 连接是否还活着、业务关键端口是否正常响应。
- 验证通过后，用
iptables-save -c > /etc/iptables.rules固化当前状态，以备后续版本对比和回滚。
这套流程多花不了两分钟，但能挡住 90% 以上的线上事故。
5.3 面试题考点与学习建议
很多人准备 Linux 面试时会专门刷“linux面试题测试”相关的题目，iptables 几乎是必考内容。和 save/restore 相关的考点通常集中在这几个方向：
iptables-save与iptables-restore的作用和区别；- iptables 规则为什么不持久化、如何实现开机自动加载；
- 规则文件里
*表名、链定义、规则行、COMMIT分别是什么意思； - 默认策略 DROP 和 ACCEPT 的区别，规则顺序对匹配结果的影响；
- 计数器
[packets:bytes]在排障中的作用。
我的建议很直接：搭一个虚拟机，开两个终端，一个终端敲iptables命令或者编辑规则文件，另一个终端用iptables-save观察变化。将规则文件改来改去、恢复来恢复去，折腾几次，比背十遍面试题都管用。
最后再分享一个我自己的体会
大概两年前，我在一台线上服务器上整理防火墙规则，手快直接把带 DROP 默认策略的规则恢复了上去，结果 SSH 瞬间断开。当时没有提前备份旧规则，脑子里一片空白。后来是通过云控制台的 VNC 登录进去，反手用iptables -F清掉所有规则才救回来的。
从那以后我养成了两个习惯：第一，任何一次iptables-restore之前，先花一秒钟把当前规则iptables-save留个档；第二，备份文件名永远带上时间戳，而不是覆盖同名文件。这两条操作加起来不到五秒，但关键时候值一台服务器。
额外分享一个小技巧：如果你管理着多台服务器，可以考虑把规则文件按服务器角色-日期的方式命名，定期归档。需要回溯某个时间点的规则变更时，直接查 Git 历史或备份目录，比靠脑子记靠谱太多了。