francomano/ProxyDoctor
GitHub: francomano/ProxyDoctor
一款轻量级网络诊断工具，用于通过各类代理执行连通性检查并快速定位代理链路中的具体故障层级。
Stars: 1 | Forks: 4
# ProxyDoctor — 代理诊断工具
**一个简约且易于测试的 Go 工具，用于通过代理运行网络诊断**
[](LICENSE)
[](CONTRIBUTING.md)
[](https://github.com/francomano/Proxydoctor/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
[](https://go.dev/)
## 为什么选择 ProxyDoctor？
**问题所在：**
当你处于企业代理环境或使用 VPN 时，可能会遇到莫名其妙的故障：
- 网站无法加载（代理配置错误？）
- 即使通过“私有”代理，你的 IP 依然发生泄露
- 你无法判断问题出在代理、DNS 还是目标网站本身
**解决方案：**
ProxyDoctor 是一款**轻量级诊断工具**，它可以：
- 通过任何代理（HTTP、HTTPS、SOCKS4、SOCKS5）运行网络检测
- 对比直连和代理连接的结果
- 准确定位发生故障的具体层级（DNS？TLS？IP 泄露？）
- 在几秒钟内为你提供可操作的诊断洞察
**适用人群：**
- 调试代理问题的开发者
- 排查 VPN 连接故障的 DevOps 工程师
- 验证代理实现的安全团队
- 任何不想再盲目猜测故障原因的人
## 主要功能
ProxyDoctor 是一款 CLI 优先的工具，旨在：
- 运行网络检测（DNS 解析、IP 检测、TLS 证书验证、端口连通性测试）
- 对比直连与代理路由连接的结果
- 识别连通性问题和代理配置错误
## 项目状态
**v0.2.0 (Alpha)**
- ✅ 包含检查注册表和依赖 DAG 的核心引擎
- ✅ 带有 diagnose 和 list-checks 命令的 CLI
- ✅ 在 `diagnose --proxy` 中支持 HTTP/HTTPS 代理
- ✅ 支持 SOCKS4/SOCKS5 代理（完整的协议实现、SOCKS4a 域名支持、符合 RFC 1929 标准的 SOCKS5 认证）
- ✅ 将 HTTP server 与核心引擎对接，提供位于 `/` 的 Web GUI 以及 `/api/checks`、`/api/diagnose` JSON endpoints
- ✅ Web GUI — 位于 `http://localhost:8080/` 的单页表单，通过 `POST /api/diagnose` 运行真实的诊断并渲染结果
- ✅ 4 项内置检查：public_ip、dns_resolve、tls_certificate、port_connectivity
- ✅ `--export json` 和 `--export markdown`（功能正常）
- ✅ 单元测试（6 个通过的测试，覆盖引擎核心）
- 🔲 更多检查（计划支持 DNS 泄露、WebRTC 泄露、地理定位、IP 信誉检测）
- 🔲 插件系统（框架已搭建，尚不具备功能性）
## 环境要求
- **Go** >= 1.25
- **Git**
## 快速开始
### 初始配置（仅首次运行需要）
```
git clone https://github.com/francomano/proxydoctor
cd ProxyDoctor
./setup.sh
```
该脚本将执行以下操作：
- 验证 Go 安装状态
- 下载并验证相关依赖
- 运行所有测试（6 个通过的测试）
- 构建 CLI 和 server 二进制文件
### 体验 Web GUI
```
# 启动服务器
./run.sh server
# 在浏览器中打开
open http://localhost:8080
```
输入 URL（以及可选的代理 + 代理类型），点击“Run diagnosis”——它将运行与 CLI 相同的 `core/engine.DiagnosisOrchestrator`，并将结果渲染为可视化卡片。
该 GUI 由两个 JSON endpoints 提供支持，也可直接调用：
```
# 列出可用检查
curl http://localhost:8080/api/checks
# 运行诊断
curl -X POST http://localhost:8080/api/diagnose \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","proxy":"socks5://77.245.76.107:1080","proxy_type":"socks5"}'
```
### 使用 CLI
```
# 获取帮助
./run.sh cli --help
# 列出可用检查
./run.sh cli list-checks
# 运行诊断（直接连接）
./run.sh cli diagnose --url https://example.com
# 使用自定义 timeout 运行诊断
./run.sh cli diagnose --url https://example.com --timeout 10s
# 仅运行选定的检查
./run.sh cli diagnose --url https://example.com --checks public_ip,dns_resolve
# 通过 HTTP proxy 运行诊断
./run.sh cli diagnose --url https://example.com --proxy http://127.0.0.1:3128 --proxy-type http
# 通过 SOCKS5 proxy 运行诊断（带 scheme）
./run.sh cli diagnose --url https://example.com --proxy socks5://127.0.0.1:1080 --proxy-type socks5
# 通过 SOCKS5 proxy 运行诊断（纯 host:port + type）
./run.sh cli diagnose --url https://example.com --proxy 127.0.0.1:1080 --proxy-type socks5
# 比较直接和代理的诊断结果
./run.sh cli diagnose --url https://example.com --proxy socks5://127.0.0.1:1080 --compare
# 将结果导出为 JSON
./run.sh cli diagnose --url https://example.com --export json --output report.json
```
### 运行 Server
```
# 在 :8080 上启动 HTTP server
./run.sh server
```
### 运行测试
```
# 运行所有测试
./run.sh test
# 或者直接
go test -v ./...
```
## 文件结构
```
ProxyDoctor/
├── setup.sh ← One-time setup (install deps, test, build)
├── run.sh ← Convenience launcher (cli, server, test)
├── cmd/
│ ├── cli/ ← CLI application (diagnose, list-checks)
│ └── server/ ← HTTP API server (minimal, stdlib only) + web GUI
├── core/
│ ├── engine/ ← Orchestration engine (tests included)
│ ├── check/ ← Result types and interfaces (tests included)
│ ├── adapters/ ← Proxy implementations (Direct, HTTP, HTTPS, SOCKS4, SOCKS5)
│ ├── checks/ ← Diagnostic checks (public_ip, dns_resolve, tls_cert, port_scan)
│ └── utils/ ← Shared helpers (proxy URL parsing)
├── go.mod, go.sum ← Go modules
├── README.md
├── ARCHITECTURE.md
├── CHANGELOG.md
├── NEXT_STEPS.md
└── VERSION
```
## 内置检查项
| 检查项 | 类别 | 描述 |
|---|---|---|
| `public_ip` | network | 通过 ipify.org、icanhazip.com、ifconfig.me 检测公网 IP 地址 |
| `dns_resolve` | network | 通过当前连接将主机名解析为 IP 地址 |
| `tls_certificate` | tls | 验证 TLS 证书（颁发者、过期时间、密码套件、TLS 版本） |
| `port_connectivity` | network | 测试 80、443、8080、8443 端口的 TCP 连通性 |
## 代理输入格式
CLI 和 GUI 支持多种格式的代理 URL：
| 格式 | 示例 | 说明 |
|---|---|---|
| `scheme://host:port` | `socks5://77.245.76.107:1080` | 根据 scheme 自动检测类型 |
| `host:port` + 类型 | `77.245.76.107:1080` + `--proxy-type socks5` | 需指定明确的类型 |
| `host` + 类型 | `77.245.76.107` + `--proxy-type socks5` | 使用默认端口（SOCKS 为 1080，HTTP 为 8080） |
| 包含认证 | `socks5://user:pass@host:port` | 从 URL 中提取凭据 |
## 已知问题 / 限制
- DNS 泄露、WebRTC 泄露、地理定位和 IP 信誉检查已列入计划，但尚未实现。
标签：EVTX分析, Go, Python脚本, Ruby工具, 代理工具, 情报分析, 日志审计, 网络安全辅助, 网络诊断, 运维工具