Docker iptables 与 nftables 兼容性问题排查

Checo2026年6月3日大约 3 分钟

Docker iptables 与 nftables 兼容性问题排查

在 Debian 12 服务器上用 1Panel 安装 Docker 应用时，遇到过一个很典型的问题：容器可以创建成功，但启动时端口映射失败。表面看是 Docker 报错，实际原因是 iptables 后端和 Docker 链不兼容。

症状

Docker 容器创建完成后，启动阶段报错：

Error response from daemon: failed to set up container networking:
driver failed programming external connectivity on endpoint ...
Unable to enable OPEN PORT rule:
iptables: No chain/target/match by that name. (exit status 1)

这个报错容易误导人。容器本身不是不能创建，而是在 Starting 阶段设置端口映射失败。

根因

Debian 12 bookworm 默认使用 iptables-nft，也就是 nftables 后端。Docker 会在 iptables 里维护自己的 DOCKER 链，用于 bridge 网络和端口映射。

当 filter 表中的 DOCKER 链与 nft 后端状态不兼容时，就会出现类似错误：

iptables v1.8.9 (nf_tables): chain `DOCKER' in table `filter' is incompatible, use 'nft' tool.

一个关键细节是：NAT 表里的 DOCKER 链可能还是正常的，所以已有端口映射不一定会立刻坏。真正受影响的是新建容器或新增端口映射。

快速诊断

先看当前 iptables 使用的后端：

update-alternatives --query iptables | grep -E 'Status|Value'

再检查 filter 表里的 Docker 链：

iptables -L DOCKER -n

如果这里出现 incompatible 或链不存在，再看 NAT 表状态：

iptables -t nat -L DOCKER -n

最后确认当前容器和端口映射：

docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

如果已有容器还在正常运行，但新容器起不来，基本就可以锁定在 Docker 端口映射和 iptables 后端兼容性上。

修复步骤

1. 备份现有规则

修网络规则前先备份，后面出问题才有回滚依据：

mkdir -p /root/backup-iptables-$(date +%Y%m%d)
iptables-save > /root/backup-iptables-$(date +%Y%m%d)/iptables-all.txt
iptables-save -t nat > /root/backup-iptables-$(date +%Y%m%d)/iptables-nat.txt
docker ps --format '{{.Names}} {{.Image}} {{.Status}}' > /root/backup-iptables-$(date +%Y%m%d)/containers.txt

2. 切换到 legacy 模式

把 IPv4 和 IPv6 的 iptables 都切到 legacy：

update-alternatives --set iptables /usr/sbin/iptables-legacy
update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

3. 重启 Docker

systemctl restart docker

如果容器配置了 restart: always 或 unless-stopped，Docker 重启后会自动拉起。

4. 验证

检查 DOCKER 链是否能正常显示：

iptables -L DOCKER -n

确认容器状态：

docker ps

检查关键端口是否监听：

ss -tlnp | grep -E ':80 |:443 |:3000 '

如果是 1Panel 里安装失败的应用，这时重新安装或重新启动应用，一般就可以恢复。

注意事项

host 网络模式的容器通常不受这个问题影响，例如 openresty 直接监听宿主机端口。
bridge 网络模式的容器依赖 iptables 做端口映射，MySQL、new-api 这类容器会受影响。
修复前确认重要容器有 restart policy，避免重启 Docker 后服务没有自动恢复。
如果系统启用了 firewalld，可能还要检查它是否改写了规则。
生产环境不要直接清空 iptables 规则，先备份再操作。

环境记录

这次遇到问题的环境大致如下：

项目	值
系统	Debian 12 bookworm
Docker	28.3.2
面板	1Panel
iptables	v1.8.9
修复方向	`iptables-nft` 切换为 `iptables-legacy`

总结

这个问题的核心不是容器镜像，也不是 1Panel 本身，而是 Docker 依赖的 iptables 链和 Debian 默认 nftables 后端不兼容。

排查时可以按这个顺序走：

看容器是否是 Created 成功、Starting 失败
查 iptables -L DOCKER -n
确认 iptables 当前后端
备份规则
切换 legacy
重启 Docker 并验证容器端口