IDURAR ERP CRM 项目实战指南：基于 MERN 栈与 Ant Design 的开源 ERP/CRM 系统部署与架构解析

• 后端
• 前端
• 企业应用
• CRM

IDURAR 是一款免费开源（Fair-Code）的 ERP / CRM 系统，覆盖发票（Invoice）、报价（Quote）、付款（Payment）、客户（Customer）管理与基础会计能力，基于 Advanced MERN 技术栈（Node.js / Express.js / MongoDB / React.js）构建，前端采用 Ant Design（AntD）与 Redux 生态。本篇指南以项目官方 README 为骨架，结合 安装说明 与仓库源码，系统讲解其技术架构、核心业务模块、从零到一的完整部署流程，以及源码级的关键实现原理，帮助你快速在本机跑通系统并理解其设计脉络。

项目概览：一个什么样的 ERP / CRM

IDURAR 定位为"Simple To Use"（简单易用）的开源 ERP / CRM 软件，官方将其描述为Open Source ERP / CRM（Invoice / Quote / Accounting）Based on Advanced Mern Stack (Node.js / Express.js / MongoDb / React.js) with Ant Design (AntD) and Redux。它并非传统意义上"重"的 ERP，而是聚焦中小团队最常打交道的业务闭环：

• Invoice Management—— 发票管理
• Payment Management—— 付款 / 收款管理
• Quote Management—— 报价单管理
• Customer Management—— 客户（CRM 联系人）管理
• Ant Design Framework (AntD)—— 基于蚂蚁设计体系的前端 UI
• Mern Stack（Node.js / Express.js / MongoDb / React.js）—— 前后端统一的 JavaScript 技术栈

README 同时强调这是一个Fair-Code（公平代码）项目：IDURAR is Open "Fair-Code" Source ERP / CRM (Invoice / Inventory / Accounting / HR)，即在开放源码的同时保留商业化的合理边界。项目遵循 GNU Affero General Public License v3.0（AGPL-3.0）发布，并明确说明：允许免费用于个人或商业用途（Yes You can use IDURAR for free for personal or Commercial use）。

仓库中的实体证据

从仓库源码结构看，后端业务模型与 README 描述的能力一一对应。业务实体（appModels）目录 backend/src/models/appModels 下包含三个核心模型：

• Client.js—— 客户模型（name、phone、country、address、email、assigned 等字段）
• Invoice.js—— 发票模型（编号、年份、明细 items、税率、金额、付款状态、recurring 周期、converted 来源等字段）
• Payment.js—— 付款模型

值得注意的一个设计：后端路由并非手工逐个注册，而是通过 backend/src/models/utils/index.js 用glob动态扫描appModels目录下所有模型文件，自动生成routesList（实体名 + 控制器名），再在 appApi.js 中统一注册 RESTful 路由。这意味着新增一个业务模块只需新增模型文件并放置对应控制器，路由会自动生成，这是该项目"约定优于配置"思想的典型体现。

技术架构：前后端分离的 MERN 全栈

后端：Express + Mongoose

后端位于 backend 目录，核心入口在 backend/src/server.js。从源码可见以下关键事实：

• 使用dotenv加载.env与.env.local两个环境文件（require('dotenv').config({ path: '.env' })与.env.local）；
• 通过mongoose.connect(process.env.DATABASE)连接 MongoDB；
• 启动时通过globSync('./src/models/**/*.js')自动加载所有 Mongoose 模型；
• 监听端口默认8888（app.set('port', process.env.PORT || 8888)）；
• 强制要求 Node.js 版本 ≥ 20：源码中有一段版本检查逻辑，低于 20 会直接process.exit()并提示Please upgrade your node.js version at least 20 or greater。

在 backend/src/app.js 中可以看到后端中间件与路由的组织方式：

• 全局中间件：cors（允许跨域并携带凭证）、cookieParser、express.json、express.urlencoded、compression（gzip 压缩）；
• 路由挂载点：/api（认证路由 coreAuthRouter）、/api（需经过adminAuth.isValidAuthToken校验的核心 API 与 ERP 业务 API）、/download（PDF 下载）、/public（公共资源）；
• 404 兜底与生产环境错误处理集中在 backend/src/handlers/errorHandlers.js。

认证相关路由在 backend/src/routes/coreRoutes/coreAuth.js：提供/login、/forgetpassword、/resetpassword、/logout四个接口，登录后的业务 API 统一由adminAuth.isValidAuthToken中间件保护（实现见 backend/src/controllers/coreControllers/adminAuth）。

前端：React 18 + AntD 5 + Redux

前端位于 frontend 目录。从 frontend/package.json 可见其依赖：react^18.3.1、antd^5.14.1、@reduxjs/toolkit^2.2.1、react-redux^9.1.0、react-router-dom^6.22.0、vite^5.4.8，并声明"type": "module"（ESM）。注意：虽然 README 声称基于 CRA 脚手架，但当前仓库前端已迁移至Vite构建（见 frontend/vite.config.js），这一点以仓库实际内容为准。

前端 API 地址配置集中在 frontend/src/config/serverApiConfig.js：

• 开发模式下默认请求http://localhost:8888/api/（后端 8888 端口）；
• 生产模式或VITE_DEV_REMOTE=remote时，请求import.meta.env.VITE_BACKEND_SERVER + 'api/'；
• 登录令牌存储名为x-auth-token。

Vite 开发服务器（端口 3000）将/api前缀请求代理到后端（默认http://localhost:8888/），代理目标可通过环境变量VITE_BACKEND_SERVER覆盖，实现"前端连远程后端"的远程开发模式（对应npm run dev:remote脚本）。前端环境模板见 frontend/temp.env。

前端路由表在 frontend/src/router/routes.jsx 中定义，业务页面包括：/invoice（含/invoice/create、/invoice/read/:id、/invoice/update/:id、/invoice/pay/:id）、/quote、/payment、/customer、/settings、/profile等，与 README 声明的四大管理模块一一对应。

后端依赖速览（backend/package.json）

从 backend/package.json 可以还原后端技术选型：

其中 PDF 渲染采用Pug 模板引擎，模板文件（Invoice.pug、Quote.pug、Offer.pug、Payment.pug）位于 backend/src/pdf，下载路由见 backend/src/routes/coreRoutes/coreDownloadRouter.js，下载处理器在 backend/src/handlers/downloadHandler/downloadPdf.js。

从零部署：9 步本地跑通 IDURAR

README 的 Getting started 章节给出了完整的 9 步安装流程（详见 INSTALLATION-INSTRUCTIONS.md），本节将每一步展开并结合仓库源码补充说明。

Step 1：克隆仓库

git clone https://github.com/idurar/idurar-erp-crm.git cd idurar-erp-crm

Step 2：创建 MongoDB 账号与数据库集群

• 前往 MongoDB 官网注册账号；
• 创建一个新的数据库 / Cluster，并记录下"Connect to your application URI"（连接字符串）；
• 将连接串中的<password>替换为你自己的数据库密码；
• 将当前 IP 加入 MongoDB 的 IP 白名单（IP 变更时需要重新添加）。

Step 3：编辑环境变量文件

在 backend 目录下有一个.env文件，用于存放项目运行所需的环境变量。仓库中的 backend/.env 模板如下：

#DATABASE = "mongodb://localhost:27017" #RESEND_API = "your resend_api" #OPENAI_API_KEY = "your open_ai api key" JWT_SECRET= "your_private_jwt_secret_key" NODE_ENV = "production" OPENSSL_CONF='/dev/null' PUBLIC_SERVER_FILE="http://localhost:8888/"

各变量的作用（结合 backend/src/server.js 与 backend/src/setup/setupConfig.json 推断）：

注：server.js同时加载.env与.env.local，后者可用于覆盖本地专属配置且不提交到版本库。

Step 4：更新 MongoDB URI

在.env中找到以下行：

DATABASE="your-mongodb-uri"

将"your-mongodb-uri"替换为第 2 步中获得的真实连接字符串。若只是本地 MongoDB，可参考模板使用mongodb://localhost:27017（若需指定库名可追加数据库名，例如mongodb://localhost:27017/idurar）。

Step 5：安装后端依赖

cd backend npm install

npm install会按照 backend/package.json 安装全部依赖。注意该文件engines字段声明了node: 20.9.0、npm: 10.2.4，且server.js在启动时会检查 Node 主版本号，低于 20 会直接退出，请先确认环境版本。

Step 6：运行 Setup 脚本（初始化）

npm run setup

该命令对应node src/setup/setup.js，是数据库初始化的关键步骤。阅读 backend/src/setup/setup.js 源码，它实际完成四件事：

1. 创建初始管理员账号：生成默认管理员admin@admin.com（用户名 IDURAR / 密码admin123，通过newAdminPassword.generateHash(salt, 'admin123')进行加盐哈希），写入Admin与AdminPassword两个集合；
2. 写入默认设置：通过globSync('./src/setup/defaultSettings/**/*.json')扫描 backend/src/setup/defaultSettings 下所有 JSON 设置文件（含appSettings.json、companySettings.json、clientSettings.json、financeSettings.json、invoiceSettings.json、moneyFormatSettings.json、quoteSettings.json），批量写入Setting集合；
3. 创建默认税率：插入Tax 0%（taxValue: '0'）作为默认税种；
4. 创建默认付款方式：插入Default Payment（描述为Default Payment Mode (Cash, Wire Transfer)）。

👍 Admin created : Done! 👍 Settings created : Done! 👍 Taxes created : Done! 👍 PaymentMode created : Done! 🥳 Setup completed :Success!

初始化完成后，请牢记默认管理员账号密码（admin@admin.com/admin123），并建议登录后立即在个人设置中修改。

Step 7：启动后端服务器

npm run dev

该命令对应nodemon src/server.js --ignore public/（热重载开发模式）。启动成功后控制台会输出Express running → On PORT : 8888。如果想以常规方式运行（无热重载），可改用npm start（node src/server.js）。生产部署则使用NODE_ENV=production启动。

Step 8：安装前端依赖

另开一个终端窗口：

cd frontend npm install

Step 9：启动前端服务器

npm run dev

对应vite命令。启动后浏览器访问http://localhost:3000即可看到登录页面，使用第 6 步生成的管理员账号登录。

常见问题：OpenSSL 兼容错误

安装说明特别强调：若前端启动时遇到 OpenSSL 错误（error:0308010C:digital envelope routines::unsupported），原因是 Node.js 17 与部分 Webpack/OpenSSL 版本的兼容问题（对应 Node.js 与 Webpack 的公开 issue）。可尝试以下任一方案：

1. 升级到 Node.js v20（推荐，本项目engines也要求 Node 20）；
2. 启用 legacy OpenSSL provider：

# Unix-like（Linux / macOS / Git bash） export NODE_OPTIONS=--openssl-legacy-provider # Windows CMD set NODE_OPTIONS=--openssl-legacy-provider # Windows PowerShell $env:NODE_OPTIONS = "--openssl-legacy-provider"

设置后重新执行npm run dev。若仍有问题，可参考 StackOverflow 上关于ERR_OSSL_EVP_UNSUPPORTED的社区讨论（安装说明末尾给出了相关线索）。此外仓库的 backend/.env 中也提供了OPENSSL_CONF='/dev/null'这一缓解手段。

核心业务模块与数据模型

发票（Invoice）模块

从 backend/src/models/appModels/Invoice.js 可见发票模型的完整字段设计，这是理解整个业务的核心：

• 编号体系：number+year双字段（required: true），配合 backend/src/middlewares/inventory/generateUniqueNumber.js 生成唯一编号，体现"按年度编号"的会计惯例；
• 金额体系：items（明细数组：itemName / description / quantity / price / total）+taxRate、subTotal、taxTotal、total、discount、credit，金额计算工具见 backend/src/settings/useMoney.js（基于 currency.js 保证精度）；
• 状态机：paymentStatus枚举unpaid / paid / partially（未付/已付/部分付款）；status枚举draft / pending / sent / refunded / cancelled / on hold；另有isOverdue（是否逾期）、approved（是否审批）布尔标志；
• 关联关系：client（客户，autopopulate: true自动填充）、payment（付款记录数组）、converted（记录从 Quote/Offer 转换而来）；
• 周期发票：recurring枚举daily / weekly / monthly / annually / quarter；
• 附件：files数组与pdf字段（PDF 文件路径）。

发票的前端模块（frontend/src/modules/InvoiceModule）包含创建、表格、读取、更新、记录付款五个子模块；后端对应控制器在 backend/src/controllers/appControllers/invoiceController（含 create / read / update / remove / sendMail / summary / paginatedList / schemaValidate 等），其中sendMail.js负责通过邮件把发票发送给客户。

报价（Quote）模块

报价单与发票共享几乎相同的业务骨架，前端模块位于 frontend/src/modules/QuoteModule。特别之处在于：业务路由 appApi.js 中为quote额外注册了/quote/convert/:id接口（对应控制器中的convert方法），用于将报价单一键转换为发票；发票模型的converted字段正是为记录这一转换来源而设计（enum: ['quote', 'offer']）。

付款（Payment）模块

付款模块用于记录发票的实际收款情况，前端位于 frontend/src/modules/PaymentModule。发票模型中的payment数组与paymentStatus（unpaid / paid / partially）字段，即由该模块联动更新，形成"发票 → 收款 → 状态"的闭环。

客户（Customer）模块

客户模型 backend/src/models/appModels/Client.js 字段简洁：name（必填）、phone、country、address、email，以及createdBy/assigned（关联 Admin，用于记录创建人与归属销售）。前端页面位于 frontend/src/pages/Customer，配置见 frontend/src/pages/Customer/config.js。

动态路由机制：新模块如何自动挂载

前文提到业务路由是自动生成的，这里展开其机制：backend/src/models/utils/index.js 扫描appModels目录，为每个模型生成{ entity, modelName, controllerName }三元组；appApi.js 据此为每个实体统一注册 9 个 RESTful 接口：

POST /api/{entity}/create GET /api/{entity}/read/:id PATCH /api/{entity}/update/:id DELETE /api/{entity}/delete/:id GET /api/{entity}/search GET /api/{entity}/list GET /api/{entity}/listAll GET /api/{entity}/filter GET /api/{entity}/summary POST /api/{entity}/mail （invoice / quote / payment 额外） GET /api/{entity}/convert/:id （quote 额外）

统一路由的实现依赖 backend/src/controllers/middlewaresControllers/createCRUDController 提供的通用 CRUD 控制器（create / read / update / remove / listAll / paginatedList / search / filter / summary），这也是 IDURAR 保持代码简洁的关键架构设计。

配置体系：默认设置与设置 API

IDURAR 将系统配置以键值对形式持久化在 MongoDB 的Setting集合中，由 backend/src/models/coreModels/Setting.js 建模。默认设置来自 backend/src/setup/defaultSettings 目录下的 7 个 JSON 文件（按setupCategory分组）：

• appSettings.json—— 应用级设置：日期格式（默认DD/MM/YYYY）、语言（默认en_us）、国家、时区、公司邮箱、行业等；
• companySettings.json—— 公司信息（用于发票/报价抬头）；
• clientSettings.json—— 客户模块默认项；
• financeSettings.json—— 财务/会计相关设置；
• invoiceSettings.json—— 发票默认编号规则等；
• moneyFormatSettings.json—— 货币与金额显示格式；
• quoteSettings.json—— 报价单默认项。

后端设置 API 定义在 backend/src/routes/coreRoutes/coreApi.js 中，除标准 CRUD 外还提供了按设置键操作的接口：

• GET /api/setting/readBySettingKey/:settingKey—— 按键读取单个设置；
• GET /api/setting/listBySettingKey—— 按键批量查询；
• PATCH /api/setting/updateBySettingKey/:settingKey?—— 按键更新；
• PATCH /api/setting/updateManySetting—— 批量更新；
• PATCH /api/setting/upload/:settingKey?—— 上传设置（如公司 Logo，经singleStorageUpload中间件处理图片）。

对应控制器在 backend/src/controllers/coreControllers/settingController，中间件实现（加载、按键读写等）在 backend/src/middlewares/settings。前端设置页面位于 frontend/src/pages/Settings，涵盖 General / Company / Finance / Money Format / Company Logo 等子页面。

认证与安全机制

认证流程集中在 backend/src/controllers/coreControllers/adminAuth：

• 登录：/api/login校验邮箱密码，签发 JWT；
• 鉴权：isValidAuthToken中间件保护所有业务 API（app.js 中app.use('/api', adminAuth.isValidAuthToken, coreApiRouter)与erpApiRouter），前端将令牌存储于x-auth-token（见 frontend/src/config/serverApiConfig.js）；
• 密码管理：/api/forgetpassword（忘记密码）、/api/resetpassword（重置密码）、/api/logout（登出）；
• 密码存储：通过 backend/src/models/coreModels/AdminPassword.js 使用 bcryptjs 加盐哈希（setup 脚本中generateHash(salt, 'admin123')即其示例）；
• 限流防护：依赖express-rate-limit，且密码哈希使用 bcryptjs 本身自带计算成本，可抵御暴力破解；
• 错误兜底：统一的 404 与生产错误处理在 backend/src/handlers/errorHandlers.js。

二次开发与扩展方向

基于仓库结构，可以梳理出几条典型的扩展路径：

1. 新增业务实体：在backend/src/models/appModels/新增 Mongoose 模型文件 → 在backend/src/controllers/appControllers/新增对应控制器 → 路由由routesList自动生成，前端再补充页面路由（参考 frontend/src/router/routes.jsx）即可；
2. 定制发票/报价 PDF：修改 backend/src/pdf 下的 Pug 模板（Invoice.pug、Quote.pug、Offer.pug、Payment.pug）；
3. 接入邮件通知：配置RESEND_API后使用sendMail控制器发送发票/报价/付款邮件；
4. 远程开发：设置VITE_DEV_REMOTE=remote与VITE_BACKEND_SERVER指向远程后端，实现前端直连远端 API（对应npm run dev:remote脚本）。

结语

IDURAR 以"发票-报价-付款-客户"为核心业务闭环，用 MERN 全栈 + Ant Design + Redux 构建了一个结构清晰、易于扩展的开源 ERP / CRM 系统：后端通过模型扫描自动生成 RESTful 路由，前端按模块组织页面与状态管理，设置体系全部数据库化，并内置 PDF 生成、邮件发送、JWT 认证等企业级能力。按本文 9 步流程完成部署后，你即可用admin@admin.com/admin123登录系统，体验从创建客户、开报价、转发票到记录收款的完整业务链路，并在此基础上按需二次开发。

如果你希望了解更详细的贡献规范、维护者信息或面向 AI Agent 的结构化项目画像，可分别查阅 CONTRIBUTING.md、MAINTAINERS.md 与 llms.txt。

• 后端
• 前端
• 企业应用
• CRM