Skip to content

MICROSERVICES_USAGE.md

Latest commit

 

History

History
395 lines (288 loc) · 8.85 KB

MICROSERVICES_USAGE.md

File metadata and controls

395 lines (288 loc) · 8.85 KB
Raw

Lumin Cloud 微服务核心组件使用指南

📋 目录

概述

Lumin Cloud 是一个基于 Spring Cloud 的微服务平台，已实现以下核心功能：

  1. ✅ 服务注册与发现 - Nacos
  2. ✅ 配置中心 - Nacos Config
  3. ✅ 认证授权中心 - OAuth2 + JWT
  4. ✅ 链路追踪 - Sleuth + Zipkin
  5. ✅ 限流熔断 - Sentinel

已实现的核心组件

1. 服务注册与发现（Nacos）

所有微服务都已集成 Nacos 服务注册与发现功能：

  • lumin-gateway - API网关（端口8080）
  • lumin-auth - 认证授权服务（端口9001）
  • lumin-user - 用户服务（端口9002）

2. 配置中心（Nacos Config）

通过 bootstrap.yml 配置文件，所有服务启动时会从 Nacos 配置中心加载配置。

3. 认证授权中心（OAuth2/JWT）

lumin-auth 模块实现了完整的 OAuth2 授权服务器：

  • 支持多种授权模式：authorization_code、refresh_token、client_credentials、password
  • 使用 RSA 密钥对进行 JWT 签名
  • 提供 JWT 工具类用于令牌生成和验证

4. 链路追踪（Sleuth/Zipkin）

所有服务都集成了：

  • Spring Cloud Sleuth - 自动生成 traceId 和 spanId
  • Zipkin - 上报链路数据到 Zipkin Server
  • 日志中包含链路追踪信息：[%X{traceId:-},%X{spanId:-}]

5. 限流熔断（Sentinel）

所有服务都配置了 Sentinel：

  • Gateway 层面对不同服务进行限流
  • 服务层面可以配置细粒度的接口限流
  • 支持从 Nacos 动态配置限流规则

快速开始

前置条件

确保以下基础设施已启动：

  1. Nacos Server (端口 8848)

    # 使用 Docker 启动
docker run -d --name nacos -p 8848:8848 -e MODE=standalone nacos/nacos-server:v2.3.0

  2. Sentinel Dashboard (端口 8858)

    # 使用 Docker 启动
docker run -d --name sentinel -p 8858:8858 bladex/sentinel-dashboard:1.8.6

  3. Zipkin Server (端口 9411)

    # 使用 Docker 启动
docker run -d --name zipkin -p 9411:9411 openzipkin/zipkin:latest

或者使用项目提供的 docker-compose.yml：

docker-compose up -d nacos sentinel zipkin

启动服务

方式一：使用启动脚本（推荐）

# Windows
start-services.bat

# Linux/Mac
chmod +x start-services.sh
./start-services.sh

方式二：手动启动

# 启动网关
cd lumin-gateway
mvn spring-boot:run

# 启动认证服务
cd lumin-auth
mvn spring-boot:run

# 启动用户服务
cd lumin-user
mvn spring-boot:run

验证服务

  1. 查看 Nacos 控制台

  2. 访问网关健康检查

    curl http://127.0.0.1:8080/health

组件详细说明

1. Nacos 服务注册与发现

配置示例

spring:
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
        namespace: 
        group: DEFAULT_GROUP

服务间调用

Gateway 通过服务名进行路由：

spring:
  cloud:
    gateway:
      routes:
        - id: lumin-auth
          uri: lb://lumin-auth  # lb:// 表示负载均衡
          predicates:
            - Path=/auth/**

2. Nacos Config 配置中心

配置文件命名规则

在 Nacos 中创建配置文件：

  • Data ID: {service-name}-{profile}.yml
  • Group: DEFAULT_GROUP

例如：

  • lumin-gateway-dev.yml
  • lumin-auth-dev.yml
  • lumin-user-dev.yml

本地配置优先级

bootstrap.yml > Nacos Config > application.yml

3. OAuth2 + JWT 认证授权

获取访问令牌

密码模式：

curl -X POST http://127.0.0.1:8080/auth/oauth2/token \
  -H "Authorization: Basic bHVtaW4tY2xpZW50OnNlY3JldA==" \
  -d "grant_type=password&username=admin&password=admin123&scope=read write"

客户端模式：

curl -X POST http://127.0.0.1:8080/auth/oauth2/token \
  -H "Authorization: Basic bHVtaW4tY2xpZW50OnNlY3JldA==" \
  -d "grant_type=client_credentials&scope=read write"

使用令牌访问资源

curl http://127.0.0.1:8080/user/api/user/info \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

JWT 配置

jwt:
  secret: "your-secret-key-here"
  expiration: 7200  # 2小时
  refresh-expiration: 604800  # 7天

4. Sleuth + Zipkin 链路追踪

配置说明

spring:
  sleuth:
    sampler:
      probability: 1.0  # 采样率 0.0-1.0
  zipkin:
    base-url: http://127.0.0.1:9411/
    enabled: true

查看链路

  1. 访问 Zipkin UI：http://127.0.0.1:9411
  2. 点击 "Run Query" 查看最近的请求链路
  3. 可以看到完整的调用链：Gateway -> Auth/User Service

日志格式

日志中包含 traceId 和 spanId：

2024-01-01 12:00:00.000 [http-nio-8080-exec-1] [a1b2c3d4e5f6g7h8,i1j2k3l4m5n6o7p8] INFO ...

5. Sentinel 限流熔断

Gateway 限流配置

// 对认证服务限流：QPS = 200
rules.add(new GatewayFlowRule("lumin-auth")
    .setCount(200)
    .setIntervalSec(1));

// 对用户服务限流：QPS = 500
rules.add(new GatewayFlowRule("lumin-user")
    .setCount(500)
    .setIntervalSec(1));

服务级别限流

@PostConstruct
public void initFlowRules() {
    List<FlowRule> rules = new ArrayList<>();
    
    FlowRule rule = new FlowRule();
    rule.setResource("getUserInfo");
    rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
    rule.setCount(100); // QPS = 100
    rules.add(rule);
    
    FlowRuleManager.loadRules(rules);
}

Sentinel Dashboard

  1. 访问：http://127.0.0.1:8858
  2. 用户名/密码：sentinel/sentinel
  3. 可以实时查看：
    • QPS
    • 响应时间
    • 限流情况
    • 熔断状态

API测试

1. 健康检查

# 网关健康检查
curl http://127.0.0.1:8080/health

# 用户服务健康检查（通过网关）
curl http://127.0.0.1:8080/user/api/user/health

2. 获取用户信息

# 先获取 token
TOKEN=$(curl -X POST http://127.0.0.1:8080/auth/oauth2/token \
  -H "Authorization: Basic bHVtaW4tY2xpZW50OnNlY3JldA==" \
  -d "grant_type=password&username=admin&password=admin123&scope=read write" \
  | jq -r '.access_token')

# 使用 token 访问用户信息
curl http://127.0.0.1:8080/user/api/user/info \
  -H "Authorization: Bearer $TOKEN"

3. 测试限流

使用 Apache Bench 或 JMeter 进行压力测试：

# 安装 Apache Bench
# Ubuntu: sudo apt-get install apache2-utils
# CentOS: sudo yum install httpd-tools

# 测试限流（发送1000个请求，并发10个）
ab -n 1000 -c 10 http://127.0.0.1:8080/user/api/user/info

当超过限流阈值时，会返回 429 Too Many Requests。

常见问题

Q1: 服务无法注册到 Nacos？

检查项：

  1. Nacos 是否正常启动
  2. 配置文件中的 server-addr 是否正确
  3. 网络是否通畅
  4. 查看应用日志是否有错误信息

Q2: OAuth2 认证失败？

检查项：

  1. Client ID 和 Secret 是否正确
  2. 用户名和密码是否正确
  3. Scope 是否在允许范围内
  4. 授权类型是否已配置

默认测试账号：

  • admin / admin123
  • user / user123

Q3: Zipkin 看不到链路数据？

检查项：

  1. Zipkin 服务是否正常启动
  2. spring.zipkin.base-url 配置是否正确
  3. spring.sleuth.sampler.probability 是否设置为 1.0
  4. 查看应用日志是否有上报失败的错误

Q4: Sentinel Dashboard 看不到服务？

检查项：

  1. Sentinel Dashboard 是否正常启动
  2. spring.cloud.sentinel.transport.dashboard 配置是否正确
  3. 服务是否有流量（Sentinel 是懒加载的，需要有请求才会显示）
  4. 检查防火墙是否阻止了 8719、8720、8721 端口

Q5: 配置中心不生效？

检查项：

  1. 确认使用了 bootstrap.yml 而不是仅在 application.yml 中配置
  2. Nacos 中的 Data ID 是否正确（格式：{service-name}-{profile}.yml）
  3. Group 是否匹配
  4. 配置文件的 file-extension 是否为 yml

下一步建议

  1. 持久化配置 - 将配置保存到 Nacos 配置中心
  2. 数据库集成 - 添加 MyBatis Plus 和 MySQL 支持
  3. Redis 缓存 - 集成 Redis 用于缓存和会话管理
  4. 消息队列 - 集成 RabbitMQ 或 Kafka
  5. 分布式事务 - 集成 Seata
  6. API 文档 - 集成 Knife4j/Swagger

技术支持

如有问题，请查看：