Skip to content

doc: 添加拦截器配置说明 #491

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

doc: 添加拦截器配置说明 #491

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
04decbe
doc: 添加拦截器配置说明
May 16, 2025
8a72228
尝试ipv6支持
May 22, 2025
a19a738
支持ipv6查询
Jun 13, 2025
6d18a3b
支持IP预设使用CNAME，同时修正了来源显示错误的问题
Jun 13, 2025
076795d
Merge branch 'master' into master
Jun 14, 2025
97e106d
update
Jun 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 121 additions & 127 deletions doc/wiki/加速服务使用说明.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,179 +1,173 @@
# 1. 加速服务:
1. 什么是 `加速服务`？
`加速服务` 即 `代理服务`，它通过中间人攻击的方式，将网络请求拦截下来，并经过DNS加速、篡改、重定向、代理等一系列的功能，达到加速访问、或访问原本无法访问的站点等目的。

1. 什么是 `加速服务`？

- `加速服务` 即 `代理服务`，它通过中间人攻击的方式，将网络请求拦截下来，并经过DNS加速、修改、重定向、代理等一系列的功能，达到加速访问、或访问原本无法访问的站点等目的。<br>
2. 如何启动加速服务：<br>
- 点击首页的【代理服务】右侧的开关按钮，即可启动/关闭加速服务。<br>
- 点击首页的【系统代理】右侧的开关按钮，即可将dev-sidecar设置/不设置为系统默认代理。（系统只能有一个默认代理，在将dev-sidecar与其他网络辅助软件共用时请谨慎开启本开关）<br>
- 点击首页的【NPM加速】和【Git.exe代理】右侧的开关按钮，即可启动/关闭dev-sidecar为对应软件提供的加速服务。如果你的电脑上并未安装NPM或Git，则这两个按钮将不可用，这是正常情况。

2. 启动加速服务：点击首页的 `代理服务` 右侧的开关按钮，即可启动加速服务。

# 2. 根证书使用说明：

1. 什么是根证书：TODO
2. [为什么需要安装根证书这么高风险性的步骤](https://github.com/docmirror/dev-sidecar/blob/master/doc/caroot.md)
3. 如何安装根证书：参见dev-sidecar【首页】的【安装根证书】按钮（注意Firefox浏览器还需要一次手动导入根证书）
1. 什么是根证书？
2. [为什么需要安装根证书这么高风险性的步骤](https://github.com/docmirror/dev-sidecar/blob/master/doc/caroot.md)
3. 如何安装根证书：

# 3. 模式：

1. 安全模式：TODO
2. 默认模式：TODO
3. 增强模式（彩蛋）：TODO
1. 安全模式：
2. 默认模式：
3. 增强模式（彩蛋）：

# 4. 拦截功能使用和配置说明：

## 4.1. 拦截器类型：

### 1）请求拦截器：
| 请求拦截器名称 | 拦截器配置名 | 请求拦截优先级 | 作用 |
| ----------------- | -------------- | ------------- | --------- |
| OPTIONS请求拦截器 | options | 101 | 直接响应200，不发送该OPTIONS请求 |
| 快速成功拦截器 | success | 102 | 直接响应200，不发送该请求 |
| 快速失败拦截器 | abort | 103 | 直接响应403，不发送该请求 |
| 缓存请求拦截器 | cacheXxx | 104 | 如果缓存还生效，直接响应304，不发送该请求<br>如果缓存已过期或无缓存，则发送请求<br>注：只对GET请求生效！ |
| 重定向拦截器 | redirect | 105 | 重定向到指定地址，直接响应302，不发送该请求 |
| 请求篡改拦截器 | requestReplace | 111 | 篡改请求头，达到想要的目的 |
| 代理拦截器 | proxy | 121 | 将请求转发到指定地址 |
| SNI拦截器 | sni | 122 | 设置 `servername`，用于避开GFW |

### 2）响应拦截器：
| 响应拦截器名称 | 拦截器配置名 | 响应拦截优先级 | 作用 |
| ---------------- | --------------- | ------------- | --------- |
| OPTIONS响应拦截器 | options | 201 | 设置跨域所需的响应头，避免被浏览器的跨域策略阻拦 |
| 缓存响应拦截器 | cacheXxx | 202 | 设置缓存所需的响应头，使浏览器缓存当前请求<br>注：只对GET请求生效！ |
| 响应篡改拦截器 | responseReplace | 203 | 篡改响应头，避免被浏览器的安全策略阻拦 |
| 脚本拦截器 | script | 211 | 注入JavaScript脚本到页面中，如：Github油猴脚本 |

## 4.2. 拦截配置说明书：

TODO：内容待完善
1. 请求拦截器：
| 请求拦截器名称 | 拦截器配置名 | 请求拦截优先级 | 快速响应码 |
| ----------------- | -------------- | ------------- | --------- |
| OPTIONS请求拦截器 | options | 101 | 200 |
| 快速成功拦截器 | success | 102 | 200 |
| 快速失败拦截器 | abort | 103 | 403 |
| 缓存请求拦截器 | cacheXxx | 104 | 304 |
| 重定向拦截器 | redirect | 105 | 302 |
| 请求篡改拦截器 | requestReplace | 111 | |
| 代理拦截器 | proxy | 121 | |
| SNI拦截器 | sni | 122 | |

2. 响应拦截器：
| 响应拦截器名称 | 拦截器配置名 | 响应拦截优先级 |
| ---------------- | --------------- | ------------- |
| OPTIONS响应拦截器 | options | 201 |
| 缓存响应拦截器 | cacheXxx | 202 |
| 响应篡改拦截器 | responseReplace | 203 |
| 脚本拦截器 | script | 211 |

# 5. 域名白名单：

选择哪些域名不会被dev-sidecar处理。

**注意：** 该设置与【系统代理-自定义排除域名】的区别在于：

1. 前者只是被dev-sidecar自身忽略，后者则是写入系统设置、不会被（任何的）系统代理处理，在手动修改系统代理设置时务必小心后者可能残留的作用！
2. 在条目较多时，前者的性能不如后者，可能产生明显延迟。<br>

在config.json的 `proxy.excludeIpList:object` 中设置，**该字段**格式如下：<br>
> 注意：这里点号用来作为JSON object嵌套关系的缩写，冒号指明该条目的类型（主要用来区分object和list），并没有哪一个Object的key为 `proxy.excludeIpList`。为避免歧义，配置中object和list的key总不应包含点号。下同）
# 6. DNS服务管理：

## 6.1. 配置 `DNS-over-HTTPS` 的DNS服务：
```json
{
"proxy": {
"excludeIpList": {
"example1.com": true,
"example2.com": false,
"example3.com": null,
"example4.com": {
"desc1": "域名对应字段设置为false时会被处理，null会移除现有设置（多用于远程配置）",
"desc2": "其他情况下就和设置true一样，不会被处理。因而你可以像这样插入注释",
"desc3": "同样的技巧可以用在其他本应设置一个bool值的地方",
"desc4": "原则上来说config.json不支持//形式的注释，但下文为了方便阅读，还是这么写了"
}
}
"cloudflare": {
"type": "https",
"server": "https://1.1.1.1/dns-query",
"cacheSize": 1000
}
}
```
或
```json
{
"cloudflare": {
"server": "https://1.1.1.1/dns-query", // 地址上带有 `https://`，type可以不配置
"cacheSize": 1000
}
}
```

# 6. DNS服务管理：

用来配置在dev-sidecar中需要的指定DNS，出于保密和可靠起见建议使用DoH和DoT。<br>
在 `server.dns.provider:object` 中设置，**其中的每个条目** 格式如下：

## 6.1. 配置 `DNS-over-HTTPS`（简称DoH）：
> 注：并非被所有DNS支持，但是保证只要能使用就一定匿名且可靠的DNS服务。
## 6.2. 配置 `DNS-over-TLS` 的DNS服务：

```json
"cloudflare": {
"type": "https", // 如果server上以"https://"开头指明了协议，就不需要写type了
"server": "https://1.1.1.1/dns-query",
"cacheSize": 1000
{
"cloudflareTLS": {
"type": "tls",
"server": "1.1.1.1",
"port": 853, // 不配置时，默认端口为：853
"servername": "cloudflare-dns.com", // SNI
"cacheSize": 1000
}
}
```
或

## 6.2. 配置 `DNS-over-TLS`（简称DoT）：
> 并非被所有DNS支持，但是保证只要能使用就一定匿名且可靠的DNS服务。
```json
{
"cloudflareTLS": {
"server": "tls://1.1.1.1",
"port": 853, // 不配置时，默认端口为：853
"servername": "cloudflare-dns.com", // SNI
//"sni": "cloudflare-dns.com", // SNI缩写配置
"cacheSize": 1000
}
}
```
或

```json
"cloudflareTLS": {
"type": "tls", // 如果server上以"tls://"开头指明了协议，就不需要写type了
"server": "1.1.1.1",
"port": 853, // 不配置时，默认端口为：853
"servername": "cloudflare-dns.com", // 需要伪造成的SNI
//"sni": "cloudflare-dns.com", // SNI缩写配置
"cacheSize": 1000
{
"cloudflareTLS": {
"server": "tls://1.1.1.1:853",
"servername": "cloudflare-dns.com", // SNI
//"sni": "cloudflare-dns.com", // SNI缩写配置
"cacheSize": 1000
}
}
```

## 6.3. 配置 `TCP` 的DNS服务：
> 并非被所有DNS支持，该方法既不保密也不可靠

```json
"googleTCP": {
"type": "tcp", // 如果server上以"tcp://"开头指明了协议，就不需要写type了
"server": "8.8.8.8",
"port": 53, // 不配置时，默认端口为：53
"cacheSize": 1000
{
"googleTCP": {
"type": "tcp",
"server": "8.8.8.8",
"port": 53, // 不配置时，默认端口为：53
"cacheSize": 1000,
}
}
```

## 6.4. 配置 `UDP` 的DNS服务：
> 所有DNS服务器均支持UDP方式，但该方法既不保密也不可靠
或

```json
"google": {
"type": "udp", // 如果server上以"udp://"开头指明了协议，就不需要写type了
"server": "8.8.8.8",
"port": 53, // 不配置时，默认端口为：53
"cacheSize": 1000
{
"googleTCP": {
"server": "tcp://8.8.8.8",
"port": 53, // 不配置时，默认端口为：53
"cacheSize": 1000,
}
}
```

# 7. DNS设置：

选择哪些域名需要使用指定的DNS（需要先在【DNS服务管理】中设置）获取IP。<br>
在config.json中的 `server.dns.mapping:key-value` 中设置，**其中的每个条目**格式如下：
或

```json
"*.example.com": "your-dns-name"
{
"googleTCP": {
"server": "tcp://8.8.8.8:53",
"cacheSize": 1000,
}
}
```

# 8. IP预设置：

为一些DNS无法获取的域名手动设置ip，起到类似于hosts的作用（仅在dev-sidecar开启时生效）。<br>
在config.json中的 `server.preSetIpList:object` 中设置，**其中的每个条目**格式如下：
## 6.4. 配置 `UDP` 的DNS服务：

```json
{
"example.com": {
"1.1.1.1": true, // 如果有多个IP，可以继续添加
"1.0.0.1": false, // 指定为false时，不使用该IP
"2.2.2.2": {
"desc": "这样可以合法的在配置中插入注释。上面使用的//注释方式在文件中是不允许的"
}
"google": {
"type": "udp",
"server": "8.8.8.8",
"port": 53, // 不配置时，默认端口为：53
"cacheSize": 1000,
}
}
```
或

# 9. IP测速：

用来对从指定的DNS与IP预设置中获取到的IP测试TCP延迟，也可以用来测试DoH和DoT服务器的可用性，后者操作如下：先在【DNS服务管理】中配置好需要测试的DNS设置，然后在【IP测速】里添加一个没有设置【IP预设置】的辅助域名，并选择使用需检测的DNS进行解析。<br>
对于DoH/DoT而言，由于答案不能被篡改和窃听，所以辅助域名要么获得真实IP（说明可用）要么没有收到答案（说明不可用）。该方法不适用于常规TCP/UDP的DNS，因为它们没有加密，即使收到答案也可能被篡改而不可用）。<br>
在config.json中的 `server.dns.speedTest:object`中设置，**该条目** 格式如下：
```json
{
"google": {
"server": "udp://8.8.8.8",
"port": 53, // 不配置时，默认端口为：53
"cacheSize": 1000,
}
}
```
或

```json
"speedTest": {
"hostnameList": [
"example1.com",
"example2.com"
],
"dnsProviders": [
"your-DNS-name-used-in-test1",
"your-DNS-name-used-in-test2"
]
{
"google": {
"server": "udp://8.8.8.8:53",
"cacheSize": 1000,
}
}
```

# 7. DNS设置：

# 8. IP预设置：

# 9. IP测速：
Loading