# process_monitor

**Repository Path**: mmlya/process_monitor

## Basic Information

- **Project Name**: process_monitor
- **Description**: 个人项目进程监控面板（本机 localhost）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Process Monitor

本机个人项目进程面板：用 `projects.yaml` 白名单登记项目，在网页上查看状态并启停。支持 Ubuntu（systemd user/system）、macOS（launchd）以及通用进程/npm 项目。

默认监听 `0.0.0.0:3920`（本机 `127.0.0.1` 与局域网 IP 均可访问）。面板无鉴权，勿暴露到公网；若只需本机访问可设 `HOST=127.0.0.1`。

## 要求

- Node.js 20+
- Linux：`systemctl --user` 的 user unit；system 级需配置 sudo 密码
- macOS：可选 `~/Library/LaunchAgents` 下的 LaunchAgent

## 安装与启动

### 一键安装（推荐）

克隆后在项目根目录执行（自动识别 Linux / macOS）：

```bash
cd /path/to/process_monitor
chmod +x deploy/*.sh
./deploy/install.sh
```

| 平台 | 安装内容 |
|------|----------|
| **Linux** | `npm install` + 用户级 systemd（`~/.config/systemd/user/process_monitor.service`）并启动 |
| **macOS** | `npm install` + LaunchAgent（`~/Library/LaunchAgents/com.user.process-monitor.plist`）并启动 |

浏览器打开：http://127.0.0.1:3920 （局域网可用本机 IP）

常用命令：

```bash
# Linux
systemctl --user status process_monitor
journalctl --user -u process_monitor -f

# macOS
launchctl print gui/$(id -u)/com.user.process-monitor
tail -f ~/Library/Logs/process-monitor.log

# 卸载开机自启（保留源码与 projects.yaml）
./deploy/uninstall.sh
```

也可分平台直接调用：`./deploy/install-linux.sh` / `./deploy/install-macos.sh`。  
仅安装依赖、不立刻启动服务：`START_NOW=0 ./deploy/install.sh`。

若尚无 `projects.yaml`，安装脚本会从 `projects.example.yaml` 生成一份空配置。

### 手动前台运行

```bash
npm install
npm start
# 或
./deploy/run.sh
```

开发模式（改代码自动重启）：

```bash
npm run dev
```

环境变量：

| 变量 | 默认 | 说明 |
|------|------|------|
| `HOST` | `0.0.0.0` | 绑定地址；`0.0.0.0` 允许本机+局域网，`127.0.0.1` 仅本机 |
| `PORT` | `3920` | 端口 |
| `PROJECTS_CONFIG` | 项目根目录 `projects.yaml` | 配置路径 |
| `PROCESS_MONITOR_SUDO_PASSWORD` | — | 可覆盖文件中的 sudo 密码 |

## 配置 `projects.yaml`

```yaml
projects:
  # Ubuntu user systemd
  - id: hermes-agent
    name: Hermes Agent
    type: systemd
    unit: hermes-gateway.service
    scope: user

  # system 级（启停需 sudo）
  - id: ditabooktrans
    name: DitaBookTrans
    type: systemd
    unit: ditabooktrans.service
    scope: system

  # macOS LaunchAgent
  - id: hermes-agent-mac
    name: Hermes Agent
    type: launchd
    label: com.user.hermes-agent
    # plist: /Users/you/Library/LaunchAgents/com.user.hermes-agent.plist  # 可选

  # 通用进程 / npm
  - id: hermes-web-ui
    name: Hermes Web UI
    type: process
    cwd: /path/to/hermes-web-ui
    start_cmd: hermes-web-ui start --port 8647 --no-open
    stop_cmd: hermes-web-ui stop   # 可选
    port: 8647                     # 强烈建议：用端口判定运行
    url: http://127.0.0.1:8647     # 可选：卡片网页直达
    match: hermes-web-ui           # 可选，PID 丢失时的命令行兜底
    match_exclude:                 # 可选，匹配时排除子串
      - mcp_stdio_watchdog
```

改完配置后可在面板「更多 → 重载配置」，或调用 `POST /api/reload`。面板「配置 / 添加」会原子写回 YAML。

### 字段说明

| 字段 | 适用类型 | 说明 |
|------|----------|------|
| `id` | 全部 | 唯一标识 |
| `name` | 全部 | 显示名 |
| `type` | 全部 | `systemd` / `launchd` / `process` |
| `unit` | systemd | 如 `foo.service` |
| `scope` | systemd | `user`（默认）或 `system` |
| `label` | launchd | LaunchAgent label |
| `plist` | launchd | plist 路径；默认 `~/Library/LaunchAgents/<label>.plist` |
| `cwd` | process | 工作目录 |
| `start_cmd` | process | 启动命令（经 shell 执行） |
| `stop_cmd` | process | 可选自定义停止命令 |
| `port` | process | 期望监听端口（优先用于运行判定） |
| `url` | 全部 | 网页直达；完整地址按原文打开，仅端口号时用「打开链接主机」 |
| `alias` | 全部 | 用户别名；卡片第一行突出显示；可筛选；清空保存即删除（兼容旧 `note`） |
| `match` | process | 命令行匹配子串，用于状态兜底 |
| `match_exclude` | process | 字符串或数组；匹配时排除包含这些子串的进程 |

## 面板能力

- 列表状态：运行中 / 已停止 / 异常；端口、内存、pid
- 筛选：按文本与状态；顶栏汇总运行数
- 启停重启；添加 / 编辑 / 删除（删除仅移出白名单）
- **设置**：本机 sudo 密码（`~/.process_monitor/sudo.env`，0600）；打开链接主机 loopback / 局域网自动 / 自定义（`settings.json`）
- **扫描服务**：Linux 扫描 systemd unit 目录；macOS 扫描 `~/Library/LaunchAgents` 与 `/Library/LaunchAgents`，勾选导入
- **从模板添加**：指定 `.service.in`；已安装则加入观测，未安装则展开模板并安装到 `~/.config/systemd/user`（无需 sudo）
- **创建服务**：Linux 生成 `.service.in` 并安装到用户级 systemd；macOS 生成 LaunchAgent plist 并安装到 `~/Library/LaunchAgents`
- **卸载**（user 卡片）：systemd stop/disable 删 unit；launchd bootout 删用户 plist；均从白名单移除（保留模板/脚本）

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/health` | 健康检查（含 sudo、打开主机、局域网 IP） |
| `POST` | `/api/reload` | 重新加载 YAML |
| `GET` / `PUT` | `/api/settings/sudo` | 读取是否已配置 / 设置或清除密码 |
| `GET` / `PUT` | `/api/settings/panel` | 打开链接主机等面板设置 |
| `GET` | `/api/projects` | 列表与实时状态 |
| `POST` | `/api/projects` | 创建（ID 冲突 → 409） |
| `GET` | `/api/projects/:id` | 单项目状态 |
| `GET` / `PUT` | `/api/projects/:id/config` | 读 / 更新配置（更新会 merge，保留元数据） |
| `DELETE` | `/api/projects/:id` | 从白名单删除 |
| `POST` | `/api/projects/:id/start\|stop\|restart` | 启停 |
| `GET` | `/api/services/scan` | 扫描 systemd unit |
| `POST` | `/api/services/import` | 勾选导入 |
| `POST` | `/api/services/from-template` | 模板安装并添加 |
| `POST` | `/api/services/create-from-exec` | Linux：生成 `.service.in` 并安装 user unit；macOS：生成并安装 LaunchAgent |
| `POST` | `/api/services/:id/uninstall` | 卸载 user systemd unit 或用户 LaunchAgent，并从白名单移除 |
| `GET` | `/api/fs/browse?path=` | 浏览本机目录（创建服务选路径） |
| `GET` | `/api/fs/homes` | 常用目录快捷方式 |

## 平台说明

- **Ubuntu**：`scope: user` 走 `systemctl --user`；`scope: system` 写操作需 sudo 密码。
- **macOS**：用 `launchd` + label；可扫描 LaunchAgents 导入；「创建服务」写入 `~/Library/LaunchAgents`。没有 plist 的项目用 `process`。
- **npm / 普通进程**：`type: process`，停止时尽量杀掉整棵进程树；有 `port` 时以端口为准判定运行。
- PID 文件目录：`~/.process_monitor/pids/`

## 技术栈

TypeScript · Hono · execa · pidtree · 静态网页面板