feat(tuic): rewrite docs and expand generator to 2.0.0-dev7

Add quick-start, server and client configuration references, and
restructure the TUIC docs navigation. Expand the config generator schema
to cover all effective dev7 sections, add an optional-integer validator
primitive, and update the generator, browser and site tests.

Author: Itsusinn

README.md

@@ -18,7 +18,7 @@ npm ci --prefix config-generator
 npm run dev --prefix config-generator
 ```
 
-打开 `http://127.0.0.1:8080/`。无需启动 Python 或 Zensical。支持配对生成、服务端或客户端单独生成、多用户、三种证书模式、SOCKS5 认证、重连、0-RTT 和 TCP/UDP 转发；“配置详解”可按枚举分支浏览 YAML，并通过悬浮或键盘聚焦查看逐项说明。
+打开 `http://127.0.0.1:8080/`。无需启动 Python 或 Zensical。支持配对生成、服务端或客户端单独生成、多用户、三种证书模式、SOCKS5 认证、日志、连接、TCP/UDP 转发、Quinn/quiche 后端、出站与 ACL 路由、DNS/GeoData、RESTful 管理与 HTTP/3 伪装；“配置详解”可按枚举分支浏览 YAML，并通过悬浮或键盘聚焦查看逐项说明。
 
 安装了 [just](https://just.systems/) 时，可用仓库根目录的快捷命令：
 

config-generator/schema/config.xml

@@ -220,6 +220,7 @@ pub(super) fn validators(node: Option<&Element>) -> Result<BTreeMap<String, Elem
 			"required",
 			"length",
 			"integer",
+			"optional-integer",
 			"host",
 			"socket",
 			"endpoint",

config-generator/src/dsl/metadata.rs

@@ -66,6 +66,9 @@ impl Document {
 				_ => false,
 			},
 			"integer" => !text.is_empty() && text.bytes().all(|b| b.is_ascii_digit()) && text.parse::<u64>().is_ok_and(range),
+			"optional-integer" => {
+				text.is_empty() || (text.bytes().all(|b| b.is_ascii_digit()) && text.parse::<u64>().is_ok_and(range))
+			}
 			"host" => validation::host_rule(&text).is_none(),
 			"socket" => validation::endpoint(&text, true).is_some(),
 			"endpoint" => validation::endpoint(&text, false).is_some(),

config-generator/src/dsl/rules.rs

@@ -36,9 +36,18 @@ fn complete_default_pair() -> Result<(), String> {
 	let expected = json!({
 		"server": {"server":"[::]:8443", "log_level":"info", "users":{u.uuid.clone():u.password},
 			"tls":{"hostname":"tuic.example.com", "alpn":["h3"], "certificate":"/etc/tuic/fullchain.pem", "private_key":"/etc/tuic/privatekey.pem"},
-			"backend":{"mode":"quinn", "quinn":{"congestion_control":{"controller":"bbr"}}}},
-		"client": {"server":"tuic.example.com:8443", "uuid":u.uuid, "password":u.password, "log_level":"info", "reconnect":true, "lazy":true,
-			"reconnect_initial_backoff":"500ms", "reconnect_max_backoff":"30000ms", "tls":{"sni":"tuic.example.com", "alpn":["h3"], "skip_cert_verify":false}, "local":{"server":"127.0.0.1:1080"}}
+			"backend":{"mode":"quinn", "quinn":{"congestion_control":{"controller":"bbr", "initial_window":1048576},
+				"initial_mtu":1200, "min_mtu":1200, "gso":true, "pmtu":true, "send_window":16777216, "receive_window":8388608, "max_idle_time":"30s"}},
+			"auth_timeout":"3s", "stream_timeout":"60s",
+			"outbound":{"default":{"type":"direct", "ip_mode":"v4first", "tfo":false}},
+			"experimental":{"drop_loopback":true, "drop_private":true}},
+		"client": {"server":"tuic.example.com:8443", "uuid":u.uuid, "password":u.password, "log_level":"info",
+			"udp_relay_mode":"native", "heartbeat":"3s", "gc_interval":"3s", "gc_lifetime":"15s",
+			"reconnect":true, "lazy":true,
+			"reconnect_initial_backoff":"500ms", "reconnect_max_backoff":"30000ms",
+			"tls":{"sni":"tuic.example.com", "alpn":["h3"], "skip_cert_verify":false},
+			"backend":{"quinn":{"congestion_control":{"controller":"bbr"}, "send_window":16777216, "receive_window":8388608}},
+			"local":{"server":"127.0.0.1:1080"}}
 	});
 	assert!(build_configs(&s)? == expected);
 	Ok(())
@@ -228,7 +237,7 @@ fn forwarding_arrays_and_conflicts() -> Result<(), String> {
 }
 
 #[test]
-fn controllers_and_unsupported_client_fields() -> Result<(), String> {
+fn controllers_and_wired_client_transport() -> Result<(), String> {
 	for (controller, _) in options("controller") {
 		let mut s = ready()?;
 		s.controller = controller.clone();
@@ -237,9 +246,9 @@ fn controllers_and_unsupported_client_fields() -> Result<(), String> {
 			c["server"]["backend"]["quinn"]["congestion_control"]["controller"],
 			*controller
 		);
-		for key in ["backend", "udp_relay_mode", "proxy"] {
-			assert!(c["client"].get(key).is_none());
-		}
+		assert_eq!(c["client"]["udp_relay_mode"], "native");
+		assert_eq!(c["client"]["backend"]["quinn"]["congestion_control"]["controller"], "bbr");
+		assert!(c["client"].get("proxy").is_none());
 		assert!(c["client"]["tls"].get("certificates").is_none());
 	}
 	Ok(())
@@ -291,3 +300,72 @@ fn form_dsl_binding_and_visibility() -> Result<(), String> {
 	assert!(certificate.is_some_and(|f| !f.visible(&s)));
 	Ok(())
 }
+
+fn outbound_row(id: u64, name: &str, kind: &str) -> serde_json::Value {
+	json!({"id": id, "name": name, "type": kind, "ipMode": "v4first", "bindIpv4": "", "bindIpv6": "",
+		"bindDevice": "", "tfo": false, "routingMarkEnabled": false, "routingMark": "",
+		"socksAddr": "", "socksUsername": "", "socksPassword": "", "allowUdp": false})
+}
+
+#[test]
+fn server_advanced_sections_cover_dev7() -> Result<(), String> {
+	let mut s = ready()?;
+	s.extra.insert("logEnabled".into(), json!(true));
+	s.extra.insert("logFile".into(), json!("/var/log/tuic/server.log"));
+	s.extra.insert("backendMode".into(), json!("quiche"));
+	s.extra.insert("dnsEnabled".into(), json!(true));
+	s.extra.insert("dnsMode".into(), json!("custom"));
+	s.extra.insert(
+		"dnsServers".into(),
+		json!([{"id": 0, "server": "tls://1.1.1.1#cloudflare-dns.com"}]),
+	);
+	s.extra.insert("geodataEnabled".into(), json!(true));
+	s.extra.insert("geosite".into(), json!("/var/lib/tuic/geosite.dat"));
+	s.extra.insert("geoip".into(), json!("/var/lib/tuic/geoip.dat"));
+	s.extra.insert("restfulEnabled".into(), json!(true));
+	s.extra.insert("masqueradeEnabled".into(), json!(true));
+	s.extra.insert(
+		"acls".into(),
+		json!([{"id": 0, "addr": "private", "outbound": "reject", "ports": "", "hijack": ""}]),
+	);
+	s.extra.insert("rules".into(), json!([{"id": 0, "rule": "MATCH,default"}]));
+	s.extra.insert(
+		"outbounds".into(),
+		json!([outbound_row(0, "default", "direct"), outbound_row(1, "proxy", "socks5")]),
+	);
+	s.extra.get_mut("outbounds").expect("outbounds")[1]["socksAddr"] = json!("127.0.0.1:1080");
+	assert!(validate(&s).is_empty());
+	let c = build_configs(&s)?;
+	assert_eq!(c["server"]["log"]["log_file"], "/var/log/tuic/server.log");
+	assert_eq!(c["server"]["backend"]["mode"], "quiche");
+	assert!(c["server"]["backend"].get("quinn").is_none());
+	assert_eq!(c["server"]["backend"]["quiche"]["max_concurrent_bi_streams"], 100);
+	assert_eq!(c["server"]["dns"]["servers"][0], "tls://1.1.1.1#cloudflare-dns.com");
+	assert_eq!(c["server"]["geodata"]["geoip"], "/var/lib/tuic/geoip.dat");
+	assert_eq!(c["server"]["restful"]["enabled"], true);
+	assert_eq!(c["server"]["masquerade"]["enabled"], true);
+	assert_eq!(c["server"]["acl"][0]["addr"], "private");
+	assert_eq!(c["server"]["rules"][0], "MATCH,default");
+	assert_eq!(c["server"]["outbound"]["default"]["type"], "direct");
+	assert_eq!(c["server"]["outbound"]["proxy"]["addr"], "127.0.0.1:1080");
+	assert!(c["server"]["outbound"]["proxy"].get("ip_mode").is_none());
+	Ok(())
+}
+
+#[test]
+fn client_transport_windows_and_0rtt() -> Result<(), String> {
+	let mut s = ready()?;
+	s.extra.insert("udpRelayMode".into(), json!("quic"));
+	s.extra.insert("clientController".into(), json!("cubic"));
+	s.extra.insert("clientSendWindow".into(), json!(4194304));
+	s.extra.insert("clientReceiveWindow".into(), json!(2097152));
+	s.zero_rtt = true;
+	assert!(validate(&s).is_empty());
+	let c = build_configs(&s)?;
+	assert_eq!(c["client"]["udp_relay_mode"], "quic");
+	assert_eq!(c["client"]["zero_rtt_handshake"], true);
+	assert_eq!(c["client"]["backend"]["quinn"]["congestion_control"]["controller"], "cubic");
+	assert_eq!(c["client"]["backend"]["quinn"]["send_window"], 4194304);
+	assert_eq!(c["client"]["backend"]["quinn"]["receive_window"], 2097152);
+	Ok(())
+}

config-generator/tests/generator.rs

@@ -21,6 +21,7 @@ await page.route('**/*', route => route.request().url().startsWith(new URL(base)
 const id = key => page.locator(`[id="cg-${key}"]`);
 const preview = page.locator('#cg-preview-code');
 const click = name => page.getByRole('button', { name, exact: true }).click();
+const section = label => page.locator('summary', { hasText: label });
 async function jsonOutput(side) {
   await click(side === 'server' ? '服务端' : '客户端');
   await id('format').selectOption('json');
@@ -115,7 +116,7 @@ try {
   await click('配对生成');
   console.log('PASS: validation, IPv6 and independent modes');
 
-  await page.locator('summary').click();
+  await section('高级选项').click();
   await id('localAuth').check(); await id('localUsername').fill('tester'); await id('localPassword').fill('a " \\ # 中文');
   await click('＋ 添加转发');
   await id('forwards.0.listen').fill('127.0.0.1:8080'); await id('forwards.0.remote').fill('example.com:80');
@@ -129,11 +130,34 @@ try {
   client = await jsonOutput('client'); assert.equal(client.local.password, undefined); assert.equal(client.local.udp_forward, undefined);
   console.log('PASS: local auth, reconnect, forward editing and removal');
 
+  await section('QUIC 后端').click();
+  await id('backendMode').selectOption('quiche');
+  server = await jsonOutput('server');
+  assert.equal(server.backend.mode, 'quiche');
+  assert.equal(server.backend.quiche.max_concurrent_bi_streams, 100);
+  await id('backendMode').selectOption('quinn');
+  server = await jsonOutput('server');
+  assert.equal(server.backend.quinn.congestion_control.initial_window, 1048576);
+  await section('QUIC 后端').click();
+
+  await section('路由与出站').click();
+  await id('dnsEnabled').check();
+  await id('dnsMode').selectOption('custom');
+  await id('dnsServers.0.server').fill('tls://1.1.1.1#cloudflare-dns.com');
+  server = await jsonOutput('server');
+  assert.equal(server.dns.mode, 'custom');
+  assert.equal(server.dns.servers[0], 'tls://1.1.1.1#cloudflare-dns.com');
+  assert.equal(server.outbound.default.type, 'direct');
+  assert.equal(server.experimental.drop_private, true);
+  await id('dnsEnabled').uncheck();
+  await section('路由与出站').click();
+  console.log('PASS: backend selection, routing, outbound and DNS sections');
+
   const injection = '<img src=x onerror=alert(1)> " \\ 中文';
   await id('users.0.password').fill(injection);
   await id('format').selectOption('yaml'); assert.ok((await preview.textContent()).includes(injection.slice(0, 27)));
   await id('format').selectOption('toml'); assert.equal(await page.locator('#config-generator img').count(), 0);
-  await id('reveal').uncheck(); await page.locator('summary').click();
+  await id('reveal').uncheck(); await section('高级选项').click();
   await page.evaluate(() => window.scrollTo(0, 0));
   await page.screenshot({ path: resolve('.cache/config-generator-desktop.png'), fullPage: true });
   await page.setViewportSize({ width: 390, height: 844 });

tests/config-generator/browser.mjs

@@ -0,0 +1,156 @@
+# 客户端配置
+
+`tuic-client` 读取单个配置文件，字段以 TOML、JSON5 或 YAML 表示。本页列出 2.0.0-dev7 的全部字段、默认值与行为；**未生效字段**单独标注。
+
+## 配置文件与加载 {#format}
+
+- 格式由扩展名推断：`.toml`、`.json`、`.json5`、`.yaml`、`.yml`。
+- `TUIC_FORCE_TOML` 强制按 TOML 解析；`TUIC_CONFIG_FORMAT` 显式指定格式。
+- 命令行只有 `-c`、`--config <PATH>`；未提供时报错退出。
+
+现代布局把连接字段放在顶层，`[tls]`、`[backend.quinn]`、`[local]` 分组。旧的 `[relay]` 表仍被接受并自动迁移（见[旧 `[relay]` 迁移](#migration)），但会输出弃用告警。
+
+## 顶层字段 {#top-level}
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `server` | 字符串 | 必填 | 服务端 `host:port`；IPv6 使用 `[addr]:port`。 |
+| `uuid` | UUID | 全零 | TUIC 用户 UUID。 |
+| `password` | 字符串 | 空 | TUIC 用户密码。 |
+| `ip` | IP | 无 | 显式服务端 IP，绕过域名解析。 |
+| `udp_relay_mode` | 枚举 | `native` | `native` 或 `quic`。 |
+| `zero_rtt_handshake` | 布尔 | `false` | 恢复会话时发送 0-RTT 早期数据。 |
+| `heartbeat` | 时长 | `3s` | 心跳间隔。 |
+| `gc_interval` | 时长 | `3s` | UDP 分片回收间隔。 |
+| `gc_lifetime` | 时长 | `15s` | UDP 分片保留时间。 |
+| `reconnect` | 布尔 | `true` | 断开后自动重连。 |
+| `reconnect_initial_backoff` | 时长 | `500ms` | 首次重连等待。 |
+| `reconnect_max_backoff` | 时长 | `30s` | 退避上限。 |
+| `lazy` | 布尔 | `true` | 按需连接；`false` 为启动即连接，失败时退出。 |
+| `log_level` | 字符串 | `info` | 日志级别。 |
+| `tls` | 表 | 见 [`[tls]`](#tls) | TLS 验证与协商。 |
+| `backend` | 表 | 见 [`[backend.quinn]`](#backend) | QUIC 传输参数。 |
+| `local` | 表 | 见 [`[local]`](#local) | 本地代理与转发。 |
+| `proxy` | 表 | 见[预留字段](#reserved) | 上游 SOCKS5，当前未生效。 |
+| `ipstack_prefer` | 枚举 | `v4first` | 地址族偏好，当前未生效。 |
+| `timeout` | 时长 | `8s` | 连接超时，当前未生效。 |
+
+## `[tls]` {#tls}
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `sni` | 字符串 | 无 | SNI 覆盖；缺省时从 `server` 主机名推导。 |
+| `alpn` | 字符串列表 | `[]` | ALPN 列表；为空时回退到 `h3`。 |
+| `skip_cert_verify` | 布尔 | `false` | 跳过证书链与主机名校验。 |
+| `certificates` | 路径列表 | `[]` | 自定义信任证书，当前未生效。 |
+| `disable_sni` | 布尔 | `false` | 不发送 SNI，当前未生效。 |
+| `disable_native_certs` | 布尔 | `false` | 禁用平台信任库，当前未生效。 |
+
+用 IP 连接时，`server` 的主机名是 IP 字面量，无法作为 SNI。此时应显式设置 `tls.sni` 为证书域名；否则客户端会使用占位 SNI 并告警。
+
+客户端默认使用平台证书验证（`rustls-platform-verifier`）。`tls.certificates` 不会被读取，因此自签名或私有 CA 场景目前只能通过 `skip_cert_verify = true` 绕过（仅限测试）。
+
+!!! warning "ALPN 必须与服务端一致"
+    服务端为空时不声明 ALPN；客户端为空时回退 `h3`。两端都建议显式设置 `alpn = ["h3"]`。
+
+## `[backend.quinn]` {#backend}
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `congestion_control.controller` | 枚举 | `bbr` | `bbr`、`bbr3`、`cubic`、`newreno`。 |
+| `send_window` | 整数 | `16777216` | 未经确认可发送的最大字节数。 |
+| `receive_window` | 整数 | `8388608` | 每条流可接收的最大字节数。 |
+| `initial_mtu` | 整数 | `1200` | 初始 MTU，当前未生效。 |
+| `min_mtu` | 整数 | `1200` | 最小 MTU，当前未生效。 |
+| `gso` | 布尔 | `true` | UDP GSO，当前未生效。 |
+| `pmtu` | 布尔 | `true` | 路径 MTU 发现，当前未生效。 |
+
+客户端 `backend.mode` 仅支持 `quinn`。
+
+## `[local]` {#local}
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `server` | 套接字 | `127.0.0.1:1080` | 本地 SOCKS5 监听地址。 |
+| `username` | 字符串 | 无 | SOCKS5 用户名。 |
+| `password` | 字符串 | 无 | SOCKS5 密码。 |
+| `tcp_forward` | 表数组 | `[]` | 静态 TCP 转发。 |
+| `udp_forward` | 表数组 | `[]` | 静态 UDP 转发。 |
+| `dual_stack` | 布尔 | 无 | 双栈监听，当前未生效。 |
+| `max_packet_size` | 整数 | `1500` | UDP 最大包大小，当前未生效。 |
+
+SOCKS5 认证与 TUIC 用户认证相互独立。改为非回环监听地址时建议启用认证并配置防火墙。
+
+转发项：
+
+```toml
+[[local.tcp_forward]]
+listen = "127.0.0.1:8080"
+remote = "example.com:80"
+
+[[local.udp_forward]]
+listen = "127.0.0.1:5353"
+remote = "8.8.8.8:53"
+timeout = "60s"
+```
+
+`listen` 必须是 `IP:端口`，`remote` 可为域名或 `IP:端口`。服务端默认拦截回环和私有目标地址，见[服务端 `[experimental]`](../server/config.md#experimental)。
+
+## 预留与未生效字段 {#reserved}
+
+以下字段可被解析，但当前版本未接入运行逻辑：
+
+| 字段 | 说明 |
+| --- | --- |
+| `ipstack_prefer` | 地址族偏好。 |
+| `timeout` | 连接超时。 |
+| `proxy.server` / `proxy.username` / `proxy.password` / `proxy.udp_buffer_size` | 通过上游 SOCKS5 建立 QUIC 连接。 |
+| `tls.certificates` | 自定义信任证书。 |
+| `tls.disable_sni` | 抑制 SNI。 |
+| `tls.disable_native_certs` | 禁用平台信任库。 |
+| `backend.quinn.initial_mtu` / `min_mtu` / `gso` / `pmtu` | 传输细节。 |
+| `local.dual_stack` / `max_packet_size` | 本地监听细节。 |
+
+## 旧 `[relay]` 迁移 {#migration}
+
+旧配置把所有连接字段放在 `[relay]` 下。解析时按下列规则迁移，且**现代字段优先**：
+
+| `[relay]` 字段 | 迁移目标 |
+| --- | --- |
+| `certificates`、`alpn`、`disable_sni`、`sni`、`disable_native_certs`、`skip_cert_verify` | `[tls]` |
+| `congestion_control` | `[backend.quinn.congestion_control].controller` |
+| `send_window`、`receive_window`、`initial_mtu`、`min_mtu`、`gso`、`pmtu` | `[backend.quinn]` |
+| 其余（`server`、`uuid`、`password`、`ip`、`udp_relay_mode` 等） | 顶层同名字段 |
+
+迁移会输出弃用告警，建议尽快改写为现代布局。
+
+## 完整示例 {#example}
+
+```toml
+log_level = "info"
+server = "tuic.example.com:8443"
+uuid = "00000000-0000-4000-8000-000000000001"
+password = "change-this-password"
+udp_relay_mode = "native"
+zero_rtt_handshake = false
+heartbeat = "3s"
+reconnect = true
+reconnect_initial_backoff = "500ms"
+reconnect_max_backoff = "30s"
+lazy = true
+
+[tls]
+sni = "tuic.example.com"
+alpn = ["h3"]
+skip_cert_verify = false
+
+[backend.quinn.congestion_control]
+controller = "bbr"
+
+[local]
+server = "127.0.0.1:1080"
+
+[[local.tcp_forward]]
+listen = "127.0.0.1:8080"
+remote = "example.com:80"
+```