一次完整的 Docker 启动失败排错之旅：从 `start-limit` 到 `network not found

---

一次完整的 Docker 启动失败排错之旅：从 start-limit 到 network not found

你是否也曾自信地敲下 sudo systemctl start docker，却只得到一个冰冷的 failed？这是一个开发者和运维工程师都可能遇到的场景。本文将通过一个真实的排错案例，带你一步步地剖析问题、定位根源、解决故障，最终让 Docker 服务起死回生。

第一幕：初见端倪 - Active: failed (Result: start-limit)

一切始于一个常规的 Docker 服务启动命令，但系统却返回了错误。我们立刻检查服务状态：

$ systemctl status docker.service
● docker.service - Docker Application Container Engine
   Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; vendor preset: disabled)
   Active: failed (Result: start-limit) since Tue 2025-08-05 23:23:57 CST; 41s ago
  Process: 12037 ExecStart=/usr/bin/dockerd ... (code=exited, status=1/FAILURE)
 Main PID: 12037 (code=exited, status=1/FAILURE)

Aug 05 23:23:57 my-linux-server systemd[1]: Failed to start Docker Application Container Engine.
Aug 05 23:23:57 my-linux-server systemd[1]: docker.service failed.

诊断分析：
Active: failed 告诉我们服务失败了，但更关键的是 Result: start-limit。这表示 systemd 在短时间内多次尝试启动 Docker 守护进程 (dockerd)，但每次都以失败告终。为了保护系统，systemd 决定暂时放弃。

核心教训 #1 ：systemctl status 只告诉我们"发生了什么"，但要了解"为什么发生"，我们必须深入日志。

第二幕：深挖日志 - ZONE_CONFLICT 防火墙冲突

我们使用 journalctl 来查看 Docker 服务的详细日志：

$ journalctl -u docker.service --no-pager
...
Aug 05 23:23:55 my-linux-server dockerd[12037]: failed to start daemon: Error initializing network controller: error creating default "bridge" network: Failed to program NAT chain: ZONE_CONFLICT: 'docker0' already bound to a zone
...

诊断分析：

问题清晰了！错误是 ZONE_CONFLICT: 'docker0' already bound to a zone。

这通常发生在启用了 firewalld 的系统（如 CentOS/RHEL）上。Docker 尝试创建和管理 docker0 网桥并配置 NAT 规则，但 firewalld 防火墙发现 docker0 接口已经被分配到了一个防火墙区域（zone），从而阻止了 Docker 的操作，导致冲突。

解决方案：

我们需要明确告诉 firewalld，docker0 是一个可信的接口，让 Docker 自行管理。

# 1. 将 docker0 接口永久添加到 trusted 区域
sudo firewall-cmd --permanent --zone=trusted --add-interface=docker0

# 2. 重新加载防火墙规则使之生效
sudo firewall-cmd --reload

第三幕：峰回路转 - 新的错误 networks have same bridge name

在解决了防火墙问题后，我们再次尝试启动 Docker，但依旧失败。查看最新的日志，发现错误变了：

$ journalctl -u docker.service --no-pager
...
Aug 05 23:33:31 my-linux-server dockerd[3762]: failed to start daemon: Error initializing network controller: ... conflicts with network ...: networks have same bridge name
...

诊断分析：

这个错误 networks have same bridge name 意味着 Docker 内部的网络状态出现了不一致。很可能是由于之前的反复失败和异常关闭，导致 Docker 的网络数据库文件 (/var/lib/docker/network/files/local-kv.db) 损坏或包含了陈旧的、冲突的数据。

解决方案：

清理 Docker 损坏的网络状态文件，让它在下次启动时重建一个干净的状态。

# 停止 Docker 服务（如果正在尝试运行）
sudo systemctl stop docker.service

# 删除网络状态数据库文件
sudo rm /var/lib/docker/network/files/local-kv.db

注意：此操作是安全的，仅重置网络定义，不会影响镜像和容器数据。

第四幕：拨云见日 - 彻底的清理与重启

在修复过程中，我们还遇到了配置冲突（-b 和 --bip 互斥）以及一个关键的系统警告：

$ sudo systemctl stop docker.service
Warning: Stopping docker.service, but it can still be activated by:
  docker.socket

诊断分析：

这个警告揭示了 systemd 的"套接字激活"机制。即使我们停止了 docker.service，docker.socket 依然在监听。任何 docker 命令的调用都会通过 socket 自动唤醒服务，这可能在我们修复过程中造成干扰。

最终的、完整的解决方案：

我们需要一次彻底的、不受干扰的清理和重启。

1. 彻底停止 Docker，包括服务和套接字。

   sudo systemctl stop docker.socket
   sudo systemctl stop docker.service

2. 重置配置文件 ，排除所有自定义配置的干扰。编辑 /etc/docker/daemon.json，将其内容清空为 {}。

   sudo nano /etc/docker/daemon.json
   # 文件内容修改为:
   # {}

3. 清理损坏的网络状态（我们在第三幕中已执行）。

   sudo rm /var/lib/docker/network/files/local-kv.db

4. 重置并重启。

   sudo systemctl daemon-reload
   sudo systemctl reset-failed docker.service
   sudo systemctl start docker.service

执行完这一系列操作后，systemctl status docker.service 终于显示了久违的绿色 active (running)！

第五幕：最后的胜利 - 解决应用层的 network not found

Docker 守护进程终于正常运行了。但当我们用 docker-compose 启动应用时，又遇到了最后一个问题：

Error response from daemon: network a_very_long_id not found

诊断分析：

这是一个预期中的"错误"。因为我们清除了 Docker 的所有网络状态，它"忘记"了之前由 docker-compose 创建的自定义网络。而我们的应用配置（docker-compose.yml）仍然指向那个已经被遗忘的网络 ID。

解决方案：

让 docker-compose 彻底重建整个应用栈，包括它所需的网络。

1. 进入你的项目目录。

   cd /path/to/your/project

2. 拆除旧的应用栈，移除所有状态不一致的容器和网络定义。

   sudo docker-compose down

3. 重新构建并启动 ，-d 表示后台运行，--build 强制重新构建镜像。

   sudo docker-compose up -d --build

docker-compose 会发现网络不存在，于是自动创建一个新的、干净的网络，并启动新的容器连接到该网络。至此，所有问题都已解决，应用恢复正常。

总结与启示

这次排错之旅告诉我们：

1. 日志是你的罗盘 ：systemctl status 只是起点，journalctl 才是帮你找到方向的工具。
2. 理解系统交互 ：Docker 并非孤立运行，它与 systemd、firewalld 等系统服务紧密交互。ZONE_CONFLICT 就是典型的例子。
3. 注意隐藏机制 ：docker.socket 的套接字激活机制很容易被忽略，但在关键时刻它可能是导致问题反复出现的"幕后黑手"。
4. 敢于重置状态：当内部状态（如网络数据库）损坏时，备份后大胆地清理并让服务重建，往往是最高效的解决方案。
5. 分清层次 ：要区分是 Docker 守护进程 的问题，还是 应用层 （如 docker-compose）的配置问题。守护进程恢复后，应用层也需要同步更新。

希望这次的经历能为你在未来的 Docker 排错道路上提供一份有用的地图。