rwadurian/backend/infrastructure/README.md

# RWA Infrastructure - 可观测性与服务治理

可插拔的基础设施组件，支持按需启用，不影响现有微服务代码。

## 架构概览

```
                     ┌─────────────────────────────────────────────────────┐
                     │                    Grafana                          │
                     │          (统一可视化仪表盘 :3030)                     │
                     └───────┬─────────────┬─────────────┬─────────────────┘
                             │             │             │
              ┌──────────────▼──┐  ┌───────▼───────┐  ┌──▼──────────────┐
              │   Prometheus    │  │     Loki      │  │     Jaeger      │
              │   (指标 :9090)   │  │  (日志 :3100)  │  │  (追踪 :16686)  │
              └────────┬────────┘  └───────┬───────┘  └────────┬────────┘
                       │                   │                    │
                       │            ┌──────▼───────┐            │
                       │            │   Promtail   │            │
                       │            │  (日志收集)   │            │
                       │            └──────┬───────┘            │
                       │                   │                    │
    ┌──────────────────▼───────────────────▼────────────────────▼────────┐
    │                                                                     │
    │                         RWA 微服务集群                               │
    │   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
    │   │ identity │ │  wallet  │ │   mpc    │ │  reward  │ │ presence │ │
    │   └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
    │                              ...                                    │
    └─────────────────────────────────┬───────────────────────────────────┘
                                      │
                             ┌────────▼────────┐
                             │     Consul      │
                             │ (服务发现 :8500) │
                             └─────────────────┘
```

## 快速开始

### 1. 启动所有组件

```bash
cd infrastructure
./deploy.sh up
```

### 2. 按需启动

```bash
# 只启动服务发现
./deploy.sh up consul

# 启动日志系统
./deploy.sh up loki grafana

# 启动追踪系统
./deploy.sh up jaeger grafana

# 启动监控系统
./deploy.sh up prometheus grafana
```

### 3. 访问地址

| 服务 | 地址 | 用途 |
|------|------|------|
| Consul | http://localhost:8500 | 服务发现 & 配置中心 |
| Jaeger | http://localhost:16686 | 链路追踪 UI |
| Grafana | http://localhost:3030 | 统一仪表盘 |
| Prometheus | http://localhost:9090 | 指标查询 |
| Loki | http://localhost:3100 | 日志 API |

## 组件说明

### Consul - 服务发现与配置中心

**功能：**
- 服务注册与发现
- 健康检查
- KV 配置存储
- 多数据中心支持

**配置文件：**
- `consul/config/services.json` - 服务注册定义
- `consul/config/kv-defaults.json` - 默认 KV 配置

**使用示例：**
```bash
# 查看已注册服务
curl http://localhost:8500/v1/catalog/services

# 读取配置
curl http://localhost:8500/v1/kv/rwa/config/global/log_level?raw

# 更新配置
curl -X PUT -d 'debug' http://localhost:8500/v1/kv/rwa/config/global/log_level
```

### Jaeger - 分布式链路追踪

**功能：**
- 请求链路追踪
- 性能瓶颈分析
- 服务依赖可视化
- 错误定位

**接入方式（NestJS）：**
```typescript
// 安装依赖
npm install @opentelemetry/sdk-node @opentelemetry/exporter-jaeger

// 在 main.ts 中初始化
import { NodeSDK } from '@opentelemetry/sdk-node';
import { JaegerExporter } from '@opentelemetry/exporter-jaeger';

const sdk = new NodeSDK({
  traceExporter: new JaegerExporter({
    endpoint: 'http://jaeger:14268/api/traces',
  }),
  serviceName: 'identity-service',
});
sdk.start();
```

### Loki + Promtail - 日志聚合

**功能：**
- 自动收集 Docker 容器日志
- 日志标签化与索引
- LogQL 查询
- 与 Grafana 深度集成

**日志查询示例（Grafana）：**
```logql
# 查看所有错误日志
{job="rwa-backend"} |~ "error|Error|ERROR"

# 按服务筛选
{service="identity-service"} | json | level="error"

# 查看特定 trace
{trace_id="abc123"}
```

### Prometheus - 指标监控

**功能：**
- 指标收集
- 告警规则
- PromQL 查询

**告警规则：**
- `prometheus/rules/rwa-alerts.yml` - 预定义告警规则

### Grafana - 统一可视化

**预置仪表盘：**
- RWA Services Overview - 服务概览
- Kong Dashboard - API 网关监控
- Presence Dashboard - 用户在线状态

**数据源：**
- Prometheus (指标)
- Loki (日志)
- Jaeger (追踪)

## 目录结构

```
infrastructure/
├── docker-compose.yml          # 主编排文件
├── deploy.sh                   # 部署脚本
├── .env.example                # 环境变量模板
├── README.md                   # 本文档
│
├── consul/
│   └── config/
│       ├── services.json       # 服务注册
│       └── kv-defaults.json    # KV 默认配置
│
├── jaeger/                     # Jaeger 配置 (使用默认)
│
├── loki/
│   ├── loki-config.yml         # Loki 配置
│   └── promtail-config.yml     # Promtail 配置
│
├── prometheus/
│   ├── prometheus.yml          # Prometheus 配置
│   └── rules/
│       └── rwa-alerts.yml      # 告警规则
│
└── grafana/
    └── provisioning/
        ├── datasources/
        │   └── datasources.yml # 数据源配置
        └── dashboards/
            ├── dashboards.yml  # 仪表盘配置
            └── rwa-services-overview.json
```

## 常用命令

```bash
# 启动
./deploy.sh up                    # 启动所有
./deploy.sh up consul jaeger      # 启动指定组件

# 管理
./deploy.sh status                # 查看状态
./deploy.sh health                # 健康检查
./deploy.sh logs grafana          # 查看日志
./deploy.sh restart               # 重启

# 停止
./deploy.sh down                  # 停止所有
```

## 与现有服务集成

这些组件是**完全可选的**，不需要修改现有微服务代码即可获得以下能力：

| 能力 | 无需改代码 | 需要少量改动 |
|------|-----------|-------------|
| 服务健康监控 | ✅ Consul 健康检查 | - |
| 日志聚合 | ✅ Docker 日志自动收集 | - |
| 基础指标 | ✅ Kong Prometheus 插件 | - |
| 详细指标 | - | 添加 Prometheus 中间件 |
| 链路追踪 | - | 添加 OpenTelemetry SDK |
| 动态配置 | - | 集成 Consul KV |

## 扩展配置

### 添加告警通知

编辑 `prometheus/prometheus.yml`，配置 Alertmanager：

```yaml
alerting:
  alertmanagers:
    - static_configs:
        - targets: ['alertmanager:9093']
```

### 添加更多服务到 Consul

编辑 `consul/config/services.json`，添加新服务定义。

### 自定义 Grafana 仪表盘

将 JSON 文件放入 `grafana/provisioning/dashboards/` 目录即可自动加载。

## 生产环境建议

1. **持久化存储**：当前使用 Docker volumes，生产环境建议使用外部存储
2. **高可用**：Consul 建议 3-5 节点集群
3. **安全**：配置 TLS 和访问控制
4. **资源限制**：添加 Docker 资源限制配置