# cloud-gateway

**Repository Path**: bwg_group/cloud-gateeay

## Basic Information

- **Project Name**: cloud-gateway
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-10
- **Last Updated**: 2026-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BWG Cloud Gateway

> 基于 Spring Cloud Gateway 实现的统一 API 网关，替代原有的 Ingress Gateway

## 目录

- [技术栈](#技术栈)
- [核心依赖](#核心依赖)
- [功能特性](#功能特性)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [路由配置](#路由配置)
- [配置说明](#配置说明)
- [监控运维](#监控运维)
- [故障排查](#故障排查)

---

## 技术栈

| 技术 | 版本 | 说明 |
|-----|------|-----|
| JDK | 21 | 由 iby-parent 管理 |
| Spring Boot | 3.5.7 | 由 iby-parent 管理 |
| Spring Cloud | 2025.0.1 | 由 iby-parent 管理 |
| iby-spring-cloud-starter-gateway | 1.0.0-SNAPSHOT | 提供网关核心、限流、日志、监控等功能 |
| Redis | - | 分布式限流 |
| Resilience4j | - | 熔断降级 |

---

## 核心依赖

```xml
<dependencies>
    <dependency>
        <groupId>com.inboyu</groupId>
        <artifactId>iby-spring-cloud-starter-gateway</artifactId>
    </dependency>
</dependencies>
```

**已包含的传递依赖**：
- spring-cloud-starter-gateway
- spring-boot-starter-actuator
- spring-boot-starter-data-redis-reactive
- micrometer-registry-prometheus
- resilience4j-spring-boot3
- iby-spring-cloud-starter-common（ExternalResult、ResponseCodeEnum）
- lombok

---

## 功能特性

### 业务实现功能

| 过滤器 | 功能描述 |
|-------|---------|
| `AuthenticationFilter` | 内部 API 认证：验证 Bearer Token，解析用户信息并传递给下游服务 |
| `PublicAuthFilter` | 公开 API 认证：可选验证，有 Token 则解析，无 Token 则放行 |

### IBY Starter 提供功能

| 功能 | 配置前缀 | 说明 |
|-----|---------|------|
| 全局错误处理 | - | 统一错误响应格式（ExternalResult） |
| 安全头过滤 | - | 添加 X-Content-Type-Options、X-Frame-Options 等 |
| Redis 限流 | `iby.gateway.rate-limit` | 分布式限流，支持 IP/用户/租户/路径维度 |
| 并发限流 | `iby.gateway.concurrency-limit` | 并发请求数限制 |
| 访问日志 | `iby.gateway.access-log` | 请求日志记录，支持慢请求监控 |
| 脱敏 | `iby.gateway.desensitize` | 日志字段脱敏 |
| IP 白名单 | `iby.gateway.ip-whitelist` | IP 白名单过滤 |
| IP 黑名单 | `iby.gateway.ip-blacklist` | IP 黑名单过滤 |
| Prometheus 指标 | - | 性能指标收集 |

---

## 项目结构

```
bwg-cloud-gateway/
├── pom.xml                                    # Maven 配置
├── .gitlab-ci.yml                             # CI/CD 配置
├── README.md
├── src/
│   └── main/
│       ├── java/com/inboyu/gateway/
│       │   ├── BwgCloudGatewayApplication.java
│       │   ├── config/
│       │   │   ├── GatewayConfig.java        # CORS + AuthProperties
│       │   │   └── GatewayHealthIndicator.java
│       │   ├── constant/
│       │   │   └── GatewayConstants.java     # 常量定义
│       │   ├── filter/
│       │   │   ├── AuthenticationFilter.java # 内部 API 认证
│       │   │   └── PublicAuthFilter.java     # 公开 API 认证
│       │   └── utils/
│       │       └── GatewayUtils.java         # 工具类
│       └── resources/
│           └── application.yml                # 配置文件
```

---

## 快速开始

### 本地开发

#### 1. 启动 Redis
```bash
docker run -d -p 6379:6379 --name redis redis:latest
```

#### 2. 配置环境变量
```bash
export REDIS_HOST=localhost
export REDIS_PORT=6379

# 配置后端服务地址
export AUTH_SERVICE_URL=http://localhost:8081
export ADMIN_SERVICE_URL=http://localhost:8082
# ... 其他服务
```

#### 3. 启动网关
```bash
mvn spring-boot:run
```

### Docker 运行

```bash
docker build -t bwg-cloud-gateway:latest .
docker run -d -p 8080:8080 \
  -e REDIS_HOST=redis \
  -e AUTH_SERVICE_URL=http://auth-center:8080 \
  bwg-cloud-gateway:latest
```

---

## 路由配置

### 内部服务路由（需要完整认证）

| 路径 | 目标服务 | 环境变量 |
|-----|---------|---------|
| `/api/v1/admin/**` | 管理服务 | `${ADMIN_SERVICE_URL}` |
| `/api/v1/listing/**` | 列表服务 | `${LISTING_SERVICE_URL}` |
| `/api/v1/listing-batch/**` | 列表批处理 | `${LISTING_BATCH_URL}` |
| `/api/v1/operation/**` | 运营中心 | `${OPERATION_CENTER_URL}` |
| `/api/v1/sale/**` | 销售服务 | `${SALES_SERVICE_URL}` |
| `/api/v1/marketing/**` | 营销服务 | `${MARKETING_SERVICE_URL}` |
| `/api/v1/orders/**` | 订单服务 | `${ORDER_SERVICE_URL}` |
| `/api/v1/billing/**` | 账单服务 | `${BILLING_SERVICE_URL}` |
| `/api/v1/logs/**` | 日志服务 | `${LOGS_SERVICE_URL}` |
| `/api/v1/payment/**` | 支付中心 | `${PAYMENT_CENTER_URL}` |
| `/api/v1/device/**` | 设备服务 | `${DEVICE_SERVICE_URL}` |

### 公开路由（可选认证）

| 路径 | 目标服务 | 说明 |
|-----|---------|------|
| `/api/v1/auth/**` | 认证服务 | 无需认证 |
| `/api/v1/listing/public/**` | 列表服务 | 可选认证 |
| `/api/v1/marketing/public/**` | 营销服务 | 可选认证 |
| `/api/v1/sale/public/**` | 销售服务 | 可选认证 |
| `/api/v1/billing/public/**` | 账单服务 | 可选认证 |
| `/api/v1/orders/public/**` | 订单服务 | 可选认证 |

---

## 配置说明

### 环境变量

#### 必需配置

```bash
# Redis
REDIS_HOST=tenant-system-redis
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DATABASE=0

# 服务 URL
AUTH_SERVICE_URL=http://auth-center-app.franchise-dev.svc.cluster.local
ADMIN_SERVICE_URL=http://admin-service-app.franchise-dev.svc.cluster.local
LISTING_SERVICE_URL=http://listing-service-app.franchise-dev.svc.cluster.local
LISTING_BATCH_URL=http://listing-service-batch.franchise-dev.svc.cluster.local
OPERATION_CENTER_URL=http://operation-center-app.franchise-dev.svc.cluster.local
SALES_SERVICE_URL=http://sales-service-app.franchise-dev.svc.cluster.local
MARKETING_SERVICE_URL=http://marketing-service-app.franchise-dev.svc.cluster.local
ORDER_SERVICE_URL=http://order-service-app.franchise-dev.svc.cluster.local
BILLING_SERVICE_URL=http://billing-service-app.franchise-dev.svc.cluster.local
LOGS_SERVICE_URL=http://logs-service-app.franchise-dev.svc.cluster.local
PAYMENT_CENTER_URL=http://payment-center-app.franchise-dev.svc.cluster.local
DEVICE_SERVICE_URL=http://device-service-app.franchise-dev.svc.cluster.local
```

#### 可选配置

```bash
# 网关端口
GATEWAY_PORT=8080

# HTTP 代理
HTTP_PROXY_HOST=
HTTP_PROXY_PORT=
```

### IBY Gateway Starter 配置

```yaml
iby:
  gateway:
    # Redis 限流配置
    rate-limit:
      enabled: true
      default-limit: 100      # 每秒请求数
      key-type: ip           # ip, user, tenant, path

    # 并发限流配置
    concurrency-limit:
      enabled: false
      default-limit: 50      # 并发请求数

    # IP 白名单
    ip-whitelist:
      enabled: false
      ips: []

    # IP 黑名单
    ip-blacklist:
      enabled: false
      ips: []

    # 访问日志配置
    access-log:
      enabled: true
      slow-threshold: 3000       # 慢请求阈值（毫秒）
      log-request-body: true     # 记录请求体
      log-response-body: true    # 记录响应体

    # 脱敏配置
    desensitize:
      enabled: true
      fields:
        - password
        - token
        - secret
        - idCard
        - phone
```

### 认证配置

```yaml
gateway:
  auth:
    auth-service-url: http://auth-center-app
    public-auth-path: /api/v1/auth/public
    auth-path: /api/v1/auth
    exclude-paths:
      - /api/v1/auth/**
      - /actuator/**
      - /health
      - /info
```

### CORS 配置

```yaml
gateway:
  cors:
    allowed-origins:
      - https://franchise-management-dev.test.inboyu.com
      - https://localhost.com:5173
    allowed-headers:
      - Authorization
      - Content-Type
      - X-Trace-Id
      - X-User-Id
      - X-Tenant-Id
    expose-headers:
      - X-API-Version
      - X-Trace-Id
    max-age: 3600
```

### 熔断配置

```yaml
resilience4j:
  circuitbreaker:
    configs:
      default:
        register-health-indicator: true
        sliding-window-size: 10
        minimum-number-of-calls: 5
        failure-rate-threshold: 50
        wait-duration-in-open-state: 60s
```

---

## 监控运维

### 健康检查

```bash
curl http://localhost:8080/actuator/health
```

**响应示例**：
```json
{
  "status": "UP",
  "components": {
    "redis": { "status": "UP", "details": { "redis": "connected" } },
    "gateway": { "status": "UP", "details": { "gateway": "running" } },
    "diskSpace": { "status": "UP" }
  }
}
```

### 查看路由

```bash
# 查看所有路由
curl http://localhost:8080/actuator/gateway/routes

# 查看特定路由
curl http://localhost:8080/actuator/gateway/routes/admin-service
```

### Prometheus 指标

```bash
curl http://localhost:8080/actuator/prometheus
```

**关键指标**：
- `gateway_requests_seconds` - 请求耗时
- `gateway_requests_total` - 请求总数
- `resilience4j_circuitbreaker_state` - 熔断器状态

### 日志查看

```bash
# Kubernetes
kubectl logs -f deployment/bwg-cloud-gateway -n franchise-dev

# Docker
docker logs -f bwg-cloud-gateway

# 查看 Trace ID 日志
kubectl logs deployment/bwg-cloud-gateway | grep "X-Trace-Id: xxx"
```

---

## 响应格式

网关使用 `ExternalResult` 统一响应格式：

### 成功响应
```json
{
  "success": true,
  "msg": "操作成功",
  "code": 200,
  "data": {}
}
```

### 错误响应
```json
{
  "success": false,
  "msg": "未登录",
  "code": 40101,
  "data": null
}
```

### 错误码说明

| 错误码 | 枚举值 | 说明 |
|-------|-------|------|
| 40101 | UN_LOGIN | 未登录或 Token 缺失 |
| 40102 | UN_AUTHORIZED | Token 无效或已过期 |
| 50001 | CALL_INTERFACE_ERROR | 认证服务调用失败 |

---

## 用户信息传递

认证成功后，网关会将用户信息通过请求头传递给下游服务：

| 请求头 | 说明 |
|-------|------|
| `X-User-Id` | 用户 ID |
| `X-Staff-Id` | 员工 ID |
| `X-Tenant-Id` | 租户 ID |
| `X-Role-Scope` | 角色范围 |
| `X-Client-Identifier` | 客户端标识 |
| `X-Client-Type` | 客户端类型 |

---

## 故障排查

### 问题：服务无法访问

**排查步骤**：
1. 检查服务 URL 环境变量是否正确
   ```bash
   env | grep SERVICE_URL
   ```
2. 检查目标服务是否正常
   ```bash
   curl http://target-service:8080/actuator/health
   ```
3. 检查网络连接

### 问题：认证失败

**排查步骤**：
1. 检查认证服务状态
   ```bash
   curl http://auth-center-app/actuator/health
   ```
2. 验证 Token 格式
   ```bash
   # Authorization: Bearer <token>
   curl -H "Authorization: Bearer xxx" http://gateway/api/v1/admin/test
   ```
3. 查看网关日志

### 问题：限流误触发

**解决方案**：
1. 调整限流参数
   ```yaml
   iby.gateway.rate-limit.default-limit: 200
   ```
2. 检查 Redis 连接
3. 确认限流 key 类型（ip/user/tenant/path）

### 问题：熔断触发

**排查步骤**：
1. 查看下游服务状态
2. 检查网络连接
3. 查看熔断器状态
   ```bash
   curl http://localhost:8080/actuator/health
   ```
4. 调整熔断配置

---

## 性能优化建议

| 优化项 | 配置参数 | 建议值 |
|-------|---------|-------|
| 连接池大小 | `spring.cloud.gateway.httpclient.pool.max-connections` | 500 |
| 响应超时 | `spring.cloud.gateway.httpclient.response-timeout` | 600s |
| 限流阈值 | `iby.gateway.rate-limit.default-limit` | 根据业务调整 |
| Redis 连接池 | `spring.data.redis.lettuce.pool.max-active` | 20 |

---

## 与 Ingress Gateway 对比

| 功能 | Ingress Gateway | Spring Cloud Gateway |
|-----|----------------|---------------------|
| 路由转发 | ✅ | ✅ |
| 认证鉴权 | ✅ | ✅ |
| CORS | ✅ | ✅ |
| 限流 | ❌ | ✅（Redis 分布式） |
| 熔断降级 | ❌ | ✅（Resilience4j） |
| 访问日志 | ✅ | ✅（支持脱敏） |
| 安全头 | ❌ | ✅ |
| 慢请求监控 | ❌ | ✅ |
| Prometheus | ❌ | ✅ |
| IP 访问控制 | ❌ | ✅ |

---

## 注意事项

1. **不使用服务发现**：通过固定 HTTP URL 路由，需正确配置环境变量
2. **Redis 依赖**：限流功能依赖 Redis，确保 Redis 高可用
3. **认证服务依赖**：认证功能依赖认证中心，确保服务可用
4. **监控告警**：建议配置 Prometheus + Grafana 监控
5. **熔断配置**：根据业务特点调整熔断参数