# Knot

**Repository Path**: johnroot/knot

## Basic Information

- **Project Name**: Knot
- **Description**: 是一个基于 TUN 设备的简单 VPN 实现，专注于多租户支持、安全加密传输以及 P2P 直连能力。方便的异地组网功能！
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-28
- **Last Updated**: 2025-12-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Knot

`Knot` 是一个基于 TUN 设备的简单 VPN 实现，专注于多租户支持、安全加密传输以及 P2P 直连能力。
## 特性

*   **多租户支持**: 通过 `Cluster` 和 `Identity` 管理不同的客户端组，支持复杂的网络拓扑隔离。
*   **安全加密**: 内置支持 ChaCha20-Poly1305 和 AES-256-GCM 加密算法，保障数据传输安全。
*   **P2P 直连**: 支持 UDP P2P 直连（打洞），在 NAT 环境下尽可能建立直接连接，降低延迟并减轻服务器负载。
*   **跨平台**: 支持 Linux, Windows, macOS (Darwin)。
*   **简单配置**: 客户端和服务端配置简单直观。

## 目录结构

*   `cmd/`: 应用程序入口
    *   `server/`: 服务端主程序
    *   `client/`: 客户端主程序
*   `codec/`: 自定义协议帧编解码实现
*   `crypto/`: 加密算法封装
*   `network/`: 网络连接封装与会话管理
*   `server/`: 服务端核心逻辑（ClientManager, Handler）
*   `client/`: 客户端核心逻辑（Relay, P2P, Tun）
*   `utils/`: 系统级工具（TUN 设备操作, 路由表管理）

## 编译与运行

### 1. 编译

在 `gocode` 目录下执行以下命令：

```bash
# 编译服务端
go build -o server.exe ./cmd/server

# 编译客户端
go build -o client.exe ./cmd/client
```

### 2. 运行服务端

服务端启动需要加载配置文件和客户端列表。

**步骤 1: 准备 `./cfg/config.toml`**

```toml
[server_config]
listen_addr = "0.0.0.0:8080"

[crypto_config]
# ChaCha20-Poly1305 (Recommended)
chacha20poly1305 = "your-secret-key-here"

# Or use AES-256-GCM
# aes256 = "your-secret-key-here"

# Or XOR (lightweight)
# xor = "rustun"

# Or no encryption
# crypto_config = plain

```

**步骤 2: 准备 `./cfg/clients.json`**

```json
[
  {
    "cluster": "default",
    "identity": "client-a",
    "private_ip": "10.0.0.2",
    "mask": "255.255.255.0",
    "gateway": "10.0.0.1",
    "ciders": ["10.0.0.0/24"]
  },
  {
    "cluster": "default",
    "identity": "client-b",
    "private_ip": "10.0.0.3",
    "mask": "255.255.255.0",
    "gateway": "10.0.0.1",
    "ciders": ["10.0.0.0/24"]
  }
]
```
ciders 是客户端的 IP 范围，用于路由表配置。可以指定本地网络中的 IP 范围 

例如:  "ciders": ["10.0.0.0/24","192.168.0.0/24"] 
然后本地网关指向本节点的 IP 即可实现节点网段机器互相访问

**步骤 3: 启动服务端**

```bash
./server.exe
```
或(带管理员页面模式)
```bash
.\server.exe -admin-addr 127.0.0.1:6061 -admin=true
```
*(注：服务端会默认在当前目录查找 `./cfg/clients.json`)*

### 3. 运行客户端

客户端通过命令行参数配置连接信息。

```bash
# 启动客户端 A (开启 P2P)
./client.exe -s <SERVER_IP>:8080 -i client-a -k "chacha20poly1305:your-secret-key-32-bytes-long!!" -p2p

# 启动客户端 B (开启 P2P)
./client.exe -s <SERVER_IP>:8080 -i client-b -k "chacha20poly1305:your-secret-key-32-bytes-long!!" -p2p
```

**参数说明：**
*   `-s`: 服务端地址 (IP:Port)
*   `-i`: 客户端 Identity (必须与 `clients.json` 中定义的一致)
*   `-k`: 加密密钥 (必须与服务端一致)
*   `-p2p`: 启用 P2P 直连功能 (推荐开启)
*   `-v`: 开启详细日志 (Verbose)

## Docker 部署

项目支持服务端和客户端的独立部署，并提供了现成的 Docker 镜像。

### 1. 部署服务端

使用 `docker-compose-server.yml` 部署服务端。

```bash
# 启动服务端
docker-compose -f docker-compose-server.yml up -d
```

**配置文件**:
- 服务端配置文件位于 `./knotcfg/` 目录下（包括 `clients.json` 和其他配置）。
- 容器会自动挂载该目录到 `/app/cfg`。

### 2. 部署客户端

使用 `docker-compose-client.yml` 部署客户端。

**修改配置**:
在启动前，请编辑 `docker-compose-client.yml`，修改环境变量以连接到你的服务端：

```yaml
    environment:
      - RUSTUN_SERVER=127.0.0.1:8080 # 修改为服务端的实际 IP:端口
      - RUSTUN_IDENTITY=client-1     # 修改为 clients.json 中定义的 identity
      - RUSTUN_CRYPTO=chacha20:rustun
      - RUSTUN_P2P=true
```

**启动命令**:
```bash
# 启动客户端
docker-compose -f docker-compose-client.yml up -d
```

### 3. 注意事项

-   **镜像源**: 默认使用阿里云镜像仓库 `registry.cn-hangzhou.aliyuncs.com/johnroot/knotserver:latest` 和 `knotclient:latest`，开箱即用。
-   **客户端权限**: 客户端容器需要操作 TUN 设备和网络栈，因此配置了 `cap_add: [NET_ADMIN]`。
-   **内核模块**: 宿主机（Host）必须加载 `tun` 模块。如果报错 `failed to create TUN device`，请在宿主机执行 `sudo modprobe tun`。
-   **网络连通性**: 由于客户端和服务端通常不在同一个 Docker 网络中（甚至不在同一台机器），请确保 `RUSTUN_SERVER` 填写的是服务端可访问的 IP 地址（公网 IP 或局域网 IP）。

## 协议设计

项目采用自定义的二进制协议帧格式：

`[Magic(1)][Version(1)][Type(1)][PayloadLen(4)][Payload...]`

主要帧类型：
*   **Handshake**: 客户端向服务端发起握手，携带 Identity。
*   **HandshakeReply**: 服务端响应握手，下发私有 IP 配置和路由信息。
*   **KeepAlive**: 心跳包，用于保活和 NAT 映射保持。
*   **Data**: 封装后的 IP 数据包。
*   **PeerUpdate**: 服务端推送的其他 Peer 节点地址信息（用于 P2P）。

## 开发状态

*   [x] 基础网络框架与协议
*   [x] ChaCha20-Poly1305 / AES-256-GCM 加密
*   [x] TUN 设备读写 (Windows/Linux/Darwin)
*   [x] 路由表自动管理
*   [x] 服务端多租户逻辑
*   [x] 客户端 Relay 模式
*   [x] 客户端 P2P 直连模式 (UDP)
*   [ ] 性能优化与压力测试