QUICKSTART

快速上手

全程约 15 分钟。卡住了？先看报错速查，或到社区提问。

源码部署（三步跑通）

1准备环境

以下软件必装，电商ERP / 零售ERP 基于 Spring Boot 4.1 单体架构：

JDK 17 — 运行时环境
MySQL 8 — 业务数据存储
Redis 7 — 热点缓存与登录态
Maven 3.9+ — 后端构建
Node.js 20+ — 前端构建（可选，用体验包可跳过）

# 确认安装版本
java -version
mysql --version
redis-server --version
mvn -v

2导入数据库

创建数据库后，将项目 docs/ 目录下的 SQL 脚本导入，然后检查 application.yml 中的连接配置：

mysql> CREATE DATABASE qihang-erp DEFAULT CHARSET utf8mb4;
$ mysql -uroot -p qihang-erp < docs/qihang-erp.sql

3构建并启动

$ mvn clean install
$ java -jar erp-api/target/erp-api.jar   # 后端 :8088
$ cd vue3 && npm install && npm run dev   # 前端 :88

默认账号

系统	数据库	默认账号	后端端口
🛒 电商ERP	`qihang-erp`	admin / QHerp@23	8088
🏪 零售ERP	`qihang-retail`	admin / QHerp@23	8088
📦 OMS	`qihang-oms`	admin / Andy@2025	8086
🌏 跨境ERP	`qihang-cb-erp`	admin / admin123	8080

⚠️ 首次登录后请立即修改默认密码。

演示包快速启动（免装环境）

🛒 电商ERP 微信小店版

预置微信小店通道——开店铺即有 AppKey，按指引接通真店后可跑真实订单。含完整演示数据。

🏪 零售ERP 体验包

无平台依赖，纯线下场景。商品档案 / 进销存 / POS 收银小票，适合实体店主评估。

三步跑起来

解压到任意目录 — 路径不要有中文或空格
双击启动脚本 — Windows 运行 start.bat，Mac/Linux 运行 start.sh，等 1~2 分钟
浏览器打开 — 访问 http://localhost（端口见包内说明），用默认账号登录

⚠️ 演示包用于快速评估，正式上线请自建部署或购买生产部署服务。

Docker 一键部署

一条命令跑通

前置条件：Docker 20+ 与 Docker Compose V2，至少 2GB 可用内存。

# 克隆仓库
$ git clone https://github.com/zeasin/qihang-erp-open.git
$ cd qihang-erp-open

# 一键启动（MySQL + Redis + 后端 + 前端）
$ docker compose up -d

# 查看日志
$ docker compose logs -f erp-api

# 停止
$ docker compose down

首次启动需初始化数据库，等待约 2 分钟直至日志出现 Started Application。

启动后第一件事

1️⃣ 先用演示数据逛一遍

系统内置了演示商品、订单、库存数据。登录后按「商品→订单→库存→报表」的顺序走一遍，了解核心流程。别急着接真店。

2️⃣ 微信小店版：接通真店

微信小店是唯一「开店即有 AppKey」的平台——不需要企业资质申请。按照接入指引 → 填入 AppKey 后，用你自己的真实订单跑全流程。

3️⃣ 试一下 AI 查数

电商 ERP 内置 11 个 AI 工具，用自然语言查经营数据。比如问「昨天哪个店铺卖得最好？」
需要在 application.yml 配置 DeepSeek API Key，详见下方。

4️⃣ 改掉默认密码

演示包内置测试账号（admin/QHerp@23），首次登录后立即修改密码。如果要对外开放访问，务必改密码 + 配置防火墙。

application.yml 关键配置

源码部署时需要核对的几个核心字段：

配置项	位置	说明	默认值
`spring.datasource.url`	数据源	MySQL 连接地址，含库名	`jdbc:mysql://localhost:3306/qihang-erp`
`spring.datasource.username`	数据源	MySQL 用户名	`root`
`spring.datasource.password`	数据源	MySQL 密码	按实际填写
`spring.data.redis.host`	Redis	Redis 地址	`localhost`
`spring.data.redis.port`	Redis	Redis 端口	`6379`
`spring.ai.deepseek.api-key`	AI 模块	DeepSeek API Key（可选）	空（AI 功能不启用）
`server.port`	服务端口	后端 HTTP 端口	`8088`

💡 找不到配置文件？
项目中有多个 application.yml，生效的是 erp-api/src/main/resources/ 下的那份。本地开发可复制为 application-local.yml 覆盖默认值，避免提交密码到 Git。

Nginx 反向代理配置

生产部署或本地联调前端时的标准 Nginx 配置：

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

    # 前端静态资源
    location / {
        root /path/to/erp-web/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # 后端 API 代理
    location /prod-api/ {
        proxy_pass http://127.0.0.1:8088/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # SSE 实时推送（必须关闭缓冲）
    location /api/sse/ {
        proxy_pass http://127.0.0.1:8088;
        proxy_buffering off;
        proxy_cache off;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        chunked_transfer_encoding off;
    }

    # AI 聊天流式响应
    location /api/ai/ {
        proxy_pass http://127.0.0.1:8088;
        proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

⚠️ SSE 必须关闭缓冲
proxy_buffering off 和 proxy_http_version 1.1 缺一不可，否则 AI 聊天和协助中心的实时消息推送会失效。

常见报错速查

Failed to obtain JDBC Connection

MySQL 未启动或连接信息不对：检查 application.yml 的地址、端口、账号密码，确认数据库已创建并导入了 SQL。

Unable to connect to Redis

Redis 未启动或密码不对。Linux 下 systemctl start redis；如设置了 requirepass，同步修改配置文件。

登录后页面空白 / 接口 404

F12 看 Network：多为 Nginx 未正确代理 /prod-api/。检查 proxy_pass 是否指向后端端口。

Maven 依赖下载失败

使用国内镜像：https://registry.npmmirror.com（npm 同理）。确认 JDK 是 17 而非 8/11。

AI 功能不生效

在 application.yml 配置 spring.ai.deepseek.api-key 后重启即可启用；RAG 知识库需另部署 pgvector。

端口被占用（Address already in use）

查占用进程：lsof -i:8088（Linux/Mac）或 netstat -ano | findstr 8088（Windows）。杀掉进程或改 server.port。

JDK 版本不对（UnsupportedClassVersionError）

项目要求 JDK 17。运行 java -version 确认。多 JDK 环境用 JAVA_HOME 环境变量切换。

Docker 启动后 MySQL 一直在重启

内存不足导致 MySQL OOM。Docker Desktop 建议分配至少 4GB 内存（Settings → Resources → Memory）。

前端页面样式加载不出来

Nginx 的 location / 未正确指向前端构建产物目录。确认 root 路径下有 dist/ 文件夹。

🛟

没找到答案？去问答社区提问，或到协助中心发起人工协助。

微信扫码登录