盒木ERP系统

一、部署前置准备

1.1 环境要求

根据官方README，部署盒木ERP社区版需要以下环境：

1.2 获取项目源码

项目托管在 Gitee 和 GitHub 两个平台：

Gitee（国内推荐，速度更快）：

git clone https://gitee.com/himool/erp.git
cd erp

GitHub：

git clone https://github.com/himool/HimoolERP.git
cd HimoolERP

1.3 准备 MySQL 数据库

登录 MySQL 创建数据库（注意字符集必须为 utf8mb4）：

CREATE DATABASE erp_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

建议创建专用用户：

CREATE USER 'erpuser'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON erp_db.* TO 'erpuser'@'localhost';
FLUSH PRIVILEGES;

二、后端部署详细步骤

步骤 1：安装 Python 依赖

在项目根目录执行：

python -m pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

使用阿里云镜像源可以显著提升国内下载速度。如果安装过程中出现某些包编译错误，请检查系统是否安装了必要的编译工具（如 build-essential、python3-dev、default-libmysqlclient-dev）。

步骤 2：生成配置文件

执行项目提供的配置生成脚本：

python tools/create_configs.py

执行后会生成配置文件，按提示填写数据库连接信息（数据库地址、端口、用户名、密码、数据库名）。如果使用默认端口 8000 作为后端服务端口，直接回车即可；如使用其他端口，需相应修改-3。

步骤 3：数据库迁移

创建数据库表结构：

python manage.py makemigrations
python manage.py migrate

makemigrations 生成迁移文件，migrate 将迁移应用到数据库。如果报错，优先检查数据库连接配置是否正确、MySQL 服务是否运行中。

步骤 4：创建初始用户

执行项目提供的脚本创建管理员账户：

python manage.py runscript create_user

该脚本会创建初始登录账号，具体用户名和密码请查看脚本输出或后续登录时根据提示确认。

步骤 5：启动后端服务（开发模式）

python manage.py runserver

默认监听 http://127.0.0.1:8000。可以通过访问 http://127.0.0.1:8000/api/schema/swagger-ui/ 验证 API 文档是否正常加载，以此判断后端是否启动成功。

三、前端部署详细步骤

步骤 1：安装 Vue CLI

npm install -g @vue/cli

步骤 2：安装前端依赖

进入 frontend 目录：

cd frontend
npm install

注意：项目的 package.json 中的 scripts 可能为 Linux 写法，如果在 Windows 环境下运行报错，可以手动将 "serve" 修改为 "vue-cli-service serve"-3-13。

步骤 3：启动前端开发服务

npm run serve

启动后浏览器访问前端地址（通常是 http://localhost:8080）。

步骤 4：前后端联调验证

如果前端页面能正常打开但出现服务器错误，说明前后端未正确对接。检查：

• 后端服务是否正常运行在预期端口
• 前端配置的 API 代理地址是否指向后端正确端口
• 浏览器控制台是否有 CORS 跨域错误

四、生产环境部署（uWSGI + Nginx）

4.1 后端生产部署

安装 uWSGI：

pip install uwsgi

使用项目提供的 uWSGI 配置启动：

uwsgi --ini [项目路径]/configs/uwsgi.ini

如果配置文件中的路径与实际部署路径不一致，需要先修改 uwsgi.ini 中的 chdir 和 module 等参数。

4.2 前端生产构建

进入 frontend 目录执行构建：

cd frontend
npm run build

构建产物会生成在 dist 目录中，将 Nginx 的网站根目录指向该目录即可。

4.3 Nginx 配置

项目提供了 Nginx 配置模板，位于 /configs/nginx 目录下。将该配置复制到 Nginx 站点配置目录，修改其中的 server_name、root 路径和 proxy_pass 后端地址，然后重载 Nginx：

sudo nginx -t          # 测试配置语法
sudo systemctl reload nginx

五、常见问题排查

前端启动报错（Windows 环境）：package.json 的 scripts 为 Linux 写法。将 "serve": "vue-cli-service serve" 确认或修改为 Windows 兼容格式，同时确保 vue 和 vue-template-compiler 版本一致（建议都使用 ^2.7.16）。

数据库连接失败：检查 MySQL 服务状态、create_configs.py 生成的配置文件中数据库信息是否正确、MySQL 用户是否有远程/本地访问权限。

前端页面能打开但报“服务器错误”：前后端未正确对接。确认后端 API 可访问（测试 Swagger UI），检查前端代理配置或跨域设置。

PDA 功能无法使用：PDA 打印功能需要指定型号的硬件，普通手机或平板无法直接使用该功能，需联系盒木科技购买适配设备。

六、日常运维建议

定期备份数据库：使用 mysqldump -u erpuser -p erp_db > backup_$(date +%Y%m%d).sql 定时备份。

更新项目代码：从 Gitee/GitHub 拉取最新代码后，需要重新执行 pip install -r requirements.txt（依赖可能更新）、python manage.py migrate（数据库结构可能变更），然后重启后端和前端服务。

日志监控：后端运行日志和 uWSGI 日志需定期查看，及时发现异常访问或接口报错。

七、重要合规提示

盒木ERP社区版采用 GPL-3.0 协议，使用前需注意以下要点：

个人学习免费：个人用户可免费下载源码学习使用。

商业使用需授权：禁止任何单位或个人修改软件后再次发行；商业使用需获得盒木科技授权，否则将承担法律风险。

二次开发出售需授权：如果计划将系统或源码二次开发后出售给其他客户，必须事先联系盒木科技获得商业授权