# 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**