开源ERP Ever Gauzy深度解析：模块部署与二次开发实践

Ever Gauzy 这个名字估计不少做企业管理系统的朋友已经在 GitHub 上刷到过。它是一套把 ERP、CRM、HR、薪资、项目管理和会计整合在一起的开源平台主打一个“企业内部系统全家桶”的路线。只要你对“自主可控”这点有执念不想被 SaaS 厂商的订阅费和数据结构绑定那 Ever Gauzy 就是值得你花一个下午研究的选择。这篇文章不会给你抄官网介绍我会从实际落地和使用者的角度把它的模块构成、部署流程、二次开发经验以及背后那套“为什么这么设计”的逻辑一次性讲清楚。这套系统最适合谁首先是那些规模在几十人到几百人、业务流开始从“表格管理”往“系统化管理”过渡的成长型公司其次是做定制化交付的软件服务商拿它做基座给客户做私有化部署比从零写一套管理系统省太多事。接下来说的内容全部基于实际踩坑和代码阅读经验适合打算认真上手试用的技术负责人、实施顾问和企业内部系统管理员。1. 项目整体设计与核心模块拆解1.1 模块化设计背后的产品逻辑很多人第一次打开 Ever Gauzy 的目录结构时会有点懵它明明叫“ERP”但前端是 Angular后端是 NestJS数据库用 PostgreSQL还塞了一套基于 Electron 的桌面端壳子。其实这个架构选择是有明确逻辑的——ERP 这类系统最大的痛点不是“功能不够多”而是“各个功能模块之间数据割裂”。Gauzy 早期就是按模块化思路设计的把员工、客户、项目、财务、仓储这些实体全部放在同一套数据模型里彼此之间通过关联关系串起来而不是像某些老牌系统那样每个模块独立建表、靠接口互相拉数据。从使用者的视角看这种设计的直接好处是你在“销售”模块里录入一张订单系统能自动把对应的应收款同步到“会计”模块同时项目负责人能在“任务”模块里看到这笔单对应的交付进度HR 那边也能根据项目工时自动算出绩效相关的数据。整个业务链路是闭环的不用像传统做法那样在多个软件之间手工搬运数据。1.2 模块清单到底能做多少事我按实际应用频率给 Ever Gauzy 的模块排个序方便你判断它在哪些场景能立刻产生价值账务与发票管理支持多币种、税务规则、应收账款/应付账款追踪。这里最容易忽略的一点是它默认附带“复式记账”能力也就是每一笔收入支出都能对应到借贷双方的会计科目这点对后续对接审计或者第三方财务软件非常重要。客户关系管理CRM线索管理、商机跟进、客户联系人、报价单转订单。比起专业 CRM它不算重但胜在跟后面的订单、发票、回款数据天然打通不需要做集成。项目管理与工时追踪可以按项目拆任务给团队成员分配工时支持时间跟踪。这块做得很细甚至能从桌面端直接启动计时器计时数据进入报表后直接关联薪酬算法。人力资源与薪资管理员工档案、考勤、休假、工资单、奖金、扣除项。这里要注意不同国家的税务规则不一样Ever Gauzy 提供的是计算引擎和公式自定义能力真正做本地化的时候需要你按照当地法规去配置而不是开箱即用。库存与采购管理仓库、产品、变体、采购订单、库存调整支持按批次/序列号追踪。报表与分析仪表盘很多 ERP 的报表模块就是摆设但 Gauzy 的报表是可配置的你可以自定义指标维度例如“按客户项目月份的毛利分析”。也就是说它不是一个“单点工具”而是一套覆盖“获客-签约-交付-计量-开票-回款-发放工资”全链条的完整系统。对中小公司来说这套链路一旦跑通日常经营的数据就全部沉淀在内部数据库里这也是自托管相比 SaaS 最大的吸引力。1.3 和商业 ERP 的定位差异很多人会拿 Ever Gauzy 和 Odoo 对比。两者确实都在“开源 ERP”这个赛道上但定位有明显区分。Odoo 更像一个“应用商店”式的生态平台社区版只提供基础框架很多好用的模块都在企业版付费墙后面Ever Gauzy 则在架构上更强调“All-in-One”把员工、项目、财务、库存做成了一体的数据闭环并且对“按工时做薪资结算”这类以人力服务为核心业务的场景有原生的深度支持。换句话说如果你的公司主要业务是“卖产品”Odoo 可能更合适如果你的业务核心是“卖服务和人力”比如咨询公司、软件外包团队、设计工作室那 Ever Gauzy 的基本盘——项目工时、报销审批、按人天计费、外包人员薪资——简直像量身定做。2. 核心功能深度解析与实操要点2.1 账务模块别忽略“复式记账”这个底层能力Ever Gauzy 的账务模块表面上看着就是一个“记收支”的账本但它的底层设计其实对标的是正规会计软件的“复式记账”逻辑。每一笔与资金相关的操作都会同时生成借方和贷方记录。举个例子你给客户开了一张 1000 元的发票系统会在应收账款科目挂一笔借方在销售收入科目挂一笔贷方等客户实际付款到账你再核销这笔应收系统再把银行存款增加、应收账款减少。这个设计对使用者有什么实际意义最直接的一点你不用再担心“账面上收了钱但不知道这笔钱对应哪张发票”这种混乱状况。每一笔资金流向都是可追踪的审计的时候也能拿出完整的凭证链。实际操作中我建议首次配置时务必做三件事设置好默认会计科目表不要让系统把所有交易都归到“其他收入”。把税费规则配置好尤其是跨区域业务避免后面逐张发票手动调税。定期做银行账户对账把系统记录和真实银行流水核对不要偷懒跳过这个环节。2.2 从线索到回款的完整业务闭环CRM 模块的商机环节有一个我很欣赏的设计它不是单纯记录一个“预计成交金额”而是会关联一系列后续操作。当商机状态变成“已赢单”你可以一键创建客户、生成订单然后订单又能继续转换出项目、任务、发票。这个操作链听起来很基础但实际用过你就知道少了它的话销售和项目两部之间的数据交接会浪费大量沟通成本。我在实施中通常建议客户采用这样一个标准流程销售在 CRM 里录入线索跟进到“赢单”状态系统自动创建客户档案和订单项目经理根据订单创建项目并通过订单里的产品/服务项分解出项目任务团队成员在项目管理里填报工时系统自动归集成本项目阶段性完成或全部完成后基于订单金额直接开发票财务收到款项后核销应收款同时系统把实际回款数据同步到会计台账。整套流程走下来你会直观感受到每个环节都“有据可查”而不是靠 Excel 加微信群来维持业务流转。2.3 薪资与工时的联动逻辑薪资模块是 Ever Gauzy 相对有特色的点。它的计算方式不是简单的“月薪固定工资绩效”而是允许你设置非常复杂的薪酬结构。比如某个员工的基本工资是 5000 元岗位津贴 1500 元按项目提成 3%同时还有可能因为加班产生加班工资和扣款。这套配置在传统人事软件里往往要额外购买薪酬插件但在 Ever Gauzy 里属于核心能力。工时追踪数据可以直接作为薪酬计算的输入这对软件开发团队、设计团队、咨询公司这类“按人天计费”的业务尤其有用。系统会自动统计每个成员在某项目上投入的工时并按你预先设定好的成本价和销售额价格计算出项目毛利和员工应得的绩效提成。实际操作中需要注意工时的审批流程一定要建立起来让项目经理每周确认一次否则月底会出现一堆没有审核的工时直接影响薪资计算的正确性。2.4 库存与项目型企业的适配边界库存采购模块更适合销售实体产品的团队管理仓库、采购、库存调拨。但如果你是纯服务型团队可以不用强行使用库存模块。不过它里面的“产品”概念仍然很值得用起来你可以把“设计服务一天”定义成一个“服务型产品”设置标准售价和成本这样在订单和开票时就能统一使用产品库而不是每次都手动输入一行文字描述。这算是一个在项目型公司里很容易被忽视、但能明显提升效率的小技巧。3. 部署与初始化手把手走一遍完整流程3.1 部署方案选型Docker Compose 是首选Ever Gauzy 的官方仓库提供了多种部署方式包括源码启动、Docker Compose、Kubernetes 等。我的建议很简单如果你不是特别清楚自己需要对源码做深度改造能上 Docker Compose 就上 Docker Compose。原因很实在——它把 PostgreSQL、后端 API、前端界面、桌面端打包成了几个互相配合的容器省掉了很多环境配置的麻烦。以下是一份最小化的 docker-compose.yml 片段按默认配置即可拉起一套体验环境version: 3.8 services: postgres: image: postgres:15 restart: unless-stopped environment: POSTGRES_DB: gauzy POSTGRES_USER: gauzy POSTGRES_PASSWORD: gauzy volumes: - db_data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U gauzy] interval: 10s timeout: 5s retries: 5 ports: - 5432:5432 api: build: context: . dockerfile: .docker/Dockerfile.api depends_on: postgres: condition: service_healthy environment: DB_HOST: postgres DB_PORT: 5432 DB_NAME: gauzy DB_USER: gauzy DB_PASS: gauzy ports: - 3000:3000 web: build: context: . dockerfile: .docker/Dockerfile.web depends_on: - api ports: - 8080:80 volumes: db_data:注意一点官方仓库的 Docker 镜像体积通常不小尤其 API 那个镜像是基于 NestJS 构建的首次拉取和启动需要一些耐心。如果是在国内云服务器上部署建议提前配置好镜像加速不然拉镜像的时间甚至可能超过系统初始化的时间。3.2 初始化关键步骤组织、用户、角色权限系统启动之后第一件事不是急着录入业务数据而是先把“组织”和用户体系建立起来。Ever Gauzy 的数据模型里几乎所有业务单据都依附在 Organization 下面。也就是说多公司、多团队的情况下你可以通过组织区分不同实体的数据而用户则通过角色权限决定能否访问这些组织。我建议按这个顺序做初始化创建超级管理员账号登录系统后进入“组织”页面新增一个组织。设置组织的国家、时区、货币。这步很重要因为会计模块的科目表、税务规则会跟着国家切换。创建员工账号并把员工关联到组织内部。别漏掉“邀请加入”这个动作系统发邀请邮件后员工才能自行设置密码并进入系统。配置角色权限。Ever Gauzy 提供预置角色管理员、员工、经理、会计等但对中小团队我更建议手工调整一遍按“谁需要看什么数据”来收紧权限免得员工一登录就能看到全公司薪资这种尴尬场景。配置第一套会计科目和发票模板。如果你的客户群体对企业品牌有要求发票模板建议直接改好再开第一张发票。整个初始化过程看起来不复杂但实际执行时每个步骤都藏着小细节。比如创建组织时填写的“起始财务年度”会直接影响报表的统计区间填错了后面改起来很麻烦。3.3 多语言与本地化配置Ever Gauzy 自带多语言支持界面可以在英文、中文、法文等语言之间切换。但要注意它界面的“多语言”和业务数据的“本地化”是两回事。比如你在系统中录入的客户名称、产品描述、发票抬头都是按你自己的内容存储的系统不会做翻译。真正的本地化配置重点在于货币符号、日期格式、小数精度、时区设置这些底层项。我见过不少团队因为时区设置不当导致考勤记录、工时统计和财务结账时间出现几小时偏差最后月底手动调整数据调到崩溃。所以务必在系统初始化时就把时区设置准确并且提醒所有员工在个人设置里也检查一遍自己的时区确保工时数据能落到正确的那一天。3.4 用 API 完成基础数据导入如果是老系统切换过来历史数据迁移是个大头。Ever Gauzy 没有提供一个开箱即用的“Excel 一键导入所有历史数据”的功能但它有完整的 RESTful API而且不少实体支持通过 API 批量创建。实际项目中我通常会写一个简单的导入脚本把客户、供应商、产品、历史发票等数据从 Excel 或旧系统导出成 JSON再调用 Ever Gauzy 的 API 写入。这里分享一个基础脚本的结构用 Node.js 写一个批量导入客户示例const organizations await api.get(/api/organizations); const orgId organizations.items[0].id; for (const row of customerRows) { await api.post(/api/customers, { organizationId: orgId, name: row.name, email: row.email, phone: row.phone, country: row.country, city: row.city }); }这种脚本写得顺手后也能用于日常的批量调整比如“把某批客户全部标记为某分类”“给部分员工批量设置默认成本价”。API 文档在官方仓库的 Swagger 路径下可以直接打开不必额外安装工具。4. 二次开发与定制化经验4.1 基于 NestJS 的插件式改造Ever Gauzy 的后端是 NestJS这给二次开发带来了极大的方便。NestJS 的模块化机制让你可以在不破坏主框架的前提下以增加一个 Feature Module 的方式接入自己的业务逻辑。比如客户提出“新增一种项目回款计划按里程碑自动生成发票”你可以单独写一个模块监听项目状态变更事件触发里程碑发票的生成逻辑而不必去改动原有的开票模块代码。实际操作中我建议先在源码模式下开发测试把代码跑通后再把改动整理成 Docker 镜像构建到生产环境。不建议一上来就改造线上 docker-compose 里的代码容易造成配置和代码版本混乱。开发流程可以这样走克隆 Ever Gauzy 官方仓库切到稳定版本分支。本地安装依赖推荐 pnpm启动 API 和 Web 开发服务。在apps/api/src/app/下新建自己的 feature 目录注册为模块。写 TypeScript 实体类用 TypeORM 的 Entity 定义新表。在 Controller 里暴露需要的 REST 接口。测试完毕后把代码提交到自己的仓库再走镜像构建流程。4.2 自定义字段与表单扩展Ever Gauzy 里很多实体已经预留了customFields这样的 JSON 字段可以灵活扩展不必为每个小需求都改表结构。举个例子如果要在员工档案里增加一个“紧急联系人手机号”直接在 customFields 里加一个 key-value 就行。但如果你需要的是“必填字段”或者“字段联动”这种高级校验仅靠 JSON 字段是不够的你需要在前端 Angular 组件里修改表单逻辑并在后端 DTO 里补充校验规则。这里有一个经验尽量少去改官网默认的通用实体表因为升级版本时很容易冲突。最好的做法是新建自己的扩展表用entityId去关联主表数据这样以后官方升级你的扩展数据不会丢失代码冲突也会少很多。4.3 权限体系的二次设计Ever Gauzy 的权限模型基于角色和权限点。官方默认的权限点颗粒度不算细但在实际客户环境里经常会有“这个角色只能看到自己的项目数据”这类需求。这时候一般有两种做法用默认的角色权限但把数据查询条件改为“仅当前员工关联的项目”。这需要在 Service 层做数据过滤改动代码量较大。建一个全新的角色而非直接修改默认角色。默认角色在系统升级过程中可能会被重置自定义角色则相对安全。我的建议是非必要不要改默认角色而是新建角色并通过编程方式绑定权限。此外权限调整完一定要用低权限账号实测一遍光是看代码很难发现权限漏洞。4.4 与外部系统集成时最容易踩的坑外部系统集成的关键点是认证。Ever Gauzy 默认使用 JWT 认证机制第三方系统调用 API 前需要先通过登录接口获取 token。不要在外部系统里硬编码一个长期有效的 token正确做法是做一个定时刷新 token 的服务或者用官方支持的 API Key 机制。转账到会计系统或者接第三方支付时时刻注意金额单位。Ever Gauzy 内部存储金额使用的是浮点数吗不对于金额字段它采用的是小数点精度控制但你在外部系统传值时如果使用 float可能会有精度损失。建议总是在边界处把金额转成最小货币单位比如分再进行计算避免出现差几分钱对不平的窘境。5. 常见问题与排查技巧实录5.1 部署启动慢、内存占用居高不下Ever Gauzy 整套体系对服务器的最低要求比一般开源软件高一些。API 服务基于 NestJS 和 TypeORM内存占用起步就是 1GB 以上前端 Angular 构建产物运行起来也会占一截内存。如果是在 2GB 内存的服务器上部署经常会出现系统启动到一半被杀进程、页面加载极慢的情况。我的建议是生产环境至少 4GB 内存并将数据库和 API 拆开部署。如果实在资源有限可以调低 API 进程的 Node 内存上限并关闭不常用的功能模块但代价是系统并发能力会下降。在本地体验时把桌面端关掉只用 Web 端能明显减少资源压力。5.2 登录后页面白屏或接口 502这个问题我遇到最多的原因不是代码 bug而是前端和后端启动顺序搞错了。前端容器起来后会向后端 API 发送请求如果此时 API 还没完全 ready浏览器会缓存一个失败的请求之后即便 API 恢复正常页面也会一直白屏。解决方法是确保 API 服务健康检查通过后再启动前端并在 docker-compose 里使用depends_on: condition: service_healthy。如果页面已经白屏了刷新浏览器、清除站点缓存基本能恢复。5.3 发票金额对不上汇率Ever Gauzy 支持多币种但汇率需要你手动管理或通过第三方汇率服务同步。如果你在客户报价时用的是美元开票时又按欧元结算系统会要求选择一个汇率。这里很容易出问题——很多用户直接用了“即时汇率”结果月底结汇时发现实际到账金额和系统里的应收款差一大截。我的习惯是每月月初固定一个“记账汇率”全月所有外币单据都用这个汇率月末再做一次汇兑损益调整。这比每次开票都去查实时汇率更稳定也方便财务核算。5.4 数据备份与恢复策略自托管系统的老生常谈数据库备份。PostgreSQL 的备份方式Ever Gauzy 官方推荐直接用 pg_dump。我通常的做法是每天早上做一次全量备份保留最近 14 天同时每天做一次 WAL 归档这样可以把数据恢复到任意一个时间点。不要只依赖云厂商的快照快照和数据库逻辑备份是两码事误删数据后靠快照回滚有时无法精准恢复到删除之前的状态。pg_dump -U gauzy -h localhost gauzy backup_$(date %Y%m%d).sql这条命令看起来简单但建议放在 crontab 里定时跑。真的遇到业务数据被误删时你会感谢这个习惯的。5.5 常见问题速查表现象常见原因排查思路登录后页面白屏前端请求 API 失败、缓存残留检查 API 容器健康状态强刷页面清理缓存工时无法保存没有关联项目或任务检查员工是否已被分配到该项目生成发票时报错客户缺少默认价格表或税率未配置到客户档案里补齐价格表、税率设置邮件发送失败SMTP 配置错误或端口被封检查 SMTP 服务、端口、授权码报表数据为 0没有关联组织或期间类型没选对确认报表页面顶部选择的组织和时间范围员工登录后看不到菜单角色权限不足用管理员账号调整该角色权限6. 几个值得尝试的进阶玩法6.1 用自动化任务减少重复操作Ever Gauzy 的 API 很适合做操作自动化。比如每月初自动创建所有员工的上月考勤记录、定期把未收款发票清单推送到企业微信群或钉钉群、自动把员工休假记录同步到项目排期。这些需求不一定要写复杂的代码很多情况下用脚本定时跑几个 REST API 就能完成。一个简单例子利用 cron 每天检查应收款账龄把超过 30 天未回款的发票汇总成日报推送到管理者邮箱。相比每天人工登录系统一张张看发票状态这种自动化能节省不少精力。6.2 对接 BI 报表工具Ever Gauzy 的报表模块适合日常查看但要给老板做经营分析通常也可以直接把数据库接到主流 BI 工具上。只需要给 BI 工具单独创建一个只读的 PostgreSQL 账号把需要的表和视图同步过去。数据模型设计得比较规范关联字段基本能看懂。唯一要注意的是别让 BI 查询打到生产数据库最好在凌晨同步一份数据到分析库避免影响白天业务使用。6.3 从社区版到企业版的路径Ever Gauzy 有功能更完整的企业版包含更丰富的会计功能、自动化流程和高级安全控制。我个人的建议是先用社区版跑通业务把数据模型和流程梳理清楚如果确实碰到社区版无法支持的硬需求再去考虑企业版。很多公司连社区版的核心功能都没用好就急着采购企业版结果钱花了流程还是一团乱麻。7. 从选型到落地的真实体会做开源 ERP 选型这几年我最大的感触是工具本身的能力边界往往不是决定成败的因素团队愿不愿意改变原有工作习惯才是项目能不能顺利落地的关键。Ever Gauzy 功能确实全但它也要求使用者具备一定的数据结构化思维——比如录入客户时要把行业、区域、类型这些字段填完整项目工时要有规律地提交而不是月底统一补录。我建议新团队上线的前两周不要急着把所有模块全部铺开。先把客户、项目、任务、工时这四个基础模块跑顺等大家形成了“每天顺手填报工时”的习惯再逐步开放采购、库存、薪资这些重量级模块。这样既不会让员工觉得系统太复杂又能保证数据积累质量。另外社区和文档的价值被很多人低估了。Ever Gauzy 的官方仓库里包含部署手册、API 文档和配置指南遇到问题第一时间去翻 issues 和 changelog通常能找到别人踩坑的经验。真的有个性化需求也尽量通过模块扩展去解决而不是直接改核心代码。保持升级路径畅通是开源系统持续稳定运行的基础。写到这里再分享一个我个人的习惯每次部署完 Ever Gauzy我会把所有配置项和初始化步骤记录到一个单独的文档里包括账号密码存放方式、备份策略、环境变量清单。不然过半年再回来看很容易忘了某些配置当初为什么这么设。这套系统能承载的业务深度很可观值得你把基础工作做扎实再让它跑起来。