coze-studio/docs/nats-eventbus-integration-guide.md

# NATS EventBus 集成指南

## 概述

本文档详细介绍了 NATS 作为 EventBus 在 Coze Studio 中的集成适配情况，包括架构设计、实现细节、配置说明和使用指南。

## 集成背景

### 为什么选择 NATS？

在 Coze Studio 的架构中，EventBus 承担着关键的异步消息传递任务，包括工作流执行、Agent 通信、数据处理管道等核心功能。NATS 作为一个轻量级、高性能的消息系统，为 Coze Studio 带来了以下核心优势：

1. **轻量级**: NATS 具有极小的资源占用和简单的部署架构，非常适合云原生环境
2. **高性能**: 提供低延迟、高吞吐量的消息传递，能够支撑 Coze Studio 大规模并发的 Agent 执行
3. **简单易用**: API 简洁直观，降低了开发和维护成本
4. **JetStream 支持**: 通过 JetStream 提供消息持久化、重放和流处理能力
5. **云原生**: 原生支持 Kubernetes，易于在容器化环境中部署和管理
6. **安全性**: 内置多种认证和授权机制，支持 TLS 加密

### 与其他 MQ 的对比

| 特性                   | NATS           | NSQ            | Kafka          | RocketMQ       | Pulsar         |
| ---------------------- | -------------- | -------------- | -------------- | -------------- | -------------- |
| **部署复杂度**   | 极低           | 低             | 中等           | 中等           | 中等           |
| **性能**         | 极高           | 中等           | 高             | 高             | 高             |
| **资源占用**     | 极低           | 低             | 中等           | 中等           | 中等           |
| **消息持久化**   | JetStream      | 有限           | 强             | 强             | 强             |
| **顺序性保障**   | 支持           | 弱             | 强             | 强             | 强             |
| **水平扩展性**   | 良好           | 中等           | 良好           | 良好           | 优秀           |
| **运维复杂度**   | 极低           | 低             | 高             | 中等           | 中等           |
| **云原生支持**   | 优秀           | 中等           | 中等           | 中等           | 良好           |

#### NATS 的核心优势

**轻量级和高性能**：
- **内存占用**：NATS 服务器通常只需要几十 MB 内存即可处理数百万消息
- **启动速度**：秒级启动，非常适合微服务和容器化部署
- **延迟**：亚毫秒级消息延迟，适合实时性要求高的场景
- **吞吐量**：单节点可处理数百万消息/秒

**简单性**：
- **配置简单**：最小化配置即可运行，无需复杂的集群配置
- **API 简洁**：发布/订阅模式简单直观，学习成本低
- **运维友好**：监控和调试工具丰富，问题排查容易

**云原生特性**：
- **Kubernetes 集成**：官方提供 Helm Charts 和 Operator
- **服务发现**：内置服务发现机制，无需外部依赖
- **弹性伸缩**：支持动态集群成员变更

## 架构设计

### 整体架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Coze Studio   │    │   NATS Server   │    │   JetStream     │
│   Application   │    │                 │    │   Storage       │
├─────────────────┤    ├─────────────────┤    ├─────────────────┤
│   Producer      │───▶│   Core NATS     │    │   Streams       │
│   Consumer      │◀───│   JetStream     │◀───│   Consumers     │
│   EventBus      │    │   Clustering    │    │   Key-Value     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

### 消息流转模式

NATS 在 Coze Studio 中支持两种消息模式：

1. **Core NATS**: 用于实时、轻量级的消息传递
   - 发布/订阅模式
   - 请求/响应模式
   - 队列组模式

2. **JetStream**: 用于需要持久化和高可靠性的消息
   - 流式存储
   - 消息重放
   - 消费者确认机制

## 实现细节

### Producer 实现

Producer 负责向 NATS 发送消息，支持以下特性：

```go
type Producer struct {
    nc     nats.Conn
    js     nats.JetStreamContext
    closed bool
    mu     sync.RWMutex
}

func (p *Producer) SendMessage(ctx context.Context, topic string, message []byte) error {
    // 支持 Core NATS 和 JetStream 两种模式
    if p.js != nil {
        // JetStream 模式：支持消息持久化
        _, err := p.js.Publish(topic, message)
        return err
    } else {
        // Core NATS 模式：轻量级发布
        return p.nc.Publish(topic, message)
    }
}
```

### Consumer 实现

Consumer 负责从 NATS 接收和处理消息：

```go
func (c *Consumer) RegisterConsumer(serverURL, topic, group string, handler ConsumerHandler) error {
    // 根据配置选择 JetStream 或 Core NATS
    if c.useJetStream {
        return c.startJetStreamConsumer(ctx, topic, group, handler)
    } else {
        return c.startCoreConsumer(ctx, topic, group, handler)
    }
}
```

#### JetStream Consumer 特性

- **消息确认**: 支持手动确认机制，确保消息处理成功
- **重试机制**: 失败消息自动重试，支持指数退避
- **顺序处理**: 单条消息处理，避免批处理带来的复杂性
- **流控制**: 精确的消息流控制，防止消费者过载

#### Core NATS Consumer 特性

- **队列组**: 支持负载均衡的消息分发
- **轻量级**: 无持久化开销，适合实时消息处理
- **高性能**: 极低的消息处理延迟

## 配置说明

### 环境变量配置

在 `docker/.env.example` 中添加以下 NATS 相关配置：

```bash
# Backend Event Bus
export COZE_MQ_TYPE="nats"  # 设置消息队列类型为 NATS
export MQ_NAME_SERVER="nats:4222"  # NATS 服务器地址

# NATS 特定配置
# NATS_SERVER_URL: NATS 服务器连接 URL，支持 nats:// 和 tls:// 协议
# 集群模式使用逗号分隔的 URL: "nats://nats1:4222,nats://nats2:4222"
# TLS 连接: "tls://nats:4222"
export NATS_SERVER_URL="nats://nats:4222"

# NATS_JWT_TOKEN: NATS JWT 认证令牌（留空表示无认证）
export NATS_JWT_TOKEN=""

# NATS_NKEY_SEED: NATS NKey 认证种子文件路径（可选）
export NATS_NKEY_SEED=""

# NATS_USERNAME: NATS 用户名认证（可选）
export NATS_USERNAME=""

# NATS_PASSWORD: NATS 密码认证（可选）
export NATS_PASSWORD=""

# NATS_TOKEN: NATS 令牌认证（可选）
export NATS_TOKEN=""

# NATS_STREAM_REPLICAS: JetStream 流的副本数量（默认: 1）
export NATS_STREAM_REPLICAS="1"

# NATS_USE_JETSTREAM: 启用 JetStream 模式以获得消息持久化和可靠性（默认: false）
export NATS_USE_JETSTREAM="true"
```

### Docker Compose 配置

在 `docker-compose.yml` 中的 NATS 服务配置：

```yaml
nats:
  image: nats:2.10.24-alpine
  container_name: nats
  restart: unless-stopped
  command:
    - "--jetstream"              # 启用 JetStream
    - "--store_dir=/data"        # 数据存储目录
    - "--max_memory_store=1GB"   # 内存存储限制
    - "--max_file_store=10GB"    # 文件存储限制
  ports:
    - "4222:4222"   # 客户端连接端口
    - "8222:8222"   # HTTP 监控端口
    - "6222:6222"   # 集群通信端口
  volumes:
    - ./volumes/nats:/data
  networks:
    - coze-network
  healthcheck:
    test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8222/"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 40s
```

### 应用程序配置

在 Coze Studio 应用中，通过环境变量配置 NATS：

```go
// 从环境变量读取配置
mqType := os.Getenv("COZE_MQ_TYPE")
natsURL := os.Getenv("NATS_SERVER_URL")
jwtToken := os.Getenv("NATS_JWT_TOKEN")
seedFile := os.Getenv("NATS_NKEY_SEED")
streamReplicas := os.Getenv("NATS_STREAM_REPLICAS")

// 创建 NATS EventBus
if mqType == "nats" {
    config := &nats.Config{
        ServerURL:      natsURL,
        JWTToken:       jwtToken,
        SeedFile:       seedFile,
        StreamReplicas: streamReplicas,
    }
    
    eventBus, err := nats.NewProducer(config)
    if err != nil {
        log.Fatal("Failed to create NATS producer:", err)
    }
}
```

## 部署指南

### Docker 部署

1. **配置环境变量**：
   ```bash
   cp docker/.env.example docker/.env
   # 编辑 .env 文件，设置 COZE_MQ_TYPE="nats"
   ```

2. **启动服务**：
   ```bash
   cd docker
   docker-compose up -d nats
   ```

3. **验证部署**：
   ```bash
   # 检查 NATS 服务状态
   docker-compose ps nats
   
   # 查看 NATS 监控界面
   curl http://localhost:8222/varz
   ```

### Kubernetes 部署

使用官方 Helm Chart 部署 NATS：

```bash
# 添加 NATS Helm 仓库
helm repo add nats https://nats-io.github.io/k8s/helm/charts/

# 安装 NATS
helm install nats nats/nats --set nats.jetstream.enabled=true
```

### 生产环境配置

对于生产环境，建议进行以下配置优化：

1. **集群部署**：
   ```yaml
   nats:
     cluster:
       enabled: true
       replicas: 3
   ```

2. **持久化存储**：
   ```yaml
   nats:
     jetstream:
       fileStore:
         pvc:
           size: 100Gi
           storageClassName: fast-ssd
   ```

3. **资源限制**：
   ```yaml
   nats:
     resources:
       limits:
         cpu: 2000m
         memory: 4Gi
       requests:
         cpu: 500m
         memory: 1Gi
   ```

4. **安全配置**：
   ```yaml
   nats:
     auth:
       enabled: true
       token: "your-secure-token"
     tls:
       enabled: true
   ```

## 监控和运维

### 监控指标

NATS 提供丰富的监控指标，可通过 HTTP 端点获取：

- **服务器信息**: `GET /varz`
- **连接信息**: `GET /connz`
- **订阅信息**: `GET /subsz`
- **JetStream 信息**: `GET /jsz`

### 关键监控指标

1. **性能指标**：
   - 消息吞吐量 (messages/sec)
   - 消息延迟 (latency)
   - 连接数 (connections)

2. **资源指标**：
   - 内存使用量 (memory usage)
   - CPU 使用率 (cpu usage)
   - 磁盘使用量 (disk usage)

3. **JetStream 指标**：
   - 流数量 (streams)
   - 消费者数量 (consumers)
   - 存储使用量 (storage usage)

### 日志管理

NATS 支持多种日志级别和输出格式：

```bash
# 启用调试日志
nats-server --debug

# 日志输出到文件
nats-server --log /var/log/nats.log

# JSON 格式日志
nats-server --logtime --log_size_limit 100MB
```

## 性能优化

### 连接池优化

```go
// 配置连接选项
opts := []nats.Option{
    nats.MaxReconnects(10),
    nats.ReconnectWait(2 * time.Second),
    nats.Timeout(5 * time.Second),
}

nc, err := nats.Connect(serverURL, opts...)
```

### JetStream 优化

```go
// 配置 JetStream 选项
jsOpts := []nats.JSOpt{
    nats.PublishAsyncMaxPending(1000),
    nats.PublishAsyncErrHandler(func(js nats.JetStream, originalMsg *nats.Msg, err error) {
        log.Printf("Async publish error: %v", err)
    }),
}

js, err := nc.JetStream(jsOpts...)
```

### 消费者优化

```go
// 配置消费者选项
consumerOpts := []nats.SubOpt{
    nats.Durable("coze-consumer"),
    nats.MaxDeliver(3),
    nats.AckWait(30 * time.Second),
    nats.MaxAckPending(100),
}

sub, err := js.PullSubscribe(topic, "coze-group", consumerOpts...)
```

## 故障排查

### 常见问题

1. **连接失败**：
   - 检查 NATS 服务是否启动
   - 验证网络连通性
   - 确认端口配置正确

2. **消息丢失**：
   - 检查 JetStream 是否启用
   - 验证消息确认机制
   - 查看错误日志

3. **性能问题**：
   - 监控资源使用情况
   - 检查消息积压
   - 优化消费者配置

### 调试工具

NATS 提供了丰富的调试工具：

```bash
# NATS CLI 工具
nats server info
nats stream list
nats consumer list

# 监控消息流
nats sub "coze.>"
nats pub "coze.test" "hello world"
```

## 最佳实践

### 主题命名规范

建议使用层次化的主题命名：

```
coze.workflow.{workflow_id}.{event_type}
coze.agent.{agent_id}.{action}
coze.knowledge.{kb_id}.{operation}
```

### 错误处理

实现完善的错误处理机制：

```go
func (c *Consumer) handleMessage(msg *nats.Msg) {
    defer func() {
        if r := recover(); r != nil {
            log.Printf("Message processing panic: %v", r)
            msg.Nak() // 拒绝消息，触发重试
        }
    }()
    
    if err := c.processMessage(msg.Data); err != nil {
        log.Printf("Message processing error: %v", err)
        msg.Nak()
        return
    }
    
    msg.Ack() // 确认消息处理成功
}
```

### 资源管理

正确管理 NATS 连接和资源：

```go
func (p *Producer) Close() error {
    p.mu.Lock()
    defer p.mu.Unlock()
    
    if p.closed {
        return nil
    }
    
    p.closed = true
    
    if p.nc != nil {
        p.nc.Close()
    }
    
    return nil
}
```

## 总结

NATS 作为 Coze Studio 的 EventBus 解决方案，提供了轻量级、高性能、易于部署的消息传递能力。通过 JetStream 扩展，NATS 还能提供企业级的消息持久化和流处理功能。

选择 NATS 的主要优势：
- **简单性**: 部署和维护成本低
- **性能**: 极高的消息处理性能
- **云原生**: 完美适配容器化和 Kubernetes 环境
- **可靠性**: JetStream 提供消息持久化和确认机制
- **扩展性**: 支持集群部署和水平扩展

NATS 特别适合以下场景：
- 微服务架构的服务间通信
- 实时数据流处理
- 云原生应用的消息传递
- 需要低延迟的消息系统
- 资源受限的部署环境