dekun
32c8f4b156
Web-based TCP/UDP port checker with firewall/GFW diagnosis, PM2 deployment config, and Ubuntu one-click install script. Co-authored-by: Cursor <cursoragent@cursor.com>
146 lines
3.5 KiB
Markdown
146 lines
3.5 KiB
Markdown
# CPCHECK - 云服务器端口检测工具
|
||
|
||
CPCHECK 是一款面向云服务器的端口检测工具，提供 Web 界面，支持 TCP/UDP 端口检测，并能快速定位端口问题是「未开放」「防火墙拦截」还是「被墙/网络过滤」。
|
||
|
||
## 功能特性
|
||
|
||
- **TCP/UDP 端口检测** — 输入域名或 IP + 端口，一键检测
|
||
- **智能问题诊断** — 自动分析并给出结论：
|
||
- 端口开放，服务正常可达
|
||
- 端口未开放（目标无服务监听）
|
||
- 可能被防火墙拦截（主机可达但端口超时）
|
||
- 可能被墙或上游网络过滤（主机不可达 + 端口超时）
|
||
- DNS 解析失败
|
||
- UDP 状态不确定（协议特性）
|
||
- **Web 界面** — 简洁现代的前端，实时展示检测结果与详情
|
||
- **一键部署** — Ubuntu 下 root 用户运行部署脚本即可完成安装
|
||
|
||
## 系统要求
|
||
|
||
- **操作系统**: Ubuntu（仅支持 Linux，不支持 Windows）
|
||
- **Python**: >= 3.10
|
||
- **权限**: root 用户
|
||
- **端口**: 5230（Web 服务）
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://git.bz121.com/dekun/cpcheck.git
|
||
cd cpcheck
|
||
|
||
# 一键部署（需 root）
|
||
sudo bash deploy/install.sh
|
||
```
|
||
|
||
部署完成后访问: `http://<服务器IP>:5230`
|
||
|
||
详细部署说明请参阅 [DEPLOY.md](DEPLOY.md)。
|
||
|
||
## 使用方法
|
||
|
||
1. 打开浏览器访问 `http://<服务器IP>:5230`
|
||
2. 输入目标域名或 IP 地址
|
||
3. 输入端口号（1-65535）
|
||
4. 选择协议（TCP 或 UDP）
|
||
5. 点击「开始检测」，查看诊断结论
|
||
|
||
## 诊断逻辑说明
|
||
|
||
| 检测现象 | 诊断结论 |
|
||
|---------|---------|
|
||
| TCP 连接成功 | 端口开放 |
|
||
| TCP Connection Refused | 端口未开放 |
|
||
| TCP 超时 + 主机 Ping 可达 | 可能被防火墙拦截 |
|
||
| TCP 超时 + 主机 Ping 不可达 | 可能被墙或网络过滤 |
|
||
| DNS 解析失败 | 域名问题 |
|
||
| UDP 无响应 | 状态不确定（开放或被过滤） |
|
||
| UDP ICMP Port Unreachable | 端口未开放 |
|
||
|
||
## API 接口
|
||
|
||
### 健康检查
|
||
|
||
```
|
||
GET /api/health
|
||
```
|
||
|
||
### 端口检测
|
||
|
||
```
|
||
POST /api/check
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"host": "example.com",
|
||
"port": 443,
|
||
"protocol": "tcp"
|
||
}
|
||
```
|
||
|
||
响应示例:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"host": "example.com",
|
||
"port": 443,
|
||
"protocol": "tcp",
|
||
"resolved_ip": "93.184.216.34",
|
||
"port_status": "open",
|
||
"diagnosis": "port_open",
|
||
"diagnosis_message": "端口开放，服务正常可达",
|
||
"host_reachable": true,
|
||
"dns_ok": true,
|
||
"latency_ms": 45.2,
|
||
"details": ["DNS 解析成功: example.com -> 93.184.216.34", "..."],
|
||
"elapsed_ms": 1200.5
|
||
}
|
||
}
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
cpcheck/
|
||
├── app/
|
||
│ ├── main.py # FastAPI 应用入口
|
||
│ ├── detector.py # 端口检测与诊断逻辑
|
||
│ └── config.py # 配置
|
||
├── static/
|
||
│ ├── index.html # Web 前端页面
|
||
│ ├── css/style.css
|
||
│ └── js/app.js
|
||
├── deploy/
|
||
│ └── install.sh # 一键部署脚本
|
||
├── tests/
|
||
│ └── test_detector.py # 单元测试
|
||
├── ecosystem.config.js # PM2 配置
|
||
├── requirements.txt
|
||
├── README.md
|
||
└── DEPLOY.md
|
||
```
|
||
|
||
## 运维命令
|
||
|
||
```bash
|
||
pm2 status # 查看服务状态
|
||
pm2 logs cpcheck # 查看日志
|
||
pm2 restart cpcheck # 重启服务
|
||
pm2 stop cpcheck # 停止服务
|
||
```
|
||
|
||
## 运行测试
|
||
|
||
```bash
|
||
cd /opt/cpcheck
|
||
venv/bin/python -m pytest tests/ -v
|
||
# 或使用 unittest
|
||
venv/bin/python -m unittest discover -s tests -v
|
||
```
|
||
|
||
## 许可证
|
||
|
||
MIT License
|