# FluxGate

**Repository Path**: boranli_admin/FluxGate

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FluxGate

语言：简体中文 | [English](README.en.md)

FluxGate 是一个基于 Go 开发的 API 网关和跨语言限流中心。

它可以作为独立服务部署。Java、Go、Node.js、Python、PHP 或其他语言开发的业务系统，可以选择让流量经过 FluxGate 网关，也可以在业务代码中通过 HTTP 调用 FluxGate 的限流接口。

## 功能能力

- 独立 API 网关：通过 `/gateway/{path}` 转发业务流量。
- 跨语言限流 API：通过 HTTP 调用 `POST /api/v1/limit/check` 和 `POST /api/v1/limit/release`。
- 支持多种限流维度：
  - 滑动窗口请求量限制
  - 令牌桶吞吐量和突发容量限制
  - 最大并发量限制
- Web Dashboard：访问 `/` 可进行规则管理和指标查看。
- 保留原有任务调度、重试、死信队列、Redis 分布式锁、Prometheus 指标和 OpenTelemetry 能力。

## 快速启动

```bash
docker compose up -d --build
```

启动后访问：

- Dashboard：`http://localhost:8080/`
- 网关代理：`http://localhost:8080/gateway/{path}`
- 规则 API：`http://localhost:8080/api/v1/flow/rules`
- 指标：`http://localhost:9090/metrics`

默认部署配置文件：

```text
deploy/fluxgate.json
```

## 规则示例

令牌桶规则：

```json
{
  "resource": "/api/orders",
  "algorithm": "token_bucket",
  "rate": 100,
  "capacity": 50,
  "max_concurrency": 100,
  "upstream": "http://localhost:9000",
  "description": "Order service",
  "enabled": true
}
```

滑动窗口规则：

```json
{
  "resource": "/api/users",
  "algorithm": "sliding_window",
  "max_requests": 200,
  "window_size": 1000000000,
  "max_concurrency": 80,
  "upstream": "http://localhost:9001",
  "enabled": true
}
```

`window_size` 使用 Go `time.Duration` 的纳秒值，例如 `1000000000` 表示 1 秒。

## 网关模式

如果规则资源是 `/api/orders`，下面这个请求会按最长前缀匹配到该规则：

```bash
curl http://localhost:8080/gateway/api/orders/123
```

FluxGate 会先执行限流判断，再把请求转发到规则中配置的 `upstream`。如果规则包含最大并发限制，并发租约会在上游响应结束后自动释放。

## 跨语言限流中心模式

当业务流量不经过 FluxGate 网关时，可以在业务系统里调用 HTTP 限流接口。

```bash
curl -X POST http://localhost:8080/api/v1/limit/check \
  -H "Content-Type: application/json" \
  -d '{"resource":"/api/orders"}'
```

允许通过时返回：

```json
{
  "resource": "/api/orders",
  "allowed": true,
  "lease_id": "optional-concurrency-lease",
  "remaining_concurrency": 99
}
```

如果返回了 `lease_id`，说明占用了并发名额，业务处理完成后需要释放：

```bash
curl -X POST http://localhost:8080/api/v1/limit/release \
  -H "Content-Type: application/json" \
  -d '{"lease_id":"optional-concurrency-lease"}'
```

被限流的请求会返回 HTTP `429`。

## 规则管理 API

```bash
# 查询规则
curl http://localhost:8080/api/v1/flow/rules

# 创建或更新规则
curl -X POST http://localhost:8080/api/v1/flow/rules \
  -H "Content-Type: application/json" \
  -d '{"resource":"/api/orders","algorithm":"token_bucket","rate":100,"capacity":50,"max_concurrency":100,"upstream":"http://localhost:9000","enabled":true}'

# 删除规则
curl -X DELETE http://localhost:8080/api/v1/flow/rules/%2Fapi%2Forders

# 查询运行指标快照
curl http://localhost:8080/api/v1/flow/metrics
```

## 本地构建

需要 Go 1.22+。

```bash
go test ./...
go build -o fluxgate ./cmd/fluxgate
```

指定配置文件运行：

```bash
FLUXGATE_CONFIG=deploy/fluxgate.json ./fluxgate
```