内容
# ProxyDoctor — 代理诊断
**一个最小化、可测试的Go工具，用于通过代理运行网络诊断**
[](https://github.com/francomano/ProxyDoctor/actions/workflows/test.yml)
[](https://goreportcard.com/report/github.com/francomano/ProxyDoctor)
[](https://pkg.go.dev/github.com/francomano/ProxyDoctor)
[](LICENSE)
[](CONTRIBUTING.md)
[](https://go.dev/)
<p align="center">
<img src="images/proxydoctor-logo.png" alt="ProxyDoctor Logo" width="150">
</p>
<p align="center">
<img src="images/proxydoctor-demo.gif" alt="ProxyDoctor CLI Demo" width="750">
</p>
> **使用AI辅助构建** — 该项目使用以下工具开发：
> - **GitHub Copilot** 和 **OpenCode** （代码开发和实现）
> - **GPT 5.5** 和 **Gemini Pro** （架构审查，特别是拉取请求代码审查）
## 为什么使用ProxyDoctor？
**问题：**
你位于公司代理或使用VPN后，某些事情神秘地出错了：
- 网站无法加载（代理配置错误？）
- 你的IP地址即使通过“私有”代理也泄露了
- 你无法确定问题出在代理、DNS还是网站本身
**解决方案：**
ProxyDoctor是一个**轻量级诊断工具**，可以：
- 通过任何代理（HTTP，HTTPS，SOCKS4，SOCKS5）运行网络检查
- 比较直接连接和代理连接的结果
- 确定是哪一层出现故障（DNS？TLS？IP地址泄露？）
- 在几秒钟内给出可行的洞察
**完美适用于：**
- 开发人员调试代理问题
- DevOps工程师排除VPN连接故障
- 安全团队验证代理实现
- 任何对猜测自己电脑问题感到厌烦的人
## 它能做什么
ProxyDoctor是一个CLI优先的工具，用于：
- 运行网络检查（DNS解析，IP地址检测，TLS证书验证，端口连接性）
- 比较直接连接和代理路由连接的结果
- 在GUI中显示国家标志，在CLI输出中显示国家名称，进行路由跟踪
- 确定连接问题和代理配置错误
## 项目状态
> 该版本在交付前已使用GPT 5.5通过OpenCode审查和修复。
**v0.3.0（Alpha）**
- ✅ 具有检查注册表和依赖DAG的核心引擎
- ✅ 具有诊断和列出检查命令的CLI
- ✅ `diagnose --proxy`中的HTTP/HTTPS代理支持
- ✅ SOCKS4/SOCKS5代理支持（完整的协议实现，SOCKS4a域名支持，SOCKS5按RFC 1929进行身份验证）
- ✅ 核心引擎的HTTP服务器，带有Web GUI，位于“/”和“/api/checks”、“/api/diagnose” JSON端点
- ✅ Web GUI - 单页表单，位于`http://localhost:8080/`，通过`POST /api/diagnose`运行诊断并渲染结果
- ✅ 6个内置检查：public_ip、dns_resolve、tls_certificate、port_connectivity、route_trace、ipv6_leak
- ✅ `--export json`和`--export markdown`（正在运行）
- ✅ 单元测试（6个测试通过，引擎覆盖）
- ✅ 插件系统（CheckPlugin、ExportPlugin、MiddlewarePlugin接口）
- 🧭 可选检查的重点待办事项，例如DNS泄漏、WebRTC泄漏、地理位置和IP声誉
- ✅ MCP服务器插件（模型上下文协议，在端口：9090上公开诊断/比较工具）
## 需求
- **Go** >= 1.25
- **Git**
## 快速开始
### 设置（仅需一次）
```bash
git clone https://github.com/francomano/proxydoctor
cd ProxyDoctor
./setup.sh
```
该脚本将：
- 验证Go安装
- 下载并验证依赖项
- 运行所有测试（6个测试通过）
- 构建CLI和服务器二进制文件
### 试用Web GUI
```bash
# 启动服务器
./run.sh server
# 在浏览器中打开
open http://localhost:8080
```
填写URL（和可选的代理+代理类型），点击“运行诊断” - 它运行与CLI相同的`core/engine.DiagnosisOrchestrator`并将结果呈现为卡片。
<p align="center">
<img src="images/gui.png" alt="ProxyDoctor Web GUI" width="750">
</p>
两个JSON端点支持GUI，可以直接调用：
```bash
# 列出可用检查
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
```bash
# 获取帮助
./run.sh cli --help
# 列出可用检查
./run.sh cli list-checks
# 运行诊断（直接连接）
./run.sh cli diagnose --url https://example.com
# 运行诊断并设置超时
./run.sh cli diagnose --url https://example.com --timeout 10s
# 运行选定的检查
./run.sh cli diagnose --url https://example.com --checks public_ip,dns_resolve
# 通过HTTP代理运行诊断
./run.sh cli diagnose --url https://example.com --proxy http://127.0.0.1:3128 --proxy-type http
# 通过SOCKS5代理运行诊断（带方案）
./run.sh cli diagnose --url https://example.com --proxy socks5://127.0.0.1:1080 --proxy-type socks5
# 通过SOCKS5代理运行诊断（裸主机：端口 + 类型）
./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
```
### 运行服务器
```bash
# 在:8080上启动HTTP服务器
./run.sh server
```
### 运行测试
```bash
# 运行所有测试
./run.sh test
# 或直接运行
go test -v ./...
```
## 插件系统
ProxyDoctor具有可扩展功能的插件系统。插件可以添加新的检查或长时间运行的服务。
可用插件通过`./run.sh cli`上的`--plugins`标志加载。
### 可用插件
| 插件 | ID | 类型 | 描述 |
|---|---|---|---|
| 路径跟踪 | `route_trace` | 检查 | 跟踪网络跳转并用国家信息注释公共跳转 |
| MCP服务器 | `mcp_server` | 独立 | 通过:model Context Protocol在`:9090`上公开诊断/比较工具 |
### 使用插件
**route_trace** - 使用`diagnose`注册一个新检查：
```bash
./run.sh cli diagnose --url https://example.com --plugins route_trace
```
**mcp_server** - 启动一个独立的JSON-RPC 2.0服务器：
```bash
./run.sh cli --plugins mcp_server
```
一旦启动，发送请求到`POST http://localhost:9090/mcp`：
```json
{"jsonrpc":"2.0","id":1,"method":"tools/list"}
```
```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"diagnose","arguments":{"url":"https://example.com"}}}
```
```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"compare","arguments":{"url":"https://example.com","proxy":"socks5://77.245.76.107:1080"}}}
```
### 打开代码 / AI助手集成
ProxyDoctor的MCP服务器与[OpenCode](https://opencode.ai)和任何MCP兼容的AI编码助手兼容。`opencode.jsonc`文件将其注册为远程MCP服务器：
```jsonc
{
"mcp": {
"proxydoctor": {
"type": "remote",
"url": "http://localhost:9090/mcp",
"enabled": true
}
}
}
```
一旦MCP服务器运行，助手就可以使用`diagnose`、`compare`和`list_checks`作为原生工具 - 不需要curl。
### 同时加载多个插件
```bash
./run.sh cli --plugins route_trace,mcp_server
```
### 创建插件
```go
import (
"github.com/francomano/proxydoctor/core/engine"
"github.com/francomano/proxydoctor/core/plugin"
)
type MyPlugin struct{}
func (p *MyPlugin) ID() string { return "my-plugin" }
func (p *MyPlugin) Name() string { return "My Plugin" }
func (p *MyPlugin) Version() string { return "0.1.0" }
func (p *MyPlugin) Description() string { return "Adds custom checks" }
func (p *MyPlugin) Init(_ *plugin.Context) error { return nil }
func (p *MyPlugin) Shutdown() error { return nil }
func (p *MyPlugin) RegisterChecks(r *engine.CheckRegistry) error {
r.Register(myNewCheck())
return nil
}
// 在core/plugins/registry.go中注册插件
```
插件接口：`CheckPlugin`、`ExportPlugin`、`MiddlewarePlugin`。
## 开发者指南
- `docs/CODEBASE_GUIDE.md`解释了在哪里添加检查、适配器行为、CLI功能和GUI/API行为。
- `docs/ISSUE_STARTING_POINTS.md`将每个公开的路线图问题映射到具体的代码库入口点。
## 文件结构
```
ProxyDoctor/
├── setup.sh ← 一次性设置（安装依赖、测试、构建）
├── run.sh ← 便捷启动器（cli、服务器、测试）
├── cmd/
│ ├── cli/ ← CLI应用程序（诊断、列出检查）
│ └── server/ ← HTTP API服务器（最小化、标准库仅限）+ Web GUI
├── core/
│ ├── engine/ ← 协调引擎（包含测试）
│ ├── check/ ← 结果类型和接口（包含测试）
│ ├── checks/ ← 内置诊断检查（public_ip、dns_resolve、tls_cert、port_scan、ipv6_leak）
│ ├── adapters/ ← 代理实现（直接、HTTP、HTTPS、SOCKS4、SOCKS5）
│ ├── plugin/ ← 插件系统接口和生命周期管理器
│ ├── plugins/ ← 插件实现（route_trace、mcp_server）
│ └── utils/ ← 共享帮助程序（代理URL解析）
├── go.mod, go.sum ← Go模块
├── README.md
├── ARCHITECTURE.md
├── CHANGELOG.md
├── NEXT_STEPS.md
└── VERSION
```
## 内置检查
| 检查 | 类别 | 描述 |
|---|---|---|
| `public_ip` | 网络 | 通过ipify.org、icanhazip.com、ifconfig.me检测公共IP地址 |
| `dns_resolve` | 网络 | 通过当前连接将主机名解析为IP地址 |
| `tls_certificate` | TLS | 验证TLS证书（颁发者、过期、密码套件、TLS版本） |
| `port_connectivity` | 网络 | 测试端口80、443、8080、8443的TCP连接性 |
| `ipv6_leak` | 泄漏 | 检测配置的代理/隧道是否绕过IPv6流量并暴露系统的真实公共IPv6地址 |
## 插件检查
| 检查 | 类别 | 插件ID | 描述 |
|---|---|---|---|
| `route_trace` | 网络 | `route_trace` | 跟踪到目标的网络跳转并用国家信息注释公共跳转 |
## 代理输入格式
CLI和GUI接受多种格式的代理URL：
| 格式 | 示例 | 备注 |
|---|---|---|
| `scheme://host:port` | `socks5://77.245.76.107:1080` | 从方案自动检测类型 |
| `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中提取凭据 |
## 贡献
欢迎贡献！请阅读我们的[贡献指南](CONTRIBUTING.md)以了解如何开始。
- 🐛 [报告错误](https://github.com/francomano/ProxyDoctor/issues/new?template=bug_report.md)
- ✨ [请求功能](https://github.com/francomano/ProxyDoctor/issues/new?template=feature_request.md)
- 💡 [优秀的第一个问题](https://github.com/francomano/ProxyDoctor/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
请在贡献之前阅读我们的[行为准则](CODE_OF_CONDUCT.md)。
## 项目活动
<p align="center">
<a href="https://github.com/francomano/ProxyDoctor/stargazers"><img src="https://img.shields.io/github/stars/francomano/ProxyDoctor?style=for-the-badge&color=yellow&label=Stars" alt="Stars"></a>
<a href="https://github.com/francomano/ProxyDoctor/network/members"><img src="https://img.shields.io/github/forks/francomano/ProxyDoctor?style=for-the-badge&color=green&label=Forks" alt="Forks"></a>
<a href="https://github.com/francomano/ProxyDoctor/issues"><img src="https://img.shields.io/github/issues/francomano/ProxyDoctor?style=for-the-badge&color=red&label=Issues" alt="Issues"></a>
<a href="https://github.com/francomano/ProxyDoctor/pulls"><img src="https://img.shields.io/github/pulls/francomano/ProxyDoctor?style=for-the-badge&color=purple&label=PRs" alt="Pull Requests"></a>
<a href="https://github.com/francomano/ProxyDoctor/commits"><img src="https://img.shields.io/github/last-commit/francomano/ProxyDoctor?style=for-the-badge&color=blue" alt="Last Commit"></a>
<a href="https://github.com/francomano/ProxyDoctor"><img src="https://img.shields.io/github/license/francomano/ProxyDoctor?style=for-the-badge&color=orange" alt="License"></a>
</p>
## 已知问题/限制
- 可选的DNS泄漏、WebRTC泄漏、地理位置和IP声誉检查作为未来工作在NEXT_STEPS.md中跟踪。
