# 部署文档

> 代码仓库：[https://git.bz121.com/dekun/crypto-pre-trade-system.git](https://git.bz121.com/dekun/crypto-pre-trade-system.git)

本文档说明如何在 **Ubuntu 服务器**上使用 **PM2** 守护进程部署本系统。

---

## 部署环境要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Ubuntu 20.04 / 22.04 / 24.04 |
| 运行用户 | root |
| 安装路径 | `/opt/crypto-pre-trade-system` |
| 进程守护 | PM2 |
| Python | 3.10+（虚拟环境） |
| Node.js | 18+（仅构建前端时使用） |
| 访问端口 | **1125** |

---

## 一键部署（推荐）

以 **root** 用户登录服务器，执行：

```bash
# 首次部署：克隆仓库并运行安装脚本
git clone https://git.bz121.com/dekun/crypto-pre-trade-system.git /opt/crypto-pre-trade-system
cd /opt/crypto-pre-trade-system
bash deploy/install.sh
```

脚本会自动完成：

1. 安装系统依赖（git、python3、nodejs、pm2）
2. 创建 Python 虚拟环境并安装后端依赖
3. 构建前端静态资源
4. 通过 PM2 启动服务并设置开机自启
5. 执行健康检查

部署完成后访问：**http://\<服务器IP\>:1125**

---

## 更新部署

代码有更新时，在服务器上重新执行安装脚本即可：

```bash
cd /opt/crypto-pre-trade-system
bash deploy/install.sh
```

脚本会自动 `git pull`、重新构建前端、重启 PM2 进程。

---

## 手动部署步骤

若需手动逐步部署，按以下步骤操作：

### 1. 克隆仓库

```bash
git clone https://git.bz121.com/dekun/crypto-pre-trade-system.git /opt/crypto-pre-trade-system
cd /opt/crypto-pre-trade-system
```

### 2. 安装系统依赖

```bash
apt-get update
apt-get install -y git python3 python3-venv python3-pip curl

# Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs

# PM2
npm install -g pm2
```

### 3. 后端虚拟环境

```bash
cd /opt/crypto-pre-trade-system/backend
python3 -m venv venv
venv/bin/pip install -r requirements.txt
mkdir -p data
```

### 4. 构建前端

```bash
cd /opt/crypto-pre-trade-system/frontend
npm install
npm run build
```

### 5. PM2 启动

```bash
cd /opt/crypto-pre-trade-system
mkdir -p logs
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup systemd -u root --hp /root
```

---

## PM2 常用命令

```bash
pm2 status                      # 查看进程状态
pm2 logs crypto-pre-trade       # 查看实时日志
pm2 restart crypto-pre-trade    # 重启服务
pm2 stop crypto-pre-trade       # 停止服务
pm2 delete crypto-pre-trade     # 删除进程
```

日志文件位置：

- 标准输出：`/opt/crypto-pre-trade-system/logs/pm2-out.log`
- 错误输出：`/opt/crypto-pre-trade-system/logs/pm2-error.log`

---

## 架构说明

生产环境采用 **单进程单端口** 模式：

```
PM2 → uvicorn (0.0.0.0:1125)
        ├── /api/*     → FastAPI 后端接口
        └── /*         → Vue3 前端静态资源（frontend/dist）
```

- 前端构建产物由 FastAPI 直接托管，无需额外 Nginx
- SQLite 数据库文件：`/opt/crypto-pre-trade-system/backend/data/pretrade.db`
- 重启服务不丢失数据

---

## 防火墙

若服务器开启了防火墙，需放行 1125 端口：

```bash
# ufw
ufw allow 1125/tcp

# firewalld
firewall-cmd --permanent --add-port=1125/tcp
firewall-cmd --reload
```

---

## 重置数据库

```bash
pm2 stop crypto-pre-trade
rm /opt/crypto-pre-trade-system/backend/data/pretrade.db
pm2 start crypto-pre-trade
```

重启后系统自动重建表结构并写入默认数据。

---

## 故障排查

| 现象 | 排查方式 |
|------|---------|
| 无法访问 | `pm2 status` 确认进程 online；`curl http://127.0.0.1:1125/api/health` |
| 502 / 连接拒绝 | 检查防火墙是否放行 1125 端口 |
| 前端白屏 | 确认 `frontend/dist` 存在；重新 `npm run build` |
| API 报错 | `pm2 logs crypto-pre-trade --lines 50` |
| 数据库问题 | 检查 `backend/data/` 目录权限 |

---

## 本地开发 vs 生产部署

| | 本地开发 | 生产部署 |
|---|---------|---------|
| 后端 | `uvicorn --reload --port 8000` | PM2 + uvicorn `:1125` |
| 前端 | `npm run dev :1125`（代理到 8000） | `npm run build`，由 FastAPI 托管 |
| 访问 | http://localhost:1125 | http://\<服务器IP\>:1125 |

本地开发说明见 [README.md](./README.md)。