# hussar

**Repository Path**: haart/hussar

## Basic Information

- **Project Name**: hussar
- **Description**: lancer的升级版
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-11
- **Last Updated**: 2026-02-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hussar

Hussar 是一个用 Go 编写的轻量级 API 网关，为 Nacos + Spring Boot 微服务团队提供开箱即用的前置网关方案。

## 核心特性

- 单二进制 25MB，零运行时依赖，复制即部署
- 静态文件 + API 代理 + 鉴权一体化，一个进程搞定前端部署和后端路由
- Nacos 服务发现 + 加权随机负载均衡
- 可插拔认证服务（verifyUri），网关不需要理解 token 格式
- Spring Data 分页响应自动转换为前端友好格式
- Nacos 配置热更新（atomic mux swap，在途请求不中断）
- 蓝绿发布（IP 白名单 + Nacos metadata 过滤）
- Redis 分布式 per-IP 限流
- UV/PV 页面访问统计（HTML 页面，按天按页面粒度，Redis 存储）
- 502 自动重试（传输层错误 + 幂等方法，重试一次）
- W3C Trace Context（traceparent）透传，兼容 Spring Boot 3.x
- Prometheus 监控指标（按服务拆分）

## 模块关系

```
Client Request
    │
    ▼
┌──────────────────────────────────────────────────────┐
│                   Hussar Gateway                     │
│                                                      │
│  Router (http.ServeMux)                              │
│    ├─ /ping, /health, /metrics   内置端点            │
│    ├─ /{prefix}/*                API 反向代理        │
│    └─ /*                         静态文件服务        │
│                                                      │
│  API 请求处理流程:                                   │
│    FilterChain ──→ ReverseProxy ──→ 响应处理         │
│    (Security       (lb:// Nacos     (重写/压缩/SSE)  │
│     RemoteAddr      http(s)://                       │
│     Auth)           蓝绿/重试)                       │
│                                                      │
│  服务发现:  route.go → lb/nacos.go → Nacos SDK       │
│  认证:      filter/auth.go → 认证服务/Redis Token    │
│  配置:      main.go → cfg/ → Nacos 远程配置          │
└──────────────────────────────────────────────────────┘
    │              │              │
    ▼              ▼              ▼
  后端服务A     后端服务B     静态文件
```

### 包结构

| 包 | 职责 |
|---|------|
| `main` (root) | 入口、路由、静态文件、反向代理、健康检查、监控 |
| `cfg/` | 配置结构定义、Nacos 远程配置加载、Merge 逻辑 |
| `filter/` | 过滤器链（LocalAffinity → RemoteAddr → Auth） |
| `lb/` | Nacos 服务发现、加权随机负载均衡 |
| `comp/` | Gzip 压缩 |
| `cache/` | LRU 内存缓存 |
| `tracing/` | W3C Trace Context |
| `ratelimit/` | Redis 分布式限流 |
| `uvpv/` | UV/PV 页面访问统计 |

## 运行条件

| 依赖 | 用途 | 是否必需 |
|------|------|----------|
| Go 1.25+ | 构建 | 是 |
| Redis | 限流、UV/PV 统计、旧版 Token 存储 | 配置了限流或 UV/PV 时必需 |
| Nacos | 服务发现、远程配置 | 配置了 `lb://` 路由时必需 |

## 快速开始

### 构建

```bash
# Windows
go build -ldflags "-s -w" -o hussar.exe

# Linux / macOS（静态链接）
CGO_ENABLED=0 go build -ldflags "-s -w" -o hussar
```

也可使用构建脚本：`./build_windows.cmd`、`./build_linux.cmd`、`./build_darwin.cmd`。

### 最小配置

创建 `hussar.json`：

```json
{
    "listen": ":8080",
    "base": "./static",
    "services": [
        {
            "name": "api",
            "prefix": "/api/",
            "uri": "http://localhost:9090"
        }
    ]
}
```

### 启动

```bash
./hussar hussar.json
```

### 验证

```bash
curl http://localhost:8080/ping
# pong
```

### 其他命令

```bash
hussar -version              # 显示版本
hussar -verify hussar.json   # 验证配置文件
hussar -debug hussar.json    # 调试模式（详细日志）
```

## 部署

支持 Linux systemd、Docker、直接运行等方式。详见 [deployment.md](deployment.md)。

## 配置

配置文件使用 JSON 格式，支持环境变量插值（`${VAR:default}`）和 Nacos 远程配置合并。详见 [config.md](config.md)。

## 文档索引

| 文档 | 内容 |
|------|------|
| [api.md](api.md) | 系统架构与接口文档（端点、请求流程、响应格式、认证流程） |
| [config.md](config.md) | 配置文件字段详细说明 |
| [deployment.md](deployment.md) | 部署指南（systemd、Docker、环境变量、故障排查） |
| [features.md](features.md) | 功能清单 |
| [comparison.md](comparison.md) | 与 Nginx/Spring Gateway/K8s Ingress 详细对比 |
| [issue.md](issue.md) | 已知问题与待改进项 |
| [evaluation.md](evaluation.md) | 项目整体评价 |