zishuo/Archive
1
0
Fork 0
mirror of https://github.com/bolucat/Archive.git synced 2026-04-23 00:17:16 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update On Sat Sep 6 20:35:54 CEST 2025

Browse Source
This commit is contained in:
github-action[bot]
2025-09-06 20:35:55 +02:00
parent 20396b5039
commit 93741b781f
164 changed files with 7460 additions and 3057 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nodepass/docs/zh/usage.md
+112 -47
View File
@@ -7,7 +7,7 @@ NodePass创建一个带有未加密TCP控制通道的隧道，并为数据交换
NodePass命令的一般语法是：
```bash
nodepass "<core>://<tunnel_addr>/<target_addr>?log=<level>&tls=<mode>&crt=<cert_file>&key=<key_file>&min=<min_pool>&max=<max_pool>"
nodepass "<core>://<tunnel_addr>/<target_addr>?log=<level>&tls=<mode>&crt=<cert_file>&key=<key_file>&min=<min_pool>&max=<max_pool>&mode=<run_mode>&read=<timeout>&rate=<mbps>&proxy=<mode>"
```
其中：
@@ -19,8 +19,12 @@ nodepass "<core>://<tunnel_addr>/<target_addr>?log=<level>&tls=<mode>&crt=<cert_
通用查询参数：
- `log=<level>`：日志详细级别（`none`、`debug`、`info`、`warn`、`error`或`event`）
- `min=<min_pool>`：最小连接池容量（默认：64，仅适用于client模式）
- `max=<max_pool>`：最大连接池容量（默认：1024，仅适用于client模式）
- `min=<min_pool>`：最小连接池容量（默认：64，由客户端设置）
- `max=<max_pool>`：最大连接池容量（默认：1024，服务端设置并传递给客户端）
- `mode=<run_mode>`：运行模式控制（`0`、`1`或`2`）- 控制操作行为
- `read=<timeout>`：数据读取超时时间（默认：10m，支持时间单位如30s、5m、30m等）
- `rate=<mbps>`：带宽速率限制，单位Mbps（默认：0表示无限制）
- `proxy=<mode>`：PROXY协议支持（默认：`0`，`1`启用PROXY协议v1头部传输）
TLS相关参数（仅适用于server/master模式）：
- `tls=<mode>`：数据通道的TLS安全级别（`0`、`1`或`2`）
@@ -36,7 +40,7 @@ NodePass提供三种互补的运行模式，以适应各种部署场景。
服务端模式建立隧道控制通道，并支持双向数据流转发。
```bash
nodepass "server://<tunnel_addr>/<target_addr>?log=<level>&tls=<mode>&crt=<cert_file>&key=<key_file>"
nodepass "server://<tunnel_addr>/<target_addr>?log=<level>&tls=<mode>&crt=<cert_file>&key=<key_file>&max=<max_pool>&mode=<run_mode>&read=<timeout>&rate=<mbps>&proxy=<mode>"
```
#### 参数
@@ -50,18 +54,31 @@ nodepass "server://<tunnel_addr>/<target_addr>?log=<level>&tls=<mode>&crt=<cert_
- `2`：自定义证书（需要`crt`和`key`参数）
- `crt`：证书文件路径（当`tls=2`时必需）
- `key`：私钥文件路径（当`tls=2`时必需）
- `max`：最大连接池容量（默认：1024）
- `mode`：数据流方向的运行模式控制
- `0`：自动检测（默认）- 首先尝试本地绑定，如果不可用则回退
- `1`：强制反向模式 - 服务器本地绑定目标地址并接收流量
- `2`：强制正向模式 - 服务器连接到远程目标地址
- `read`：数据读取超时时间（默认：10m，支持时间单位如30s、5m、30m等）
- `rate`：带宽速率限制，单位Mbps（默认：0表示无限制）
- `proxy`：PROXY协议支持（默认：`0`，`1`在数据传输前启用PROXY协议v1头部）
#### 服务端模式工作原理
在服务端模式下，NodePass支持两种数据流方向：
服务端模式通过`mode`参数支持自动模式检测或强制模式选择：
**模式一：服务端接收流量**（target_addr为本地地址）
**模式0：自动检测**（默认）
- 首先尝试本地绑定`target_addr`
- 如果成功，以反向模式运行（服务端接收流量）
- 如果绑定失败，以正向模式运行（服务端发送流量）
**模式1：反向模式**（服务端接收流量）
1. 在`tunnel_addr`上监听TCP隧道连接（控制通道）
2. 在`target_addr`上监听传入的TCP和UDP流量
3. 当`target_addr`收到连接时，通过控制通道向客户端发送信号
2. 绑定并在`target_addr`上监听传入的TCP和UDP流量
3. 当`target_addr`收到连接时，通过控制通道向已连接的客户端发送信号
4. 为每个连接创建具有指定TLS加密级别的数据通道
**模式二：服务端发送流量**（target_addr为远程地址）
**模式2：正向模式**（服务端发送流量）
1. 在`tunnel_addr`上监听TCP隧道连接（控制通道）
2. 等待客户端在其本地监听，并通过隧道接收连接
3. 建立到远程`target_addr`的连接并转发数据
@@ -69,14 +86,14 @@ nodepass "server://<tunnel_addr>/<target_addr>?log=<level>&tls=<mode>&crt=<cert_
#### 示例
```bash
# 数据通道无TLS加密 - 服务端接收模式
# 自动模式检测，无TLS加密
nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=0"
# 自签名证书（自动生成） - 服务端发送模式
nodepass "server://10.1.0.1:10101/192.168.1.100:8080?log=debug&tls=1"
# 强制反向模式，自签名证书
nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=1&mode=1"
# 自定义域名证书 - 服务端接收模式
nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem"
# 强制正向模式，自定义证书
nodepass "server://10.1.0.1:10101/192.168.1.100:8080?log=debug&tls=2&mode=2&crt=/path/to/cert.pem&key=/path/to/key.pem"
```
### 客户端模式
@@ -84,7 +101,7 @@ nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=2&crt=/path/to/cer
客户端模式连接到NodePass服务端并支持双向数据流转发。
```bash
nodepass "client://<tunnel_addr>/<target_addr>?log=<level>&min=<min_pool>&max=<max_pool>"
nodepass "client://<tunnel_addr>/<target_addr>?log=<level>&min=<min_pool>&mode=<run_mode>&read=<timeout>&rate=<mbps>&proxy=<mode>"
```
#### 参数
@@ -93,47 +110,62 @@ nodepass "client://<tunnel_addr>/<target_addr>?log=<level>&min=<min_pool>&max=<m
- `target_addr`：业务数据的目标地址，支持双向数据流模式(例如, 127.0.0.1:8080)
- `log`：日志级别(debug, info, warn, error, event)
- `min`：最小连接池容量（默认：64）
- `max`：最大连接池容量（默认：1024）
- `mode`：客户端行为的运行模式控制
- `0`：自动检测（默认）- 首先尝试本地绑定，如果失败则回退到握手模式
- `1`：强制单端转发模式 - 带连接池的本地代理
- `2`：强制双端握手模式 - 需要服务器协调
- `read`：数据读取超时时间（默认：10m，支持时间单位如30s、5m、30m等）
- `rate`：带宽速率限制，单位Mbps（默认：0表示无限制）
- `proxy`：PROXY协议支持（默认：`0`，`1`在数据传输前启用PROXY协议v1头部）
#### 客户端模式工作原理
在客户端模式下，NodePass支持三种操作模式：
客户端模式通过`mode`参数支持自动模式检测或强制模式选择：
**模式一：客户端单端转发**（当隧道地址为本地地址时）
**模式0：自动检测**（默认）
- 首先尝试本地绑定`tunnel_addr`
- 如果成功，以单端转发模式运行
- 如果绑定失败，以双端握手模式运行
**模式1：单端转发模式**
1. 在本地隧道地址上监听TCP和UDP连接
2. 使用连接池技术预建立到目标地址的TCP连接，消除连接延迟
3. 直接将接收到的流量转发到目标地址，实现高性能转发
4. 无需与服务端握手，实现点对点的直接转发
5. 适用于本地代理和简单转发场景
**模式二：客户端接收流量**（当服务端发送流量时）
1. 连接到服务端的TCP隧道端点（控制通道）
2. 在本地监听端口，等待通过隧道传入的连接
3. 建立到本地`target_addr`的连接并转发数据
**模式2：双端握手模式**
- **客户端接收流量**（当服务端发送流量时）
1. 连接到服务端的TCP隧道端点（控制通道）
2. 在本地监听端口，等待通过隧道传入的连接
3. 建立到本地`target_addr`的连接并转发数据
**模式三：客户端发送流量**（当服务端接收流量时）
1. 连接到服务端的TCP隧道端点（控制通道）
2. 通过控制通道监听来自服务端的信号
3. 当收到信号时，使用服务端指定的TLS安全级别建立数据连接
4. 建立到`target_addr`的本地连接并转发流量
- **客户端发送流量**（当服务端接收流量时）
1. 连接到服务端的TCP隧道端点（控制通道）
2. 通过控制通道监听来自服务端的信号
3. 当收到信号时，使用服务端指定的TLS安全级别建立数据连接
4. 建立到`target_addr`的连接并转发流量
#### 示例
```bash
# 客户端单端转发模式 - 本地代理监听1080端口，转发到目标服务器
nodepass client://127.0.0.1:1080/target.example.com:8080?log=debug
# 自动模式检测 - 本地代理监听1080端口，转发到目标服务器
nodepass "client://127.0.0.1:1080/target.example.com:8080?log=debug"
# 连接到NodePass服务端并采用其TLS安全策略 - 客户端发送模式
nodepass client://server.example.com:10101/127.0.0.1:8080
# 强制单端转发模式 - 高性能本地代理
nodepass "client://127.0.0.1:1080/target.example.com:8080?mode=1&log=debug"
# 使用调试日志连接 - 客户端接收模式
nodepass client://server.example.com:10101/192.168.1.100:8080?log=debug
# 强制双端握手模式 - 连接到NodePass服务端并采用其TLS安全策略
nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2"
# 自定义连接池容量 - 高性能配置
nodepass "client://server.example.com:10101/127.0.0.1:8080?min=128&max=4096"
# 使用调试日志和自定义连接池容量连接
nodepass "client://server.example.com:10101/192.168.1.100:8080?log=debug&min=128"
# 强制模式的资源受限配置
nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2&min=16&log=info"
# 资源受限配置 - 小型连接池
nodepass "client://server.example.com:10101/127.0.0.1:8080?min=16&max=512&log=info"
nodepass "client://server.example.com:10101/127.0.0.1:8080?min=16&log=info"
```
### 主控模式 (API)
@@ -168,11 +200,16 @@ nodepass "master://<api_addr>[<prefix>]?log=<level>&tls=<mode>&crt=<cert_file>&k
所有端点都是相对于配置的前缀（默认：`/api`）：
**受保护的端点（需要API Key）：**
- `GET {prefix}/v1/instances` - 列出所有实例
- `POST {prefix}/v1/instances` - 创建新实例，JSON请求体: `{"url": "server://0.0.0.0:10101/0.0.0.0:8080"}`
- `GET {prefix}/v1/instances/{id}` - 获取实例详情
- `PATCH {prefix}/v1/instances/{id}` - 更新实例，JSON请求体: `{"action": "start|stop|restart"}`
- `DELETE {prefix}/v1/instances/{id}` - 删除实例
- `GET {prefix}/v1/events` - 服务端发送事件流（SSE）
- `GET {prefix}/v1/info` - 获取系统信息
**公共端点（无需API Key）：**
- `GET {prefix}/v1/openapi.json` - OpenAPI规范
- `GET {prefix}/v1/docs` - Swagger UI文档
@@ -196,28 +233,53 @@ nodepass "master://0.0.0.0:9090?log=info&tls=2&crt=/path/to/cert.pem&key=/path/t
### 通过API创建和管理
您可以使用标准HTTP请求通过主控API管理NodePass实例：
NodePass主控模式提供RESTful API来管理实例，所有API请求都需要使用API Key进行身份验证。
#### API Key获取
启动主控模式后，系统会自动生成API Key并在日志中显示：
```bash
# 通过API创建和管理实例（使用默认前缀）
# 启动主控模式
nodepass "master://0.0.0.0:9090?log=info"
# 日志输出中会显示：
# INFO: API Key created: abc123def456...
```
#### API请求示例
所有受保护的API端点都需要在请求头中包含`X-API-Key`：
```bash
# 获取API Key (假设为: abc123def456789)
# 通过API创建实例（使用默认前缀）
curl -X POST http://localhost:9090/api/v1/instances \
-H "Content-Type: application/json" \
-H "X-API-Key: abc123def456789" \
-d '{"url":"server://0.0.0.0:10101/0.0.0.0:8080?tls=1"}'
# 使用自定义前缀
curl -X POST http://localhost:9090/admin/v1/instances \
-H "Content-Type: application/json" \
-H "X-API-Key: abc123def456789" \
-d '{"url":"server://0.0.0.0:10101/0.0.0.0:8080?tls=1"}'
# 列出所有运行实例
curl http://localhost:9090/api/v1/instances
curl http://localhost:9090/api/v1/instances \
-H "X-API-Key: abc123def456789"
# 控制实例（用实际实例ID替换{id}）
curl -X PUT http://localhost:9090/api/v1/instances/{id} \
-H "Content-Type: application/json" \
curl -X PATCH http://localhost:9090/api/v1/instances/{id} \
-H "X-API-Key: abc123def456789" \
-d '{"action":"restart"}'
```
#### 公共端点
以下端点不需要API Key身份验证：
- `GET {prefix}/v1/openapi.json` - OpenAPI规范
- `GET {prefix}/v1/docs` - Swagger UI文档
## 双向数据流说明
NodePass支持灵活的双向数据流配置：
@@ -228,12 +290,12 @@ NodePass支持灵活的双向数据流配置：
- **无需服务端**：独立运行，不依赖服务端握手
- **使用场景**：本地代理、简单端口转发、测试环境、高性能转发
### 服务端接收模式 (dataFlow: "-")
### 服务端接收模式
- **服务端**：在target_addr监听传入连接，通过隧道转发到客户端
- **客户端**：连接到本地target_addr提供服务
- **使用场景**：将内网服务暴露给外网访问
### 服务端发送模式 (dataFlow: "+")
### 服务端发送模式
- **服务端**：连接到远程target_addr获取数据，通过隧道发送到客户端
- **客户端**：在本地监听，接收来自服务端的连接
- **使用场景**：通过隧道代理访问远程服务
@@ -270,10 +332,13 @@ NodePass使用隧道密钥来验证客户端和服务端之间的连接。密钥
1. **客户端连接**：客户端连接到服务端的隧道地址
2. **密钥验证**：客户端发送XOR加密的隧道密钥
3. **服务端验证**：服务端解密并验证密钥是否匹配
4. **配置同步**：验证成功后，服务端发送隧道配置信息（包括TLS模式）
4. **配置同步**：验证成功后，服务端发送隧道配置信息，包括：
- 数据流向模式
- 最大连接池容量
- TLS安全模式
5. **连接确立**：握手完成，开始数据传输
这种设计确保了只有拥有正确密钥的客户端才能建立隧道连接。
这种设计确保了只有拥有正确密钥的客户端才能建立隧道连接，同时允许服务端统一管理连接池容量。
## 下一步