Add guide and reference docs pages

Copilot · spacemeowx2 · Copilot · commit f792a0b9e77c · 2026-02-01T05:51:56.000Z
Co-authored-by: spacemeowx2 &lt;8019167+spacemeowx2@users.noreply.github.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,5 @@
 *.dat
 dist/
 node_modules/
+docs/node_modules/
+docs/build/
diff --git a/docs/docs/config/reference.md b/docs/docs/config/reference.md
@@ -0,0 +1,102 @@
+---
+sidebar_position: 3
+---
+
+# 配置参考
+
+本页汇总常用配置块的字段说明，方便在编写配置时快速查阅。更完整的字段说明可以结合 JSON Schema 进行补全。
+
+## net 类型
+
+`net` 中每个节点使用 `type` 字段指定具体实现。常见类型如下：
+
+| 类型 | 说明 | 关键字段 |
+| --- | --- | --- |
+| `shadowsocks` | Shadowsocks 客户端 | `server`, `cipher`, `password`, `udp` |
+| `trojan` | Trojan 客户端 | `server`, `sni`, `password`, `udp` |
+| `http` | HTTP 代理客户端 | `server`, `port`, `username`, `password` |
+| `socks5` | SOCKS5 代理客户端 | `server`, `port`, `username`, `password` |
+| `rule` | 规则路由 | `rule`, `lru_cache_size` |
+| `local` | 本机直连 | 无 |
+
+> 不同 `net` 的字段以 Schema 生成结果为准，建议在编辑器中开启 Schema 补全。
+
+### rule 规则项
+
+`rule` 类型由若干 `rule` 条目组成，每个条目需要声明匹配条件与目标出口。
+
+| 匹配类型 | 字段 | 说明 |
+| --- | --- | --- |
+| `domain` | `method`, `domain` | 域名匹配，`method` 支持 `keyword`/`suffix`/`match` |
+| `ipcidr` | `ipcidr` | 目标 IP 段匹配 |
+| `src_ipcidr` | `ipcidr` | 源 IP 段匹配 |
+| `geoip` | `country` | 国家代码匹配 |
+| `any` | - | 匹配所有流量 |
+
+示例：
+
+```yaml
+net:
+  my_rule:
+    type: rule
+    rule:
+      - type: domain
+        method: suffix
+        domain: example.com
+        target: proxy
+      - type: any
+        target: local
+```
+
+## server 类型
+
+`server` 中每个条目定义本地监听的服务。
+
+| 类型 | 说明 | 关键字段 |
+| --- | --- | --- |
+| `http` | HTTP 代理服务 | `bind`, `net` |
+| `socks5` | SOCKS5 代理服务 | `bind`, `net` |
+| `http+socks5` | 混合模式 | `bind`, `net` |
+
+示例：
+
+```yaml
+server:
+  mixed:
+    type: http+socks5
+    bind: 127.0.0.1:10800
+    net: my_rule
+```
+
+## import 类型
+
+`import` 用于导入外部配置或订阅。
+
+| 类型 | 说明 | 关键字段 |
+| --- | --- | --- |
+| `merge` | 合并本地配置 | `source.path` |
+| `clash` | 导入 Clash 配置 | `source.poll.url`, `source.poll.interval`, `rule_name` |
+
+示例：
+
+```yaml
+import:
+  - type: merge
+    source:
+      path: ./local.yaml
+  - type: clash
+    source:
+      poll:
+        url: https://example.com/subscribe.yaml
+        interval: 86400
+    rule_name: clash_rule
+```
+
+## 常用顶级字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 配置标识（可选） |
+| `net` | 代理节点与链路 |
+| `server` | 本地监听服务 |
+| `import` | 配置导入 |
diff --git a/docs/docs/tutorial/guide.md b/docs/docs/tutorial/guide.md
@@ -0,0 +1,126 @@
+---
+sidebar_position: 4
+---
+
+# 进阶使用指南
+
+本页整理了一套较完整的实践流程，帮助你从「能跑」快速过渡到「稳定可维护」。所有示例都基于 YAML 配置格式。
+
+## 1. 准备配置文件
+
+建议从一个最小配置开始，确认服务可用后再逐步扩展。
+
+```yaml
+net:
+  ss_main:
+    type: shadowsocks
+    server: example.com:1234
+    cipher: aes-256-cfb
+    password: password
+    udp: true
+server:
+  mixed:
+    type: http+socks5
+    bind: 127.0.0.1:10800
+    net: ss_main
+```
+
+## 2. 启动与热重载
+
+默认情况下程序会读取当前目录的 `config.yaml`：
+
+```bash
+./rabbit-digger-pro
+```
+
+配置文件更新后会自动热重载。建议先在日志中确认「已重载」的提示，再进行网络请求测试。
+
+如果配置不在当前目录，可以显式指定：
+
+```bash
+./rabbit-digger-pro -c /path/to/config.yaml
+```
+
+## 3. 组合多个出口
+
+使用 `rule` 类型可以对不同目标走不同出口，下面示例展示域名分流：
+
+```yaml
+net:
+  us:
+    type: trojan
+    server: us.example.com:443
+    sni: us.example.com
+    password: "uspassword"
+    udp: true
+  jp:
+    type: shadowsocks
+    server: jp.example.com:1234
+    cipher: aes-256-cfb
+    password: "jppassword"
+    udp: true
+  my_rule:
+    type: rule
+    rule:
+      - type: domain
+        method: suffix
+        domain: google.com
+        target: jp
+      - type: domain
+        method: keyword
+        domain: twitter
+        target: us
+      - type: any
+        target: local
+server:
+  mixed:
+    type: http+socks5
+    bind: 0.0.0.0:10800
+    net: my_rule
+```
+
+## 4. 订阅与合并配置
+
+如果有 Clash 订阅，可以在 `import` 中拉取并合并：
+
+```yaml
+import:
+  - type: clash
+    poll:
+      url: https://example.com/subscribe.yaml
+      interval: 86400
+    rule_name: clash_rule
+```
+
+将合并后的规则在其他位置直接引用：
+
+```yaml
+server:
+  mixed:
+    type: http+socks5
+    bind: 127.0.0.1:10800
+    net: clash_rule
+```
+
+## 5. 使用 JSON Schema 做配置补全
+
+生成 Schema 文件后可用于编辑器补全：
+
+```bash
+./rabbit-digger-pro generate-schema > rabbit-digger-pro-schema.json
+```
+
+编辑器中引用远程 Schema 也可获得补全（示例）：
+
+```yaml
+# yaml-language-server: $schema=https://rabbit-digger.github.io/schema/rabbit-digger-pro-schema.json
+```
+
+## 6. 常见排查思路
+
+1. **检查日志**：确认配置已成功加载。
+2. **确认端口监听**：例如 `10800` 端口是否已开启。
+3. **逐步缩减配置**：从最小配置排查出问题配置块。
+4. **检查订阅内容**：确认订阅 YAML 可在浏览器打开。
+
+> 更多参数说明与字段参考请查阅「配置参考」页面。
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -69,6 +69,12 @@ const config: Config = {
           position: 'left',
           label: '配置指南',
         },
+        {
+          type: 'doc',
+          docId: 'config/reference',
+          position: 'left',
+          label: '配置参考',
+        },
         {
           href: 'https://github.com/spacemeowx2/rabbit-digger-pro',
           label: 'GitHub',
