开源电商ERP部署实战：从裸服务器到正式上线只需6步

很多朋友在 GitHub 上 Star 了项目、clone 了代码，然后卡在了「怎么跑起来」这一步。这篇文章以启航电商 ERP v4.1为例，把一次真实的生产部署过程完整记录下来。整个过程熟练之后大约 30-60 分钟。零售 ERP 和 OMS 的部署流程几乎一致，只是数据库名和端口略有差异。

💡 如果你只是想先体验功能，不必折腾环境：一键演示包免装 Java/MySQL/Redis，解压即用。本文面向的是准备上生产环境的同学。

第 0 步：准备工作清单

服务器建议 2核4G 起、50G 数据盘，CentOS 7+/Ubuntu 20+ 均可。日订单上千或多系统同机时选 4核8G。

第 1 步：安装基础环境

# Ubuntu/Debian 示例
sudo apt update
sudo apt install -y openjdk-17-jdk maven mysql-server redis-server nginx
# Node 20 使用 nvm 安装
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20

CentOS 用户可用 yum/dnf 安装对应包，或使用宝塔面板简化操作。java -version 输出包含 17 即为正确——这是新手最容易翻车的点（默认装了 JDK 8）。

第 2 步：初始化数据库

mysql -uroot -p
mysql> CREATE DATABASE `qihang-erp` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
mysql> exit;
# 导入项目 docs 目录下的 SQL 脚本
mysql -uroot -p qihang-erp < docs/qihang-erp.sql

然后编辑 erp-api/src/main/resources/application.yml，把数据源地址、账号密码改成你的实际值；Redis 有密码的话同步修改 spring.data.redis.password。

第 3 步：打包并启动后端

git clone https://gitee.com/qiliping/qihang-erp-open.git
cd qihang-erp-open
mvn clean install -DskipTests
java -jar erp-api/target/erp-api.jar   # 默认监听 8088

看到 Spring 启动完成日志后，curl http://127.0.0.1:8088 有响应即成功。生产环境建议注册成 systemd 服务：

[Unit]
Description=qihang-erp
After=syslog.target network.target

[Service]
User=www
ExecStart=/usr/bin/java -jar /opt/qihang-erp/erp-api.jar
SuccessExitStatus=143
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

第 4 步：构建前端

cd vue3        # v4.1 新版前端（Vue3 + TS + Vite）
npm install --registry=https://registry.npmmirror.com
npm run build  # 产物在 vue3/dist/

把 dist 目录上传到服务器，例如 /opt/qihang-erp/web。

第 5 步：Nginx 配置（含 SSE 关键参数）

这是最多人踩坑的一步。v4.1 的实时消息推送基于 SSE，Nginx 默认的缓冲机制会导致消息「卡住不弹」，必须加上以下三项：

server {
    listen 80;
    server_name erp.yourdomain.com;

    location / {
        root /opt/qihang-erp/web;
        try_files $uri $uri/ /index.html;
        index index.html;
    }

    location /prod-api/ {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # ↓↓↓ SSE 三件套，缺一不可 ↓↓↓
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_read_timeout 1800s;

        proxy_pass http://127.0.0.1:8088/;
    }
}

配好后记得申请 SSL 证书启用 HTTPS（Let's Encrypt 免费）——浏览器对非 HTTPS 页面的通知能力有限制。

第 6 步：登录验证与初始化

1. 浏览器访问域名，使用默认账号登录：admin / QHerp@23
2. 立即修改默认密码
3. 进入「系统设置」核对部门/角色/用户
4. 添加店铺并完成平台授权（需要各平台的 AppKey）
5. 建立商品库，绑定店铺商品 SKU
6. 配置定时拉单任务，跑通第一张自动同步的订单 🎉

三个最常见的报错排查

① Failed to obtain JDBC Connection

MySQL 连不上。按顺序检查：服务是否启动（systemctl status mysql）→ 账号密码是否正确 → 是否允许该主机连接（远程 MySQL 需要授权）。90% 是 yml 里密码没改。

② Unable to connect to Redis

Redis 未启动或设了 requirepass 但配置文件没同步密码。云 Redis 还要检查白名单。

③ 打包后访问接口 404 / 登录后页面空白

F12 看 Network：请求路径是 /prod-api/xxx 却返回 Nginx 404，说明代理没生效。确认 location /prod-api/ 的 proxy_pass 以 / 结尾且指向正确的后端端口。

进阶：Docker 一键起环境

如果服务器干净，也可以用 Docker Compose 先拉起 MySQL + Redis，再运行应用 JAR。社区仓库持续补充编排文件，欢迎 PR。