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