first commit

2026-05-28 21:43:23 +08:00
commit 1d5c97904f
33 changed files with 5250 additions and 0 deletions
@@ -0,0 +1,193 @@
+# 部署文档
+
+> 代码仓库：[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)。