# StreamingEagle

**Repository Path**: gokuding/streaming-eagle

## Basic Information

- **Project Name**: StreamingEagle
- **Description**: No description available
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Streaming Eagle

云原生 Kafka 管控平台，专注于 Kafka 运维管控、监控告警、资源治理、多活容灾等核心场景。

## 特性

- **集群管理** - 一键纳管集群，健康分析，核心组件观测
- **多维度指标观测** - 观测指标大盘，最佳实践
- **异常巡检** - 多维度健康巡检，健康分
- **能力增强** - 负载均衡，Topic 扩缩副本，副本迁移
- **告警通知** - 支持邮件和第三方 API (PagerDuty, OpsGenie, Webhook)

## 技术栈

| 分类 | 技术 |
|------|------|
| 语言 | Go 1.22+ |
| 数据库 | PostgreSQL 16 |
| API | gRPC + REST (grpc-gateway) |
| 依赖注入 | Wire |
| 数据库工具 | sqlc, golang-migrate |
| 容器 | Docker, Docker Compose |

## 架构

```
cmd/
  server/              # 入口点，Wire 注入，优雅停机
internal/
  domain/              # 业务类型和接口
  service/             # 业务逻辑
  repository/          # 数据访问层 (sqlc 生成)
  handler/
    grpc/              # gRPC 处理程序
    rest/              # REST 处理程序 (grpc-gateway)
  config/              # 配置加载
  kafka/               # Kafka 客户端
  notification/         # 通知渠道 (Email, API, Webhook)
  metrics/             # 指标收集
  loadbalancer/        # 负载均衡
proto/v1/              # Protobuf 定义
queries/               # sqlc SQL 查询
migrations/            # 数据库迁移
```

## 快速开始

### 前置条件

- Go 1.22+
- Docker & Docker Compose
- PostgreSQL 16

### 1. 启动数据库

```bash
docker-compose up -d
```

### 2. 配置数据库连接

```bash
export DATABASE_URL=postgres://eagle:eagle@localhost:5432/streaming_eagle?sslmode=disable
```

### 3. 运行迁移

```bash
make migrate-up
```

### 4. 构建并运行

```bash
make build
./bin/streaming-eagle
```

服务启动后：
- gRPC 服务: `localhost:50051`
- REST 服务: `localhost:8080`

## 开发

### Makefile 命令

| 命令 | 描述 |
|------|------|
| `make build` | 构建应用 |
| `make test` | 运行单元测试 |
| `make test-coverage` | 运行测试并生成覆盖率报告 |
| `make test-integration` | 运行集成测试 |
| `make test-race` | 运行测试并启用竞态检测 |
| `make migrate-up` | 执行数据库迁移 |
| `make migrate-down` | 回滚最后一次迁移 |
| `make migrate-create NAME=xxx` | 创建新迁移 |
| `make generate` | 使用 sqlc 生成代码 |
| `make lint` | 代码检查 |
| `make wire` | 生成 Wire 依赖注入代码 |
| `make docker-up` | 启动 Docker 容器 |
| `make docker-down` | 停止 Docker 容器 |

### 项目结构

```
internal/
  domain/           # 实体、接口、哨兵错误
    cluster.go
    broker.go
    topic.go
    alert.go
    notification.go
    errors.go
  service/          # 业务逻辑
    cluster_service.go
    broker_service.go
    topic_service.go
    alert_service.go
    notification_service.go
  repository/       # 数据访问
    postgres/
      cluster_repo.go
      broker_repo.go
      topic_repo.go
      alert_repo.go
      notification_repo.go
  handler/          # API 处理层
    grpc/
      cluster_handler.go
      broker_handler.go
      topic_handler.go
      alert_handler.go
      notification_handler.go
      auth.go          # gRPC 认证拦截器
      ratelimit.go     # gRPC 限流拦截器
    rest/
      rest.go          # REST 路由和中间件
      middleware.go     # 安全头等中间件
  kafka/            # Kafka 客户端封装
    client.go
    config.go
  config/           # 配置管理
    config.go
    notification.go
  notification/     # 通知渠道实现
    email.go
    api.go
    pagerduty.go
    opsgenie.go
    webhook.go
    formatter.go
```

### API 服务

| 服务 | 端口 | 描述 |
|------|------|------|
| gRPC | 50051 | 主要 RPC 协议 |
| REST | 8080 | grpc-gateway HTTP 端点 |

### Proto 服务

- `ClusterService` - 集群管理
- `BrokerService` - Broker 管理
- `TopicService` - Topic 管理
- `AlertService` - 告警管理
- `NotificationService` - 通知管理

## 配置

配置文件: `config.yaml`

```yaml
server:
  shutdown_timeout: "30s"

database:
  url: "postgres://eagle:eagle@localhost:5432/streaming_eagle?sslmode=disable"
  max_connections: 20
  min_connections: 5

logger:
  level: "info"
  format: "json"

grpc:
  port: "50051"
  enable_reflection: false

rest:
  port: "8080"

otel:
  endpoint: "localhost:4317"
  enabled: false

notification:
  enabled: false
  email:
    enabled: false
    smtp_host: "localhost"
    smtp_port: 587
    use_tls: true
  api:
    enabled: false
  retry:
    max_attempts: 3
    interval: "30s"
```

### 环境变量

| 变量 | 描述 |
|------|------|
| `DATABASE_URL` | PostgreSQL 连接字符串 |
| `GRPC_PORT` | gRPC 服务端口 |
| `REST_PORT` | REST 服务端口 |
| `LOG_LEVEL` | 日志级别 (debug, info, warn, error) |
| `LOG_FORMAT` | 日志格式 (json, text) |
| `OTEL_ENDPOINT` | OpenTelemetry 收集器地址 |
| `OTEL_ENABLED` | 是否启用 OpenTelemetry |
| `NOTIFICATION_ENABLED` | 是否启用通知 |
| `NOTIFICATION_EMAIL_ENABLED` | 是否启用邮件通知 |
| `NOTIFICATION_SMTP_HOST` | SMTP 服务器地址 |
| `NOTIFICATION_SMTP_PORT` | SMTP 服务器端口 |
| `NOTIFICATION_SMTP_USERNAME` | SMTP 用户名 |
| `NOTIFICATION_SMTP_PASSWORD` | SMTP 密码 |
| `NOTIFICATION_EMAIL_FROM` | 发送者邮箱 |
| `NOTIFICATION_API_ENABLED` | 是否启用 API 通知 |
| `NOTIFICATION_RETRY_MAX_ATTEMPTS` | 最大重试次数 |
| `NOTIFICATION_RETRY_INTERVAL` | 重试间隔 |

## 安全

- TLS 1.2+ 支持 (Kafka 连接)
- gRPC 认证拦截器
- HTTP 限流保护
- 安全响应头 (CSP, X-Frame-Options, HSTS 等)
- 敏感信息通过环境变量配置
- 输入验证和错误信息脱敏

## 测试

```bash
# 运行所有单元测试
make test

# 运行带覆盖率的测试
make test-coverage

# 运行集成测试 (需要数据库)
make test-integration

# 运行带竞态检测的测试
make test-race
```

## 许可证

MIT License