Docker daemon.json 配置参数详解

目标：逐项解析 Docker 守护进程配置文件 /etc/docker/daemon.json 中的核心参数（数据目录、镜像源、存储驱动、网络、日志、安全等），并给出「配置 → 重载 → 真实回显验证」的完整流程。本文档所有配置修改与验证均为 Ubuntu 22.04 + Docker 29.8.1 真机实测结果。

环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• Docker Engine：29.8.1（containerd-snapshotter 集成）
• 配置修改方式：编辑 /etc/docker/daemon.json → systemctl restart docker
• 验证命令：docker info、docker network inspect、curl 等

前置条件

• Docker 已安装并用 systemctl 管理（见《Ubuntu 22.04 安装 Docker 指南》）。
• 理解以下事实：29.8.1（snapshotter 集成）的 docker info 已不再回显经典的 Iptables / IpForward / IpMasq / Bridge / DefaultAddressPools 网络字段，这些参数以「daemon 启动校验 / 启动日志 / 实际接口 IP」为验证手段。

参数查看与修改方式

# 查看当前配置
cat /etc/docker/daemon.json

# 修改后重载
sudo systemctl restart docker
# 若因坏配置启动失败：sudo systemctl reset-failed docker && sudo systemctl start docker

⚠️ 每次改动仅保留一个 / 一组目标参数，改完务必用 docker info 验证；若改坏导致 daemon 起不来，可用 journalctl -u docker 看启动错误逐条定位。

参数总览表

一、镜像与仓库相关参数

registry-mirrors（镜像加速）

配置两个国内加速源后：

{
  "data-root": "/opt/data/docker",
  "registry-mirrors": ["https://docker.1ms.run", "https://docker.m.daocloud.io"]
}

回显：

 Registry Mirrors:
  https://docker.1ms.run/
  https://docker.m.daocloud.io/

注意事项：

• daemon 启动时不校验镜像源可达性，docker info 会列出全部已配源（含死源）；死源仅在 pull 时被尝试并超时后回退下一个。
• 作用面：仅对 docker.io / Docker Hub 生效；私有仓库走自身地址，不经 mirror。
• 语法：数组逗号分隔，地址须带 http(s)://。

insecure-registries（非 TLS 私有仓库白名单）

允许 HTTP（无 TLS）或自签证书仓库：

{
  "data-root": "/opt/data/docker",
  "insecure-registries": ["192.168.1.0/24", "10.20.30.40:5000"]
}

回显：

 Insecure Registries:
  10.20.30.40:5000
  192.168.1.0/24
  ::1/128
  127.0.0.0/8

注意事项：

• ::1/128 与 127.0.0.0/8 是 daemon 内置本地项，恒有。
• 支持 host:port 与 CIDR 两种写法；CIDR 宿主位会被自动截断到网络地址（如 10.20.30.40/24 → 10.20.30.0/24）。
• ⚠️ 安全警示：会降低对应地址的传输安全，仅对可信内网地址使用。

二、数据与存储参数

data-root（数据目录）

指定 Docker 数据根目录。实测缺目录会自动创建：

{
  "data-root": "/opt/data/docker-test-mkdir"
}

回显：

$ ls /opt/data/docker-test-mkdir
buildkit containers engine-id image network plugins runtimes swarm tmp volumes
$ docker info --format "DockerRootDir={{.DockerRootDir}}"
DockerRootDir=/opt/data/docker-test-mkdir

注意事项：

• 缺目录自动创建（root:root drwx--x---）。
• ⚠️ 新 data-root 是「空地基」：改路径后在新目录下看不到旧镜像/容器/卷。真实迁移：停止 docker → 迁移/保留旧数据 → 改配置 → 启动。

storage-driver（存储驱动）

29.8.1 默认走 containerd-snapshotter 的 overlayfs：

 Storage Driver: overlayfs
  driver-type: io.containerd.snapshotter.v1

显式配置会关闭 snapshotter 改用传统 graphdriver：

{ "data-root": "/opt/data/docker", "storage-driver": "vfs" }

Driver=vfs
[graphdriver] trying configured driver: vfs

⚠️ 改 storage-driver 后现有镜像/容器不可见，需迁移镜像层；不同 driver 之间不通用。

三、网络相关参数

bip（默认网桥网段）

改变默认 docker0 网桥网段：

{ "data-root": "/opt/data/docker", "bip": "172.28.0.1/16" }

验证：

docker0 IP= 172.28.0.1

注意事项：

• 语法 "bip": "<IP>/<掩码>"，默认 172.17.0.1/16。
• ⚠️ 与 bridge 互斥，同配启动失败。
• ⚠️ 改 bip 不会改变已创建的 docker0 接口 IP，真实主机通常需重建网桥。

bridge / fixed-cidr / default-address-pools

• bridge：默认网桥设备名，与 bip 不可同时指定，实测冲突：

failed to start daemon: You specified -b & --bip, mutually exclusive options. Please specify only one

• fixed-cidr：限制默认网桥上容器 IP 分配范围（如 172.28.0.128/25）。
• default-address-pools：创建自定义网络且不指定 --subnet 时自动分配网段：

{ "default-address-pools": [{"base": "172.30.0.0/16", "size": 24}] }

实测（不带子网建网）：

$ docker network create pool-test-nw2
2c321c4da06b...
$ docker network inspect <id> --format "Subnet={{range .IPAM.Config}}{{.Subnet}}{{end}}"
Subnet=172.30.0.0/24

iptables / ip-forward / ip-masq / icc

• iptables=false + icc=false 启动失败（真实冲突）：

failed to start daemon: You specified --iptables=false with --icc=false. ICC=false uses iptables to function. Please set --icc or --iptables to true

• 29.8.1 的 docker info 不再回显这三项；以 /proc/sys/net/ipv4/ip_forward（ip-forward）、iptables NAT 链（ip-masq）、容器互 ping（icc）为验证。
• 语义：ip-forward（默认 true，容器出网转发）、ip-masq（默认 true，默认网桥出网 NAT）、icc（默认 true，默认网桥上容器互访）。
• ⚠️ icc=false 依赖 iptables，二者不可同时为 false。

四、日志与并发参数

log-driver / log-opts

默认 json-file；可换 local 或 json-file + 轮转：

{
  "data-root": "/opt/data/docker",
  "log-driver": "json-file",
  "log-opts": {"max-size": "10m", "max-file": "3"}
}

• docker info 的 Logging Driver 能直接看到 json-file/local 切换。
• log-opts 不回显在 info；用 docker inspect <容器> --format '{{.HostConfig.LogConfig}}' 查看。语义：max-size 单文件上限到即轮转，max-file 保留文件数。

max-concurrent-downloads / max-concurrent-uploads / max-download-attempts

{
  "max-concurrent-downloads": 3,
  "max-concurrent-uploads": 3,
  "max-download-attempts": 2
}

• docker info 无对应字段，配置即生效，以实际批量拉/推带宽、失败重试次数为验证。
• 默认：downloads=3、uploads=5、attempts=5。

五、安全与运维参数

debug / live-restore / metrics-addr / userland-proxy

{
  "debug": true,
  "live-restore": true,
  "metrics-addr": "0.0.0.0:9323"
}

回显：Debug Mode: true、Live Restore Enabled: true。metrics 实测可达：

$ curl -s -o /dev/null -w "curl HTTP=%{http_code}\n" http://127.0.0.1:9323/metrics
curl HTTP=200

• debug → 冗长日志，供排障，生产一般关。
• live-restore → daemon 重启/升级时不停机运行中的容器。
• metrics-addr → 暴露 Prometheus /metrics；⚠️ 勿在生产暴露公网。
• userland-proxy → true 用 docker-proxy 用户态转发，false 纯内核 NAT（需 iptables）。true 时 info 显示 EnableUserlandProxy、UserlandProxyPath 两行，false 时消失。

hosts / tls（远程访问，安全重点）

在 daemon.json 声明监听 TCP：

{
  "data-root": "/opt/data/docker",
  "hosts": ["fd://", "tcp://0.0.0.0:2375"]
}

因 systemd 的 docker.service 已带 -H fd://，重复声明会启动失败：

the following directives are specified both as a flag and in the configuration file:
hosts: (from flag: [fd://], from file: [fd:// tcp://0.0.0.0:2375])

注意事项（安全警示重点）：

• hosts 与命令行 -H 只能二选一。
• ⚠️ 极度危险：tcp://0.0.0.0:2375 是无 TLS、无认证的 Docker API。暴露后任何能连到该端口的人都等同于拿到该主机的 root 级容器管理权限。生产不开放；如需远程访问必须配 TLS："tls": true + tlscacert/tlscert/tlskey。

六、补充参数与旧字段说明

除上文讲解的参数外，daemon.json 还支持以下常用项。部分参数在 docker info 无直接回显，按官方文档语义说明用法如下（配置方式与上文一致：改 json → systemctl restart docker）。

旧字段 graph 已更名 data-root

早期文档里用 "graph" 指定数据目录（如 "graph": "/opt/starviews/data/docker"）。当前版本该字段已更名为 data-root，写法：

{
  "data-root": "/opt/starviews/data/docker",
  "registry-mirrors": ["https://hub-mirror.c.163.com"]
}

⚠️ graph 是安装早期 1.x/18.x 时代的字段名，新版本（18.09+）用 data-root；继续写 graph 会被忽略，务必改 data-root。

DNS 相关参数

为默认网桥上所有容器统一配置 DNS：

{
  "dns": ["192.168.1.1"],
  "dns-search": ["example.com", "corp.example.com"],
  "dns-opts": ["use-vc", "timeout:3"]
}

• dns：设定容器 DNS 地址，容器内的 /etc/resolv.conf 可查看（若配 --dns 会覆盖）。
• dns-search：设定容器搜索域；如搜索域为 .example.com，解析 host 时会同时查询 host 与 host.example.com。不设置则用主机的 /etc/resolv.conf 配置容器。
• dns-opts：写入 /etc/resolv.conf 的额外选项（如 ndots、timeout）。

网络增强参数

{
  "ipv6": true,
  "default-gateway": "192.168.1.1",
  "default-gateway-v6": "fd00::1",
  "ip": "0.0.0.0",
  "mtu": 1500,
  "iptables": true,
  "ip-masq": true,
  "ip-forward": true,
  "userland-proxy": true,
  "fixed-cidr-v6": "fd00:dead:beef::/64"
}

• ipv6：是否启用 IPv6 网络（还需系统启 IPv6 内核支持）。
• default-gateway / default-gateway-v6：默认网桥上容器的默认网关 IPv4/IPv6 地址。
• ip：绑定容器端口时的默认监听 IP（默认 0.0.0.0，即映射到所有接口）。
• mtu：容器网络 MTU，内网环境按物理链路调整（如 1450 的某些云）。
• fixed-cidr-v6：默认网桥 IPv6 地址分配段。

labels（daemon 标签）

给 Docker 守护进程打标签，常用于监控/调度识别：

{
  "labels": ["nodeName=node-121", "region=cn-hangzhou"]
}

log-level（日志级别）

{ "log-level": "warn" }

可选 debug | info | warn | error | fatal，默认 info。排障可临时调 debug。

storage-opts（存储驱动选项）

随 storage-driver 使用的驱动级选项，如 overlay2：

{
  "storage-driver": "overlay2",
  "storage-opts": ["overlay2.override_kernel_check=true", "overlay2.size=15G"]
}

overlay2.size=15G 需配合按容器限大小的环境（如报告/配额），普通主机不必设。

安全隔离 / 运行时参数

{
  "userns-remap": "default",
  "selinux-enabled": false,
  "default-runtime": "runc",
  "authorization-plugins": [],
  "oom-score-adjust": -500,
  "group": "docker",
  "pidfile": "/var/run/docker.pid",
  "raw-logs": false
}

• userns-remap：用户命名空间重映射（如 default），把容器 root 映射到非特权用户，增强隔离；启用会影响卷权限，需评估。
• selinux-enabled：是否启用 SELinux 支持（RHEL/CentOS 系默认 true，Ubuntu 默认 false）。
• default-runtime：容器默认 OCI 运行时（默认 runc；装了 gVisor/Kata 等可切）。
• authorization-plugins：要加载的授权插件（外置访问控制）。
• oom-score-adjust：守护进程自身的 oom_score_adj（默认 -500）。
• group：docker.sock 的 Unix 组（默认 docker）。
• pidfile：守护进程 PID 文件路径。
• raw-logs：全时间戳的输出格式。

集群相关参数（Swarm）

{
  "cluster-store": "etcd://192.168.1.10:2379",
  "cluster-store-opts": {},
  "cluster-advertise": "192.168.1.10:2376",
  "swarm-default-advertise-addr": ""
}

用于过时的共享集群存储 / Swarm 广播地址配置；新项目一般用原生 docker swarm join，无需这些字段。

生产配置模板

适用：8GB 以上内存、SSD 磁盘、容器化部署通用场景：

{
  "data-root": "/opt/data/docker",
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" },
  "registry-mirrors": ["https://docker.1ms.run", "https://docker.xuanyuan.me"],
  "max-concurrent-downloads": 5,
  "max-concurrent-uploads": 5,
  "live-restore": true
}

生产多数环境（尤其 K8s）建议 cgroupdriver=systemd；若由云平台统一管理防火墙，可再审视 iptables=false 的影响。

常见问题

参考链接

• Docker daemon 配置参考官方文档：https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file