rwadurian/backend/infrastructure

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

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

架构概览

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

快速开始

1. 启动所有组件

cd infrastructure
./deploy.sh up

2. 按需启动

# 只启动服务发现
./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
Sentry	http://localhost:9000	崩溃收集 & 错误追踪

组件说明

Consul - 服务发现与配置中心

功能：

• 服务注册与发现
• 健康检查
• KV 配置存储
• 多数据中心支持

配置文件：

• consul/config/services.json - 服务注册定义
• consul/config/kv-defaults.json - 默认 KV 配置

使用示例：

# 查看已注册服务
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）：

// 安装依赖
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）：

# 查看所有错误日志
{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 (追踪)

Sentry - 崩溃收集与错误追踪 (独立部署)

功能：

• 崩溃收集 (Flutter + Android/iOS 原生层)
• 错误追踪与堆栈符号化
• 设备兼容性分析
• 性能监控
• Session Replay

部署方式：

Sentry 是独立部署的服务，位于 sentry/ 目录:

cd sentry

# 首次安装 (创建管理员账号)
./deploy.sh init

# 启动服务
./deploy.sh up

系统要求：

• 最低 4GB 内存，推荐 8GB+
• 约 20GB 磁盘空间

详细文档请参考: sentry/README.md

目录结构

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
│
└── sentry/                     # 崩溃收集 (独立部署)
    ├── docker-compose.yml      # Sentry 编排
    ├── deploy.sh               # 部署脚本
    ├── sentry.conf.py          # Sentry 配置
    └── README.md               # 详细文档

常用命令

# 启动
./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
崩溃收集	-	集成 sentry_flutter SDK

扩展配置

添加告警通知

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

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 资源限制配置