dev-sidecar Documentation

File: README.md Copy Chapter

dev-sidecar

开发者边车，命名取自service-mesh的service-sidecar，意为为开发者打辅助的边车工具（以下简称ds）
通过本地代理的方式将https请求代理到一些国内的加速通道上

Gitee上的同步项目已被封禁，请认准本项目唯一官方仓库地址https://github.com/docmirror/dev-sidecar 【狗头保命】

我将继续奋战在开源一线，为社区贡献更多更好的开源项目。

感兴趣的可以关注我的主页 【github】 【gitee】

打个广告 Copy Chapter

https://github.com/certd/certd

我的开源证书管理工具项目，全自动申请和部署证书，有需求的可以去试试，帮忙点个star

重要提醒 Copy Chapter

------------------------------重要提醒1---------------------------------

注意：由于electron无法监听windows的关机事件，开着ds情况下直接重启电脑，会导致无法上网，你可以手动启动ds即可恢复网络，你也可以将ds设置为开机自启。

关于此问题的更多讨论请前往：https://github.com/docmirror/dev-sidecar/issues/109

注：此问题已在 1.8.9 版本中得到解决。

------------------------------重要提醒2---------------------------------

注意：本应用启动会自动修改系统代理，所以会与其他代理软件有冲突，一起使用时请谨慎使用。

与 Watt Toolkit（原Steam++） 共用时，请以hosts模式启动Watt Toolkit

与 TUN网卡模式运行的游戏加速器 可以共用

本应用主要目的在于直连访问github，如果你已经有飞机了，那建议还是不要用这个自行车（ds）了

一、 特性 Copy Chapter

1.1、 dns优选（解决\*\*\*污染问题） Copy Section

• 根据网络状况智能解析最佳域名ip地址，获取最佳网络速度
• 解决一些网站和库无法访问或访问速度慢的问题
• 建议遇到打开比较慢的国外网站，可以优先尝试将该域名添加到dns设置中（注意：被***封杀的无效）

1.2、 请求拦截 Copy Section

• 拦截打不开的网站，代理到加速镜像站点上去。
• 可配置多个镜像站作为备份
• 具备测速机制，当访问失败或超时之后，自动切换到备用站点，使得目标服务高可用

1.3、 github加速 Copy Section

• github 直连加速 (通过修改sni实现，感谢 fastGithub 提供的思路)
• release、source、zip下载加速
• clone 加速
• 头像加速
• 解决readme中图片引用无法加载的问题
• gist.github.com 加速
• 解决git push 偶尔失败需要输入账号密码的问题（fatal: TaskCanceledException encountered / fatal: HttpRequestException encountered）
• raw/blame加速

以上部分功能通过 X.I.U 的油猴脚本实现， 以下是仓库和脚本下载链接，大家可以去支持一下。

• https://github.com/XIU2/UserScript
• https://greasyfork.org/scripts/412245

由于此脚本在ds中是打包在本地的，更新会不及时，你可以直接通过浏览器安装油猴插件使用此脚本，从而获得最新更新（ds本地的可以通过 加速服务->基本设置->启用脚本 进行关闭）。

1.4、 Stack Overflow 加速 Copy Section

• 将ajax.google.com代理到加速CDN上
• recaptcha 图片验证码加速

1.5、 npm加速 Copy Section

• 支持开启npm代理
• 官方与淘宝npm registry一键切换
• 某些npm install的时候，并且使用cnpm也无法安装时，可以尝试开启npm代理再试

安全警告：

• 请勿使用来源不明的服务/远程配置地址，有隐私和账号泄露风险
• 本应用及服务/默认远程配置端承诺不收集任何信息。介意者请使用安全模式。

二、快速开始 Copy Chapter

支持windows、Mac、Linux(Ubuntu)

2.1、DevSidecar桌面应用 Copy Section

1）下载安装包

• release下载
  Github Release

Windows: 请选择DevSidecar-x.x.x-windows-universal.exe

Mac: 请选择DevSidecar-x.x.x-macos-universal.dmg

Debian系及其他支持deb安装包的Linux: 请选择DevSidecar-x.x.x-linux-[架构].deb

其他Linux: 请选择DevSidecar-x.x.x-linux-[架构].AppImage (未做测试，不保证能用)

linux安装说明请参考 linux安装文档

注意：由于没有买应用证书，所以应用在下载安装时会有“未知发行者”等安全提示，选择保留即可。

2）安装后打开

界面应大致如下图所示：

注意：mac版安装需要在“系统偏好设置->安全性与隐私->通用”中解锁并允许应用安装

3）安装根证书

第一次打开会提示安装证书，根据提示操作即可

更多有关根证书的说明，请参考 为什么要安装根证书?

根证书是本地随机生成的，所以不用担心根证书的安全问题（本应用不收集任何用户信息）

你也可以在加速服务设置中自定义根证书（PEM格式的证书与私钥）

火狐浏览器需要手动安装证书

4）开始加速吧

去试试打开github、huggingface、docker hub吧

2.2、开启前 vs 开启后 Copy Section

三、模式说明 Copy Chapter

3.1、安全模式 Copy Section

• 此模式：关闭拦截、关闭增强、不使用远程配置、开启dns优选、开启测速
• 最安全，无需安装证书，可以在浏览器地址栏左侧查看域名证书
• 功能也最弱，只有特性1，相当于查询github的国外ip，手动改hosts一个意思。
• github的可访问性不稳定，取决于IP测速，如果有绿色ip存在，就 有可能 可以直连访问。

3.2、默认模式 Copy Section

• 此模式：开启拦截、关闭增强、使用远程配置、开启dns优选、开启测速
• 需要安装证书，通过修改sni直连访问github
• 功能上包含特性1/2/3/4。

四、 最佳实践 Copy Chapter

• 把dev-sidecar一直开着就行了（注意部分版本的windows下开着ds重启电脑，可能会无法上网，重新打开ds即可。）
• 建议遇到打开比较慢的国外网站，可以尝试将该域名添加到dns设置中（注意：被***封杀的无效）

其他加速 Copy Section

1）git clone 加速

• 方式1：快捷复制：

  开启脚本支持，然后在复制clone链接下方，即可复制到加速链接

• 方式2：

  1. 使用方式：用实际的名称替换 {} 的内容，即可加速clone https://hub.fastgit.org/{username}/{reponame}.git
  2. clone 出来的 remote "origin" 为fastgit的地址，需要手动改回来
  3. 你也可以直接使用他们的clone加速工具 fgit-go

2) 镜像网站

1）`github.com` 的镜像网站（注意：部分镜像网站不能登录）

1. hub.fastgit.org （2024/11/18：这个好像失效了？）
2. github.com.cnpmjs.org 这个很容易超限（2024/11/18：这个好像失效了？）
3. bgithub.xyz（edge浏览器可能报毒）
4. kkgithub.com
5. 5github.com

2) `youtube.com`的镜像网站（建议ipv6访问）

1. https://s3.dualstack.us-east-1.amazonaws.com/zhifan/ytb.html
2. https://s3.dualstack.us-east-1.amazonaws.com/zhifan/ytb2.html

五、api Copy Chapter

5.1、拦截配置 Copy Section

没有配置域名的不会拦截，其他根据配置进行拦截处理。

在【加速服务-拦截设置】中配置，格式如下：（更多内容参见wiki）

{
  // 要拦截的域名
  "github.com": {
    // 需要拦截url的正则表达式
    "/.*/.*/releases/download/": {
      // 拦截类型
      // "redirect": "url",        // 临时重定向（url会变，一些下载资源可以通过此方式配置）
      // "proxy": "url",           // 代理（url不会变，没有跨域问题）
      // "abort": true,            // 取消请求（适用于被***封锁的资源，找不到替代，直接取消请求，快速失败，节省时间）
      // "success": true,          // 直接返回成功请求（某些请求不想发出去，可以伪装成功返回）
      // "cacheDays": 1,           // GET请求的使用缓存，单位：天（常用于一些静态资源）
      // "options": true,          // OPTIONS请求直接返回成功请求（该功能存在一定风险，请谨慎使用）
      // "optionsMaxAge": 2592000, // OPTIONS请求缓存时间，默认：2592000（一个月）

      // 拦截配置示例：
      "redirect": "download.fastgit.org"
    },
    ".*": {
      "proxy": "github.com",
      "sni": "baidu.com" // 修改sni，规避***握手拦截
    }
  },
  "ajax.googleapis.com": {
    ".*": {
      "proxy": "ajax.loli.net", // 代理请求，url不会变
      "backup": ["ajax.proxy.ustclug.org"], // 备份，当前代理请求失败后，将会切换到备用地址
      "test": "ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js",
      "replace": "/(.*)/xxx" // 当加速地址的链接和原链接不是完全相同时，可以通过正则表达式replace，此时proxy通过$1$2来重组url， proxy:'ajax.loli.net/xxx/$1'
    }
  },
  "clients*.google.com": {
    ".*": {
      "abort": true // 取消请求，被***封锁的资源，找不到替代，直接取消请求，快速失败，节省时间
    }
  }
}

5.2、DNS优选配置 Copy Section

某些域名解析出来的ip会无法访问，（比如api.github.com会被解析到新加坡的ip上，新加坡的服务器在上午挺好，到了晚上就卡死，基本不可用）

通过从dns上获取ip列表，切换不同的ip进行尝试，最终会挑选到一个最快的ip（该功能需要事先配置好所用DNS），更多说明参见wiki

{
  "dns": {
    "mapping": {
      "api.github.com": "cloudflare", // "解决push的时候需要输入密码的问题",
      "gist.github.com": "cloudflare", // 解决gist无法访问的问题
      "*.githubusercontent.com": "cloudflare" // 解决github头像经常下载不到的问题
    }
  }
}

注意：暂时只支持IPv4的解析

六、问题排查 Copy Chapter

6.1、dev-sidecar的前两个开关没有处于打开状态 Copy Section

1. 尝试将开关按钮手动打开
2. 请尝试右键dev-sidecar图标，点退出。再重新打开
3. 如果还不行，请将日志发送给作者

如果是mac系统，可能是下面的原因

1）Mac系统使用时，首页的系统代理开关无法打开

出现这个问题可能是没有开启系统代理命令的执行权限

networksetup -setwebproxy 'WiFi' 127.0.0.1 31181
#看是否有如下错误提示
** Error: Command requires admin privileges.

如果有上面的错误提示，请尝试如下方法：

取消访问偏好设置需要管理员密码

系统偏好设置—>安全性与隐私—> 通用—> 高级—> 访问系统范围的偏好设置需要输入管理员密码（取消勾选）

6.2、没有加速效果 Copy Section

1. 本应用默认仅开启https加速，一般足够覆盖需求。
   如果你访问的是仅支持http协议的网站，请手动在【系统代理】中打开【代理HTTP请求】
2. 检查浏览器是否装了什么插件，与ds有冲突
3. 检查是否安装了其他代理软件，与ds有冲突
4. 请确认浏览器的代理设置为使用IE代理/或者使用系统代理状态
5. 可以尝试换个浏览器试试
6. 请确认网络代理设置处于勾选状态
   正常情况下ds在“系统代理”开关打开时，会自动设置系统代理。

6.3、浏览器打开提示证书不受信任 Copy Section

一般是证书安装位置不对，重新安装根证书后，重启浏览器

1）windows: 请确认证书已正确安装在“本地计算机-将所有的证书都放入下列存储：受信任的根证书颁发机构”下

2）mac: 请确认证书已经被安装并已经设置信任

3）火狐浏览器：火狐浏览器不走系统的根证书，需要在选项中添加根证书

1. 火狐浏览器->选项->隐私与安全->证书->查看证书

2. 证书颁发机构->导入

3. 选择证书文件 C:\Users(用户)\Administrator(你的账号)\.dev-sidecar\dev-sidecar.ca.crt（Mac或linux为 ~/.dev-sidecar 目录）

4. 勾选信任由此证书颁发机构来标识网站，确定即可

6.4、打开github显示连接超时 Copy Section

DevSidecar Warning: Error: www.github.com:443, 代理请求超时

1. 检查测速界面github.com是否有ip ，如果没有ip，则可能是由于你的网络提供商封锁了dns服务商的ip（试试能否ping通：1.1.1.1 / 9.9.9.9 ）
2. 如果是安全模式，则是因为不稳定导致的，等一会再刷新试试
3. 如果是增强模式，则是由于访问人数过多，正常现象

6.5、查看日志是否有报错 Copy Section

如果还是不行，请在下方加官方QQ群或提issue，附上服务日志（server.log）以便进行分析

日志打开方式：加速服务->右边日志按钮->打开日志文件夹

6.6、某些原本可以打开的网站打不开了 Copy Section

1. 可以尝试关闭pac
2. 可以将域名加入白名单

6.7、应用意外关闭导致没有网络了 Copy Section

应用开启后会自动修改系统代理设置，正常退出会自动关闭系统代理
当应用意外关闭时，可能会因为没有将系统代理恢复，从而导致完全无法上网。

对于此问题有如下几种解决方案可供选择：

1. 重新打开应用即可（右键应用托盘图标可完全退出，将会正常关闭系统代理设置）
2. 如果应用被卸载了，此时需要手动关闭系统代理设置
3. 如果你是因为开着ds的情况下重启电脑导致无法上网，你可以设置ds为开机自启

6.8、卸载应用后上不了网，git请求不了 Copy Section

如果你在卸载应用前，没有正常退出app，就有可能无法上网。请按如下步骤操作恢复您的网络：

1、关闭系统代理设置，参见：手动关闭系统代理设置
2、执行下面的命令关闭git的代理设置（如果你开启过 Git.exe代理 的开关）

git config --global --unset http.proxy
git config --global --unset https.proxy
git config --global --unset http.sslVerify

3、执行下面的命令关闭npm的代理设置（如果你开启过npm加速的开关）

npm config delete proxy
npm config delete https-proxy

6.9、其他问题 Copy Section

请查阅wiki

也可以查阅有文档tag的issue，它们被开发者认证为相当于文档级别的参考issue。

七、在其他程序使用 Copy Chapter

• java程序使用

八、贡献代码 Copy Chapter

8.1、准备环境 Copy Section

1）安装 `nodejs` 及其他环境

推荐安装 nodejs 22.x.x 的版本，其他版本未做测试

Windows上需要msvc，推荐使用VS 2022（node-gyp对VS 2026支持可能存在问题），安装时选择C++桌面开发工作负载即可。

另外还需要带distutils的python，推荐安装自带setuptools的python 3.11版本。如果本地有uv，则可以简单的运行以下命令

uv init .
uv sync
.venv/Scripts/activate.ps1 # for windows pwsh
.venv/Scripts/activate.bat # for windows cmd
source .venv/bin/activate # for linux/mac

这会根据.python-version文件自动安装python 3.11版本。如不想使用python 3.11，也可删除.python-version文件，pyproject.toml已经指定了所需依赖。

2）安装 `pnpm`

运行如下命令即可安装：

npm install pnpm --registry=https://registry.npmmirror.com

8.2、开发调试模式启动 Copy Section

运行如下命令即可开发模式启动

# 拉取代码
git clone https://github.com/docmirror/dev-sidecar

cd dev-sidecar

# 注意不要使用 `npm install` 来安装依赖，因为 `pnpm` 会自动安装依赖
pnpm install

# 运行DevSidecar
cd packages/gui
npm run electron

如果electron依赖包下载不动，可以开启ds的npm加速
如果pnpm install只是单纯卡住，大概是因为你忘记进python环境了

8.3、打包成可执行文件 Copy Section

# 先执行上面的步骤，然后运行如下命令打包成可执行文件
npm run electron:build

8.4、提交pr Copy Section

如果你想将你的修改贡献出来，请提交pr

九、联系作者 Copy Chapter

欢迎bug反馈，需求建议，技术交流等

加官方QQ群（请备注dev-sidecar，或简称DS）

• QQ 1群：390691483，人数：500 / 500（满）
• QQ 2群：667666069，人数：500 / 500（满）
• QQ 3群：419807815，人数：500 / 500（满）
• QQ 4群：438148299，人数：1004 / 2000（推荐）
• QQ 5群：767622917，人数：200 / 500

十、求star Copy Chapter

我的其他项目求star

• fast-crud : 开发crud快如闪电
• certd : 让你的证书永不过期
• trident-sync : 二次开发项目同步升级工具

十一、感谢 Copy Chapter

本项目曾使用lerna包管理工具

本项目参考如下开源项目

• node-mitmproxy
• ReplaceGoogleCDN

特别感谢

• github增强油猴脚本 本项目部分加速功能完全复制该脚本。
• 中国域名白名单，本项目的系统代理排除域名功能中，使用了该白名单。

本项目部分加速资源由如下组织提供

• FastGit UK

File: doc/caroot.md Copy Chapter

关于信任根证书的说明

一、为什么要信任根证书。 Copy Chapter

要回答这个问题需要先掌握下面两个知识点

知识点1：什么是根证书 Copy Section

百度百科-什么是根证书

当访问目标网站是https协议时，服务器会发送一个由根证书签发的网站ssl证书给浏览器，让浏览器用这个ssl证书给数据加密。
浏览器需要先验证这个证书的真伪，之后才会使用证书加密。
证书的真伪是通过验证证书的签发机构的证书是否可信，一直追溯到最初始的签发机构的证书（根证书）。
浏览器只需信任根证书，间接的就信任了这条证书链下签发的所有证书。

windows、mac、linux或者浏览器他们都内置了市面上可信的大型证书颁发机构的根证书。

知识点2：中间人攻击 Copy Section

本应用的实现原理如下图：

简单来说就是DevSidecar在本地启动了一个代理服务器帮你访问目标网站。
实际上就是 中间人攻击 的原理，只是本应用没有用它来干坏事，而是帮助开发者加速目标网站的访问。

现在可以回答为什么要信任根证书 Copy Section

当目标网站不需要加速拦截时，直接走TCP转发，不需要中间人攻击，没有安全风险，在此不多做讨论。

当目标网站需要拦截时（例如github），就需要通过中间人攻击修改请求或者请求其他替代网站，从而达到加速的目的。

例如加速github就需要修改如下几处

1. 直连访问github需要修改tls握手时的sni域名，规避***的sni阻断问题。
2. asserts.github.com等静态资源拦截替换成fastgit.org的镜像地址

DevSidecar在第一次启动时会在本地随机生成一份根证书，当有用户访问github时，就用这份根证书来签发一份假的叫github.com的证书。
如果浏览器事先信任了这份根证书，那么就可以正常访问DevSidecar返回的网页内容了。

二、信任根证书有安全风险吗 Copy Chapter

1. 根证书是DevSidecar第一次启动时本地随机生成的，除了你这台电脑没人知道这份根证书的内容。
2. 代理请求目标网站时会校验目标网站的证书（除非关闭了代理校验ssl）。

两段链路都是安全的，所以信任根证书没有问题。
但如果应用本身来源不明，或者拦截配置里的替代网站作恶，则有安全风险。

对于应用来源风险：
请勿从未知网站下载DevSidecar应用，认准官方版本发布地址
Github Release

或者从源码自行编译安装

对于拦截配置里的替代网站风险：

1. 尽量缩小替代配置的范围
2. 不使用来源不明的镜像地址，尽量使用知名度较高的镜像地址
3. 你甚至可以将其他拦截配置全部删除，只保留github相关配置

File: doc/linux.md Copy Chapter

Linux 支持

Linux使用说明，目前仅官方支持Ubuntu x86_64 GNOME桌面版（原版），其他Linux未测试

注意：需要开启 sudo 免密支持，否则请自行安装证书

一、安装 Copy Chapter

1.1. Ubuntu / Debian或其衍生版（未测试） Copy Section

• 下载DevSidecar-x.x.x.deb
• 使用 root 执行命令安装 dpkg -i DevSidecar-x.x.x.deb
• 去应用列表里面找到 dev-sidecar 应用，打开即可

1.2. 其他基于glibc的Linux系统（未测试） Copy Section

• 下载 DevSidecar-x.x.x.AppImage
• 设置可执行权限 chmod +x DevSidecar-x.x.x.AppImage
• 双击运行

1.3. 特殊的Linux系统（如Alpine和Chimera Linux） Copy Section

此处默认用户有较专业的Linux知识，故不详细描述，请参考并自行试验

• 创建Debian（最方便且省空间）容器，可使用distrobox（推荐），接下来以此为例说明

• 下载deb包并在容器内安装

• 穿透系统设置：
  在容器内 /usr/bin/gsettings 文件写入：

  bash Copy

  #!/bin/sh
  distrobox-host-exec gsettings "$@"

  并设置可执行权限

  简化版命令（请在容器内执行）:

  text Copy

  echo -e '#!/bin/sh\ndistrobox-host-exec gsettings "$@"' >/usr/bin/gsettings

• 使用命令启动应用，使用“自动安装证书”功能，回到终端，找到输出里含有 sudo 的两句命令，复制到主系统执行，如失败（或使用其他证书系统），请自行安装证书，可参考 议题 #204

1.4. 版本选择 Copy Section

不同CPU架构，选择对应的版本，如果安装失败，请下载 universal 版本

二、证书安装 Copy Chapter

默认模式和增强模式需要系统信任CA证书。
由于Linux上火狐和Chrome都不走系统证书，所以除了安装系统证书之外，还需要给浏览器安装证书

2.1. 系统证书安装 Copy Section

根据弹出的提示：

• 点击首页右上角“安装根证书”按钮
• 点击“点此去安装”
• 提示安装成功即可

2.2. 火狐浏览器安装证书 Copy Section

• 火狐浏览器->选项->隐私与安全->证书->查看证书
• 证书颁发机构->导入
• 选择证书文件在 ~/.dev-sidecar 目录下
• 勾选信任由此证书颁发机构来标识网站，确定即可

2.3. Chrome浏览器安装证书 Copy Section

证书文件目录为 ~/.dev-sidecar

File: doc/other.md Copy Chapter

其他程序使用

Java程序使用 Copy Chapter

由 Enaium 提供，未做验证，可供参考

1. 先通过keytool安装证书：

   shell Copy

   keytool -import -alias dev-sidecar -keystore "jdk路径\security\cacerts" -file 用户目录\.dev-sidecar\dev-sidecar.ca.crt

   默认密码为 changeit

2. 启动时还需要设置参数，例：

   shell Copy

   java -Dhttp.proxyHost=localhost -Dhttp.proxyPort=31181 -Dhttps.proxyHost=localhost -Dhttps.proxyPort=31181 -jar xxxx.jar

3. Gradle还需在用户目录/.gradle/gradle.properties创建配置文件：

   properties Copy

   systemProp.http.proxyHost=localhost
   systemProp.http.proxyPort=31181
   systemProp.https.proxyHost=localhost
   systemProp.https.proxyPort=31181

File: doc/recover.md Copy Chapter

卸载与恢复网络

由于应用启动后会自动设置系统代理，正常退出时会关闭系统代理。
当应用意外关闭，或者未正常退出后被卸载，此时会因为系统代理没有恢复从而导致完全上不了网。
目前electron在windows系统上无法监听系统重启事件。更多相关资料 electron issues

恢复代理设置 Copy Chapter

1、windows 代理关闭 Copy Section

如何打开查看windows代理设置：

• win10: 开始->设置->网络和Internet->最下方代理
• win7: 开始->控制面板->网络和Internet->网络和共享中心->左下角Internet选项->连接选项卡->局域网设置

2、mac 代理关闭 Copy Section

网络->网卡->代理->去掉http和https的两个勾

3、Linux（Ubuntu） Copy Section

网络->代理->选择禁用

File: packages/gui/README.md Copy Chapter

dev-sidecar-gui

Project setup Copy Chapter

You should always refer to the main README for instructions on how to set up the project.

Customize configuration Copy Section

See Configuration Reference.