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>

DEPLOY.md

@@ -0,0 +1,250 @@
+# CPCHECK 部署文档
+
+本文档详细说明如何在 Ubuntu 服务器上部署 CPCHECK 端口检测工具。
+
+## 环境要求
+
+| 项目 | 要求 |
+|------|------|
+| 操作系统 | Ubuntu 20.04 / 22.04 / 24.04 |
+| 用户权限 | root |
+| Python | >= 3.10 |
+| 安装路径 | /opt/cpcheck |
+| 服务端口 | 5230 |
+| 进程管理 | PM2 |
+
+> **注意**: 本工具仅支持 Ubuntu Linux，不支持 Windows 及其他发行版。
+
+## 一键部署
+
+### 1. 获取代码
+
+```bash
+git clone https://git.bz121.com/dekun/cpcheck.git
+cd cpcheck
+```
+
+### 2. 执行部署脚本
+
+```bash
+sudo bash deploy/install.sh
+```
+
+部署脚本会自动完成以下操作:
+
+1. 检测 Ubuntu 系统和 root 权限
+2. 安装系统依赖（python3、ping、curl 等）
+3. 安装 Node.js 和 PM2（如未安装）
+4. 复制代码到 `/opt/cpcheck`
+5. 创建 Python 虚拟环境并安装依赖
+6. 通过 PM2 启动服务
+7. 配置 PM2 开机自启
+8. 放行防火墙端口 5230（如 UFW 已启用）
+9. 执行健康检查
+
+### 3. 验证部署
+
+```bash
+# 检查 PM2 服务状态
+pm2 status
+
+# 健康检查
+curl http://127.0.0.1:5230/api/health
+
+# 测试端口检测
+curl -X POST http://127.0.0.1:5230/api/check \
+  -H "Content-Type: application/json" \
+  -d '{"host":"example.com","port":80,"protocol":"tcp"}'
+```
+
+### 4. 访问 Web 界面
+
+浏览器打开: `http://<服务器公网IP>:5230`
+
+## 手动部署
+
+如需手动部署，按以下步骤操作:
+
+```bash
+# 1. 安装依赖
+apt-get update
+apt-get install -y python3 python3-venv python3-pip iputils-ping curl git
+
+# 2. 安装 Node.js 和 PM2
+curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+apt-get install -y nodejs
+npm install -g pm2
+
+# 3. 部署代码
+mkdir -p /opt/cpcheck
+cp -r . /opt/cpcheck/
+cd /opt/cpcheck
+
+# 4. 创建虚拟环境
+python3 -m venv venv
+venv/bin/pip install -r requirements.txt
+
+# 5. 创建日志目录
+mkdir -p logs
+
+# 6. 启动服务
+pm2 start ecosystem.config.js
+pm2 save
+pm2 startup systemd -u root --hp /root
+```
+
+## 更新部署
+
+```bash
+cd /path/to/cpcheck
+git pull
+sudo bash deploy/install.sh
+```
+
+部署脚本会自动重启服务。
+
+## 防火墙配置
+
+### UFW
+
+```bash
+ufw allow 5230/tcp
+ufw reload
+```
+
+### iptables
+
+```bash
+iptables -A INPUT -p tcp --dport 5230 -j ACCEPT
+```
+
+### 云服务商安全组
+
+在云服务商控制台的安全组/防火墙规则中，放行入站 TCP 5230 端口。
+
+## 目录结构（部署后）
+
+```
+/opt/cpcheck/
+├── app/                 # 后端代码
+├── static/              # 前端静态文件
+├── venv/                # Python 虚拟环境
+├── logs/                # PM2 日志
+│   ├── error.log
+│   └── out.log
+├── ecosystem.config.js  # PM2 配置
+└── requirements.txt
+```
+
+## 运维管理
+
+### 常用 PM2 命令
+
+```bash
+pm2 status              # 查看所有进程状态
+pm2 logs cpcheck        # 实时查看日志
+pm2 logs cpcheck --lines 100  # 查看最近 100 行
+pm2 restart cpcheck     # 重启服务
+pm2 stop cpcheck        # 停止服务
+pm2 delete cpcheck      # 删除进程
+pm2 monit               # 监控面板
+```
+
+### 查看日志
+
+```bash
+# PM2 日志
+pm2 logs cpcheck
+
+# 日志文件
+tail -f /opt/cpcheck/logs/out.log
+tail -f /opt/cpcheck/logs/error.log
+```
+
+### 修改配置
+
+编辑 `/opt/cpcheck/app/config.py` 可修改超时时间等参数:
+
+```python
+CONNECT_TIMEOUT = 5   # TCP 连接超时（秒）
+UDP_TIMEOUT = 5       # UDP 检测超时（秒）
+PING_TIMEOUT = 3      # Ping 超时（秒）
+```
+
+修改后重启: `pm2 restart cpcheck`
+
+## 故障排查
+
+### 服务无法启动
+
+```bash
+# 查看错误日志
+pm2 logs cpcheck --err
+
+# 手动测试启动
+cd /opt/cpcheck
+venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 5230
+```
+
+### 端口被占用
+
+```bash
+# 查看 5230 端口占用
+ss -tlnp | grep 5230
+
+# 或
+lsof -i :5230
+```
+
+### 检测功能异常
+
+```bash
+# 确认 ping 命令可用
+ping -c 1 8.8.8.8
+
+# 确认 DNS 解析正常
+nslookup example.com
+
+# 手动测试 TCP 连接
+nc -zv example.com 80
+```
+
+### PM2 开机不自启
+
+```bash
+pm2 save
+pm2 startup systemd -u root --hp /root
+# 执行输出的命令
+```
+
+## 卸载
+
+```bash
+pm2 stop cpcheck
+pm2 delete cpcheck
+pm2 save
+rm -rf /opt/cpcheck
+```
+
+## 安全建议
+
+1. 建议通过 Nginx 反向代理并配置 HTTPS
+2. 限制访问 IP 或使用认证（如需公网暴露）
+3. 定期更新系统和依赖包
+4. 监控服务器资源使用情况
+
+## Nginx 反向代理（可选）
+
+```nginx
+server {
+    listen 80;
+    server_name check.example.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:5230;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}
+```