CPCHECK - 云服务器端口检测工具

CPCHECK 是一款面向云服务器的端口检测工具，提供 Web 界面，支持 TCP/UDP 端口检测，并能快速定位端口问题是「未开放」「防火墙拦截」还是「被墙/网络过滤」。

功能特性

• TCP/UDP 端口检测 — 输入域名或 IP + 端口，一键检测
• 智能问题诊断 — 自动分析并给出结论：
  • 端口开放，服务正常可达
  • 端口未开放（目标无服务监听）
  • 可能被防火墙拦截（主机可达但端口超时）
  • 可能被墙或上游网络过滤（主机不可达 + 端口超时）
  • DNS 解析失败
  • UDP 状态不确定（协议特性）
• Web 界面 — 简洁现代的前端，实时展示检测结果与详情
• 一键部署 — Ubuntu 下 root 用户运行部署脚本即可完成安装

系统要求

• 操作系统: Ubuntu（仅支持 Linux，不支持 Windows）
• Python: >= 3.10
• 权限: root 用户
• 端口: 5230（Web 服务）

快速开始

# 克隆仓库
git clone https://git.bz121.com/dekun/cpcheck.git
cd cpcheck

# 一键部署（需 root）
sudo bash deploy/install.sh

部署完成后访问: http://<服务器IP>:5230

详细部署说明请参阅 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"
}

响应示例:

{
  "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

运维命令

pm2 status              # 查看服务状态
pm2 logs cpcheck        # 查看日志
pm2 restart cpcheck     # 重启服务
pm2 stop cpcheck        # 停止服务

运行测试

cd /opt/cpcheck
venv/bin/python -m pytest tests/ -v
# 或使用 unittest
venv/bin/python -m unittest discover -s tests -v

许可证

MIT License