@codelook/codebox-registry/README.md

Service registry and monitoring for Codebox deployed applications

# @codelook/codebox-registry

专为 Codebox 设计的服务注册中心和监控系统，用于管理通过 Codebox 部署的应用程序。

## 功能特性

- 🔍 **服务注册与发现**：自动记录和管理所有已部署的服务
- 💓 **健康检查**：定期检查服务健康状态，支持自定义检查间隔
- 🎮 **生命周期管理**：启动、停止、重启、销毁服务
- 📊 **监控指标**：追踪服务运行时间、错误率、响应时间等
- 🌐 **RESTful API**：提供完整的 HTTP API 接口
- 💾 **持久化存储**：使用 SQLite 存储服务信息和历史记录
- 📡 **事件追踪**：记录所有服务状态变更和操作历史

## 安装

```bash
npm install @codelook/codebox-registry
```

## 快速开始

### 作为库使用

```typescript
import { ServiceRegistry, ServiceType, ServiceStatus } from '@codelook/codebox-registry';

// 创建注册中心实例
const registry = new ServiceRegistry({
  api: {
    enabled: true,
    port: 9091
  }
});

// 启动注册中心
await registry.start();

// 注册一个服务
await registry.registerService({
  id: 'srv-001',
  projectId: 'proj-001',
  serverId: 'server-001',
  deploymentId: 'deploy-001',
  name: 'my-api-service',
  type: ServiceType.Docker,
  host: 'localhost',
  port: 3000,
  url: 'http://localhost:3000',
  status: ServiceStatus.Running,
  version: '1.0.0',
  deployedAt: new Date().toISOString(),
  healthCheck: {
    enabled: true,
    endpoint: 'http://localhost:3000/health',
    interval: 30000,
    timeout: 5000,
    retries: 3
  }
});

// 获取服务状态
const stats = registry.getStatistics();
console.log(stats);
```

### CLI 使用

```bash
# 启动服务注册中心
service-registry start --port 9091

# 列出所有服务
service-registry list

# 查看统计信息
service-registry stats

# 手动健康检查
service-registry check srv-001

# 清理旧数据
service-registry cleanup --days 30
```

## API 接口

### 服务管理

```bash
# 获取所有服务
GET /api/services

# 获取单个服务
GET /api/services/:id

# 注册新服务
POST /api/services

# 更新服务
PUT /api/services/:id

# 删除服务
DELETE /api/services/:id
```

### 服务操作

```bash
# 启动服务
POST /api/services/:id/start

# 停止服务
POST /api/services/:id/stop

# 重启服务
POST /api/services/:id/restart

# 销毁服务（需要确认）
POST /api/services/:id/destroy
{
  "confirm": true
}
```

### 健康检查

```bash
# 执行健康检查
POST /api/services/:id/health-check

# 批量健康检查
POST /api/health-check/all
```

### 监控数据

```bash
# 获取服务事件
GET /api/services/:id/events

# 获取操作历史
GET /api/services/:id/operations

# 获取统计信息
GET /api/stats
```

## 配置选项

```typescript
interface RegistryConfig {
  database: {
    type: 'sqlite' | 'postgres';
    path?: string; // SQLite 数据库路径
    connectionString?: string; // PostgreSQL 连接字符串
  };
  healthCheck: {
    enabled: boolean;
    defaultInterval: number; // 默认检查间隔（毫秒）
    defaultTimeout: number; // 默认超时时间（毫秒）
    defaultRetries: number; // 默认重试次数
  };
  api: {
    enabled: boolean;
    port: number;
    host: string;
    auth?: {
      enabled: boolean;
      token?: string;
    };
  };
  monitoring: {
    retentionDays: number; // 数据保留天数
    metricsInterval: number; // 指标更新间隔（毫秒）
  };
}
```

## 与 Codebox 集成

codebox-registry 专为与 Codebox 部署工具无缝集成而设计：

```typescript
// 在 codebox 中集成
import { ServiceRegistry } from '@codelook/codebox-registry';

// 部署成功后自动注册
const registry = new ServiceRegistry();
await registry.registerService({
  id: `srv-${Date.now()}`,
  projectId: project.id,
  serverId: server.id,
  deploymentId: deployment.id,
  name: project.name,
  type: project.type,
  host: server.host,
  port: deployment.port,
  url: `http://${server.host}:${deployment.port}`,
  status: 'running',
  version: deployment.version,
  deployedAt: new Date().toISOString()
});
```

## 数据模型

### DeployedService

```typescript
interface DeployedService {
  id: string;
  projectId: string;
  serverId: string;
  deploymentId: string;
  name: string;
  type: ServiceType;
  host: string;
  port?: number;
  url: string;
  healthCheck?: HealthCheckConfig;
  status: ServiceStatus;
  version: string;
  deployedAt: string;
  lastHealthCheck?: string;
  lastStatusChange?: string;
  metrics?: ServiceMetrics;
  metadata?: Record<string, any>;
  tags?: string[];
}
```

### ServiceMetrics

```typescript
interface ServiceMetrics {
  uptime: number; // 运行时间（秒）
  requestCount: number;
  errorCount: number;
  errorRate: number;
  lastResponseTime?: number; // 最后响应时间（毫秒）
  avgResponseTime: number;
  healthChecksPassed: number;
  healthChecksFailed: number;
}
```

## License

MIT