# tiger

**Repository Path**: zfd81/tiger

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-26
- **Last Updated**: 2025-11-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tiger 代理服务使用手册

## 产品概述

Tiger 是一个高性能的 API 网关和代理服务，支持 HTTP、HTTPS、WebSocket (WS) 和 WebSocket Secure (WSS) 协议的代理转发。服务内置了 JWT token 认证机制，提供安全的访问控制和灵活的配置选项。

### 核心功能

- ✅ **多协议支持**: HTTP/HTTPS/WS/WSS 代理转发
- ✅ **JWT Token 认证**: 基于 JWT 的安全认证机制
- ✅ **静态文件服务**: 支持静态文件目录代理
- ✅ **TLS/SSL 支持**: 支持双向 SSL 认证
- ✅ **WebSocket 代理**: 完整的 WebSocket 双向代理
- ✅ **健康检查**: 内置健康检查端点

## 快速开始

### 服务启动

1. **初始化配置**（首次使用）:

```bash
./tiger init
```

2. **启动服务**:

```bash
./tiger start

# 指定端口启动
./tiger start -p 9090
```

3. **验证服务状态**:

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

## 配置文件说明

Tiger 使用 TOML 格式的配置文件 (`conf.toml`)，主要包含以下配置项：

### 基础配置

```toml
# 服务监听端口
port = 8080

# TLS/SSL 配置
[tls]
enabled = false
cert = "./ssl_key/default.crt"
key = "./ssl_key/default.key"
ca = "./ssl_key/default.ca"

# Token 提供者配置
[token_provider]
path = "/token"
signing_secret = "tiger_auth_signing_secret"
ttl = 60  # Token 有效期（分钟）

# 用户配置
[[users]]
name = "admin"
password = "123456"

[[users]]
name = "user1"
password = "password1"
```

### 路由配置

路由配置支持多种代理类型，系统会根据 `proxy_pass` 字段自动识别协议类型：

```toml
# HTTP/HTTPS 代理配置
[[routes]]
path = "/api"
proxy_pass = "http://localhost:8081"
skip_auth = false  # 是否跳过认证（默认false，需要认证）

# WebSocket Secure (WSS) 代理配置
[[routes]]
path = "/asr"
proxy_pass = "wss://localhost:8082"
skip_auth = false
max_connections = 10          # 最大连接数限制
client_cert_file = "asr.crt"   # 客户端证书文件（仅WSS需要）
client_key_file = "asr.key"    # 客户端密钥文件（仅WSS需要）
ca_file = "asr.ca"            # CA证书文件（仅WSS需要）

# WebSocket (WS) 代理配置
[[routes]]
path = "/ws"
proxy_pass = "ws://localhost:8083"
skip_auth = false
max_connections = 100         # 最大连接数限制

# 静态文件服务配置
[[routes]]
path = "/static"
proxy_pass = "./public"      # 本地文件目录路径
skip_auth = true             # 静态文件通常跳过认证
```

### 日志配置

```toml
[log]
level = "INFO"
path = "./"
rotation_time = 24     # 日志轮换间隔（小时）
retention_time = 168   # 日志保留时间（小时）
```

### 配置说明

#### 基本配置

- **端口配置**: 服务监听的端口号，默认 8080
- **TLS 配置**: 启用 HTTPS/WSS 服务所需的证书配置
- **用户管理**: 定义可访问服务的用户账户

#### 路由配置说明

路由配置支持多种代理类型，系统会根据 `proxy_pass` 字段自动识别协议类型：

- **HTTP/HTTPS 代理**: 当 `proxy_pass` 以 `http://` 或 `https://` 开头时

  - 支持认证中间件，可配置 `skip_auth`
  - 无需额外 TLS 配置

- **WebSocket Secure (WSS) 代理**: 当 `proxy_pass` 以 `wss://` 开头时

  - 支持双向 SSL 认证
  - 需要配置客户端证书相关文件
  - 可设置最大连接数限制

- **WebSocket (WS) 代理**: 当 `proxy_pass` 以 `ws://` 开头时

  - 支持 WebSocket 双向代理
  - 可设置最大连接数限制
  - 无需 TLS 配置

- **静态文件服务**: 当 `proxy_pass` 指向本地文件目录时
  - 直接提供本地文件服务
  - 通常设置 `skip_auth = true` 跳过认证

#### 日志配置

- **日志级别**: 支持 INFO、DEBUG、WARN、ERROR 等级别
- **日志路径**: 日志文件存储目录
- **轮换策略**: 日志文件轮换和保留时间设置

## 命令行工具使用

Tiger 提供了丰富的命令行工具来管理服务：

### 查看版本

```bash
./tiger version
```

### 初始化配置

```bash
# 生成默认配置文件
./tiger init
```

### 生成 Token

```bash
# 为指定用户生成带有效期的 token
./tiger sign <username> <ttl>

# TTL 格式说明：
# m (分钟), h (小时), d (天), M (月), y (年)
# 示例：
./tiger sign admin 30m    # 30分钟有效期
./tiger sign user1 1h     # 1小时有效期  
./tiger sign user2 2d     # 2天有效期
./tiger sign admin 3M     # 3个月有效期
./tiger sign user1 1y     # 1年有效期

# 如果只写单位，默认值为1
./tiger sign admin m      # 1分钟有效期
./tiger sign user1 h      # 1小时有效期
./tiger sign user2 d      # 1天有效期

# 如果没有指定单位后缀，默认使用分钟
./tiger sign admin 60     # 60分钟有效期
```

### 启动服务

```bash
# 使用默认配置启动
./tiger start

# 指定端口启动
./tiger start -p 9090
```

## API 使用示例

### 1. 获取访问 Token

**请求**:

```bash
curl -X POST http://localhost:8080/token \
  -H "T-User-Name: admin" \
  -H "T-User-Password: 123456"
```

**响应**:

```json
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### 2. HTTP 代理请求

**请求**:

```bash
curl -X GET http://localhost:8080/api/users \
  -H "Authorization: Bearer <your_token>"
```

### 3. WebSocket 连接

**JavaScript 示例**:

```javascript
const ws = new WebSocket("ws://localhost:8080/ws");
ws.onopen = function () {
  console.log("WebSocket connected");
  // 发送认证信息
  ws.send(
    JSON.stringify({
      token: "<your_token>",
    })
  );
};
```

### 4. 健康检查

**请求**:

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

**响应**:

```json
{
  "status": "healthy",
  "timestamp": 1698765432
}
```

## 安全认证机制

### Token 认证流程

1. **获取 Token**: 用户通过用户名密码获取 JWT token
2. **API 调用**: 在请求头中包含 `Authorization: Bearer <token>`
3. **Token 验证**: 服务验证 token 的有效性和用户权限
4. **请求转发**: 验证通过后转发请求到目标服务

### Token 有效期配置

Tiger 支持灵活的 token 有效期配置，支持多种时间单位：

- **分钟 (m)**: 如 `30m` 表示 30 分钟有效期
- **小时 (h)**: 如 `1h` 表示 1 小时有效期
- **天 (d)**: 如 `2d` 表示 2 天有效期
- **月 (M)**: 如 `3M` 表示 3 个月有效期（按 30 天计算）
- **年 (y)**: 如 `1y` 表示 1 年有效期（按 365 天计算）

**注意**: 如果没有指定单位后缀，默认使用分钟为单位

### 安全最佳实践

1. **定期更换签名密钥**: 定期更新 `signing_secret`
2. **使用 HTTPS**: 生产环境启用 TLS
3. **限制 token 有效期**: 避免使用永久 token
4. **监控日志**: 定期检查访问日志

## 高级配置

### WebSocket 代理配置

WebSocket 代理支持以下高级配置：

- **连接超时**: 默认 60 秒握手超时
- **最大连接数**: 限制并发 WebSocket 连接数
- **双向消息转发**: 完整的双向消息代理
- **连接统计**: 实时连接和消息统计

### 静态文件服务

静态文件服务支持：

- **自动索引**: 支持 index.html 等默认文件
- **路径重写**: 灵活的 URL 路径映射
- **MIME 类型**: 自动识别文件类型
- **目录列表**: 可配置是否显示目录列表

### 日志配置

日志系统提供：

- **多级别日志**: DEBUG, INFO, WARN, ERROR
- **文件轮换**: 自动日志文件轮换
- **保留策略**: 可配置日志保留时间
- **详细追踪**: 请求 ID 和性能指标

## 故障排除

### 常见问题

1. **端口被占用**: 检查端口是否被其他进程占用
2. **证书错误**: 确保证书文件路径正确且格式有效
3. **权限问题**: 检查文件读写权限
4. **连接超时**: 检查目标服务是否可访问

### 日志分析

日志文件位于配置的日志路径下，命名格式：`tiger_<port>.log`

关键日志信息：

- 服务启动状态
- 请求处理详情
- 错误和异常信息
- 性能统计信息

## 性能优化

### 连接池优化

Tiger 使用优化的 HTTP 连接池：

- 最大空闲连接数: 100
- 每主机最大空闲连接数: 10
- 空闲连接超时: 90 秒
- 请求超时: 60 秒

### WebSocket 性能

WebSocket 代理经过优化：

- 异步消息转发
- 连接数限制
- 内存高效的消息处理
- 详细的性能监控

## 部署建议

### 开发环境

- 使用默认配置快速启动
- 启用 DEBUG 级别日志便于调试
- 使用自签名证书测试 TLS 功能

### 生产环境

- 配置合适的 TLS 证书
- 设置合理的日志轮换策略
- 监控服务性能和资源使用
- 定期备份配置文件

## 技术支持

如有问题或建议，请参考项目文档或联系开发团队。

---

_最后更新: 2024 年_