shuzhiren-comfyui/API.md

# API 接口文档

## 基础信息

- 基础 URL: `http://localhost:3000/api`
- 认证方式: JWT Bearer Token
- 数据格式: JSON

## 认证

### 登录

```http
POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}
```

响应:
```json
{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "username": "admin"
    }
  }
}
```

后续请求需在 Header 中携带:
```
Authorization: Bearer <token>
```

---

## 实例管理

### 获取所有实例列表

```http
GET /api/instances
Authorization: Bearer <token>
```

响应:
```json
{
  "code": 200,
  "data": [
    {
      "id": "127.0.0.1:8001",
      "serverId": "server-1",
      "serverName": "主服务器",
      "ip": "127.0.0.1",
      "port": 8001,
      "enabled": true,
      "alive": true,
      "busy": false,
      "lastHeartbeat": "2024-01-01T00:00:00.000Z"
    }
  ]
}
```

### 获取单个实例详情

```http
GET /api/instances/:instanceId
Authorization: Bearer <token>
```

### 启用/禁用实例

```http
PUT /api/instances/:instanceId
Authorization: Bearer <token>
Content-Type: application/json

{
  "enabled": false
}
```

---

## 任务管理

### 获取任务列表

```http
GET /api/tasks?status=pending&limit=20&offset=0
Authorization: Bearer <token>
```

查询参数:
- `status`: 任务状态 (pending/running/completed/failed)
- `limit`: 分页数量
- `offset`: 分页偏移

响应:
```json
{
  "code": 200,
  "data": {
    "total": 100,
    "items": [
      {
        "id": "task-uuid",
        "instanceId": "127.0.0.1:8001",
        "status": "running",
        "progress": 50,
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}
```

### 提交任务

```http
POST /api/tasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "workflow": {},
  "params": {}
}
```

### 获取任务详情

```http
GET /api/tasks/:taskId
Authorization: Bearer <token>
```

### 取消任务

```http
DELETE /api/tasks/:taskId
Authorization: Bearer <token>
```

---

## 文件管理

### 上传文件

```http
POST /api/files/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: [二进制文件]
```

响应:
```json
{
  "code": 200,
  "data": {
    "fileId": "file-uuid",
    "filename": "image.png",
    "url": "https://shuzhiren.xueai.art/upload/file/xxx"
  }
}
```

### 获取文件列表

```http
GET /api/files
Authorization: Bearer <token>
```

### 删除文件

```http
DELETE /api/files/:fileId
Authorization: Bearer <token>
```

---

## 配置管理

### 获取配置

```http
GET /api/config
Authorization: Bearer <token>
```

### 更新配置

```http
PUT /api/config
Authorization: Bearer <token>
Content-Type: application/json

{
  "servers": [...],
  "healthCheck": {
    "interval": 30000
  }
}
```

---

## 监控

### 获取监控概览

```http
GET /api/monitor/overview
Authorization: Bearer <token>
```

响应:
```json
{
  "code": 200,
  "data": {
    "totalInstances": 8,
    "aliveInstances": 8,
    "busyInstances": 2,
    "pendingTasks": 5,
    "runningTasks": 2,
    "completedTasks": 100
  }
}
```

---

## WebSocket 消息协议

### 连接

```
ws://localhost:3000/ws
```

### 消息格式

所有消息遵循以下格式:

```json
{
  "type": "message_type",
  "timestamp": 1704067200000,
  "data": {},
  "requestId": "optional-uuid"
}
```

### 服务器 → 客户端 消息类型

| type | 说明 |
|------|------|
| `instance_status` | 实例状态变更 |
| `task_progress` | 任务进度更新 |
| `task_completed` | 任务完成 |
| `task_failed` | 任务失败 |
| `global_status` | 全局状态同步 |

### 实例状态变更消息

```json
{
  "type": "instance_status",
  "data": {
    "instanceId": "127.0.0.1:8001",
    "alive": true,
    "busy": false
  }
}
```

### 任务进度消息

```json
{
  "type": "task_progress",
  "data": {
    "taskId": "task-uuid",
    "progress": 50
  }
}
```

### 任务完成消息

```json
{
  "type": "task_completed",
  "data": {
    "taskId": "task-uuid",
    "result": {
      "files": ["https://..."]
    }
  }
}
```

---

## 健康检查

```http
GET /api/health
```

响应:
```json
{
  "code": 200,
  "data": {
    "status": "ok",
    "redis": "connected"
  }
}
```