# process_host

**Repository Path**: chmodke/process_host

## Basic Information

- **Project Name**: process_host
- **Description**: Process Host 是一个 Windows 平台下的进程托管工具，采用守护进程 + 管理客户端的架构，支持将任意可执行程序作为 Windows 服务托管运行，提供自动重启、日志管理、独立配置等功能。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-12
- **Last Updated**: 2026-04-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Process Host

[![Go Version](https://img.shields.io/badge/Go-1.20+-00ADD8?style=flat&logo=go)](https://go.dev/)
[![Platform](https://img.shields.io/badge/Platform-Windows-0078D6?style=flat&logo=windows)](https://www.microsoft.com/windows)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Process Host 是一个 Windows 平台下的进程托管工具，采用守护进程 + 管理客户端的架构，支持将任意可执行程序作为 Windows 服务托管运行，提供自动重启、日志管理、独立配置等功能。

> 注意：源代码均由DeepSeek生成，请勿直接插入工作交付件。

## ✨ 特性

- **服务化运行**：守护进程作为 Windows 服务运行，开机自启，无需用户登录
- **多进程托管**：同时管理多个可执行程序，每个进程独立配置
- **自动重启**：进程崩溃后自动重启，可配置重启延迟
- **客户端分离**：守护进程与管理客户端独立，通过 TCP 通信
- **独立配置**：每个托管进程拥有独立的 YAML 配置文件
- **表格化展示**：CLI 以清晰的表格展示所有进程状态
- **跨平台潜力**：核心逻辑可扩展至 Linux/macOS

## 🏗️ 架构

```
┌─────────────────────────────────────────────────────────────┐
│                    Windows Service (SCM)                    │
└─────────────────────────┬───────────────────────────────────┘
                          │ 管理
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    守护进程 (daemon)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ API Server  │  │   Manager   │  │ 配置加载器             │ │
│  │ (TCP :9527) │  │             │  │ (configs/*.yaml)    │  │
│  └──────┬──────┘  └──────┬──────┘  └─────────────────────┘  │
│         │                │                                  │
│         ▼                ▼                                  │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              托管进程 (Managed Processes)            │    │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐          │     │
│  │  │ java_app │  │ python   │  │  nginx   │  ...     │     │
│  │  └──────────┘  └──────────┘  └──────────┘          │     │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                          ▲
                          │ TCP (JSON)
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                    管理客户端 (cli)                          │
│  list | start | stop | restart | register | unregister      │
└─────────────────────────────────────────────────────────────┘
```

## 📦 安装

### 从源码编译

```bash
# 克隆仓库
git clone https://gitee.com/chmodke/process_host.git
cd process-host

# 安装依赖
go mod download

# 编译守护进程
cd daemon
go build -o phd.exe

# 编译管理客户端
cd ../cli
go build -o ph_ctl.exe
```

### 安装 Windows 服务

以**管理员身份**运行命令提示符或 PowerShell：

```cmd
# 创建服务
sc create ProcessHost binPath= "C:\path\to\phd.exe -config C:\path\to\daemon.yaml" start= auto

# 启动服务
sc start ProcessHost
```

## 🚀 快速开始

### 1. 创建守护进程配置文件

`daemon.yaml`:

```yaml
listen_addr: "127.0.0.1:9527"   # API 监听地址
config_dir: "./configs"          # 托管进程配置目录
log_dir: "./logs"                # 日志目录
```

### 2. 创建托管进程配置文件

在 `configs/` 目录下创建 `my_app.yaml`:

```yaml
name: "my_app"
enabled: true
path: "C:\\path\\to\\your\\app.exe"
args: ["-p", "8080"]
workdir: "C:\\path\\to\\your"
env:
  APP_ENV: "production"
auto_restart: true
restart_delay_sec: 10
```

### 3. 使用 CLI 管理

```cmd
# 查看所有进程状态
ph_ctl.exe list

# 启动进程
ph_ctl.exe start my_app

# 停止进程
ph_ctl.exe stop my_app

# 注册新进程
ph_ctl.exe register C:\configs\another_app.yaml

# 注销进程
ph_ctl.exe unregister my_app
```

## 📋 CLI 命令参考

| 命令 | 说明 | 示例 |
|------|------|------|
| `list` | 列出所有托管进程状态（表格形式） | `ph_ctl list` |
| `status <name>` | 查看指定进程详细状态 | `ph_ctl status my_app` |
| `start <name>` | 启动指定进程 | `ph_ctl start my_app` |
| `stop <name>` | 停止指定进程 | `ph_ctl stop my_app` |
| `restart <name>` | 重启指定进程 | `ph_ctl restart my_app` |
| `register <file>` | 注册新进程（支持 YAML/JSON） | `ph_ctl register C:\my_app.yaml` |
| `unregister <name>` | 注销并删除进程配置 | `ph_ctl unregister my_app` |

**选项**:
- `-addr string` - 守护进程地址（默认 `127.0.0.1:9527`）

## 📁 配置文件格式

### 守护进程配置 (`daemon.yaml`)

| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `listen_addr` | string | API 服务监听地址 | `127.0.0.1:9527` |
| `config_dir` | string | 托管进程配置目录 | `./configs` |
| `log_dir` | string | 日志输出目录 | `./logs` |

### 托管进程配置 (`*.yaml`)

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 否 | 进程名称，默认使用文件名 |
| `enabled` | bool | 否 | 是否随守护进程自动启动 |
| `path` | string | **是** | 可执行文件绝对路径 |
| `args` | []string | 否 | 启动参数 |
| `workdir` | string | 否 | 工作目录 |
| `env` | map[string]string | 否 | 环境变量 |
| `auto_restart` | bool | 否 | 崩溃后是否自动重启 |
| `restart_delay_sec` | int | 否 | 重启延迟（秒） |

## 🗂️ 项目结构

```
process-host/
├── go.mod
├── go.sum
├── README.md
├── daemon/
│   ├── main.go           # 守护进程入口
│   ├── service.go        # Windows 服务逻辑
│   ├── manager.go        # 进程管理器
│   └── api.go            # TCP API 服务
├── cli/
│   └── main.go           # 管理客户端
├── configs/              # 托管进程配置目录
│   └── example.yaml
├── daemon.yaml           # 守护进程配置
```

## 🔧 开发调试

### 非服务模式运行守护进程

```bash
cd daemon
go run . -config daemon.yaml
# 或直接运行编译后的程序
.\phd.exe -config daemon.yaml
```

按 `Ctrl+C` 优雅退出。

### 查看日志

日志文件位于 `log_dir` 配置的目录下：
- `daemon.log` - 守护进程日志
- `<进程名>.log` - 各托管进程的输出日志

## ❓ 常见问题

### Q: 服务启动失败，报错 1053？

A: 通常是配置文件路径问题或依赖缺失。请检查：
1. `daemon.yaml` 中的路径是否正确
2. 托管进程的 `path` 是否使用绝对路径
3. 工作目录是否有写入权限

### Q: CLI 无法连接守护进程？

A: 确保：
1. 守护进程服务已启动
2. 防火墙允许本地 9527 端口通信
3. `-addr` 参数与守护进程配置一致

### Q: 进程启动后立即退出？

A: 查看守护进程日志，通常是因为：
1. 可执行文件路径错误
2. 缺少依赖的 DLL 或环境变量
3. 工作目录权限不足

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件。