Frappe HR 开源 HRMS 深度解析:从 13 大功能模块到 Docker 与 Bench 双模式部署实战
Frappe HR 开源 HRMS 深度解析:从 13 大功能模块到 Docker 与 Bench 双模式部署实战
Frappe HR(仓库名 hrms)是一套由 Frappe Technologies 维护的开源 HR 与薪资(Payroll)管理系统,定位于"现代、易用、开箱即用",在 README.md 中官方将其描述为 Open Source, modern, and easy-to-use HR and Payroll Software。本文将以该文档为主线,结合当前仓库源码,系统梳理它的功能模块、技术架构,并完整还原 Docker Compose 与本地 bench 两套开发环境搭建流程,帮助读者从"看得懂功能"到"跑得起系统"。
项目定位:为什么会有 Frappe HR
Frappe HR 诞生的动机很朴素:Frappe 团队在自身规模扩张时,需要一套真正意义上的开源 HR 软件,但在市面没有找到理想的现成方案,于是决定自己构建。最初它只是 ERPNext 内的一组模块,从 version 14 起这些模块趋于成熟,Frappe HR 才独立成单独的产品(见 README.md 的 Motivation 一节)。这一演进路径也反映在当前仓库的依赖关系上:pyproject.toml 明确声明应用依赖 frappe >= 17.0.0-dev,<18.0.0 与 erpnext >= 17.0.0-dev,<18.0.0,而 hrms/hooks.py 中 required_apps = ["frappe/erpnext"],说明它必须运行在 Frappe 框架 + ERPNext 之上,属于典型的 Frappe 生态应用。
功能全景:覆盖员工全生命周期的 13 大模块
README 宣称 Frappe HR 提供 13 个以上模块,覆盖从员工管理、入职(Onboarding)、请假到薪资、税务等完整链路。打开 hrms/modules.txt 可以看到官方模块清单:
HR Setup
Tenure
Recruitment
Shift and Attendance
Leaves
Expenses
Performance
Payroll
Tax and Benefits
HR
结合 hrms/desktop_icon 目录下的工作区配置文件(expenses.json、leaves.json、payroll.json、performance.json、recruitment.json、shift_&attendance.json、tax&_benefits.json、tenure.json、hr_setup.json、frappe_hr.json),以及 hrms/hooks.py 中大量的 doc_events 与 scheduler_events 挂钩,可以还原各模块的落地形态。
Employee Lifecycle:员工全生命周期管理
从入职(Employee Onboarding)、转岗(Employee Transfer)、晋升(Employee Promotion)、离职(Employee Separation)到离职面谈(Exit Interview),README 强调让员工在整个生命周期中更轻松。仓库在 hrms/controllers/employee_boarding_controller.py 提供了入职流程的控制器实现,并在 hrms/hooks.py 中通过 doc_events 将 Project、Task 的更新与入职/离职状态联动:
"Project": {"validate": "hrms.controllers.employee_boarding_controller.update_employee_boarding_status"},
"Task": {"on_update": "hrms.controllers.employee_boarding_controller.update_task"},
也就是说,HR 可以基于项目管理视图来驱动入职/离职模板的进度,每一步任务完成都会自动同步到员工档案。
Leave and Attendance:假期与考勤
这是使用频率最高的模块之一,README 强调的能力包括:配置假期政策(Leave Policy)、一键拉取区域性节假日(regional holidays)、支持地理定位的上下班打卡(check-in/check-out with geolocation capturing)、通过报表跟踪假期余额与考勤。仓库中的实现证据非常充分:
- hrms/hr/doctype/leave_type、leave_allocation、leave_application 等 Doctype 构成假期体系;
- hrms/hr/doctype/employee_checkin 对应打卡记录,其移动端能力由 frontend 与 hrms/hr/doctype/employee_attendance_tool 支撑;
- 节假日的缓存失效逻辑位于 hrms/utils/holiday_list.py,并在 hrms/hooks.py 中通过
Holiday List的on_update/on_trash事件调用invalidate_cache,保证员工档案里的节假日列表实时更新; - 定时任务会每天处理班次考勤:
shift_type.process_auto_attendance_for_all_shifts、过期分配失效、假期余额结转(hrms.hr.utils.allocate_earned_leaves)等(见 hrms/hooks.py 的scheduler_events)。
Expense Claims and Advances:报销与员工预支
该模块支持员工预支款(Employee Advance)、费用报销(Expense Claim)以及多级审批工作流,并与 ERPNext 会计核算无缝集成。README 提到的"与 ERPNext accounting 无缝集成"在源码里体现得很直接:hrms/hooks.py 为 Payment Entry、Journal Entry、Unreconcile Payment 等会计单据注册了 hrms.hr.doctype.expense_claim.expense_claim.update_payment_for_expense_claim 回调,一旦报销被付款或凭证过账,报销单状态随之同步;同时声明 invoice_doctypes = ["Expense Claim"]、accounting_dimension_doctypes 包含 Expense Claim 系列、repost_allowed_doctypes = ["Expense Claim"],表明它深度参与总账、会计维度与重过账流程。
Performance Management:绩效管理
README 描述的能力是:目标跟踪(Goals)、目标与关键结果领域(KRA)对齐、员工自评、评价周期(Appraisal Cycle)管理。仓库对应 hrms/hr/doctype/goal、appraisal、appraisal_cycle、appraisal_kra、appraisal_template 等 Doctype,并在绩效相关 Mixin hrms/mixins/appraisal.py 中承载公共逻辑。
Payroll & Taxation:薪资与税务
README 强调的能力包括:创建薪资结构(Salary Structure)、配置所得税税率档位(Income Tax Slab)、运行标准工资核算(Standard Payroll)、支持附加工资(Additional Salary)与周期外付款(off cycle payments)、在工资单上查看收入构成(income breakup)。仓库侧证据:
- hrms/payroll/doctype/salary_structure、salary_slip、payroll_entry、income_tax_slab、additional_salary 一应俱全;
- 印度区域化的 HRA 免税与边际减免(Marginal Relief)计算实现在 hrms/regional/india/utils.py,通过 hrms/hooks.py 的
regional_overrides挂钩替换通用实现; - 工资单与工资凭证的审计追踪(Audit Trail)能力通过
audit_trail_doctypes = ["Expense Claim", "Payroll Entry", "Salary Slip", "Leave Encashment", "Gratuity"]开启。
Frappe HR Mobile App:移动端
README 专门把移动 App 列为独立能力:随时随地请假与审批、上下班打卡、查看员工档案。当前仓库的移动端实现以 PWA(Progressive Web App)形态存在:frontend/package.json 显示它基于 Vue 3 + Ionic(@ionic/vue)+ frappe-ui 构建,并引入了 vite-plugin-pwa 与 workbox 实现离线能力;根目录 package.json 也提供了 dev-pwa、build-pwa 脚本。此外仓库还有另一个 Vue + TypeScript 前端 roster(排班/花名册应用),两者构建产物分别输出到 hrms/www/hrms.html 与 hrms/www/roster.html。
Under the Hood:技术底座
README 在 "Under the Hood" 一节明确了两层技术底座:
- Frappe Framework:基于 Python 和 JavaScript 的全栈 Web 应用框架,提供数据库抽象层、用户认证和 REST API 等基础设施。当前仓库的 pyproject.toml 限定版本范围为
>=17.0.0-dev,<18.0.0,即面向 Frappe v17; - Frappe UI:基于 Vue 的 UI 组件库,用于构建 Frappe Framework 之上的单页应用。frontend 与 roster 两个前端工程均依赖
frappe-ui: 0.1.105。
这套"Python 后端 + Vue 前端"的架构,使 HR 业务逻辑(Doctype、审批流、薪资计算)沉淀在 hrms 目录,而交互界面以现代 SPA 形式呈现。仓库根 package.json 通过 postinstall 脚本串联 install-pwa-deps 与 install-roster-deps,一键安装两个前端工程依赖。
生产部署:托管方案(Managed Hosting)
对于生产环境,README 推荐了 Frappe Cloud——一个开源的 Frappe 应用托管平台。它负责安装、升级、监控、维护与支持等全生命周期运维,支持在一个平台内管理多个 Frappe 部署,并提供了专门的 HRMS 一键开通入口。由于托管平台不依赖本仓库代码,这里不再展开部署细节;自托管用户可参考官方文档与社区讨论。
开发环境搭建(方式一):Docker Compose 一键启动
这是 README 给出的最快上手路径,前提是机器上已安装 Docker 与 docker-compose。仓库 docker 目录内置了完整的编排文件与初始化脚本:
git clone https://gitcode.com/GitHub_Trending/hr/hrms
cd hrms/docker
docker-compose up
启动后需要等待初始化脚本完成站点创建,之后浏览器访问 http://localhost:8000 即可看到 HR 登录页,默认凭据为:
- 用户名:
Administrator - 密码:
admin
编排结构解读
docker/docker-compose.yml 定义了三个服务:
| 服务 | 镜像 | 作用与要点 |
|---|---|---|
mariadb |
mariadb:10.8 |
数据库。通过 command 显式指定 --character-set-server=utf8mb4、--collation-server=utf8mb4_unicode_ci,确保中文等多字节字符集正确;root 密码为 123;数据挂载到命名卷 mariadb-data 持久化 |
redis |
redis:alpine |
缓存与队列后端,供 Frappe 的 cache / queue / socketio 使用 |
frappe |
frappe/bench:latest |
应用容器。command: bash /workspace/init.sh 启动初始化;工作目录 /home/frappe;将当前目录挂载到 /workspace;映射 8000(站点 Web)与 9000(socketio 实时端口) |
init.sh 初始化流水线
docker/init.sh 是这套编排的核心脚本,它幂等地处理"已有 bench"与"全新 bench"两种情形:
- 幂等判断:若
/home/frappe/frappe-bench/apps/frappe已存在,说明 bench 已初始化,直接cd frappe-bench && bench start启动; - 初始化 bench:
bench init --skip-redis-config-generation frappe-bench,跳过本机 Redis 配置生成(因为 Redis 由容器提供); - 指向容器化基础设施:依次执行
bench set-mariadb-host mariadb、bench set-redis-cache-host redis://redis:6379、bench set-redis-queue-host redis://redis:6379、bench set-redis-socketio-host redis://redis:6379,把数据库与 Redis 全部指向同网络内的容器服务名; - 精简 Procfile:用 sed 删除 Procfile 中的
redis与watch行,避免在容器内重复启动本机 Redis; - 拉取应用:
bench get-app erpnext与bench get-app hrms(对应 hooks.py 中required_apps = ["frappe/erpnext"]); - 创建站点:
bench new-site hrms.localhost,使用--mariadb-root-password 123、--admin-password admin、--no-mariadb-socket(因为走 TCP 而非本地 socket); - 安装与配置:
bench --site hrms.localhost install-app hrms,随后set-config developer_mode 1开启开发者模式、enable-scheduler启用调度器(HR 大量定时任务依赖它)、clear-cache、bench use hrms.localhost设为默认站点; - 启动:
bench start,同时拉起 Web、Worker、SocketIO 等进程。
可以看到,README 中"wait for some time until the setup script creates a site"的描述,背后正是这套完整的 bench 初始化流程。值得一提的还有版本兼容性:仓库 hrms/patches/v15_0/check_version_compatibility_with_frappe.py 的存在说明 Frappe HR 对框架版本有严格校验,若与本仓库声明的版本范围不符,安装时会被拦截。
开发环境搭建(方式二):本地 bench 手工搭建
适合需要深入二次开发、调试源码的工程师。README 给出的完整步骤为:
- 参照 Frappe 官方安装文档搭建 bench,并保持服务运行:
$ bench start
- 另开一个终端窗口,依次执行:
$ bench new-site hrms.localhost
$ bench get-app erpnext
$ bench get-app hrms
$ bench --site hrms.localhost install-app hrms
$ bench --site hrms.localhost add-to-hosts
- 通过
http://hrms.localhost:8080访问站点。
其中 new-site 创建站点、get-app 拉取应用源码(hrms 依赖 erpnext,因此需要一并拉取)、install-app hrms 执行应用安装(会触发 hrms/hooks.py 中的 after_install = "hrms.install.after_install" 与 setup_wizard_stages 引导配置)、add-to-hosts 将 hrms.localhost 写入 hosts 便于本地域名访问。
本地环境的运行前提
- Python 版本要求
>=3.10(见 pyproject.toml); - Frappe 与 ERPNext 版本均需落在
>=17.0.0-dev,<18.0.0区间; - 代码质量方面,仓库用 Ruff 做 lint 与格式化(pyproject.toml 中
[tool.ruff]配置了line-length = 110、target-version = "py310",isort 按 frappe → erpnext → hrms 的导入分节),二次开发前建议保持同样的风格。
源码导览:从 hooks.py 看懂应用与框架的握手
安装好环境后,建议从 hrms/hooks.py 开始阅读——它是 Frappe 应用与框架的"声明式接口",几乎所有能力都从这里注册:
- 应用元信息:
app_name = "hrms"、app_title = "Frappe HR"、GPL v3 许可; - 前端资源:
app_include_js = <a href="https://link.gitcode.com/i/53350a32a55a876a47d46c49e8ef6e96" target="_blank">"hrms.bundle.js"]、app_include_css = "hrms.bundle.css",对应 [hrms/public/js/hrms.bundle.js 与 hrms/public/scss/hrms.bundle.scss; - 页面路由:
website_route_rules将/hrms/<path>路由到 hrms 前端、/hr/<path>路由到 roster 前端,与 hrms/www/hrms.html、hrms/www/roster.html 两个入口对应; - 文档事件(doc_events):覆盖 Employee、Company、Timesheet、Payment Entry、Journal Entry、Loan、Project、Task 等 Doctype,实现报销付款同步、员工审批人角色维护、入职状态联动等横切逻辑;
- 定时任务(scheduler_events):从每小时、每天到每周/每月,承载生日与工龄纪念日提醒(hrms/controllers/employee_reminders.py)、考勤自动处理、假期余额结转、过期招聘关闭等后台作业;
- Doctype 类覆盖:
override_doctype_class将 Employee、Timesheet、Payment Entry、Project 替换为 hrms/overrides 下的增强实现; - 全局搜索集成:
global_search_doctypes将 Salary Slip、Leave Application、Expense Claim、Job Opening 等纳入 ERPNext 全局搜索。
学习与社区
README 为上手与排障整理了四条社区路径(均为外部站点,这里以文字说明):Frappe School 提供框架与 ERPNext 的官方课程;docs.frappe.io/hr 是 Frappe HR 的扩展文档;ERPNext 用户论坛聚集了大量使用与实施经验;Frappe HR 专属 Telegram 群可获取即时帮助。
参与贡献
README 给出了三条贡献准则:遵循 Issue 提报规范、安全漏洞请通过官方安全渠道私密上报(切勿公开讨论)、Pull Request 需符合贡献指南。仓库本身也为协作做了工程化准备:
- commitlint.config.js 约束提交信息格式;
- codecov.yml 配置覆盖率门禁,CI 徽章见 README 顶部;
- 测试代码分散在 hrms/tests(如 hrms/tests/test_api.py、hrms/tests/test_roster.py)与各 Doctype 的 tests 目录,例如 hrms/controllers/tests/test_employee_reminders.py;
- MANIFEST.in、semgrep/test-correctness.yml 保障打包与静态安全扫描。
结语
Frappe HR 的价值在于:它把 HR 领域的复杂业务——生命周期、考勤、报销、绩效、薪资税务——沉淀为一套可自由部署、可深度定制的开源系统,并提供了 Docker 与 bench 两种开箱路径。对希望快速体验的团队,docker-compose up 五分钟左右即可得到一个含 ERPNext 与 HR 全套模块的环境;对需要二次开发的团队,则可以从 hrms/hooks.py 出发,沿着 doc_events、scheduler_events 与 hrms/hr/doctype 的 Doctype 体系,逐步深入这套现代 HRMS 的实现细节。