205 lines
5.5 KiB
Markdown
205 lines
5.5 KiB
Markdown
# mcp-ssh-manager macOS 自启 launchd
|
||
|
||
本指南适用于 **macOS 13+（含 macOS 26）**，使用 **launchd** 设置登录后自启。方案可回滚、可调试、可日志追踪，不修改业务代码，也不使用第三方守护工具。
|
||
|
||
## 1) 自适应探测规则
|
||
|
||
脚本会按顺序自动探测启动方式，成功即用：
|
||
|
||
1) 若 `command -v mcp-ssh-manager` 存在，使用其绝对路径作为 `ProgramArguments[0]`。
|
||
2) 否则按以下范围搜索仓库或安装路径：
|
||
- 当前工作目录及其父级（最多向上 5 层），查找 `package.json` 且 `name` 含 `mcp-ssh-manager`。
|
||
- `~/code`、`~/projects`、`~/src` 下搜索目录名包含 `mcp-ssh-manager`，深度 `<=3`。
|
||
- `/usr/local`、`/opt/homebrew` 下搜索 `mcp-ssh-manager` 相关文件。
|
||
3) 若找到 Node 项目：
|
||
- 优先 `pnpm start` 或 `npm run start`（`scripts.start` 存在时）。
|
||
- 否则使用 `node <entry>`，入口依次为：`dist/index.js` -> `build/index.js` -> `index.js` -> `src/index.ts`。
|
||
4) Node 解释器绝对路径优先级：`/opt/homebrew/bin/node` -> `/usr/local/bin/node` -> `which node`。
|
||
5) `ProgramArguments` 使用绝对路径，禁止依赖 shell PATH 或 `~/.zshrc`。
|
||
|
||
## 2) 安装脚本
|
||
|
||
同目录脚本：`docs/mcp/install-launchd.sh`。用法：
|
||
|
||
```
|
||
./install-launchd.sh install
|
||
```
|
||
|
||
脚本会生成并安装 plist：
|
||
|
||
```
|
||
~/Library/LaunchAgents/com.bvisible.mcp-ssh-manager.plist
|
||
```
|
||
|
||
日志目录：
|
||
|
||
```
|
||
~/Library/Logs/mcp-ssh-manager/
|
||
```
|
||
|
||
## 3) 生成的 plist 完整内容
|
||
|
||
脚本会根据探测结果生成 plist。以下为两种可能的完整内容示例。
|
||
|
||
**示例 A：直接使用二进制**
|
||
|
||
```
|
||
<?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.bvisible.mcp-ssh-manager</string>
|
||
|
||
<key>ProgramArguments</key>
|
||
<array>
|
||
<string>/usr/local/bin/mcp-ssh-manager</string>
|
||
</array>
|
||
|
||
<key>EnvironmentVariables</key>
|
||
<dict>
|
||
<key>PATH</key>
|
||
<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
|
||
</dict>
|
||
|
||
<key>RunAtLoad</key>
|
||
<true/>
|
||
|
||
<key>KeepAlive</key>
|
||
<true/>
|
||
|
||
<key>StandardOutPath</key>
|
||
<string>/Users/USER/Library/Logs/mcp-ssh-manager/out.log</string>
|
||
|
||
<key>StandardErrorPath</key>
|
||
<string>/Users/USER/Library/Logs/mcp-ssh-manager/err.log</string>
|
||
</dict>
|
||
</plist>
|
||
```
|
||
|
||
**示例 B：Node 项目入口**
|
||
|
||
```
|
||
<?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.bvisible.mcp-ssh-manager</string>
|
||
|
||
<key>ProgramArguments</key>
|
||
<array>
|
||
<string>/opt/homebrew/bin/node</string>
|
||
<string>/Users/USER/path/to/mcp-ssh-manager/dist/index.js</string>
|
||
</array>
|
||
|
||
<key>WorkingDirectory</key>
|
||
<string>/Users/USER/path/to/mcp-ssh-manager</string>
|
||
|
||
<key>EnvironmentVariables</key>
|
||
<dict>
|
||
<key>PATH</key>
|
||
<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
|
||
</dict>
|
||
|
||
<key>RunAtLoad</key>
|
||
<true/>
|
||
|
||
<key>KeepAlive</key>
|
||
<true/>
|
||
|
||
<key>StandardOutPath</key>
|
||
<string>/Users/USER/Library/Logs/mcp-ssh-manager/out.log</string>
|
||
|
||
<key>StandardErrorPath</key>
|
||
<string>/Users/USER/Library/Logs/mcp-ssh-manager/err.log</string>
|
||
</dict>
|
||
</plist>
|
||
```
|
||
|
||
## 4) plist 关键字段说明
|
||
|
||
- `Label`：launchd 唯一标识，用于 `launchctl` 管理。
|
||
- `ProgramArguments`：启动命令与参数，必须为绝对路径，禁止使用 shell 包裹。
|
||
- `WorkingDirectory`：Node 项目使用的工作目录，必须为绝对路径。
|
||
- `EnvironmentVariables`：明确指定 PATH，避免 launchd 的默认 PATH 过短。
|
||
- `RunAtLoad`：plist 加载时立即启动。
|
||
- `KeepAlive`：进程退出时自动拉起。
|
||
- `StandardOutPath`/`StandardErrorPath`：stdout 与 stderr 日志路径。
|
||
|
||
## 5) 一键命令
|
||
|
||
以下命令均可直接复制执行：
|
||
|
||
```
|
||
./install-launchd.sh install
|
||
./install-launchd.sh uninstall
|
||
./install-launchd.sh status
|
||
./install-launchd.sh logs
|
||
```
|
||
|
||
## 6) 手动命令
|
||
|
||
**安装与启动：**
|
||
|
||
```
|
||
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.bvisible.mcp-ssh-manager.plist
|
||
launchctl kickstart -k gui/$(id -u)/com.bvisible.mcp-ssh-manager
|
||
```
|
||
|
||
**卸载与停止：**
|
||
|
||
```
|
||
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.bvisible.mcp-ssh-manager.plist
|
||
rm -f ~/Library/LaunchAgents/com.bvisible.mcp-ssh-manager.plist
|
||
```
|
||
|
||
**状态与调试：**
|
||
|
||
```
|
||
launchctl print gui/$(id -u)/com.bvisible.mcp-ssh-manager
|
||
```
|
||
|
||
**日志追踪：**
|
||
|
||
```
|
||
tail -f ~/Library/Logs/mcp-ssh-manager/out.log ~/Library/Logs/mcp-ssh-manager/err.log
|
||
```
|
||
|
||
## 7) 验证是否自启成功
|
||
|
||
1) 登录后检查 launchd 状态：
|
||
|
||
```
|
||
launchctl print gui/$(id -u)/com.bvisible.mcp-ssh-manager
|
||
```
|
||
|
||
2) 查看日志是否有持续输出：
|
||
|
||
```
|
||
tail -f ~/Library/Logs/mcp-ssh-manager/out.log
|
||
```
|
||
|
||
## 8) 常见问题与排查
|
||
|
||
- **权限问题**：LaunchAgents 以当前用户运行，避免写入 root 目录。
|
||
- **WorkingDirectory 不存在**：确保仓库路径存在且为绝对路径。
|
||
- **Node 路径错误**：确认 `/opt/homebrew/bin/node` 或 `/usr/local/bin/node` 可执行。
|
||
- **端口占用**：检查已有进程是否占用目标端口，必要时先停止旧进程。
|
||
- **PATH 不一致**：保证 `EnvironmentVariables.PATH` 包含常用路径。
|
||
|
||
**临时前台运行对照验证：**
|
||
|
||
- 若使用二进制：
|
||
|
||
```
|
||
/usr/local/bin/mcp-ssh-manager
|
||
```
|
||
|
||
- 若使用 Node 入口：
|
||
|
||
```
|
||
/opt/homebrew/bin/node /Users/USER/path/to/mcp-ssh-manager/dist/index.js
|
||
```
|
||
|