@cliz/inlets/README.md

Cloud Native Tunnel

# Inlets

Cloud Native Tunnel - 支持 HTTP 和 TCP 隧道的云原生隧道服务

## 功能特性

- ✅ HTTP & TCP 双隧道支持
- ✅ Token / Credentials / Public 三种认证方式
- ✅ 自动重连、心跳保活
- ✅ 流量统计（按客户端统计）
- ✅ **带宽限制**（全局和客户端级别）
- ✅ 配置文件热重载
- ✅ 通知集成（Webhook）

## 快速开始

### 服务器端

```bash
# 使用配置文件启动
inlets server --domain tunnels.example.com --config /path/to/inlets.yml

# 或使用命令行参数
inlets server --domain tunnels.example.com --token your-token
```

### 客户端

```bash
# HTTP 隧道
inlets http 127.0.0.1:9000 -s myapp -t token

# TCP 隧道
inlets tcp 127.0.0.1:22 -p 20100 --credentials clientId:clientSecret
```

## 配置文件

### 基础配置

创建配置文件 `inlets.yml`：

```yaml
domain: tunnels.example.com
port: 8080
tcpPort: 8443
secure: true
token: your-shared-token
```

### 客户端配置

```yaml
domain: tunnels.example.com

clients:
  - clientId: client-a
    clientSecret: secret-a
  - clientId: client-b
    clientSecret: secret-b
```

### 带宽限制配置

#### 全局带宽限制

为所有客户端设置默认带宽限制：

```yaml
domain: tunnels.example.com
token: your-token

bandwidthLimits:
  global:
    uploadBytesPerSecond: 1048576      # 1 MB/s 上传
    downloadBytesPerSecond: 2097152    # 2 MB/s 下载
```

#### 客户端级带宽限制

为特定客户端设置独立的带宽限制：

```yaml
domain: tunnels.example.com

clients:
  - clientId: premium-client
    clientSecret: premium-secret
    bandwidthLimit:
      uploadBytesPerSecond: 5242880      # 5 MB/s
      downloadBytesPerSecond: 10485760   # 10 MB/s

bandwidthLimits:
  global:
    uploadBytesPerSecond: 1048576        # 默认：1 MB/s
    downloadBytesPerSecond: 2097152      # 默认：2 MB/s
  clients:
    standard-client:
      uploadBytesPerSecond: 2048000      # 2 MB/s
      downloadBytesPerSecond: 4096000    # 4 MB/s
```

**带宽限制规则：**
1. **客户端级别限制**：如果配置了客户端限制，该客户端不能超过自己的限制
2. **全局限制**：如果配置了全局限制，**所有客户端的总带宽不能超过全局限制**
3. **双重限制**：如果同时配置了客户端限制和全局限制，两个限制都需要满足
4. **优先级**：客户端限制 > 全局限制 > 无限制

**带宽单位：**
- 使用字节/秒（bytes per second）
- 1 MB/s = 1048576 字节/秒
- 1 KB/s = 1024 字节/秒

### 完整配置示例

```yaml
domain: tunnels.example.com
port: 8080
tcpPort: 8443
secure: true
token: your-shared-token

clients:
  - clientId: premium-client
    clientSecret: premium-secret
    bandwidthLimit:
      uploadBytesPerSecond: 5242880      # 5 MB/s
      downloadBytesPerSecond: 10485760   # 10 MB/s
  - clientId: standard-client
    clientSecret: standard-secret

bandwidthLimits:
  global:
    uploadBytesPerSecond: 1048576        # 1 MB/s
    downloadBytesPerSecond: 2097152      # 2 MB/s
  clients:
    standard-client:
      uploadBytesPerSecond: 2048000      # 2 MB/s
      downloadBytesPerSecond: 4096000    # 4 MB/s

notification:
  provider: webhook
  url: https://hooks.example.com/inlets
  interval: 60000
```

## 配置说明

### 服务器配置项

| 配置项 | 说明 | 默认值 |
| --- | --- | --- |
| `domain` | 服务器域名（必填） | - |
| `port` | HTTP 服务端口 | `8080` |
| `tcpPort` | TCP 服务端口 | `8443` |
| `secure` | 是否使用 HTTPS | `false` |
| `token` | 共享 token（token 认证模式） | - |
| `clients` | 客户端列表（credentials 认证模式） | - |
| `bandwidthLimits` | 带宽限制配置 | - |
| `notification` | 通知配置 | - |

### 带宽限制配置项

| 配置项 | 说明 | 单位 |
| --- | --- | --- |
| `uploadBytesPerSecond` | 上行带宽限制 | 字节/秒 |
| `downloadBytesPerSecond` | 下行带宽限制 | 字节/秒 |

### 客户端配置项

| 配置项 | 说明 |
| --- | --- |
| `clientId` | 客户端 ID（必填） |
| `clientSecret` | 客户端密钥（必填） |
| `bandwidthLimit` | 客户端带宽限制（可选） |
| `config` | 客户端特定配置（可选） |

## 配置文件热重载

服务器支持配置文件热重载。当配置文件发生变化时，服务器会自动重新加载配置，包括：

- 客户端列表
- 带宽限制设置
- 通知配置

**注意：** 带宽限制的更改会在新的连接上生效，现有连接会继续使用旧的限制直到断开。

## 带宽限制实现

- **算法**：使用令牌桶算法实现平滑的带宽限制
- **检查时机**：在数据发送/接收时实时检查
- **超限处理**：超过限制的数据会被延迟或丢弃
- **性能影响**：带宽限制会增加少量 CPU 开销，通常可以忽略不计

## 更多文档

- [配置文件示例](./CONFIG_EXAMPLE.md) - 详细的配置示例和说明
- [Go 客户端文档](./go/README.md) - Go 客户端的使用说明

## 许可证

MIT