IPTables-Management/README.md

IPTables-Management

一个基于 Bash 的中文交互式 IPTables 端口转发管理工具，面向 Debian 12/13。

• 启动时自动做环境自检。
• 仅管理本工具创建的 MGMT:<UUID> 规则。
• 支持 TCP / UDP / both，支持 IPv4 / IPv6 / both。
• 在 FORWARD 默认策略为 DROP 时也会补齐回程放行规则。
• 支持 iptables-persistent / netfilter-persistent save 持久化。
• 所有写操作通过 flock 串行化，降低多实例并发竞争风险。
• 附带单元测试与真实 iptables 集成测试。

目录结构

.
├── iptables-forward.sh      # 主入口
├── install.sh               # 创建 /usr/local/bin/iptables-forward 符号链接
├── lib/                     # 业务模块
├── tests/                   # 测试与 mock
└── plan_iptables_forward.md # 实施方案

运行要求

• Debian 12/13
• Bash 4+
• root 或 sudo
• iptables
• ip6tables
• iptables-persistent（提供 netfilter-persistent）

首次运行若缺依赖，脚本会列出缺失项并询问是否自动安装。

安装

直接运行

sudo ./iptables-forward.sh

安装到 PATH

sudo ./install.sh
sudo iptables-forward

默认会创建：

/usr/local/bin/iptables-forward -> /path/to/IPTables-Management/iptables-forward.sh

若目标路径已存在且不是当前仓库脚本的符号链接，install.sh 会拒绝覆盖；--uninstall 也只会删除当前脚本创建的链接，避免误删其它文件。

使用说明

交互模式

sudo ./iptables-forward.sh

主菜单提供：

• 查看所有转发规则
• 添加新的转发规则
• 删除现有转发规则
• 查看系统环境状态
• 立即保存到磁盘
• 退出

主菜单状态行会同时显示环境状态、规则数、持久化可用性与运行态健康；若数据库里存在半残规则，运行态 会降级为 [!]。

规则列表中的状态列含义：

• ✓：该条规则对应的 PREROUTING / POSTROUTING / 双向 FORWARD 运行态规则都存在
• !：至少缺少一条运行态规则，或仅剩数据库记录

列表表头与内容会按显示宽度对齐，中文与 ASCII 混排时也尽量保持列起始位置一致。

批处理模式

用于自动化测试或脚本调用：

sudo ./iptables-forward.sh --batch add <proto> <listen_port> <target_ip> <target_port> <ipver> [desc]
sudo ./iptables-forward.sh --batch delete <uuid>
sudo ./iptables-forward.sh --batch list
sudo ./iptables-forward.sh --batch save
sudo ./iptables-forward.sh --batch env

参数说明：

• proto: tcp / udp / both
• ipver: 4 / 6 / both
• target_ip:
  • ipver=4 时传单个 IPv4
  • ipver=6 时传单个 IPv6
  • ipver=both 时传 IPv4,IPv6，例如 127.0.0.1,::1

示例：

sudo ./iptables-forward.sh --batch add tcp 8080 192.168.1.100 80 4 "web"
sudo ./iptables-forward.sh --batch add both 5353 127.0.0.1,::1 53 both "dns"

成功时标准输出会返回新规则 UUID。

存储与持久化

规则元数据默认保存在：

/var/lib/iptables-forward/rules.db

格式为一行一条：

uuid=a1b2c3d4|proto=tcp|lport=8080|tip=192.168.1.100|tport=80|ipver=4|desc=web|created=2026-04-17T10:00:00+0800

添加/删除规则时会自动调用：

netfilter-persistent save

以便把规则保存到：

/etc/iptables/rules.v4
/etc/iptables/rules.v6

测试

运行全部测试

tests/run_all.sh

跳过集成测试

tests/run_all.sh --skip-integration

测试覆盖：

• tests/test_cli.sh：入口脚本与安装脚本帮助输出
• tests/test_install.sh：安装脚本的 install/uninstall 实际行为与误覆盖保护
• tests/test_interactive.sh：交互主菜单的 add/list/delete/save 回归
• tests/test_common.sh：输入校验
• tests/test_storage.sh：规则存储
• tests/test_env_check.sh：环境检查与修复
• tests/test_rules_unit.sh：mock iptables 下的增删回滚、双向 FORWARD 规则与并发写保护
• tests/test_integration.sh：真实 iptables 生命周期 + FORWARD=DROP 下的命名空间端到端 IPv4/IPv6 TCP 转发 + save/reload 持久化回放测试

tests/test_integration.sh 的执行策略：

• root 环境下直接执行
• 非 root 但支持 unshare -Urn 时，会进入隔离网络命名空间执行
• 两者都不满足时会输出 SKIP
• 流量验证会额外创建 client / router / backend 三段临时 veth + netns，并用 Python TCP server 验证 IPv4/IPv6 add / reload / delete 对真实转发流量的影响
• 持久化验证不会直接改写宿主 /etc/iptables，而是通过临时 netfilter-persistent 包装器把 save/reload 落到测试目录中的 rules.v4 / rules.v6

手工验收建议

建议按 plan_iptables_forward.md 再做以下实机验证：

1. 在干净 Debian 12/13 上首次启动，确认自动安装流程可用。
2. 准备一台实际后端服务主机，验证从第三方主机访问转发端口时流量确实命中目标服务。
3. 重启系统后确认规则仍存在，且菜单中状态仍为健康。
4. 删除规则后再次验证外部访问失败。

故障排查

1. 提示必须使用 root

脚本必须以 root 执行：

sudo ./iptables-forward.sh

2. 自动安装失败

可手动安装依赖后重试：

sudo apt-get update
sudo apt-get install -y iptables iptables-persistent

3. 持久化保存失败

确认以下命令可执行：

command -v netfilter-persistent
sudo netfilter-persistent save

4. 系统使用 nft 后端

Debian 12/13 默认常见为 iptables-nft。本项目不自动切换到 legacy 后端，而是依赖发行版默认配置。

5. 其它防火墙工具干扰

若系统启用了 ufw 或 firewalld，可能覆盖或影响转发规则。脚本会给出黄色警告，但不会自动关闭这些服务。

卸载

删除 PATH 链接

sudo ./install.sh --uninstall

删除脚本管理的规则与状态

sudo iptables-save | grep -v 'MGMT:' | sudo iptables-restore
sudo ip6tables-save | grep -v 'MGMT:' | sudo ip6tables-restore
sudo netfilter-persistent save
sudo rm -rf /var/lib/iptables-forward
sudo rm -f /etc/sysctl.d/99-iptables-forward.conf

可选：卸载持久化包

sudo apt-get remove --purge iptables-persistent