Linux systemd依赖网络就绪状态的启动顺序配置

我在 Linux 上遇到过一种很容易误判的启动问题：服务文件已经写了 After=network.target，但程序启动时仍拿不到可用地址，或者 DNS 和默认路由还没有准备好。原因是 network.target 只表示网络管理栈已经启动，并不承诺网络连接已经建立。需要网络客户端条件的服务，应在 [Unit] 中同时使用 Wants=network-online.target 和 After=network-online.target；普通监听型服务通常只保留 After=network.target，再由程序自己处理网络变化。

systemd 官方说明：https://systemd.io/NETWORK_ONLINE/

network.target 与 network-online.target 的职责边界

这两个 target 名字相近，语义却不是一回事。network.target 是被网络管理服务拉起的被动单元，排序到它之后，更多是为了关机时让使用网络的服务先停下来；启动阶段不能据此推断接口、地址、路由或 DNS 已经就绪。给业务服务盲目添加 Wants=network.target，既不能获得等待效果，还会把依赖方向写反。

network-online.target 则是消费者按需拉起的主动目标。它通常等待网络管理器报告“已配置、可路由”的状态，但“online”的具体判定仍取决于当前网络管理器和接口配置。远程挂载、需要启动即访问外部服务的同步客户端，才适合使用它；一个能先监听本地地址、稍后重试连接的网络服务，不应为了省事拖慢整台机器的启动。

服务单元里的依赖配置怎么写

假设 sync-client.service 启动后必须访问远端 API，可以把等待条件放在服务自己的消费者边界中：

[Unit]
Description=远端同步客户端
# 由消费者主动拉起网络就绪目标
Wants=network-online.target
# 只表达启动排序，不负责拉起目标
After=network-online.target

[Service]
Type=simple
# 程序仍需自行处理断网和重试
ExecStart=/usr/local/bin/sync-client --config /etc/sync-client/config.toml
Restart=on-failure

[Install]
WantedBy=multi-user.target

改完后执行 systemctl daemon-reload，再重启或重新启动服务。这里 Wants= 负责把目标纳入这次启动事务，After= 负责排序；只有写 After= 而没有任何依赖把目标拉起来时，排序关系可能没有实际等待对象。反过来，只有 Wants= 没有 After=，两个单元仍可能并行启动。

等待服务要和网络管理器配套

配置了 network-online.target 不代表系统自动知道应该等谁。NetworkManager 常见的实现是 NetworkManager-wait-online.service，systemd-networkd 则对应 systemd-networkd-wait-online.service。官方文档说明，主网络管理服务启用时通常会带上对应等待单元，但最好在故障机器上直接确认：

# 查看两个常见等待实现，通常只有当前网络管理器对应的一项会启用
systemctl is-enabled NetworkManager-wait-online.service systemd-networkd-wait-online.service

# 查看网络就绪目标实际拉入了哪些依赖
systemctl list-dependencies network-online.target

# 查看当前服务声明的依赖与排序关系
systemctl show sync-client.service -p Wants -p Requires -p After

如果两个 wait-online 单元都没有启用，服务即使写对了依赖也可能只等到一个空目标；如果等待时间异常长，则应回头看 DHCP、载波、桥接或接口的 RequiredForOnline= 等条件，而不是简单把 timeout 无限调大。

排查启动顺序时先看依赖再看时间

遇到“服务启动太早”时，我会先确认它是否真的进入了等待链，再看启动日志。下面三条命令分别回答依赖是否存在、哪一段拉长了关键链、服务本身是否在网络错误后退出：

# 观察服务之后的静态依赖，确认 network-online.target 是否在链路中
systemctl list-dependencies --after sync-client.service

# 查看本次启动的关键路径，定位等待来自哪个单元
systemd-analyze critical-chain sync-client.service

# 查看本次启动中客户端自身的连接失败和重试记录
journalctl -b -u sync-client.service --no-pager

常见问题

只写 After=network-online.target 可以吗？

不建议。它只建立排序，不主动把目标拉进启动事务；对于必须等待网络的消费者，通常应与 Wants=network-online.target 配对。

network-online.target 能保证外部 API 一定可访问吗？

不能。它的“online”由网络管理器定义，连接随后仍可能中断，应用必须保留超时、重试和恢复逻辑。

为什么加了等待后开机变慢？

常见原因是 DHCP、无线扫描、网卡载波或桥接接口没有达到 wait-online 的条件。先用依赖树和日志确认具体等待单元，再修正接口配置。