dekun
521a0fc66f
Proxy is optional via manual env vars only; update.sh also drops quiet pip/npm flags. Co-authored-by: Cursor <cursoragent@cursor.com>
173 lines
4.4 KiB
Markdown
173 lines
4.4 KiB
Markdown
# Ubuntu PM2 部署文档
|
||
|
||
> **中学成绩档案系统** · 版权所有 © 马建军 · 微信 **dekun03** · 手机 **18364911125**
|
||
> 仓库：[https://git.bz121.com/dekun/secondary-school-grade-archive.git](https://git.bz121.com/dekun/secondary-school-grade-archive.git)
|
||
|
||
---
|
||
|
||
## 1. 部署方式
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 方式 | **PM2**（非 Docker） |
|
||
| 系统 | Ubuntu 20.04 / 22.04 / 24.04 |
|
||
| 用户 | **root** |
|
||
| 目录 | `/opt/secondary-school-grade-archive` |
|
||
| 端口 | **23566**（Web + API 统一入口） |
|
||
| 反向代理 | **不包含**，请自行配置 |
|
||
|
||
### 架构
|
||
|
||
```
|
||
浏览器 → :23566 (PM2: grade-web, Express 静态 + /api 反代)
|
||
└──→ 127.0.0.1:8000 (PM2: grade-api, Uvicorn)
|
||
└──→ PostgreSQL (本机)
|
||
└──→ uploads/
|
||
└──→ Ollama (本机可选, :11434)
|
||
```
|
||
|
||
PM2 进程：
|
||
|
||
| 名称 | 说明 |
|
||
|------|------|
|
||
| `grade-api` | FastAPI / Uvicorn |
|
||
| `grade-web` | 前端静态资源 + `/api` 反向代理 |
|
||
|
||
---
|
||
|
||
## 2. 环境要求
|
||
|
||
- CPU 2 核+，内存 4 GB+（OCR 建议 8 GB）
|
||
- 磁盘 15 GB+
|
||
- 可访问 Git 仓库与 npm / PyPI
|
||
|
||
---
|
||
|
||
## 3. 一键部署
|
||
|
||
```bash
|
||
git clone https://git.bz121.com/dekun/secondary-school-grade-archive.git /opt/secondary-school-grade-archive
|
||
cd /opt/secondary-school-grade-archive
|
||
chmod +x deploy/*.sh
|
||
bash deploy/install.sh
|
||
```
|
||
|
||
脚本自动完成：
|
||
|
||
1. 检测 root、Ubuntu、端口 23566
|
||
2. 安装 PostgreSQL、Python3、Node.js 20、PM2
|
||
3. 克隆/更新代码
|
||
4. 生成 `.env`（随机密钥、数据库密码）
|
||
5. 创建 PostgreSQL 用户与数据库
|
||
6. Python 虚拟环境 + `pip install`
|
||
7. 前端 `npm ci && npm run build`
|
||
8. `pm2 start` 并设置开机自启
|
||
|
||
部署成功后访问：**`http://<服务器IP>:23566`**
|
||
|
||
---
|
||
|
||
## 4. 环境变量（`.env`）
|
||
|
||
| 变量 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| `WEB_PORT` | 23566 | 对外 Web 端口 |
|
||
| `API_PORT` | 8000 | 内部 API 端口 |
|
||
| `DATABASE_URL` | 自动生成 | PostgreSQL 连接 |
|
||
| `SECRET_KEY` | 自动生成 | JWT 密钥 |
|
||
| `UPLOAD_DIR` | `.../uploads` | 错题图片目录 |
|
||
| `OLLAMA_BASE_URL` | `http://127.0.0.1:11434` | 本地 Ollama |
|
||
|
||
修改后重启：
|
||
|
||
```bash
|
||
cd /opt/secondary-school-grade-archive
|
||
pm2 reload deploy/pm2/ecosystem.config.cjs --update-env
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 常用命令
|
||
|
||
```bash
|
||
cd /opt/secondary-school-grade-archive
|
||
|
||
pm2 status # 进程状态
|
||
pm2 logs # 全部日志
|
||
pm2 logs grade-api # 后端日志
|
||
pm2 logs grade-web # 网关日志
|
||
|
||
bash deploy/update.sh # 拉代码 + 重建 + 重启
|
||
bash deploy/backup.sh # 备份数据库与 uploads
|
||
bash deploy/uninstall.sh # 停止 PM2 服务
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Ollama（可选）
|
||
|
||
```bash
|
||
curl -fsSL https://ollama.com/install.sh | sh
|
||
ollama pull qwen2.5:7b
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 反向代理（自行配置）
|
||
|
||
将域名/HTTPS 流量转发到 **`http://127.0.0.1:23566`** 即可。
|
||
使用 HTTPS 后请更新 `.env` 中 `CORS_ORIGINS`。
|
||
|
||
---
|
||
|
||
## 8. 防火墙
|
||
|
||
```bash
|
||
ufw allow 22/tcp
|
||
ufw allow 23566/tcp
|
||
ufw enable
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 故障排查
|
||
|
||
| 现象 | 处理 |
|
||
|------|------|
|
||
| 无法访问 | `pm2 status` · `ss -tlnp \| grep 23566` |
|
||
| 502 / API 错误 | `pm2 logs grade-api` |
|
||
| 数据库连接失败 | `systemctl status postgresql` · 检查 `.env` 中 `DATABASE_URL` |
|
||
| 前端空白 | 确认 `frontend/dist` 存在 · `pm2 logs grade-web` |
|
||
|
||
---
|
||
|
||
## 10. 自定义参数
|
||
|
||
```bash
|
||
WEB_PORT=23566 INSTALL_DIR=/opt/secondary-school-grade-archive bash deploy/install.sh
|
||
|
||
# 使用官方 PyPI（海外服务器可去掉国内镜像）
|
||
PIP_MIRROR=https://pypi.org/simple bash deploy/install.sh
|
||
```
|
||
|
||
### 网络代理（可选，脚本内不内置）
|
||
|
||
一键部署**不会**自动配置代理。无代理环境可直接运行，不会因代理报错。
|
||
|
||
若本机网络需走代理，请在**执行安装前**手动 export（仅当前终端生效）：
|
||
|
||
```bash
|
||
export HTTP_PROXY=http://你的代理地址:端口
|
||
export HTTPS_PROXY=http://你的代理地址:端口
|
||
bash deploy/install.sh
|
||
```
|
||
|
||
不设置则不走代理。`pip install` 会**显示完整下载/安装进度**，不再静默。
|
||
|
||
---
|
||
|
||
## 11. 版权
|
||
|
||
见 [LICENSE](../LICENSE) · [COPYRIGHT.md](../COPYRIGHT.md)
|
||
技术支持：微信 **dekun03** · 手机 **18364911125**
|