Skip to content

Commit 7868586

Browse files
ItsusinnItsusinn
committed
docs(tuic): add server and client pages
Migrate the tuic-server and tuic-client READMEs into the TUIC manual as Simplified Chinese pages, rewritten against the current configuration schema ([backend.quinn], [masquerade], modern client top-level layout) instead of the legacy [quic]/[camouflage]/[relay] forms. Add the pages to the navigation and index, and cross-link them from the getting-started and Docker pages.
1 parent 6766bea commit 7868586

6 files changed

Lines changed: 412 additions & 1 deletion

File tree

‎tuic/docs/client.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# 客户端
2+
3+
`tuic-client` 是 TUIC 协议的客户端实现，提供本地 SOCKS5 服务与 TCP/UDP 端口转发。它保持精简，只包含一个可用 TUIC 客户端所需的核心能力；如需 HTTP 入站、负载均衡等功能，可自行实现或选用其它实现。
4+
5+
本页介绍客户端的安装、启动与配置。服务端请见[服务端](server.md)；最小配置与验证步骤见[快速入门](getting-started.md)；成对的示例配置可在[配置生成器](/config-generator/)本地生成。
6+
7+
## 安装
8+
9+
预编译的二进制文件可在 [GitHub Releases](https://github.com/Itsusinn/tuic/releases) 获取，也可以使用 Cargo 安装：
10+
11+
```console
12+
cargo install --git https://github.com/Itsusinn/tuic.git tuic-client
13+
```
14+
15+
从源码构建需要 Rust `1.85.0` 或更高版本以及 Git，详见[快速入门](getting-started.md)。
16+
17+
## 启动
18+
19+
```console
20+
tuic-client -c /etc/tuic/client.toml
21+
```
22+
23+
默认按需连接（`lazy = true`）：仅在收到第一个代理请求时才建立 QUIC 连接；连接中断后默认自动重连。客户端在 `local.server` 暴露 SOCKS5 服务，将应用指向该地址即可，例如：
24+
25+
```console
26+
curl --socks5-hostname 127.0.0.1:1080 https://example.com
27+
```
28+
29+
## 配置
30+
31+
配置文件格式根据扩展名判断：
32+
33+
- **TOML**：`.toml`（推荐）
34+
- **JSON5**：`.json`、`.json5`（兼容旧配置）
35+
- **YAML**：`.yaml`、`.yml`
36+
37+
扩展名无法识别时客户端会报错退出；可用环境变量 `TUIC_CONFIG_FORMAT`（`toml`、`json`、`json5`、`yaml`、`yml`）显式指定格式。旧的 `[relay]` 段会在解析时自动迁移到顶层连接字段与 `[tls]`，但新配置应使用下文的当前写法。
38+
39+
### 完整示例
40+
41+
```toml
42+
# 日志级别
43+
log_level = "info"
44+
45+
# 服务器地址（主机名:端口或 IP:端口；IPv6 写作 [地址]:端口）
46+
server = "example.com:443"
47+
48+
# 用户 UUID 与密码
49+
uuid = "00000000-0000-4000-8000-000000000001"
50+
password = "change-this-password"
51+
52+
# 可选：出站连接的绑定 IP
53+
# ip = "192.168.1.100"
54+
55+
# IP 栈偏好：v4first, v6first, v4only, v6only
56+
ipstack_prefer = "v4first"
57+
58+
# UDP 中继模式：native 或 quic
59+
udp_relay_mode = "native"
60+
61+
# 启用 0-RTT 握手
62+
zero_rtt_handshake = false
63+
64+
# 连接超时
65+
timeout = "8s"
66+
67+
# 心跳间隔
68+
heartbeat = "3s"
69+
70+
# 垃圾回收间隔与保留时长
71+
gc_interval = "3s"
72+
gc_lifetime = "15s"
73+
74+
# 连接中断后自动重连
75+
reconnect = true
76+
# 首次重连退避；每次失败后翻倍
77+
reconnect_initial_backoff = "500ms"
78+
# 重连退避上限
79+
reconnect_max_backoff = "30s"
80+
81+
# 按需连接：true 为懒加载（默认），false 为启动即连接、失败即退出
82+
lazy = true
83+
84+
[tls]
85+
# 可选：自定义证书路径
86+
# certificates = ["/path/to/cert.pem"]
87+
# ALPN 协议（例如 ["h3"]）
88+
alpn = []
89+
# 禁用 SNI（Server Name Indication）
90+
disable_sni = false
91+
# 可选：覆盖 SNI 主机名
92+
# sni = "custom.example.com"
93+
# 禁用系统原生证书库
94+
disable_native_certs = false
95+
# 跳过证书校验（不安全，仅用于测试）
96+
skip_cert_verify = false
97+
98+
[backend]
99+
# QUIC 后端：quinn
100+
mode = "quinn"
101+
102+
[backend.quinn]
103+
# 拥塞控制：cubic, new_reno, bbr, bbr3
104+
[backend.quinn.congestion_control]
105+
controller = "bbr"
106+
# QUIC 发送窗口（字节）
107+
send_window = 16777216
108+
# QUIC 接收窗口（字节）
109+
receive_window = 8388608
110+
# 初始 MTU
111+
initial_mtu = 1200
112+
# 最小 MTU
113+
min_mtu = 1200
114+
# 启用通用分段卸载（GSO）
115+
gso = true
116+
# 启用路径 MTU 发现
117+
pmtu = true
118+
119+
# 可选：通过上游 SOCKS5/HTTP 代理连接服务器
120+
# [proxy]
121+
# server = "127.0.0.1:1080"
122+
# username = "proxy_user"
123+
# password = "proxy_pass"
124+
# udp_buffer_size = 2048
125+
126+
[local]
127+
# 本地 SOCKS5 服务地址
128+
server = "127.0.0.1:1080"
129+
# 可选：SOCKS5 认证
130+
# username = "socks_user"
131+
# password = "socks_pass"
132+
# 是否启用双栈（IPv4 与 IPv6）
133+
dual_stack = true
134+
# 最大 UDP 包大小
135+
max_packet_size = 1500
136+
137+
# TCP 端口转发
138+
# [[local.tcp_forward]]
139+
# listen = "127.0.0.1:8080"
140+
# remote = "example.com:80"
141+
142+
# UDP 端口转发
143+
# [[local.udp_forward]]
144+
# listen = "127.0.0.1:5353"
145+
# remote = "8.8.8.8:53"
146+
# timeout = "60s"
147+
```
148+
149+
字段级说明与取值范围以[配置生成器](/config-generator/)为准。
150+
151+
### 端口转发
152+
153+
除 SOCKS5 外，客户端还可以把本地端口直接转发到远端目标：
154+
155+
```toml
156+
[local]
157+
server = "127.0.0.1:1080"
158+
159+
[[local.tcp_forward]]
160+
listen = "127.0.0.1:8080"
161+
remote = "example.com:80"
162+
163+
[[local.udp_forward]]
164+
listen = "127.0.0.1:5353"
165+
remote = "8.8.8.8:53"
166+
timeout = "60s"
167+
```
168+
169+
默认情况下，服务端会阻止回环与私有目标；如需访问内网，需在服务端配置路由与访问控制。
170+
171+
## 许可证
172+
173+
本仓库代码依据 [GNU General Public License v3.0 or later](https://github.com/Itsusinn/tuic/blob/main/LICENSE) 发布。欢迎提交 Issue 与 Pull Request。

‎tuic/docs/docker.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Docker 部署
22

3-
本页面介绍如何使用官方镜像运行 `tuic-server`。客户端仍按[快速入门](getting-started.md)在宿主机或其它容器中运行。
3+
本页面介绍如何使用官方镜像运行 `tuic-server`。服务端的完整配置见[服务端](server.md)，客户端仍按[快速入门](getting-started.md)在宿主机或其它容器中运行。
44

55
## 前置条件
66

‎tuic/docs/getting-started.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
本页面提供了让 `tuic-server` 和 `tuic-client` 组合快速投入运行的最简步骤。
44

5+
本页只覆盖最小可用步骤；完整的服务端与客户端配置见[服务端](server.md)与[客户端](client.md)。
6+
57
## 先决条件
68

79
- 客户端可访问的服务器，该服务器需拥有公共 IP 地址或可解析的域名。

‎tuic/docs/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ TUIC 是一个基于 QUIC 传输协议实现的 0-RTT 代理协议。旨在最
1414
## 手册导航
1515

1616
- [快速开始](getting-started.md)：获取程序、最小配置、启动与验证。
17+
- [服务端](server.md)：安装、启动与完整配置、TLS 与 ACME。
18+
- [客户端](client.md)：安装、启动与完整配置、SOCKS5 与端口转发。
1719
- [Docker 部署](docker.md)：使用官方镜像运行服务端。
1820
- [配置生成器](/config-generator/)：在浏览器本地生成服务器与客户端配置。
1921

0 commit comments

Comments
 (0)