Procman / 进程管理器

English | 中文

---

English

A comprehensive process manager with web interface, real-time monitoring, and user management capabilities. Procman provides daemon/service functionality with HTTP API, WebSocket support, and a React-based frontend for managing processes.

Purpose

Procman is designed to simplify process management in development and production environments by providing:

• Unified Process Management: Start, stop, monitor, and restart processes from a single interface
• Real-time Monitoring: Live process status updates and resource monitoring
• Web-based Interface: Modern React dashboard accessible from any browser
• Terminal Access: Web-based terminal sessions for direct process interaction
• Log Management: Centralized log viewing with real-time streaming and filtering
• User Management: Role-based access control for team environments
• Cross-platform Support: Fully tested on Linux, with Windows and macOS support (untested)
• Procfile Support: Compatible with standard Procfile specification for process definitions

Basic Usage

1. Installation and Build

# Clone the repository
git clone <repository-url>
cd procman

# Build the application
go build -o procman ./cmd/procman

# Or use the build script for version info
./build.sh

2. Starting Procman

# Run in foreground (recommended for first time)
./procman run

# Or start as daemon/service
./procman start

3. Using PROCMAN_ADMIN_TOKEN

For administrative operations without web login, use the admin token:

# Set admin token environment variable
export PROCMAN_ADMIN_TOKEN="your-secure-admin-token"

# Start with admin token
./procman -admin-token "your-secure-admin-token" start

# Use admin token for API calls
curl -H "Authorization: Bearer your-secure-admin-token" \
  http://localhost:8080/api/v1/admin/users

4. Web Interface Access

1. Open browser and navigate to http://localhost:8080
2. Login with default credentials:
   • Username: admin
   • Password: secret
3. Change default credentials immediately for security

5. Process Management

# Start specific processes
./procman up web worker

# Stop all processes
./procman down

# View process status
./procman ps

# View logs with follow mode
./procman logs -f web

How to Build

Prerequisites

• Go 1.23 or later
• Node.js 18+ (for frontend development)

Backend Build

# Build for current platform
go build -o procman ./cmd/procman

# Cross-platform builds
GOOS=linux GOARCH=amd64 go build -o procman-linux ./cmd/procman
GOOS=windows GOARCH=amd64 go build -o procman.exe ./cmd/procman
GOOS=darwin GOARCH=amd64 go build -o procman-macos ./cmd/procman

# Build with version information
./build.sh

Frontend Build

cd web
npm install
npm run build    # Production build
npm run dev      # Development server

Testing

# Run comprehensive test suite
./test.sh

# Specific test categories
./test-e2e.sh          # End-to-end tests
./test-daemon-simple.sh # Daemon functionality
./test-concurrency.sh   # Concurrency tests
./test-performance.sh   # Performance tests

Common APIs

Authentication

# Login to get JWT token
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"secret"}'

Process Management

# List all processes
GET /api/v1/processes

# Start a process
POST /api/v1/processes/:id/start

# Stop a process  
POST /api/v1/processes/:id/stop

# Get process logs
GET /api/v1/processes/:id/logs?follow=true

# Process health check
GET /api/v1/processes/:id/health

Terminal Management

# List terminal sessions
GET /api/v1/terminal/sessions

# Create new terminal session
POST /api/v1/terminal/sessions

# WebSocket terminal connection
WS /terminal/ws?session_key=<key>

User Management (Admin Only)

# List users
GET /api/v1/admin/users

# Create user
POST /api/v1/admin/users
{
  "username": "newuser",
  "password": "password",
  "role": "user"
}

# Update user role
PUT /api/v1/admin/users/:id/role

System Information

# Health check
GET /health

# System status
GET /api/v1/status

# WebSocket for real-time updates
WS /ws

Security Considerations

⚠️ Important Security Notes:

1. Do NOT expose Procman to public internet without proper security measures
2. Change default credentials immediately after installation
3. Use HTTPS in production environments
4. Restrict network access to trusted networks only
5. Regular security updates - keep Go and dependencies updated

Recommended Security Setup

# Use strong admin token
export PROCMAN_ADMIN_TOKEN=$(openssl rand -hex 32)

# Run behind reverse proxy with SSL
# Configure firewall to restrict access
# Use strong passwords for all users
# Enable audit logging

Network Security

• Internal Networks Only: Deploy only on private/internal networks
• VPN Access: Use VPN for remote access instead of direct internet exposure
• Firewall Rules: Implement strict firewall rules
• Authentication: Always use authentication, never run in open mode

Planned Improvements

• Enhanced process health monitoring with custom health checks
• Process dependency management and startup ordering
• Integration with container orchestration (Docker, Kubernetes)
• Advanced monitoring and metrics collection (Prometheus integration)
• Multi-node cluster support for distributed process management

---

中文

一个功能全面的进程管理器，具有 Web 界面、实时监控和用户管理功能。Procman 提供守护进程/服务功能，包含 HTTP API、WebSocket 支持和基于 React 的前端界面。

软件用途

Procman 旨在通过提供以下功能简化开发和生产环境中的进程管理：

• 统一进程管理：从单一界面启动、停止、监控和重启进程
• 实时监控：实时进程状态更新和资源监控
• Web 界面：可从任何浏览器访问的现代 React 仪表板
• 终端访问：用于直接进程交互的 Web 终端会话
• 日志管理：集中式日志查看，支持实时流式传输和过滤
• 用户管理：团队环境的基于角色的访问控制
• 跨平台支持：在 Linux 上完全测试，支持 Windows 和 macOS（未测试）
• Procfile 支持：兼容标准 Procfile 规范进行进程定义

基本使用方法

1. 安装和构建

# 克隆仓库
git clone <repository-url>
cd procman

# 构建应用程序
go build -o procman ./cmd/procman

# 或使用构建脚本获取版本信息
./build.sh

2. 启动 Procman

# 前台运行（首次使用推荐）
./procman run

# 或作为守护进程/服务启动
./procman start

3. 使用 PROCMAN_ADMIN_TOKEN

对于无需 Web 登录的管理操作，使用管理员令牌：

# 设置管理员令牌环境变量
export PROCMAN_ADMIN_TOKEN="your-secure-admin-token"

# 使用管理员令牌启动
./procman -admin-token "your-secure-admin-token" start

# 使用管理员令牌进行 API 调用
curl -H "Authorization: Bearer your-secure-admin-token" \
  http://localhost:8080/api/v1/admin/users

4. Web 界面访问

1. 打开浏览器并导航到 http://localhost:8080
2. 使用默认凭据登录：
   • 用户名：admin
   • 密码：secret
3. 为了安全起见，请立即更改默认凭据

5. 进程管理

# 启动特定进程
./procman up web worker

# 停止所有进程
./procman down

# 查看进程状态
./procman ps

# 查看日志并跟踪模式
./procman logs -f web

如何构建

前置要求

• Go 1.23 或更高版本
• Node.js 18+（用于前端开发）

后端构建

# 为当前平台构建
go build -o procman ./cmd/procman

# 跨平台构建
GOOS=linux GOARCH=amd64 go build -o procman-linux ./cmd/procman
GOOS=windows GOARCH=amd64 go build -o procman.exe ./cmd/procman
GOOS=darwin GOARCH=amd64 go build -o procman-macos ./cmd/procman

# 使用版本信息构建
./build.sh

前端构建

cd web
npm install
npm run build    # 生产构建
npm run dev      # 开发服务器

测试

# 运行综合测试套件
./test.sh

# 特定测试类别
./test-e2e.sh          # 端到端测试
./test-daemon-simple.sh # 守护进程功能
./test-concurrency.sh   # 并发测试
./test-performance.sh   # 性能测试

常见 API

身份验证

# 登录获取 JWT 令牌
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"secret"}'

进程管理

# 列出所有进程
GET /api/v1/processes

# 启动进程
POST /api/v1/processes/:id/start

# 停止进程
POST /api/v1/processes/:id/stop

# 获取进程日志
GET /api/v1/processes/:id/logs?follow=true

# 进程健康检查
GET /api/v1/processes/:id/health

终端管理

# 列出终端会话
GET /api/v1/terminal/sessions

# 创建新终端会话
POST /api/v1/terminal/sessions

# WebSocket 终端连接
WS /terminal/ws?session_key=<key>

用户管理（仅管理员）

# 列出用户
GET /api/v1/admin/users

# 创建用户
POST /api/v1/admin/users
{
  "username": "newuser",
  "password": "password", 
  "role": "user"
}

# 更新用户角色
PUT /api/v1/admin/users/:id/role

系统信息

# 健康检查
GET /health

# 系统状态
GET /api/v1/status

# 实时更新的 WebSocket
WS /ws

安全注意事项

⚠️ 重要安全说明：

1. 不要将 Procman 暴露到公网，除非有适当的安全措施
2. 立即更改默认凭据
3. 在生产环境中使用 HTTPS
4. 限制网络访问仅限可信网络
5. 定期安全更新 - 保持 Go 和依赖项更新

推荐安全设置

# 使用强管理员令牌
export PROCMAN_ADMIN_TOKEN=$(openssl rand -hex 32)

# 在带 SSL 的反向代理后运行
# 配置防火墙限制访问
# 为所有用户使用强密码
# 启用审计日志

网络安全

• 仅内部网络：仅在私有/内部网络上部署
• VPN 访问：使用 VPN 进行远程访问，而不是直接互联网暴露
• 防火墙规则：实施严格的防火墙规则
• 身份验证：始终使用身份验证，永远不要在开放模式下运行

计划中的改进

• 增强的进程健康监控，支持自定义健康检查
• 进程依赖管理和启动排序
• 与容器编排集成（Docker、Kubernetes）
• 高级监控和指标收集（Prometheus 集成）
• 分布式进程管理的多节点集群支持