dekun
32c8f4b156
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>
251 lines
4.6 KiB
Markdown
251 lines
4.6 KiB
Markdown
# 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;
|
|
}
|
|
}
|
|
```
|