dev-sidecar README

The project's README from github.com/docmirror/dev-sidecar. As one markdown file: README.md.

dev-sidecar

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

GitHub stars

Star History Chart

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

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

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

打个广告

https://github.com/certd/certd

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

重要提醒

------------------------------重要提醒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）了

一、 特性

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

1.2、 请求拦截

1.3、 github加速

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

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

1.4、 Stack Overflow 加速

1.5、 npm加速

安全警告：

二、快速开始

支持windows、Mac、Linux(Ubuntu)

2.1、DevSidecar桌面应用

1）下载安装包

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 开启后

开启前 开启后
头像
clone
zip 下载 秒下的，实在截不到速度的图

三、模式说明

3.1、安全模式

3.2、默认模式

四、 最佳实践

其他加速

1）git clone 加速

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

5.1、拦截配置

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

在【加速服务-拦截设置】中配置，格式如下：（更多内容参见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优选配置

某些域名解析出来的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的解析

六、问题排查

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

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

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

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

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

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

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

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

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

6.2、没有加速效果

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

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

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

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显示连接超时

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、查看日志是否有报错

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

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

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

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

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

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

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

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

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

如果你在卸载应用前，没有正常退出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、其他问题

请查阅wiki

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

七、在其他程序使用

八、贡献代码

8.1、准备环境

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 -g pnpm --registry=https://registry.npmmirror.com

8.2、开发调试模式启动

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

# 拉取代码
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、打包成可执行文件

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

8.4、提交pr

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

九、联系作者

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

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

十、求star

我的其他项目求star

十一、感谢

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

lerna

本项目参考如下开源项目

特别感谢

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

dev-sidecar (docmirror/dev-sidecar)

Searching Database…

24.5K ·GitHub
Dev-sidecar
这是什么？Dev-Sidecar（DS）是一款本地代理桌面应用，帮助开发者（尤其是中国大陆的开发者）访问 GitHub、npm、Stack Overflow 等类似服务。它通过优化 DNS 查询，并将被屏蔽或访问缓慢的请求经由加速镜像转发来实现这一点。
这是浏览器插件还是独立应用？它是一款独立的 Electron 桌面应用，而不是浏览器扩展。运行后，它会自动修改系统级代理设置，以拦截并重定向流量。
我该怎么安装并开始使用？从 GitHub Releases 下载适合你操作系统的安装包（例如 Windows 的 DevSidecar-x.x.x-windows-universal.exe、macOS 的 .dmg，或 Linux 的 .deb/.AppImage），安装后，在首次启动时批准根证书提示，即可启用完全加速。
使用它需要安装根证书吗？需要。默认模式（完全加速）需要安装本地生成的根证书；安全模式完全不需要证书，但它只提供基于 DNS 的优化，效果要弱得多。
运行它会有什么副作用吗，比如重启之后？在某些 Windows 版本上，DS 运行时重启电脑（v1.8.9 起已修复）可能导致网络断开，直到你重新启动应用才能恢复。此外，DS 还可能与同时运行的其他代理或 VPN 软件产生冲突。
这个应用会收集我的数据吗？不会。应用本身及其默认的远程配置服务器都声明不收集任何信息。如果你仍然不放心，可以在安全模式下运行，无需安装任何证书。
GitHub 加速到底是怎么实现的？它会改写 TLS SNI，使你能够直接连接 GitHub。同时，它通过加速镜像代理 releases、zip 下载、克隆流量、头像、raw/blame 内容以及 gist 页面，并可选配用户脚本，用于额外的网站修复。
安全模式和默认模式到底有什么区别？安全模式只做 DNS 优化，不需要证书，因此最安全，但效果较弱；默认模式会安装证书并启用完整的请求拦截，从而为 GitHub、npm 和 Stack Overflow 提供更强的加速效果。
它也能加速 npm 安装吗？可以。它能代理 npm 镜像源的流量，并允许你在官方源和淘宝镜像之间切换。当 'npm install' 即使通过 cnpm 也失败时，这一功能会有所帮助。
加速不生效的话，我该检查什么？确保 DS 首页上的两个主开关都已打开，检查是否有冲突的代理软件或浏览器扩展，并确认浏览器设置为使用系统/IE 代理。
What are similar projects?russia-mobile-internet-whitelist, CF-Workers-TGProxy, Open-Box, XX-Net, gate, fq-book, back4app-vless, trojan
Which topics is it in?certificate, proxy-server, gfw, pnpm, anti-censorship, dns, reverse-proxy, censorship-circumvention, github, electron, vue, proxy
Creator
docmirror
Size
12.9 MB
Stars
24.5K
Updated
CommitOct 16Releasev2.3.1Oct 08
Age
6y
Commits · 90 Days