Initial release: CPCHECK cloud port detection tool

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>
2026-06-16 15:24:40 +08:00
commit 32c8f4b156
16 changed files with 1351 additions and 0 deletions
@@ -0,0 +1,145 @@
+# 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