macOS launchctl 服务依赖配置实战：以 Kafka 依赖 Zookeeper 为例

---

• 概述
• 实现方案
  • 核心配置项
  • 1. Zookeeper 服务定义
  • 2. Kafka 服务定义（带依赖配置）
  • 3. 加载服务
  • 4. 验证效果
• 拓展：其他常见的服务依赖场景
• 注意事项
• 总结
• 延伸阅读

概述

在 macOS 环境下使用 launchctl 管理服务时，经常会遇到服务依赖的问题。

以 Kafka 为例：Kafka 在启动时必须依赖 Zookeeper 服务已经成功运行，否则 Kafka 会因为无法连接 Zookeeper 而启动失败。

如果直接通过 launchctl 将两个服务都配置为开机自启，由于启动顺序不可控，很可能出现以下情况：

Zookeeper 尚未启动 → Kafka 尝试启动 → 连接 Zookeeper 失败 → Kafka 启动失败 ❌

本文将演示如何通过 launchctl 的 plist 配置，让 Kafka 在启动时等待 Zookeeper 就绪后再启动，从根本上解决启动顺序问题。

实现方案

核心配置项

在 launchd 的 plist 配置中，通过以下两个关键配置实现服务依赖：

配置项	作用
KeepAlive + OtherJobEnabled	指定当前服务依赖的目标服务 Label，只有当目标服务启用时，当前服务才会保持运行
After	明确指定当前服务在哪些服务之后启动（启动顺序控制）

两者配合使用，可以确保：

1. 启动顺序：依赖服务（Zookeeper）先启动
2. 运行依赖：依赖服务异常退出时，当前服务（Kafka）也会自动停止（可选行为）

1. Zookeeper 服务定义

Zookeeper 作为被依赖的服务，不需要特殊配置，按标准方式定义即可：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>Description</key>
        <string>Zookeeper - 是一个开源的分布式协调服务，为分布式应用提供高效且可靠的协调功能，最初由雅虎开发，后来成为 Apache 软件基金会的顶级项目。</string>
        <key>Disabled</key>
        <true/>
        <key>KeepAlive</key>
        <true/>
        <key>Label</key>
        <string>apache.org.zookeeper</string>
        <key>ProcessType</key>
        <string>Background</string>
        <key>ProgramArguments</key>
        <array>
            <string>/usr/local/opt/kafka/bin/zookeeper-server-start.sh</string>
            <string>/usr/local/opt/kafka/config/zookeeper.properties</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>StandardErrorPath</key>
        <string>/usr/local/var/log/zookeeper.log</string>
        <key>StandardOutPath</key>
        <string>/usr/local/var/log/zookeeper.log</string>
        <key>Version</key>
        <string>v3.8.4</string>
    </dict>
</plist>

2. Kafka 服务定义（带依赖配置）

Kafka 服务的配置是本文的核心，重点在 KeepAlive 和 After 字段：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>Description</key>
        <string>Kafka - 是一个开源分布式事件流平台，成千上万公司用于高性能数据管道，流分析，数据集成和关键任务应用程序。</string>
        <key>Disabled</key>
        <true/>
        <key>KeepAlive</key>
        <dict>
            <key>OtherJobEnabled</key>
            <string>apache.org.zookeeper</string>
        </dict>
        <key>After</key>
        <array>
            <string>apache.org.zookeeper</string>
        </array>
        <key>Label</key>
        <string>apache.org.kafka</string>
        <key>ProcessType</key>
        <string>Background</string>
        <key>ProgramArguments</key>
        <array>
            <string>/usr/local/opt/kafka/bin/kafka-server-start.sh</string>
            <string>/usr/local/opt/kafka/config/server.properties</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>StandardErrorPath</key>
        <string>/usr/local/var/log/kafka.log</string>
        <key>StandardOutPath</key>
        <string>/usr/local/var/log/kafka.log</string>
        <key>Version</key>
        <string>v3.9.0</string>
    </dict>
</plist>

依赖配置详解

<key>KeepAlive</key>
<dict>
    <key>OtherJobEnabled</key>
    <string>apache.org.zookeeper</string>
</dict>
<key>After</key>
<array>
    <string>apache.org.zookeeper</string>
</array>

字段	值	含义
KeepAlive OtherJobEnabled	apache.org.zookeeper	Kafka 会检查 Zookeeper 服务是否处于 enabled 状态，只有当 Zookeeper 启用时，Kafka 才会保持运行
After	[apache.org.zookeeper]	明确告知 launchd：Kafka 必须在 Zookeeper 之后启动，保证启动顺序

对比：无依赖 vs 有依赖

无依赖配置（常规方式）：

<key>KeepAlive</key>
<true/>

这种配置下，Kafka 不会检查任何外部服务状态，开机时可能与 Zookeeper 同时启动或先于 Zookeeper 启动，导致启动失败。

有依赖配置（本文方式）：

<key>KeepAlive</key>
<dict>
    <key>OtherJobEnabled</key>
    <string>apache.org.zookeeper</string>
</dict>
<key>After</key>
<array>
    <string>apache.org.zookeeper</string>
</array>

Kafka 会等待 Zookeeper 启动并启用后，再启动自己，彻底解决启动顺序问题。

3. 加载服务

配置完成后，执行以下命令加载服务：

# 加载 Kafka 服务（Zookeeper 同理）
launchctl load ~/Library/LaunchAgents/apache.org.kafka.plist

# 或者使用 bootstrap（macOS 10.10+ 推荐）
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/apache.org.kafka.plist

4. 验证效果

# 查看 Zookeeper 服务状态
launchctl print gui/$UID/apache.org.zookeeper

# 查看 Kafka 服务状态（可以看到依赖关系）
launchctl print gui/$UID/apache.org.kafka

# 查看服务运行日志
tail -f /usr/local/var/log/zookeeper.log
tail -f /usr/local/var/log/kafka.log

当系统重启后，launchd 会按照以下顺序启动：

1. Zookeeper 启动 ✅
2. Zookeeper 状态变为 enabled
3. Kafka 检测到 Zookeeper 已就绪
4. Kafka 启动 ✅

拓展：其他常见的服务依赖场景

场景	依赖关系	配置方式
Web 服务 + 数据库	Nginx 依赖 MySQL	OtherJobEnabled → com.mysql.mysqld
消息队列 + 存储	RabbitMQ 依赖 PostgreSQL	OtherJobEnabled → org.postgresql.postgres
监控工具 + 被监控服务	Prometheus 依赖 Node Exporter	OtherJobEnabled → io.prometheus.node_exporter
微服务调用链	Service B 依赖 Service A	同上，层层递进

注意事项

1. plist 文件位置：本文示例使用用户级服务，plist 存放在 ~/Library/LaunchAgents/。如果是系统级服务，需放在 /Library/LaunchDaemons/ 并使用 sudo 加载。

2. Disabled 字段：示例中 Disabled 为 true，表示服务默认禁用。可以通过以下命令启用：

   launchctl enable gui/$UID/apache.org.kafka

3. 循环依赖：避免出现 A 依赖 B、B 又依赖 A 的循环依赖情况，会导致服务无法正常启动。

4. 依赖服务 Label 必须准确：OtherJobEnabled 和 After 中填写的 Label 必须与依赖服务的 Label 完全一致。

总结

• macOS 下通过 launchctl 管理服务依赖，核心是配置 KeepAlive + OtherJobEnabled 和 After 组合。
• OtherJobEnabled 指定依赖的目标服务 Label，确保目标服务启用时当前服务才保持运行。
• After 控制启动顺序，确保依赖服务优先启动。
• 通过本方案，可以完美解决 Kafka 依赖 Zookeeper 等类似的服务启动顺序问题。

延伸阅读

• macOS launchctl 完全指南：系统服务管理利器
• Apple 官方 launchd.plist 文档
• Apache Kafka 官方文档
• Apache Zookeeper 官方文档