Auto-sync: 2026-04-22 04:02

wiki/concepts/launchd.md

@@ -0,0 +1,111 @@
+# launchd
+
+> macOS 原生服务管理器，用于管理系统级和用户级守护进程（daemons）和代理（agents）。
+
+## Overview
+launchd 是 macOS 的核心初始化系统和服务管理器，替代了传统的 Unix init (SysV)、BSD rc 和 xinetd。它负责在系统启动时启动系统级服务，并在用户登录时启动用户级服务。
+
+## Key Concepts
+- **Daemon（守护进程）**：系统级后台服务，在系统启动时运行，无需用户登录
+- **Agent（代理）**：用户级后台服务，随用户登录启动
+- **LaunchAgent**：用户级代理，存放在 `~/Library/LaunchAgents/`
+- **LaunchDaemon**：系统级守护进程，存放在 `/Library/LaunchDaemons/`
+- **plist 文件**：Property List 格式的配置文件，定义服务参数
+
+## launchctl Commands
+```bash
+# 加载服务（启动）
+launchctl load ~/Library/LaunchAgents/com.frpc.client.plist
+
+# 卸载服务（停止）
+launchctl unload ~/Library/LaunchAgents/com.frpc.client.plist
+
+# 启动服务
+launchctl start com.frpc.client
+
+# 停止服务
+launchctl stop com.frpc.client
+
+# 列出所有已加载的服务
+launchctl list
+
+# 查看服务状态
+launchctl print gui/$UID/com.frpc.client
+```
+
+## plist Configuration Example
+```xml
+<?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>Label</key>
+    <string>com.frpc.client</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/opt/frp/frp_0.65.0_darwin_arm64/frpc</string>
+        <string>-c</string>
+        <string>/opt/frp/frp_0.65.0_darwin_arm64/frpc.toml</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>/opt/frp/frp_0.65.0_darwin_arm64/frpc.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>/opt/frp/frp_0.65.0_darwin_arm64/frpc.error.log</string>
+</dict>
+</plist>
+```
+
+## Key Properties
+| 属性 | 说明 |
+|------|------|
+| Label | 唯一标识符 |
+| ProgramArguments | 要执行的命令及参数数组 |
+| RunAtLoad | 是否在加载时立即启动 |
+| KeepAlive | 是否保持持续运行（崩溃后自动重启）|
+| StandardOutPath | 标准输出日志路径 |
+| StandardErrorPath | 错误输出日志路径 |
+| WorkingDirectory | 工作目录 |
+
+## Comparison with Other Service Managers
+
+| 特性 | launchd | systemd (Linux) | tmux | nohup |
+|------|---------|-----------------|------|-------|
+| 系统级服务 | ✅ | ✅ | ❌ | ❌ |
+| 用户级服务 | ✅ | ✅ | ❌ | ❌ |
+| 开机自启 | ✅ | ✅ | ❌ | ❌ |
+| 持久会话 | ❌ | ❌ | ✅ | ❌ |
+| 简单后台 | ❌ | ❌ | ❌ | ✅ |
+| 崩溃重启 | ✅ | ✅ | ❌ | ❌ |
+
+## Use Cases in Home Server
+- **FRP 客户端**：开机自启的内网穿透服务
+- **N8n**：自动化工作流服务
+- **OpenClaw**：AI Agent 服务
+- **Home Assistant**：智能家居控制中心
+
+## Best Practices
+1. **使用 LaunchAgents**（而非 LaunchDaemons）：用户级代理更安全，权限更少
+2. **配置 KeepAlive**：确保服务崩溃后自动重启
+3. **设置日志路径**：便于故障排查
+4. **使用软链接版本路径**：便于升级时不修改 plist
+5. **定期检查服务状态**：确保服务正常运行
+
+## Related Concepts
+- [[frp]] — 内网穿透工具，常用 launchd 管理
+- [[Gatekeeper]] — macOS 安全机制
+- [[Mac Mini M4]] — 常使用 launchd 管理 Home Server 服务
+
+## References
+- Apple Developer Documentation: Daemons and Services
+- `man launchd.plist`
+- `man launchctl`