# 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