Files

T

dekun 32c8f4b156 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

4.6 KiB

Raw Permalink Blame History

CPCHECK 部署文档

本文档详细说明如何在 Ubuntu 服务器上部署 CPCHECK 端口检测工具。

环境要求

项目	要求
操作系统	Ubuntu 20.04 / 22.04 / 24.04
用户权限	root
Python	>= 3.10
安装路径	/opt/cpcheck
服务端口	5230
进程管理	PM2

注意: 本工具仅支持 Ubuntu Linux，不支持 Windows 及其他发行版。

一键部署

1. 获取代码

git clone https://git.bz121.com/dekun/cpcheck.git
cd cpcheck

2. 执行部署脚本

sudo bash deploy/install.sh

部署脚本会自动完成以下操作:

检测 Ubuntu 系统和 root 权限
安装系统依赖（python3、ping、curl 等）
安装 Node.js 和 PM2（如未安装）
复制代码到 /opt/cpcheck
创建 Python 虚拟环境并安装依赖
通过 PM2 启动服务
配置 PM2 开机自启
放行防火墙端口 5230（如 UFW 已启用）
执行健康检查

3. 验证部署

# 检查 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

手动部署

如需手动部署，按以下步骤操作:

# 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

更新部署

cd /path/to/cpcheck
git pull
sudo bash deploy/install.sh

部署脚本会自动重启服务。

防火墙配置

UFW

ufw allow 5230/tcp
ufw reload

iptables

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 命令

pm2 status              # 查看所有进程状态
pm2 logs cpcheck        # 实时查看日志
pm2 logs cpcheck --lines 100  # 查看最近 100 行
pm2 restart cpcheck     # 重启服务
pm2 stop cpcheck        # 停止服务
pm2 delete cpcheck      # 删除进程
pm2 monit               # 监控面板

查看日志

# PM2 日志
pm2 logs cpcheck

# 日志文件
tail -f /opt/cpcheck/logs/out.log
tail -f /opt/cpcheck/logs/error.log

修改配置

编辑 /opt/cpcheck/app/config.py 可修改超时时间等参数:

CONNECT_TIMEOUT = 5   # TCP 连接超时（秒）
UDP_TIMEOUT = 5       # UDP 检测超时（秒）
PING_TIMEOUT = 3      # Ping 超时（秒）

修改后重启: pm2 restart cpcheck

故障排查

服务无法启动

# 查看错误日志
pm2 logs cpcheck --err

# 手动测试启动
cd /opt/cpcheck
venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 5230

端口被占用

# 查看 5230 端口占用
ss -tlnp | grep 5230

# 或
lsof -i :5230

检测功能异常

# 确认 ping 命令可用
ping -c 1 8.8.8.8

# 确认 DNS 解析正常
nslookup example.com

# 手动测试 TCP 连接
nc -zv example.com 80

PM2 开机不自启

pm2 save
pm2 startup systemd -u root --hp /root
# 执行输出的命令

卸载

pm2 stop cpcheck
pm2 delete cpcheck
pm2 save
rm -rf /opt/cpcheck

安全建议

建议通过 Nginx 反向代理并配置 HTTPS
限制访问 IP 或使用认证（如需公网暴露）
定期更新系统和依赖包
监控服务器资源使用情况

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;
    }
}

4.6 KiB Raw Permalink Blame History