Docker配置hosts导致服务无法启动的排查与正确实践

1. 问题现象与排查思路拆解

1.1 这个报错到底在说什么

先把场景还原一下。你在一台 Linux 机器上，为了让容器内部能通过某个自定义域名访问到指定服务，动手改了 Docker 的配置，比如往daemon.json里塞了hosts字段，或者直接改了/etc/hosts之后重启 Docker，结果systemctl restart docker直接报错，服务起不来了。这时候systemctl status docker一看，大概率是Job for docker.service failed或者start request repeated too quickly这类提示。

这个问题的核心矛盾在于：Docker 守护进程的启动流程对配置文件的格式和内容极其敏感，任何它不认识的字段、格式错误的 JSON、或者与运行环境冲突的配置，都会导致守护进程在初始化阶段直接退出。而hosts这个词在 Docker 的语境里有好几层含义，很多人会把它们搞混，这是踩坑的根源。

我见过太多人把「给容器加 hosts 解析」和「给 Docker 守护进程本身配 hosts」这两件事混为一谈。前者是容器运行时的行为，后者是守护进程启动时的行为，两者的配置位置、生效方式、出错表现完全不同。你如果往daemon.json里写了一个 Docker 不支持的hosts字段，守护进程解析配置时就会直接报unknown field然后拒绝启动。这就是最典型的「配置 hosts 导致 Docker 起不来」的场景。

1.2 三种「hosts」场景必须先分清

在动手排查之前，你得先确认自己到底想干哪件事，因为不同诉求对应的正确做法完全不一样。我把它整理成一张表，你对号入座：

这张表是我踩了无数次坑之后总结出来的。最要命的就是第一行：很多人以为daemon.json是个万能配置箱，什么都能往里塞，实际上它只接受 Docker 官方定义的那几十个字段，多一个都不行。Docker 的配置解析器是严格模式，遇到未知字段直接 fatal，连警告都不给你。

1.3 排查的第一步永远是看日志

不管你是哪种场景，服务起不来第一件事就是看日志，别瞎猜。我常用的命令组合是这样的：

# 看服务状态和最近的日志 systemctl status docker -l --no-pager # 看 Docker 守护进程自己的日志 journalctl -u docker.service -n 100 --no-pager # 如果是配置问题，直接手动前台启动看报错 dockerd --debug

最后那条dockerd --debug是杀手锏。它会绕过 systemd，直接在前台把守护进程拉起来，所有配置解析的错误会原封不动打印在终端上。你大概率会看到类似这样的输出：

unable to configure the Docker daemon with file /etc/docker/daemon.json: invalid character 'x' looking for beginning of value

或者：

unknown field "hosts" in daemon configuration

看到unknown field就实锤了，你写了个 Docker 不认的字段。看到invalid character就是 JSON 格式写错了，多半是多了个逗号、少了引号、或者用了单引号。这两种是最高频的原因，占了这类问题的八成以上。

提示：dockerd --debug前台启动时如果成功，会一直占着终端不退出，这时候你按 Ctrl+C 就能停掉，不会影响 systemd 管理的服务。用它来验证配置是否合法，比反复重启服务高效得多。

2. daemon.json 配置的坑与正确写法

2.1 为什么 daemon.json 不接受 hosts 字段

这里得讲清楚原理，不然你下次还会犯。Docker 守护进程的配置文件daemon.json采用的是白名单式的字段校验。Docker 源码里定义了一个Config结构体，只有结构体里声明的字段才能被反序列化，其他一律报错。这个设计是故意的，目的是防止用户写错字段名却浑然不知，导致配置静默失效。

那hosts到底能不能配？答案是：在特定版本和特定场景下可以，但绝大多数人用错了地方。Docker 守护进程本身确实有一个hosts配置项，但它指的是Docker API 的监听地址，比如unix:///var/run/docker.sock或者tcp://0.0.0.0:2375，跟域名解析半毛钱关系都没有。你要是写了个"hosts": ["example.com:1.2.3.4"]，Docker 会尝试把它当成 API 监听地址去解析，解析失败直接退出。

我实测过，在较新的 Docker 版本里，往daemon.json写这种 hosts 数组，报错信息大概是：

failed to parse daemon config: json: cannot unmarshal string into Go struct field Config.hosts of type []string

或者干脆就是unknown field。总之就是起不来。所以记住一句话：daemon.json 里的 hosts 是给 Docker API 用的，不是给容器做域名解析用的。

2.2 正确的 daemon.json 长什么样

既然说到了，我干脆把一份生产环境常用的daemon.json模板贴出来，你可以直接抄。这份配置我用了很久，覆盖了镜像加速、日志轮转、存储驱动、数据目录这些高频需求：

{ "data-root": "/var/lib/docker", "storage-driver": "overlay2", "log-driver": "json-file", "log-opts": { "max-size": "100m", "max-file": "3" }, "registry-mirrors": [ "https://your-mirror.example.com" ], "max-concurrent-downloads": 10, "max-concurrent-uploads": 5, "default-ulimits": { "nofile": { "Name": "nofile", "Hard": 65536, "Soft": 65536 } }, "live-restore": true, "iptables": true, "ip-forward": true }

几个关键点解释一下。log-opts里的日志轮转是必须配的，不然容器日志能把磁盘撑爆，这是运维事故的高发区。live-restore开启后，Docker 守护进程重启时容器不会跟着停，对生产环境很友好。default-ulimits解决的是容器内文件句柄数不够的问题，跑高并发服务时经常遇到。

写这个文件有几个硬性规矩，违反了必挂：

• 必须是合法 JSON，不能有注释，不能有尾随逗号，字符串必须用双引号。
• 字段名大小写敏感，># 1. 先备份，这是保命操作 cp /etc/docker/daemon.json /etc/docker/daemon.json.bak # 2. 改配置 vim /etc/docker/daemon.json # 3. 验证 JSON 语法 jq . /etc/docker/daemon.json # 4. 用前台模式验证配置能否被 Docker 接受 dockerd --validate --config-file /etc/docker/daemon.json # 5. 验证通过后再重载 systemctl reload docker # 如果 reload 不支持，再 restart systemctl restart docker # 6. 确认服务状态 systemctl is-active docker docker info

  第 4 步的dockerd --validate是很多人不知道的隐藏功能，它只校验配置不启动服务，安全得很。第 5 步优先用reload而不是restart，因为 reload 是平滑重载，对运行中的容器影响最小。当然，不是所有配置项都支持热重载，像>docker run -d \ --name myapp \ --add-host api.internal:192.168.1.100 \ --add-host db.internal:192.168.1.101 \ nginx:latest

  这个参数的作用是往容器内的/etc/hosts文件里追加条目。容器启动后，你docker exec -it myapp cat /etc/hosts就能看到这两行。这种方式的好处是只影响这一个容器，不会污染宿主机，也不会影响 Docker 守护进程。

  --add-host还支持一个特殊值host-gateway，用来指向宿主机：

  docker run -d --add-host host.docker.internal:host-gateway myapp

  这个在开发环境特别有用，容器里想访问宿主机上跑的服务，直接用host.docker.internal这个域名就行，不用去查宿主机的 IP。这个特性在 Docker 20.10 之后才支持，老版本用不了，这点要注意。

  3.2 compose 里的 extra_hosts 写法

  如果你用 docker compose 编排服务，对应的配置项叫extra_hosts，写在服务的定义里：

  version: "3.8" services: web: image: nginx:latest extra_hosts: - "api.internal:192.168.1.100" - "db.internal:192.168.1.101" - "host.docker.internal:host-gateway" ports: - "80:80"

  这里有个坑我得提醒你：extra_hosts是写在service 层级下的，不是写在顶层。我见过有人把它写到和services平级的位置，compose 直接报Additional property extra_hosts is not allowed。这个错误信息其实挺明确的，但新手容易懵。

  另外，compose 文件里的version字段现在其实已经废弃了，新版 compose 会警告你。但为了兼容老版本，留着也无妨，不影响功能。

  3.3 批量场景用自定义网络加别名

  如果你有一堆容器需要互相通过域名访问，一个个加--add-host太蠢了。这时候应该用 Docker 的自定义网络加网络别名：

  # 创建自定义网络 docker network create --driver bridge mynet # 启动容器时加入网络并指定别名 docker run -d --name db --network mynet --network-alias database mysql:8 docker run -d --name cache --network mynet --network-alias redis-cache redis:7 docker run -d --name app --network mynet myapp:latest

  这样app容器里就能直接用database和redis-cache这两个域名访问对应服务，Docker 内置的 DNS 服务器会自动解析。这是最优雅的方案，因为它不依赖任何静态 IP，容器重建后 IP 变了也不影响解析。

  自定义网络的好处还不止于此。默认的 bridge 网络不支持自动 DNS 解析，只有自定义网络才支持。所以哪怕你不需要别名，只要涉及容器间通信，都应该用自定义网络，这是最佳实践。

  方案	适用场景	是否影响 Docker 服务	动态 IP 友好
  --add-host	单个容器加少量静态解析	否	否
  extra_hosts	compose 编排	否	否
  自定义网络别名	多容器互访	否	是
  改 daemon.json	不存在这种用法	是，会挂	否

  这张表建议收藏，下次遇到类似需求直接对照选方案，能避开九成的坑。

  4. 服务已经起不来的急救与恢复

  4.1 快速恢复服务的三步法

  假设你现在已经处于 Docker 起不来的状态，业务可能还等着恢复，这时候别慌，按这个顺序来：

  第一步，定位坏配置。用dockerd --debug前台启动，把报错信息完整看一遍。如果报的是unknown field，那就是 daemon.json 里有非法字段；如果报的是invalid character，那就是 JSON 语法错误。把出错的行号和字段记下来。

  第二步，回滚配置。如果你之前备份过，直接cp daemon.json.bak daemon.json覆盖回去。如果没备份，就把可疑字段删掉，或者干脆把 daemon.json 临时清空成{}，先让服务起来再说。空配置是合法的，Docker 会用默认值启动。

  # 临时清空配置，先恢复服务 echo '{}' > /etc/docker/daemon.json systemctl start docker systemctl is-active docker

  第三步，逐步加回配置。服务起来之后，别急着把原来的配置一股脑塞回去。一个字段一个字段地加，每加一个就dockerd --validate验证一次，确认没问题再继续。这样能精确定位到底是哪个字段惹的祸。

  我踩过最坑的一次是，配置里有个字段名拼错了，storage-driver写成了storage_driver，下划线换成了连字符。Docker 报unknown field，但我盯着看了半天没发现，因为两个词长得太像了。后来用dockerd --validate才定位到。所以验证工具一定要用，别靠肉眼。

  4.2 常见报错信息对照表

  我把这类问题常见的报错信息整理成一张速查表，你对着报错找原因，比瞎试快得多：

  报错信息关键词	根本原因	解决方法
  unknown field "hosts"	daemon.json 写了非法字段	删除该字段，改用 --add-host
  invalid character	JSON 语法错误	用 jq 检查并修复
  cannot unmarshal	字段类型不对	检查值的类型，数组还是字符串
  failed to start daemon	配置冲突或端口占用	看完整日志，排查端口和 socket
  start request repeated too quickly	反复失败被 systemd 限流	先修配置，再systemctl reset-failed docker
  permission denied	文件权限或 SELinux	检查文件权限，排查安全策略

  最后那个start request repeated too quickly特别值得说。systemd 有个启动频率限制，服务短时间内失败太多次会被临时禁止启动。这时候你光修配置还不够，得先systemctl reset-failed docker把失败计数清零，否则修好了也起不来。这个坑我见过太多人卡住，明明配置改对了，就是起不来，急得团团转。

  4.3 预防胜于救火：配置管理习惯

  与其每次出事再救，不如养成几个好习惯，从源头避免。

  习惯一，配置即代码。把daemon.json纳入版本管理，每次改动都有记录，出问题能快速 diff 出改了什么。哪怕不用 git，至少保留最近几个版本的备份。

  习惯二，改前必验证。前面反复强调的dockerd --validate和jq，养成肌肉记忆。改完配置先验证，再重启，这个顺序不能反。

  习惯三，变更窗口化。生产环境的 Docker 配置变更，尽量安排在低峰期，并且准备好回滚方案。别在业务高峰期动守护进程配置，万一挂了影响面太大。

  习惯四，用配置管理工具。如果机器多，手工改配置迟早出事。用 Ansible、SaltStack 这类工具统一管理，配置模板化，改一处推全网，一致性有保障。

  提示：systemctl reset-failed docker这个命令建议记牢。它专门用来清除 systemd 对某个服务的失败计数，是「服务反复启动失败后被锁死」场景的救命命令。

  5. 几个容易混淆的边界场景

  5.1 改 /etc/hosts 后重启 Docker 会怎样

  有人会问：我不动 daemon.json，就改宿主机的/etc/hosts，然后重启 Docker，会不会有问题？答案是：一般不会导致 Docker 起不来，但可能不生效。

  Docker 守护进程启动时确实会读宿主机的/etc/hosts，但它主要是为了解析自己的 API 监听地址和镜像仓库地址。你往里加的普通域名条目，Docker 守护进程不一定用得上。而且容器内的/etc/hosts是 Docker 在容器启动时动态生成的，跟宿主机的/etc/hosts是两回事，你改宿主机的不影响容器内的。

  真正需要注意的是，如果你在/etc/hosts里把localhost或者127.0.0.1指向了错误的东西，那可能会影响 Docker 守护进程的启动。因为 Docker 启动时会解析localhost，解析错了就可能卡住。这种情况比较少见，但确实存在。

  5.2 容器内 /etc/hosts 被挂载覆盖的坑

  另一个高频坑是：有人为了给容器加解析，直接把宿主机的 hosts 文件挂载进容器：

  # 错误示范，别这么干 docker run -v /etc/hosts:/etc/hosts myapp

  这么干会导致容器启动异常，因为 Docker 在容器启动时需要往/etc/hosts里写入容器自己的主机名和网络信息，你把文件挂载覆盖了，Docker 写不进去，容器就可能起不来或者网络异常。正确的做法还是用--add-host，让 Docker 自己管理这个文件。

  如果确实需要完全自定义容器内的 hosts，可以用--add-host加多条，或者用 init 容器在启动后动态修改。但直接挂载覆盖是绝对要避免的。

  5.3 Docker Desktop 环境的特殊性

  如果你用的是桌面版 Docker（比如在开发机上），情况又有点不一样。桌面版 Docker 跑在一个轻量虚拟机里，daemon.json的位置和 Linux 原生环境不同，通常在设置界面里配置，而不是直接改文件。你在宿主机上改/etc/hosts，对虚拟机里的 Docker 守护进程基本没影响。

  桌面版环境里想给容器加解析，还是用--add-host或者 compose 的extra_hosts，这个跨环境是通用的。别去折腾虚拟机的配置文件，容易把整个 Docker 环境搞坏，重装起来很麻烦。

  6. 实操心得与避坑清单

  6.1 我踩过的三个真实坑

  坑一：JSON 尾随逗号。这个太经典了。我写配置时习惯性地在最后一个字段后面加了个逗号，JSON 标准不允许尾随逗号，Docker 直接报invalid character '}'。肉眼看了十分钟没看出来，jq一跑就定位到了。从此我改完配置必跑jq。

  坑二：字段名想当然。我以为 Docker 支持dns字段配全局 DNS，就写了个"dns": ["8.8.8.8"]。结果 Docker 报unknown field。后来查文档才知道，全局 DNS 配置的正确字段是dns，但它的值格式和我想的不一样，而且这个字段在某些版本里行为有变化。教训是：别猜字段名，查官方文档。

  坑三：reload 不生效。我改了配置用systemctl reload docker，以为生效了，结果发现某些字段根本没重载。后来才明白，Docker 的 reload 只支持部分字段的热重载，像>