# clientv4

**Repository Path**: tmhulw/clientv4

## Basic Information

- **Project Name**: clientv4
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-14
- **Last Updated**: 2025-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Client V4

一个基于 TypeScript 的客户端工具,支持主进程通过 WebSocket 监听命令,动态启动和管理子进程。

## 功能特性

- 主进程通过 WebSocket 连接到命令服务器,接收和处理命令
- 支持动态加载和启动子进程
- 子进程独立连接到自己的 WebSocket 服务器
- 主进程和子进程通过 onMessage/onClose 进行通信
- 支持进程的启动、关闭、重启等管理操作
- 自动重连机制
- 实时监控子进程的 CPU、内存使用情况
- 每个子进程都有唯一的 UUID 标识
- 定期更新进程监控数据(默认 2 秒间隔)

## 项目结构

```
src/
├── main.ts              # 主进程入口文件
├── process-manager.ts   # 进程管理器
├── client-base.ts       # 子进程基类
├── example-client.ts    # 示例子进程实现
└── types.ts            # 类型定义
```

## 安装依赖

```bash
npm install
```

## 使用方法

### 1. 构建项目

```bash
npm run build
```

### 2. 启动主进程

```bash
npm start
```

或开发模式:

```bash
npm run dev
```

主进程会连接到 `ws://localhost:8080` 等待命令。

### 3. 发送命令

通过 WebSocket 向主进程发送命令:

#### 启动子进程

```json
{
  "type": "start",
  "data": {
    "id": "client1",
    "name": "Example Client",
    "scriptPath": "./client/v1.0/index.js",
    "config": {
      "clientId": "client-001",
      "wsUrl": "ws://localhost:8081",
      "businessData": {
        "userId": "user-12345",
        "companyId": "company-abc",
        "region": "us-west",
        "permissions": ["read", "write"],
        "metadata": {
          "tier": "premium"
        }
      }
    }
  }
}
```

**配置说明:**
- `clientId`: 客户端唯一标识（必填）
- `wsUrl`: 子进程连接的 WebSocket 地址（必填）
- `businessData`: 业务数据，可以包含任意自定义字段（可选）

#### 关闭子进程

```json
{
  "type": "stop",
  "data": {
    "id": "client1"
  }
}
```

#### 重启子进程

```json
{
  "type": "restart",
  "data": {
    "id": "client1"
  }
}
```

#### 查询进程状态

```json
{
  "type": "status",
  "data": {
    "id": "client1"
  }
}
```

返回示例:
```json
{
  "type": "status",
  "data": {
    "id": "client1",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example Client",
    "status": "running",
    "startTime": 1702345678901,
    "pid": 12345,
    "metrics": {
      "cpuUsage": 2.5,
      "memoryUsage": 52428800,
      "memoryUsageMB": 50.0,
      "uptime": 120000,
      "lastUpdate": 1702345798901
    }
  }
}
```

#### 列出所有进程

```json
{
  "type": "list",
  "data": {}
}
```

## 自定义子进程

继承 `ClientBase` 类来创建自定义子进程。子进程文件应放在 `client/版本号/index.ts` 中。

### 创建客户端

```typescript
import { ClientBase } from '../../src/client-base';
import { IClientConfig, IMessage } from '../../src/types';

export class Client extends ClientBase {
  constructor(
    config: IClientConfig,
    onMessage: (message: IMessage) => void,
    onClose: () => void
  ) {
    super(config, onMessage, onClose);
  }

  // 初始化时的逻辑
  protected async onInit(): Promise<void> {
    console.log('Client initialized');
    console.log('Client ID:', this.config.clientId);
    console.log('Business Data:', this.config.businessData);

    // 向主进程发送消息
    this.sendToMainProcess({
      type: 'ready',
      data: {
        clientId: this.config.clientId,
        message: 'Client is ready'
      }
    });
  }

  // 销毁时的逻辑
  protected async onDestroy(): Promise<void> {
    console.log('Client destroyed');
  }

  // 处理来自子进程 WebSocket 的消息
  protected handleMessage(message: IMessage): void {
    console.log('Received from child ws:', message);

    // 可以访问配置信息
    const { clientId, businessData } = this.config;

    // 向主进程发送消息
    this.sendToMainProcess({
      type: 'result',
      data: {
        clientId,
        businessData,
        result: message.data
      }
    });

    // 向子进程 WebSocket 发送消息
    this.sendToChildWs({
      type: 'response',
      data: { success: true }
    });
  }
}
```

### 目录结构示例

```
client/
├── v1.0/
│   └── index.ts    # v1.0 版本客户端
├── v2.0/
│   └── index.ts    # v2.0 版本客户端（支持高级功能）
└── custom/
    └── index.ts    # 自定义版本
```

### 配置对象访问

在子进程中，可以通过 `this.config` 访问配置:

```typescript
protected async onInit(): Promise<void> {
  // 访问客户端 ID
  const clientId = this.config.clientId;

  // 访问 WebSocket URL
  const wsUrl = this.config.wsUrl;

  // 访问业务数据
  const userId = this.config.businessData?.userId;
  const permissions = this.config.businessData?.permissions;

  // 访问自定义配置字段
  const customField = this.config.customField;
}
```

## 架构说明

### 通信流程

1. 主进程连接到命令服务器 (默认: ws://localhost:8080)
2. 命令服务器发送启动命令给主进程
3. 主进程动态加载子进程模块并实例化
4. 子进程在 init 时连接到自己的 WebSocket 服务器 (如: ws://localhost:8081)
5. 子进程通过 onMessage 回调向主进程发送消息
6. 主进程通过 ProcessManager 管理所有子进程

### 进程状态

- `idle`: 空闲
- `starting`: 启动中
- `running`: 运行中
- `stopping`: 关闭中
- `stopped`: 已停止
- `error`: 错误

## 注意事项

- 确保命令服务器 WebSocket (端口 8080) 正在运行
- 确保子进程的 WebSocket 服务器正在运行
- 子进程脚本路径必须是有效的模块路径
- 子进程模块必须导出一个 `Client` 类