Docker IPv6链路本地地址固定配置：LinkLocalIPv6Address与PrefixLen详解

最近有不少朋友问 Docker 网络配置里LinkLocalIPv6Address和LinkLocalIPv6PrefixLen这两个参数是干嘛的，也有人是从某个容器管理面板的输入框里看到的，还有人是翻 API 文档时见到这两个字段的名字。其实不用纠结它具体出现在哪个入口，这俩参数放在一起，要干的事情就一句话：给容器的网络接口指定一条固定的 IPv6 链路本地地址。

听起来简单，实际落地时坑不少。我最早被这个东西搞懵，是因为在容器里跑一个需要绑定固定链路本地地址的集群组件，容器每次重建地址都变，服务发现直接失效。后来翻了不少资料，看了 Docker 底层 API 的 IPAM 设计，才算彻底搞明白。这篇就把这两个参数的原理、配置方式和排障经验一次讲透，就算你对 IPv6 还不太熟，按照步骤也能自己复现。

1. 链路本地地址：IPv6 世界里最容易被忽略的“门牌号”

1.1 为什么容器需要链路本地地址

IPv6 地址分类里，单播地址又分成三种：全局单播地址（Global Unicast Address）、唯一本地地址（Unique Local Address）和链路本地地址（Link-Local Address）。前面两种大家多少听说过，链路本地地址是最容易被忽略的。

链路本地地址长什么样？最常见的形式是fe80::开头的地址，比如fe80::1，前缀是fe80::/10。这类地址有几个非常特殊的性质：

• 永远不出二层网络。也就是说，这个地址只在同一个物理链路或虚拟局域网内有效，路由器不会转发任何以fe80::为源或目的地址的报文。
• 不需要手动配置也能有。只要接口启用了 IPv6，内核就会自动生成一个链路本地地址。
• 每个接口至少一个。一台设备的每个启用 IPv6 的接口，都会有自己的链路本地地址。

我用个生活化的类比：链路本地地址等于工位号，只在同一个办公室（同一个二层网络）里有用，出了办公室门就没人认这个号了。而全局单播地址等于手机号，任何人在任何地方都能通过它找到你。

那容器呢？Docker 给容器创建的网络接口（通常叫eth0），本质上是宿主机上的一个虚拟接口对，容器的eth0和宿主机的veth设备配对组成一条虚拟网线。容器之间通过 Docker 网桥通信时，它们就在同一个二层网络里。这时候，链路本地地址在容器里同样存在，而且承担着一个重要职责：IPv6 邻居发现协议（NDP）依赖链路本地地址。

NDP 在 IPv6 里相当于 IPv4 的 ARP，用来解析同一个链路内邻居的 MAC 地址。NDP 的报文源地址必须是链路本地地址。所以可以这么说：只要启用了 IPv6，容器就离不开链路本地地址。

1.2 fe80::/10 与自动生成规则

既然系统会自动生成链路本地地址，为什么还要手动指定？先看看自动生成规则。

Linux 系统生成 IPv6 链路本地地址有两种主流方式：

• EUI-64 规则：根据接口的 MAC 地址，把0xfffe插入 MAC 中段，再翻转 U/L 位，得到一个 64 位的接口标识符，拼接在fe80::后面。比如 MAC 是02:42:ac:11:00:02，算出链路本地地址一般是fe80::42:acff:fe11:2/64。
• 隐私扩展（RFC 4941）：生成随机接口标识符，定期更换，强调匿名性。

Docker 容器也有同样的情况。如果容器启用了 IPv6，内核会自动给容器的eth0配置一个基于 MAC 地址的链路本地地址。

问题来了：这个地址不是固定的。容器网络命名空间重建后，MAC 地址可能变，计算出来的链路本地地址也跟着变。哪怕 MAC 地址不变，如果你在容器里启用了隐私扩展，地址也可能定期轮换。

对于跑在容器里的服务，如果某个程序配置绑定了特定链路本地地址，或者另一个主机 / 容器通过这个链路本地地址访问它，地址一换，连接立刻断。这时候就需要LinkLocalIPv6Address来人为固定一个值，让容器每次启动后的链路本地地址都是同一张“门牌号”。

注意：在 IPv6 里，链路本地地址和全局单播地址是独立配置的，互不替代。你给容器指定了固定链路本地地址，内核依然会自动生成默认的那个，能看得到两个fe80::/64地址。这正常，别觉得是配置冲突。

2. 两个参数的真实身份：地址 + 前缀长度的组合

2.1 从 Docker API 的 IPAMConfig 说起

在 Docker 的底层设计中，容器的网络配置被拆解成若干独立的字段，IPAMConfig（IP Address Management Config）就是负责管理网络地址分配的核心结构。在 Docker Engine API 里，创建容器时可以指定每个网络端点的 IPAM 配置，其中三个字段是关键：

LinkLocalIPv6Address和LinkLocalIPv6PrefixLen，本质是对LinkLocalIPs中 IPv6 这条数据的拆分展示。

把这两个字段分开设计，是有实际考虑的在某些管理平台或配置工具中，需要把“地址值”和“前缀长度”分开录入，于是就成了你在界面上看到的两个输入框：一个让你填地址，一个让你填前缀长度。LinkLocalIPv6Address存具体地址，LinkLocalIPv6PrefixLen存前缀位数。二者合起来才是一条完整的地址配置，比如fe80::2/64。

Docker Python SDK 中也有对应的参数。用 SDK 创建容器时，可以传入类似这样的配置：

import docker client = docker.from_env() network = client.networks.get("my-ipv6-net") container = client.containers.run( "ubuntu:22.04", command="sleep infinity", detach=True, network=network.name, ipv6_address="2001:db8:1::100", endpoint_config={ "IPAMConfig": { "IPv4Address": "172.20.0.100", "IPv6Address": "2001:db8:1::100", "LinkLocalIPs": ["fe80::2"] } } )

这段代码里没有出现前缀长度，是因为 Docker 的处理逻辑是：链路本地地址在容器内默认按/64配置。IPv6 链路本地地址的标准前缀虽然是fe80::/10，但在 Linux 网络栈、Docker 网桥和绝大多数实际部署中，链路本地地址的子网都是/64。这也是为什么很多工具界面只让你填地址，前缀长度给你默认好，或者作为一个单独字段让你选填，默认就是 64。

但标题里的LinkLocalIPv6PrefixLen出现了，说明某些工具或框架允许你显式控制这个值。那我们就必须搞清楚：这个前缀长度到底影响什么。

2.2 前缀长度的分量比想象中重

地址前缀的作用是告诉内核，这个地址属于哪个子网、目标地址在什么范围内算同一链路。对于链路本地地址来说，前缀长度直接参与内核路由决策。

举个例子。容器接口上配置了fe80::abcd:1/64，内核会认为fe80::abcd:1到fe80::abcd:ffff:ffff:ffff:ffff这个区间内的地址都在同一链路上，发往这些地址的报文会走邻居发现协议解析 MAC 地址然后直接发送。

如果你在配置时把前缀长度写成了/10，也就是理论上 IPv6 链路本地地址的完整前缀长度fe80::/10，这时候内核会认为所有从fe8000::到febfffff范围的地址都算同一链路。听着好像没问题？实际上问题很大。标准实现中，同一个二层网络里所有启用 IPv6 的节点默认都在fe80::/64这个子网内通信，大家使用的是基于 MAC 地址推算的地址。你把前缀扩到/10，等于宣称一个巨大的地址空间都在你的接口上，这不符合链路本地地址的实际部署模型，容易引发邻居解析异常、路由冲突。

反过来，写成/128也不行。/128表示这个地址只匹配它自己，往fe80::abcd:2发的报文内核会认为目标不在同一链路，直接返回Network is unreachable。

所以结论是：除非你非常清楚自己在做什么，否则LinkLocalIPv6PrefixLen一律填 64。

3. 实操：三种方式配置容器的 IPv6 链路本地地址

这一章直接上可复现的操作。以下三种方式，适用场景不太一样，我按推荐程度排了序。

3.1 方式一：通过 Docker SDK / API 精确设置

如果你的容器是通过程序化方式创建的，比如写自动化脚本、做平台二次开发，用 SDK 或者直接调 API 是最干净的方案。

先准备网络环境。要让容器启用 IPv6，宿主机 Docker daemon 需要开启 IPv6 支持，同时创建一个带 IPv6 子网的网络。具体步骤：

1. 修改/etc/docker/daemon.json，加入：

{ "ipv6": true, "fixed-cidr-v6": "2001:db8:1::/64" }

2. 重启 Docker：

sudo systemctl restart docker

3. 创建自定义网络，指定 IPv6 子网：

docker network create --ipv6 --subnet=172.20.0.0/16 --subnet=2001:db8:1::/64 my-ipv6-net

然后通过 Python SDK 创建容器并指定链路本地地址：

import docker client = docker.from_env() container = client.containers.run( "ubuntu:22.04", command="sleep infinity", detach=True, network="my-ipv6-net", ipv6_address="2001:db8:1::100", endpoint_config={ "IPAMConfig": { "IPv4Address": "172.20.0.100", "IPv6Address": "2001:db8:1::100", "LinkLocalIPs": ["fe80::2"] } } ) print(container.id)

进入容器验证：

docker exec -it <容器ID> ip -6 addr show eth0

预期能看到类似输出：

1: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 state UP inet6 fe80::2/64 scope link inet6 2001:db8:1::100/64 scope global

注意第一行，fe80::2/64 scope link，链路本地地址固定为fe80::2，前缀是/64，作用范围是 link，这说明配置已经生效。

走 API 的方式原理一样。直接向 Docker 的 socket 发送 POST 请求时，body 里的网络配置结构如下：

{ "NetworkingConfig": { "EndpointsConfig": { "my-ipv6-net": { "IPAMConfig": { "IPv4Address": "172.20.0.100", "IPv6Address": "2001:db8:1::100", "LinkLocalIPs": ["fe80::2"] } } } } }

你可能会问，LinkLocalIPv6Address这个字段名在 API 里哪儿去了？实际上在 Docker Engine API 的EndpointIPAMConfig中，链路本地地址的字段名是复数形式的LinkLocalIPs。标题里的LinkLocalIPv6Address更多是上层工具或者开发库对单个 IPv6 链路本地地址的命名，对应到底层就是这个数组元素。

提示：不同版本的 Docker SDK 字段名可能有差异。用 Python SDK 时，字段是endpoint_config；用 Go SDK 时，结构体是network.EndpointIPAMConfig，字段为LinkLocalIPs。如果你写的代码编译不过，优先检查字段名。

3.2 方式二：借助 docker run 加启动脚本

如果不想写代码，又需要固定链路本地地址，可以在docker run之后进入容器手动配置，或者通过容器的启动命令自动配置。这种方式更适合临时调试、少量容器场景。

先正常启动一个容器：

docker run -itd --name test-v6 --network my-ipv6-net --ip6 2001:db8:1::100 ubuntu:22.04

进入容器：

docker exec -it test-v6 bash

然后执行：

ip -6 addr add fe80::2/64 dev eth0

验证：

ip -6 addr show dev eth0

这个方式手动添加的链路本地地址，问题在于：容器重启后失效。容器里的eth0接口在每次容器启动时由 Docker 重建，手动ip addr add配的地址不会保留。

解决办法是把配置动作放进容器的入口脚本里。比如写一个启动脚本：

#!/bin/bash ip -6 addr add fe80::2/64 dev eth0 2>/dev/null || true exec "$@"

构建镜像时把脚本复制进去，并设置为 ENTRYPOINT：

FROM ubuntu:22.04 RUN apt-get update && apt-get install -y iproute2 COPY entrypoint.sh /entrypoint.sh RUN chmod +x /entrypoint.sh ENTRYPOINT ["/entrypoint.sh"] CMD ["sleep", "infinity"]

或者不用重新构建镜像，直接覆盖容器的启动命令：

docker run -itd \ --name test-v6 \ --network my-ipv6-net \ --ip6 2001:db8:1::100 \ --entrypoint /bin/bash \ ubuntu:22.04 \ -c "ip -6 addr add fe80::2/64 dev eth0 && sleep infinity"

这样每次容器启动都会先配置链路本地地址，再运行实际进程。

3.3 方式三：在 Compose 生态中变通

Docker Compose 目前没有直接的键值来设置容器链路本地 IPv6 地址，这是很多人找半天找不到参数的原因。但不代表做不了，有变通方案。

思路是利用 Compose 的ipv6_address设置全局单播地址，再靠容器内的 entrypoint 脚本补链路本地地址配置。

docker-compose.yml示例：

services: app: image: ubuntu:22.04 container_name: app-v6 command: ["/entrypoint.sh", "sleep", "infinity"] networks: my-ipv6-net: ipv6_address: 2001:db8:1::100 ipv4_address: 172.20.0.100 volumes: - ./entrypoint.sh:/entrypoint.sh networks: my-ipv6-net: driver: bridge enable_ipv6: true ipam: config: - subnet: 172.20.0.0/16 - subnet: 2001:db8:1::/64

entrypoint.sh内容：

#!/bin/bash ip -6 addr add fe80::2/64 dev eth0 2>/dev/null || true exec "$@"

启动：

docker compose up -d

验证：

docker exec app-v6 ip -6 addr show eth0

这个方案的核心思路是：Compose 负责分配网络和全局 IPv6 地址，用户脚本负责补充配置链路本地地址。脚本里的|| true是有讲究的，如果地址已经存在（比如再次执行命令），ip -6 addr add会报错，加上这个可以让脚本幂等执行。

提示：Compose 的enable_ipv6: true在较新的 Docker Compose 版本中语法不变，但依赖 daemon 本身已经开启 IPv6 支持。如果 Docker daemon 没开 IPv6，Compose 不会自动开启，会直接报错或忽略。

4. 踩坑实录与问题排查

配置链路本地地址，最坑的几个问题我都遇到过，列出来帮你少走弯路。

4.1 Docker 没开启 IPv6，参数被静默忽略

这是最常见的问题。LinkLocalIPs配置传进去了，但容器里ip -6 addr show什么都看不到，用docker inspect看网络配置，也没发现异常，整个配置像被吞了一样。

原因很简单：Docker daemon 的 IPv6 支持没开启，全局 IPv6 子网没分配，链路本地地址配置根本没有载体。Docker 默认网络bridge是不支持 IPv6 的，如果你的容器跑在默认网络下，哪怕 API 传了 LinkLocalIPs 也不会生效。

排查方法：

1. 在宿主机执行：

docker network inspect bridge | grep -i ipv6

如果EnableIPv6是 false，就说明网络没开。

2. 检查 daemon 配置：

cat /etc/docker/daemon.json

看有没有"ipv6": true和"fixed-cidr-v6"。这两个缺一不可。

3. 确认当前容器连的哪个网络：

docker inspect <容器ID> --format '{{range $key, $value := .NetworkSettings.Networks}}{{$key}} {{end}}'

解决办法：按 3.1 节的方式配置 daemon.json 和自定义网络，然后把容器连到自定义 IPv6 网络上。

4.2 链路本地地址冲突引发诡异网络问题

链路本地地址是二层域内唯一的，如果你给多个容器配了相同的fe80::2，它们在同一个 Docker 网桥下，会发生地址冲突，现象非常隐蔽。

我第一次遇到时，容器 A 能 ping 通fe80::2，过几秒又不通了，有时候容器 B 响应，有时候 A 自己响应。看路由表一切正常，网桥也正常，最后才发现两个容器用了同一个链路本地地址。

IPv6 的邻居发现机制里，地址冲突会导致邻居缓存反复更新，流量在冲突节点之间抖来抖去。症状就是通断交替，看起来像网络拥塞，实际上是地址打架。

排查命令，在宿主机上抓包：

tcpdump -i docker0 -n icmp6

能看到大量 Neighbor Solicitation / Neighbor Advertisement 报文的循环。也可以直接在容器里 ping 固定的链路本地地址，再用ip neigh show看 MAC 地址是否反复变化。

解决方法很简单：给每个容器分配唯一的链路本地地址。建议链路本地地址的最后一段和容器全局 IPv6 地址的后缀保持一致，比如全局地址是2001:db8:1::10，链路本地地址就取fe80::10。这样既好记又好排查。

4.3 前缀长度写错导致 Network is unreachable

我见过有人把LinkLocalIPv6PrefixLen配成 10，觉得 IPv6 链路本地地址标准前缀就是/10，没问题。结果容器里访问同一个链路内的 IPv6 全局地址没问题，一旦访问对方的链路本地地址，立刻报Network is unreachable。

原因我前面分析过：内核会按照地址前缀建立路由表。前缀配置为/10时，Linux 会把目标范围内地址当作链路内可达，但实际邻居发现的处理方式在/64子网内才正常工作，过高层次的前缀会让邻居发现报文发不出去。

正确做法很简单：前缀填 64，不要填 10。虽然 IPv6 链路本地地址的标准前缀确实是/10，但那是地址类型的分类前缀，不是接口的子网前缀。实际网络中默认链路本地子网前缀是/64。这个点翻 RFC 4291 也能验证，链路本地地址的接口标识符长度是 64 位。

4.4 容器重启后地址丢失

这种场景多发生在 Docker 版本较老的镜像里。老版本iproute2可能在容器启动时没有正确保留手动添加的地址，或者你的启动命令里没有做幂等处理。

如果发现地址时有时无，检查启动脚本是否正确执行。可以用：

docker logs <容器ID>

看看容器的 stdout / stderr 有没有ip -6 addr add报错。加上|| true的幂等逻辑，排除重复执行导致的报错。

4.5 Docker Desktop 下的 IPv6 限制

Windows 和 macOS 上的 Docker Desktop 对 IPv6 的支持一直比较受限。Docker Desktop 默认的虚拟机里 IPv6 支持不完整，即使你在daemon.json开了 IPv6，链路本地地址的固定配置也可能不生效。

如果你在 Docker Desktop 上做实验发现配置不生效，建议优先在 Linux 环境验证。如果是 Docker Desktop 需要支持 IPv6 场景，检查 Settings -> Resources -> Network 里的 IPv6 选项是否勾选，并且把 Docker daemon 配置中 IPv6 相关项设置齐全。

5. 一些经验与建议

5.1 地址规划思路

在给容器配置固定链路本地地址之前，建议先做一个简单的地址规划，别随手填。我个人的思路是：

• 每个容器的链路本地地址和它在该网络中的全局 IPv6 地址对齐，比如全局2001:db8:1::10，链路本地取fe80::10。
• 宿主机网桥的链路本地地址固定为fe80::1，这样容器内要访问宿主机时，用fe80::1比找宿主机全局地址更稳定。
• 预留一段链路本地地址给基础组件，比如fe80::2留给网关代理，fe80::3留给 DNS 服务。
• 避免使用fe80::1给多个容器，这在大部分 Linux 系统里已经默认被网桥占用了。

5.2 固定链路本地地址的实际收益

很多人觉得 IPv6 链路本地地址反正只在本二层有效，对它不够重视。但在容器场景里，固定它有几个实际收益：

• 服务注册更可靠。像 etcd、Consul、某些分布式存储组件，节点间探测会让节点上报自己的地址。如果上报的是变化的链路本地地址，集群会频繁出现节点抖动。
• 排障更容易。链路本地地址固定后，抓包时一眼能看出流量来自哪个容器，不用每次对着 MAC 地址猜是谁。
• 安全策略可下发。某些网络策略工具支持按 IPv6 链路本地地址做白名单，地址固定后才好配策略。

5.3 最后分享一个调试技巧

配置完链路本地地址后，最快的验证方式是容器内执行：

ping6 -c 3 fe80::1

在 Docker 环境下，fe80::1通常是网桥的地址，能 ping 通说明对应链路本地地址生效。如果这步都通，再去排查更深入的问题。这个技巧我每次搭完容器环境都会先跑一遍，几秒钟就能确认链路是不是通的。

另一个技巧是查看邻居表：

ip -6 neigh show dev eth0

能看到已解析的链路本地地址对应的 MAC。如果某个目标反复在REACHABLE和STALE之间跳变，基本就是它有多个地址同时对同一链路通信，或存在地址冲突，按 4.2 的思路去排查就行。

关于LinkLocalIPv6Address和LinkLocalIPv6PrefixLen，要说的话就这么多。核心记住一点：链路本地地址在 IPv6 网络里不是可有可无的配角，容器世界里它同样影响服务可用性。固定地址，填对前缀，网络就稳了一半。