# dev-sidecar-rs

**Repository Path**: pauljoihn21/dev-sidecar-rs

## Basic Information

- **Project Name**: dev-sidecar-rs
- **Description**: 开发者边车工具 Rust 重写版 - 加速 GitHub/npm/Docker Hub 访问
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DevSidecar RS

开发者边车工具 Rust 重写版，加速 GitHub、npm、Docker Hub、crates.io 等海外服务的访问。

通过运行本地 MITM HTTPS 代理、注入根 CA 证书，并对请求应用 DNS 优选、SNI 重写、拦截/重定向规则来实现加速。

![Version](https://img.shields.io/badge/version-2.2.0-blue)
![License](https://img.shields.io/badge/license-MPL--2.0-green)
![Rust](https://img.shields.io/badge/rust-1.85%2B-orange)

## 技术栈

- **前端**: Dioxus 0.7 + DaisyUI + Tailwind CSS v4
- **后端**: Rust (hyper + reqwest + hickory-resolver)
- **MITM 代理**: ds-proxy (hyper) + ds-tls (rcgen + rustls)
- **DNS**: ds-dns (hickory-resolver, DoH/DoT/UDP/TCP)
- **桌面**: Dioxus desktop (tray-icon, global-hotkey, single-instance)
- **缓存**: moka (LRU, TTL)
- **日志**: tracing + tracing-appender (按天轮转)

## 项目结构

```
crates/
├── ds-app/                  # Dioxus 桌面应用 (SSR + Desktop)
│   ├── src/
│   │   ├── main.rs          # 入口，日志初始化
│   │   ├── app.rs           # 根组件、侧边栏、路由
│   │   ├── server_fn.rs     # Server Functions (启动/停止代理、配置管理)
│   │   ├── pages/           # 各页面 (首页、加速服务、系统代理、设置、插件)
│   │   ├── components/      # 公共组件 (布局、开关、CA 安装)
│   │   ├── desktop/         # 桌面专属 (托盘菜单、自启动)
│   │   ├── hooks/           # 自定义 Hooks (配置、主题、插件状态)
│   │   └── state/           # GlobalSignal 全局状态
│   └── assets/              # 图标、CSS
│
├── ds-core/                 # 核心编排器
│   ├── src/
│   │   ├── orchestration.rs # DevSidecar 主 API: startup/shutdown
│   │   ├── config/          # 配置加载、合并、默认值
│   │   ├── plugin/          # 插件系统 (git, node, pip, cargo, overwall, proxy)
│   │   ├── event.rs         # 事件总线 (tokio broadcast)
│   │   ├── status.rs        # 状态管理 (dot-path 更新)
│   │   └── proxy_engine.rs  # ProxyEngine trait
│
├── ds-proxy/                # HTTP/HTTPS 代理服务器
│   ├── src/
│   │   ├── server.rs        # 代理服务器主入口 (CONNECT + HTTP)
│   │   ├── fake_server.rs   # MITM 拦截处理 (TLS 握手 + 请求转发)
│   │   ├── request.rs       # 请求转发器 (reqwest + SNI 重写 + DNS)
│   │   ├── interceptor/     # 拦截器管线 (域名匹配、路径正则)
│   │   ├── handler/         # 请求上下文、ProxyAction 枚举
│   │   ├── middleware/
│   │   │   ├── overwall.rs            # Overwall 中间件 (gfwlist/PAC)
│   │   │   ├── response_interceptor.rs# 响应拦截 (缓存、脚本注入、替换)
│   │   │   └── request_cache.rs       # 请求缓存 (moka LRU)
│   │   ├── connect.rs       # 直连隧道 (无 MITM 的 CONNECT)
│   │   └── body_util.rs     # 公共 body 辅助函数
│
├── ds-tls/                  # TLS/证书管理
│   ├── src/
│   │   ├── tls_server.rs    # TlsCertManager (CA 加载 + 假证书签名)
│   │   ├── ca.rs            # CA 根证书生成 (rcgen)
│   │   ├── cert_cache.rs    # 证书 LRU 缓存
│   │   └── sni.rs           # SNI 提取
│
├── ds-dns/                  # DNS 解析系统
│   ├── src/
│   │   ├── resolver.rs      # 统一解析器 (多 provider + IP 缓存)
│   │   ├── provider/        # DNS 协议实现 (UDP/TCP/DoH/DoT/预设 IP)
│   │   ├── choice.rs        # DynamicChoice 故障转移
│   │   ├── speed_test.rs    # IP 测速 + 定时测速
│   │   └── request_counter.rs # 请求计数器
│
└── ds-shell/                # 系统操作
    └── src/
        ├── system_proxy.rs  # 设置系统代理
        ├── ca_install.rs    # 安装 CA 证书
        ├── loopback.rs      # 启用回环
        ├── auto_launch.rs   # 开机自启
        ├── cargo_config.rs  # Cargo 配置读写 (toml_edit 智能合并)
        └── exec.rs          # 命令执行封装
```

## 功能特性

### 🖥️ 桌面端功能
- **系统托盘**: 最小化到托盘，后台持续运行
- **全局快捷键**: 支持 `Alt+S` 快速显示/隐藏窗口
- **Dock 控制**: macOS 下可隐藏/显示 Dock 图标
- **窗口策略**: 支持关闭时退出、隐藏到托盘或提示确认
- **开机自启**: 支持开机自动启动应用
- **单实例**: 防止重复启动多个应用实例

### 🔒 MITM TLS 拦截
- 动态生成目标域名的假证书（由本地 CA 签名）
- TLS 握手后解密流量，应用拦截规则
- 支持 HTTP keep-alive 和连接超时管理

### DNS 优选与故障转移
- 多协议 DNS 解析：UDP、TCP、DoH (DNS-over-HTTPS)、DoT (DNS-over-TLS)
- 预设 IP 列表（绕过 DNS 查询）
- IP 缓存（moka, TTL 5 分钟）减少重复查询
- DynamicChoice 故障转移：连续 3 次错误或成功率 < 40% 自动切换
- 定时测速：后台周期性测试 IP 延迟，自动优选

### SNI 重写
- 在 TLS 层修改 `ServerName`，绕过 GFW 的 SNI 封锁
- 使用 `tokio-rustls` 直接建立 TLS 连接，自定义 SNI
- 保留原始 `Host` 头，确保服务器正确响应

### 拦截器管线
- 域名匹配：精确匹配 + 通配符 (`*.docker.com`)
- 路径正则：支持捕获组模板替换 (`${host}`, `${p[1]}`)
- 动作类型：`Forward`、`Redirect`、`Proxy`、`Abort`、`ReturnSuccess`、`SniRewrite`、`Cache`
- 请求阶段：OPTIONS 预检 (CORS)、请求头替换
- 响应阶段：Cache-Control 注入、HTML 脚本注入、响应头替换

### Overwall 穿墙
- gfwlist/PAC 规则解析（支持 `||`, `*`, `^` 语法）
- Base64 自动解码
- PAC 文件自动下载更新
- 代理服务器转发（含密码认证）
- MITM 路径完整集成

### 请求缓存
- 基于 moka LRU 缓存的 GET 请求缓存
- 响应阶段自动存储，请求阶段自动命中
- 支持 `cacheDays` / `cacheHours` 配置

### 按需证书验证
- 根据 `unVerifySsl` 配置决定是否接受无效证书
- SNI 重写场景自动使用 NoVerifier

## 🚀 快速开始

### 安装

1. **下载 release**: 从 [Releases](https://gitee.com/pauljoihn21/dev-sidecar-rs/releases) 下载对应平台的安装包
2. **macOS**: 打开 `.dmg` 文件，将应用拖到 Applications 文件夹
3. **Windows**: 运行 `.exe` 安装程序
4. **Linux**: 解压后运行 `dev-sidecar`

### 首次使用

1. **安装 CA 证书**: 首次启动时点击「安装 CA 证书」按钮，将证书添加到系统信任链
2. **启动加速**: 点击首页的「启动加速」按钮，或托盘菜单的「启动代理」
3. **验证加速**: 打开浏览器访问 https://github.com 测试加速效果

### 插件功能

| 插件 | 功能 |
|------|------|
| NPM 加速 | 自动设置 npm registry 为淘宝镜像 |
| Git 代理 | 自动配置 Git 使用 DevSidecar 代理 |
| PIP 加速 | 自动设置 PyPI 镜像为清华源 |
| Cargo 加速 | 配置 cargo 代理或 rsproxy.cn 镜像，加速 crates.io |
| 网络检测 | 检测 GitHub、npmjs 等站点的连通性 |
| 增强功能 | 支持 PAC/gfwlist 规则，实现智能分流 |

## 🔧 开发

### 环境要求

- Rust 1.85+ (Edition 2024)
- Node.js 18+ (用于 Tailwind CSS)
- pnpm

### 启动开发

```bash
# 1. 启动 Tailwind CSS 监听
pnpm css:watch

# 2. 启动 Dioxus 开发服务器
dx serve
```

### 构建发布

```bash
# 编译 CSS
pnpm css:build

# 桌面端构建 (开发)
dx serve

# 桌面端构建 (发布)
cargo build --release

# 打包应用 (生成 .dmg/.exe/.deb)
dx bundle --release
```

### 构建优化

项目已配置 Release 优化：
- `lto = true` - 链接时优化
- `codegen-units = 1` - 单代码生成单元
- `strip = true` - 去除调试符号
- `panic = "abort"` - 减小二进制体积

优化后的二进制大小约 **9.7MB** (macOS ARM64)

### 测试

```bash
# 运行全部测试
cargo test

# 运行单个 crate 测试
cargo test -p ds-proxy
cargo test -p ds-dns

# 运行特定测试
cargo test -p ds-proxy -- test_proxy_server_lifecycle
```

### 代码检查

```bash
# 编译检查
cargo check

# Clippy 检查
cargo clippy

# 自动修复
cargo clippy --fix --allow-dirty
```

## 配置

用户配置文件位于 `~/.dev-sidecar-rs/config.json`，配置合并顺序：

1. 默认配置 (`ds-core/src/config/default.rs`)
2. 远程共享配置
3. 远程个人配置
4. 用户本地覆盖 (`~/.dev-sidecar-rs/config.json`)

### 关键文件路径

| 文件 | 路径 |
|------|------|
| 用户配置 | `~/.dev-sidecar-rs/config.json` |
| CA 证书 | `~/.dev-sidecar-rs/dev-sidecar.ca.crt` |
| CA 私钥 | `~/.dev-sidecar-rs/dev-sidecar.ca.key.pem` |
| PAC 文件 | `~/.dev-sidecar-rs/pac.txt` |
| 日志文件 | `~/.dev-sidecar-rs/logs/dev-sidecar.log.YYYY-MM-DD` |
| Cargo 配置 | `~/.cargo/config.toml`（Cargo 加速插件管理） |

## 默认端口

| 服务 | 端口 | 说明 |
|------|------|------|
| HTTPS 代理 | 31181 | 主代理端口 (CONNECT + HTTP) |
| HTTP 代理 | 31180 | 辅助代理端口 |

## 常见问题

### Q: 为什么需要安装 CA 证书？
A: DevSidecar 使用 MITM（中间人）技术拦截 HTTPS 流量以实现加速。为了浏览器信任代理生成的假证书，需要将 DevSidecar 的 CA 证书安装到系统信任链。

### Q: 如何卸载 CA 证书？
A: 在应用设置中点击「卸载 CA 证书」，或手动从系统钥匙串/证书管理器中删除 "DevSidecar CA"。

### Q: 启动代理后某些网站无法访问？
A: 尝试以下步骤：
1. 检查是否有其他代理软件冲突
2. 尝试切换 DNS 配置
3. 在设置中调整拦截规则

### Q: macOS 提示应用已损坏？
A: 运行以下命令移除隔离属性：
```bash
xattr -cr /Applications/DsApp.app
```

## 贡献指南

欢迎提交 Issue 和 PR！请确保：
1. 代码通过 `cargo clippy` 检查
2. 代码通过 `cargo fmt` 格式化
3. 添加必要的测试

## 致谢

- [Dioxus](https://dioxuslabs.com/) - Rust GUI 框架
- [rcgen](https://github.com/rustls/rcgen) - 证书生成
- [hickory-resolver](https://github.com/hickory-dns/hickory-dns) - DNS 解析

## License

MPL-2.0