Files

T

dekun e797d188ee Switch production deployment from Docker to PM2 on Ubuntu.

Add Express gateway, ecosystem config, and one-click install with native PostgreSQL, Node, and Python venv on port 23566.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-28 11:52:20 +08:00

3.8 KiB

Raw Blame History

Ubuntu PM2 部署文档

中学成绩档案系统 · 版权所有 © 马建军 · 微信 dekun03 · 手机 18364911125
仓库：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. 一键部署

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

脚本自动完成：

检测 root、Ubuntu、端口 23566
安装 PostgreSQL、Python3、Node.js 20、PM2
克隆/更新代码
生成 .env（随机密钥、数据库密码）
创建 PostgreSQL 用户与数据库
Python 虚拟环境 + pip install
前端 npm ci && npm run build
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

修改后重启：

cd /opt/secondary-school-grade-archive
pm2 reload deploy/pm2/ecosystem.config.cjs --update-env

5. 常用命令

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（可选）

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. 防火墙

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. 自定义参数

WEB_PORT=23566 INSTALL_DIR=/opt/secondary-school-grade-archive bash deploy/install.sh

11. 版权

见 LICENSE · COPYRIGHT.md
技术支持：微信 dekun03 · 手机 18364911125

3.8 KiB Raw Blame History Unescape Escape