简介协同办公OA系统是企业数字化转型中最基础也最具代表性的业务应用其核心价值在于打通审批流、权限管控与消息协同。从技术原理来看一套成熟的OA系统通常基于RBAC权限模型设计用户-角色-菜单的细粒度访问控制并引入Flowable等工作流引擎驱动业务流程同时结合Spring Boot构建模块化后端服务配合Vue等前端框架实现前后端分离架构。这种组合不仅提升了开发效率还赋予了系统灵活的二次开发能力是企业自建OA、替代商业定制的高性价比方案。在实际应用场景中无论是高校毕业设计、个人Spring Boot练手项目还是企业内部办公平台搭建都可以参考这种源码级实践路径。本文围绕一套完整Java OA系统源码从技术选型、核心模块设计到部署上线与常见避坑策略系统梳理了OA系统从0到1的落地全过程。 做Java开发这些年经手过不少企业项目但要说最能体现“Java后端基本功”的还得是协同办公OA系统。这个品类特别有意思你说它难无非就是增删改查加审批流你说它简单用户权限、流程引擎、消息通知、文件协同这些模块每个都能单独写成几篇长文。我最近正好在系统梳理一套完整的Java协同办公OA系统源码从技术选型到部署上线再到二次开发踩了不少坑也积累了一些实战经验。这篇就围绕这套源码把OA系统从设计到落地的完整链路讲清楚。不管你是准备用Java做毕业设计、想把OA作为Spring Boot练手项目的开发者还是公司需要自建OA的技术负责人这篇内容应该都能给你一些参考价值。1. 项目整体设计与技术选型思路1.1 技术栈选型为什么是 Spring Boot Vue 这套组合OA系统的本质是“一堆业务模块 一套权限体系 一条审批链路”。看起来简单但真正落地时对技术选型的要求其实很高既要快速开发又要稳定易维护还得方便日后扩展。我最终选定的组合是Spring Boot 2.7 Spring Security JWT MyBatis-Plus Redis MySQL Vue 3 Element Plus。后端用Spring Boot基本没什么悬念这是目前Java生态里开发效率最高的框架。Spring Security加JWT做认证授权既保证了安全性又贴合前后端分离的场景。MyBatis-Plus是我个人比较偏好的ORM框架OA系统里有大量复杂的多表关联查询和报表统计MyBatis-Plus在写复杂SQL时比JPA更灵活而且代码生成器能直接省掉大量重复的CRUD工作。前端选Vue 3 Element Plus主要是因为Element Plus的组件库对后台管理系统极其友好。表格、表单、弹窗、树形控件这些OA高频组件都是开箱即用能省下大量写UI的时间。这里有个选型细节要提一下如果你的团队对Vue不熟其实也可以考虑用若依这类已经封装好的脚手架做基础但前提是你得能驾驭它的代码结构否则后期维护反而是灾难。有个比较关键的决定是我放弃了微服务架构选择了单体应用。很多人一上来就想上Spring Cloud但OA系统绝大多数场景根本用不到微服务。单体应用部署简单、调试方便、资源占用低对几百人规模的企业完全够用。等到系统真正出现性能瓶颈时再按模块拆分也不迟这就是所谓的“演进式架构”。提示技术选型不是越新越好也不是越复杂越好核心是匹配业务场景和团队能力。如果团队里没人用过微服务强行上Spring Cloud只会把项目拖垮。1.2 系统架构与模块边界划分这套OA系统的整体架构可以用“前后端分离 模块化单体”来概括。前端独立部署通过Nginx反向代理访问后端API后端按业务领域拆分为独立模块代码层面用Maven多模块工程管理。模块划分是我觉得这套源码里最有参考价值的部分。我在设计时没有按“部门模块”“员工模块”这种传统方式划分而是围绕“协同”这个核心诉求拆了六个核心模块模块核心功能技术要点用户权限模块用户、角色、菜单、部门管理数据权限控制RBAC模型Spring Security JWT工作流模块审批流程定义、发起、审批、驳回、会签、转办Flowable流程引擎BPMN 2.0消息中心模块站内信、待办通知、公告提醒、企业微信通知WebSocket实时推送 第三方推送文件管理模块文件上传下载、在线预览、协同编辑MinIO存储KkFileView预览日程任务模块日程管理、任务分配、提醒Quartz定时任务 消息推送报表统计模块考勤统计、审批统计、项目进度看板ECharts MyBatis-Plus聚合查询这种按业务能力划分模块的方式好处在后期扩展时能明显感受到。比如公司想加一个“物资领用审批”只需要在工作流模块里定义新的流程模板在菜单里挂上对应入口就行完全不需要动其他模块的代码。数据层面我用了MySQL Redis的组合。MySQL存业务主数据Redis承担三件事JWT token的存储和校验、热点数据的缓存、以及协同编辑时的会话状态管理。数据库连接池用HikariCP这是目前综合表现最好的连接池Spring Boot 2.x默认就是它不需要额外配置。1.3 和商业OA系统的对比为什么要做自己的OA讲到OA系统很多人第一反应是“直接用泛微、致远不就行了干嘛自己开发”这个问题的答案恰恰是我做这套源码的出发点。商业OA的优势是功能全面、开箱即用但问题也很突出。最核心的问题是定制成本高。商业OA虽然提供表单设计和流程配置但一旦遇到公司特有的业务逻辑比如“部门主管审批后需要抄送财务和HR”“合同金额超过50万需要走专项会签”这些规则在商业OA里实现起来非常痛苦。定制开发按人天收费价格不菲而且升级后定制代码可能被覆盖。第二是系统集成难。现在企业越来越依赖企业微信、钉钉这类的办公平台需要把OA的待办消息、公告通知直接推送到企微或钉钉上。商业OA虽然也支持但接口文档复杂、权限模型封闭对接周期往往比预期长很多。而自研OA在消息推送、单点登录这些集成点上完全自主可控实现一次就能长期受益。我见过太多公司在商业OA上投入大量预算最后用的还是最基础的审批和公告功能真正有价值的定制需求全卡在售后和成本上。自研OA虽然初期投入大但系统是完全属于自己的资产数据不绑死、功能可演进、代码可审计。对于有一定技术团队的公司来说这个账其实是划算的。2. 核心功能实现与实操要点2.1 RBAC权限模型从表设计到接口鉴权权限系统是OA系统的地基也是面试中最高频的考点。这套源码用的是经典的五表RBAC模型用户表、角色表、菜单表、用户角色关联表、角色菜单关联表。在此基础上我额外加了一张部门表通过“用户所属部门”来实现数据权限的控制。表设计的关键在于菜单表必须支持树形结构即菜单可以有多级子菜单而且类型要区分目录、菜单、按钮三级。这就涉及到“按钮级权限”的概念比如同样是“审批管理”菜单A角色只能查看列表B角色可以点击“通过”按钮这就是通过按钮权限进行细粒度控制的。后端接口的权限控制我分了两个层面。第一层是身份认证所有请求先走JWT过滤器校验token是否有效、是否过期第二层是请求授权使用Spring Security的PreAuthorize注解配合自定义权限表达式在方法级别控制“谁可以访问这个接口”。这样一来权限控制的粒度可以精确到任何一个按钮、任何一个接口。这里分享一个我在实际项目中踩过的坑JWT的过期时间设置。如果你把token过期时间设成7天用户登录后超过7天没有操作系统会强制退出这在OA这种需要长期在线的场景里非常影响体验。但设置过长又有安全隐患。我的方案是“双token机制”一个短期token负责正常业务一个长期refresh token负责刷新。这样既保证了安全用户登录一次能一直用不用反复输密码。2.2 工作流审批Flowable在OA中的落地细节工作流是OA系统最硬核的部分也是拉开项目和项目之间差距的分水岭。我用的Flowable引擎它是Activity 5/6的延续版本API更简洁、社区更活跃而且是国内企业级项目中使用率最高的流程引擎。Flowable的核心思路是“流程定义驱动业务”。流程定义用一个BPMN 2.0标准的XML文件描述里面定义了节点、连线、条件、任务分配规则。在实际业务中你只需要在管理后台里维护好这个流程定义文件业务代码完全不用改。举个例子请假审批流程定义如下发起申请 → 直属领导审批 → 部门经理审批 → 抄送HR。这个流程在Flowable里有清晰的任务节点定义而系统内的“新增请假”功能只需要调用发起流程的API后续的流转全部交给Flowable管理。但流程引擎本身只是“骨架”真正的业务复杂度在于各种边界情况。比如“驳回”操作就有驳回到上一步、驳回到发起人、驳回到指定节点三种模式对应到Flowable里是对不同任务节点的处理逻辑。再比如“会签”就是一单申请需要多个人同时审批全部同意才算通过这在Flowable里需要配置多实例节点并设定AND类型的完成条件。这些细节如果不在开发前梳理清楚后期改起来会非常痛苦。注意如果项目里的审批流程很复杂建议不要过度依赖Flowable自带的设计器。它的在线流程设计器界面并不友好我一般用IntelliJ IDEA的Flowable BPMN插件画好流程文件再上传到系统里部署。这样既方便调试也便于维护。2.3 消息中心WebSocket实时推送与企业微信通知协同办公的核心在“协同”协同的核心在“消息及时触达”。这套源码里消息中心实现了两条推送链路系统内的实时推送以及系统外的第三方平台推送。系统内推送我用的是WebSocket。当前端监听到有待办审批、公告发布、日程提醒这类事件时后端通过WebSocket连接推送到对应客户端网页上不用刷新就能看到红色角标。WebSocket这层的技术难度在于鉴权HTTP协议可以带token头但WebSocket握手时的鉴权方式就得另想办法。我的做法是允许首次握手请求带token参数建立连接后立刻校验token失败则直接关闭连接。另外提醒一点Nginx层如果有代理需要配置WebSocket的Upgrade头否则连接会一直断开这个问题在线上非常常见。系统外推送主要对接企业微信。现在很多公司的办公入口已经从PC端网页转移到了企业微信所以这套OA系统为企业微信预留了完整的对接方案企业微信内置应用可以配置可信域名后端调用企业微信的API发送“应用消息”就能把审批待办、会议通知推送到员工的企业微信上。这里有一个细节推送消息的卡片里包含了审批详情页的链接员工在企业微信里点开就能直接处理审批整套链路非常顺滑。类似方案的原理网上常说的“泛微OA与企业微信集成”走的也是这套逻辑。文件消息的推送还有个常见问题“协同办公无法下载文件”。我排查过很多次这类案例绝大多数不是代码问题而是Nginx或网关层对上传/下载接口的超时时间设置太短导致大文件下载时连接被强制断开。解决方法是给文件接口单独设置更长的代理超时时间并且下载接口响应头里必须带上正确的Content-Disposition和Content-Length这样客户端才能正确触发下载行为。2.4 文件管理预览、下载与在线协同编辑OA系统的文件管理功能上分三个层次最基本的存储与下载进阶的在线预览以及高阶的多人协同编辑。存储层我用MinIO搭了私有的对象存储服务。相比直接存服务器本地磁盘MinIO的好处是支持分片上传和断点续传大文件上传体验好支持桶策略方便做权限控制数据高可用不会因为单点磁盘故障丢数据。MinIO的Java SDK集成也不复杂核心代码量不大下载上传接口封装好之后其他模块调用就好。在线预览我接的是KkFileView这是一个开源的文档预览服务支持office、PDF、图片、视频等多种格式而且代码直接可用没必要重复造轮子。预览模块部署时可以把KkFileView单独部署成独立服务这样预览功能出问题时不会影响主业务。多人协同编辑是目前OA系统里最有技术含量的方向之一。OpenOffice的LibreOffice Online配合WOPI协议可以实现Web端多人同时编辑同一个文档。但说实话这个方案部署复杂度相当高对服务器资源要求也不低如果不是公司有强需求建议优先用“在线预览 评论留言”的轻量方案替代效果差距不大但维护成本能降一个量级。想要一步到位做在线编辑的可以先把Collabora Online独立部署做技术验证再考虑接入业务系统。3. 本地搭建与上线部署完整记录3.1 环境准备与初始化配置先把环境清单列出来我建议直接用这些版本因为这套源码就是基于以下版本验证过的JDK 1.8或11都行建议11后面排查问题省心Maven 3.6用3.8.x比较稳MySQL 5.78.0更好注意驱动版本Redis 5.0Node.js 14用于前端构建Nginx 1.20拿到源码后第一步不是急着启动而是先把配置改好。后端配置在application-dev.yml文件里改动点有三个数据库连接串、Redis连接串、文件存储路径。数据库建议先用源码自带的sql/init.sql初始化脚本里面包含了建库建表和基础数据管理员账号、角色权限、测试流程模板等直接用Navicat或命令行导入即可。有个从源码头开始就容易踩的坑JDK版本和Maven编译级别不一致。源码里我设置了maven.compiler.source为1.8但你本机装了JDK 17Maven编译时会报错。解决办法是保持源码里配的编译级别和你本机安装的JDK一致或者在IDE里Override对应的编译参数否则报错排查能让你怀疑人生。前端部分更简单npm install安装依赖然后npm run dev启动开发环境浏览器访问8080端口。前端的API请求地址统一在.env.development文件里配置指向后端服务的地址即可。前后端都启动成功后用管理员账号登录系统会跳转到工作台首页。3.2 前后端打包与Nginx部署本地验证没问题后接着就是部署到服务器。后端打包用mvn clean package -Dmaven.test.skiptrue生成一个可执行的jar包。这里要注意Spring Boot的打包插件有没有配好否则打出来的jar包不能独立运行。打包成功后在服务器上运行java -Xms512m -Xmx1024m -jar oa-system.jar --spring.profiles.activeprod生产环境的配置我放在application-prod.yml里数据库和Redis的地址要改成服务器上的实际地址日志级别建议调整为WARN避免生产环境日志量过大。前端部署稍微麻烦一点。npm run build会生成dist目录把这个目录下所有文件上传到服务器然后通过Nginx做静态资源服务。核心Nginx配置如下server { listen 80; server_name oa.example.com; # 前端静态资源 root /opt/oa-frontend/dist; index index.html; # 前端history路由防止刷新404 location / { try_files $uri $uri/ /index.html; } # 后端API反向代理 location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } # WebSocket代理 location /ws/ { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; } }这个配置里有几个关键点。第一是try_files $uri $uri/ /index.html如果这行不写前端页面刷新时会出现404因为Vue Router的history模式在刷新时会去真实路径找文件而这个路径并不存在。第二是8080端口的API地址生产环境你不想暴露服务端口必须用反向代理。第三是WebSocket要更换协议头并设置长连接超时否则协同编辑和待办通知功能会间歇性失灵。3.3 二次开发扩展点如何快速新增业务模块源码的价值除了直接用更在于二次开发。我在这套源码里预留了一个biz包路径专门放新开发的业务模块。比如公司需要一套“会议室预订”功能开发路径是这样的先在MySQL里建一张meeting_room_booking表然后在后端biz包下新建meeting模块按“Controller → Service → Mapper”结构写好增删改查接口权限部分只需要在菜单管理后台挂一个新的菜单和对应的按钮权限即可。前端在src/views下新建一个meeting页面用Element Plus的表格加表单组件几十行代码就能搞定一个像样的预订列表页面。一个值得提的扩展点是OA系统和第三方系统的单点登录集成。源码里预留了SsoFilter的代码位内部走JWT登录外部系统只要实现一个回调接口再依赖JWT生成token就能实现一次登录、多处共享Session的效果。这个网上关于“泛微OA单点登录”的讨论很多但自研实现其实也不复杂核心就是信任链和token传递。4. 常见问题排查与实战避坑清单4.1 典型问题排查速查表基于这套源码在实际使用中的高频问题我整理了一张排查速查表涵盖了从前端到后端、从部署到运行的各类场景。这张表建议直接收藏遇到问题先查一遍大概率能省下大量排查时间。问题现象大概率原因解决方案前端页面刷新后404Nginx未配置history路由回退在location /中添加try_files配置登录成功但接口返回401JWT过期或Redis中token信息丢失检查refreshToken刷新机制确认Redis持久化配置文件上传失败或文件大小为0Nginx限制上传大小在Nginx配置中增加client_max_body_size 50m文件下载时浏览器一直转圈代理超时时间过短为文件接口单独配置proxy_read_timeoutWebSocket连接不断断开Nginx未配置Upgrade头按上文配置Upgrade和Connection请求头审批流程发起后找不到下一步人流程模板任务分配表达式配置错误检查BPMN文件中candidateGroups和assignee的配置列表查询慢或数据库连接池耗尽连接池大小配置不合理按并发量调整maximum-pool-size检查慢SQL日志系统内存持续增长最终OOMJVM堆设置过小或代码缓存未清理设置-Xms和-Xmx用jstat检查GC情况时间显示比正常时间慢8小时数据库时区与服务器时区不一致JDBC URL添加serverTimezoneAsia/Shanghai下载的文件名中文乱码响应头未做编码处理使用URLEncoder.encode(fileName, UTF-8)处理文件名上述问题里前四个是部署期最容易踩的后几个是长期运行过程中逐渐暴露的。尤其“时间慢8小时”这个问题看起来问题不大但审批记录里的时间错乱会直接影响业务判断一定要在数据库初始化阶段就处理时区问题。4.2 我在实际开发中踩过的坑说到真实避坑每次都忍不住先讲工作流这块。Flowable的数据库表有几十张刚开始用的时候完全不知道哪些表要先关注。踩过几次坑之后我总结出了一个经验出问题时第一时间看几张学号以ACT_RU_开头的表这是运行时数据表里面全是当前正在执行的任务。而历史数据在ACT_HI_表里已经结束的流程实例都在那里。分清“运行时”和“历史”这两类表排查流程问题能少走好几条弯路。第二个坑是Redis缓存和数据库的一致性。OA系统里角色的权限变更、菜单修改这类操作会直接影响到token校验的结果。如果只改数据库不清理Redis缓存用户刷新页面的权限还是旧的。我的方案比较简单粗暴在修改角色或菜单的接口里主动调用Redis删除对应缓存宁可下次查询时重建也要确保变更即时生效。这个问题还牵扯到多台服务器时缓存需要广播但单体部署时直接删就够了不用过度设计。第三个坑跟定时任务有关。日程提醒、审批超时提醒这些功能都用到了Quartz定时任务。在本地开发时定时任务跑得很正常但生产环境是集群部署时每个节点都会同时触发任务导致重复发送提醒用户被各种重复通知烦到崩溃。我的解决办法是在定时任务里加一个分布式锁用Redis实现每次任务执行前先尝试加锁拿到锁的节点才执行任务。代码量不大但能避免一个非常影响体验的问题。第四个坑其实是个容易被忽略的“小点”报错日志。系统上线初期经常出现用户报告“页面打不开”但后端日志没有明显异常。排查了很长时间才发现是接口返回的JSON里包含了大量的空值字段前端在解析时NPE抛异常。这个问题的根治办法是全局配置Jackson对所有字段统一做空值处理并且约定后端接口必须用统一响应体返回错误信息要携带明确的状态码。这套规范建立起来后联调效率提升非常明显。也顺便说说Java版本这个老生常谈的话题。网上关于“Java环境变量配置”的教程一搜一大把但总有人绕不开这个坑。Windows环境下配置JAVA_HOME和PATH最关键的坑是系统变量和用户变量会同时生效如果两边都配了一个不同版本的JDK命令行输出java -version的结果会跟预期完全不一致。遇到这种情况把用户变量里的Java相关配置清掉只保留系统变量那一份问题立刻解决。另外Mac用户直接在~/.zshrc里配置即可Linux服务器装Java也建议用sudo apt install openjdk-11-jdk这类包管理器方式比自己解压配置省心很多。最后我想聊一下代码学习路径的问题。这段时间经常有人问我Java的OA系统源码应该怎么学我的建议是不要按顺序从头到尾硬啃而是“带着问题学”。你先跑起来然后用实际工作里的需求去逼自己改代码。比如公司要求“审批驳回时允许选择驳回到任何一步”你就去Flowable文档里查怎么实现完整驳回要求“文件上传时自动压缩图片”你就去研究Thumbnailator集成。当你把七八个这样的真实需求逐一落地后这套源码里的绝大部分逻辑就都吃透了。我个人认为这种“需求驱动式学习”比任何结构化的教程都管用。如果你打算用这套源码做二次开发最后再分享一个我个人的习惯不管系统多忙每一次上线前必须把数据库备份做完整。OA系统里的审批数据、日志数据一旦丢失找回的代价是不可想象的。自己搭一套简单的备份脚本每天定时备份看起来是个很基础的事但不出问题的人永远不会理解备份有多重要直到真正的故障发生时。希望这篇分享能帮你少走些弯路。本文还有配套的精品资源点击获取 Java协同办公OA系统实战：从Spring Boot设计到部署
简介协同办公OA系统是企业数字化转型中最基础也最具代表性的业务应用其核心价值在于打通审批流、权限管控与消息协同。从技术原理来看一套成熟的OA系统通常基于RBAC权限模型设计用户-角色-菜单的细粒度访问控制并引入Flowable等工作流引擎驱动业务流程同时结合Spring Boot构建模块化后端服务配合Vue等前端框架实现前后端分离架构。这种组合不仅提升了开发效率还赋予了系统灵活的二次开发能力是企业自建OA、替代商业定制的高性价比方案。在实际应用场景中无论是高校毕业设计、个人Spring Boot练手项目还是企业内部办公平台搭建都可以参考这种源码级实践路径。本文围绕一套完整Java OA系统源码从技术选型、核心模块设计到部署上线与常见避坑策略系统梳理了OA系统从0到1的落地全过程。 做Java开发这些年经手过不少企业项目但要说最能体现“Java后端基本功”的还得是协同办公OA系统。这个品类特别有意思你说它难无非就是增删改查加审批流你说它简单用户权限、流程引擎、消息通知、文件协同这些模块每个都能单独写成几篇长文。我最近正好在系统梳理一套完整的Java协同办公OA系统源码从技术选型到部署上线再到二次开发踩了不少坑也积累了一些实战经验。这篇就围绕这套源码把OA系统从设计到落地的完整链路讲清楚。不管你是准备用Java做毕业设计、想把OA作为Spring Boot练手项目的开发者还是公司需要自建OA的技术负责人这篇内容应该都能给你一些参考价值。1. 项目整体设计与技术选型思路1.1 技术栈选型为什么是 Spring Boot Vue 这套组合OA系统的本质是“一堆业务模块 一套权限体系 一条审批链路”。看起来简单但真正落地时对技术选型的要求其实很高既要快速开发又要稳定易维护还得方便日后扩展。我最终选定的组合是Spring Boot 2.7 Spring Security JWT MyBatis-Plus Redis MySQL Vue 3 Element Plus。后端用Spring Boot基本没什么悬念这是目前Java生态里开发效率最高的框架。Spring Security加JWT做认证授权既保证了安全性又贴合前后端分离的场景。MyBatis-Plus是我个人比较偏好的ORM框架OA系统里有大量复杂的多表关联查询和报表统计MyBatis-Plus在写复杂SQL时比JPA更灵活而且代码生成器能直接省掉大量重复的CRUD工作。前端选Vue 3 Element Plus主要是因为Element Plus的组件库对后台管理系统极其友好。表格、表单、弹窗、树形控件这些OA高频组件都是开箱即用能省下大量写UI的时间。这里有个选型细节要提一下如果你的团队对Vue不熟其实也可以考虑用若依这类已经封装好的脚手架做基础但前提是你得能驾驭它的代码结构否则后期维护反而是灾难。有个比较关键的决定是我放弃了微服务架构选择了单体应用。很多人一上来就想上Spring Cloud但OA系统绝大多数场景根本用不到微服务。单体应用部署简单、调试方便、资源占用低对几百人规模的企业完全够用。等到系统真正出现性能瓶颈时再按模块拆分也不迟这就是所谓的“演进式架构”。提示技术选型不是越新越好也不是越复杂越好核心是匹配业务场景和团队能力。如果团队里没人用过微服务强行上Spring Cloud只会把项目拖垮。1.2 系统架构与模块边界划分这套OA系统的整体架构可以用“前后端分离 模块化单体”来概括。前端独立部署通过Nginx反向代理访问后端API后端按业务领域拆分为独立模块代码层面用Maven多模块工程管理。模块划分是我觉得这套源码里最有参考价值的部分。我在设计时没有按“部门模块”“员工模块”这种传统方式划分而是围绕“协同”这个核心诉求拆了六个核心模块模块核心功能技术要点用户权限模块用户、角色、菜单、部门管理数据权限控制RBAC模型Spring Security JWT工作流模块审批流程定义、发起、审批、驳回、会签、转办Flowable流程引擎BPMN 2.0消息中心模块站内信、待办通知、公告提醒、企业微信通知WebSocket实时推送 第三方推送文件管理模块文件上传下载、在线预览、协同编辑MinIO存储KkFileView预览日程任务模块日程管理、任务分配、提醒Quartz定时任务 消息推送报表统计模块考勤统计、审批统计、项目进度看板ECharts MyBatis-Plus聚合查询这种按业务能力划分模块的方式好处在后期扩展时能明显感受到。比如公司想加一个“物资领用审批”只需要在工作流模块里定义新的流程模板在菜单里挂上对应入口就行完全不需要动其他模块的代码。数据层面我用了MySQL Redis的组合。MySQL存业务主数据Redis承担三件事JWT token的存储和校验、热点数据的缓存、以及协同编辑时的会话状态管理。数据库连接池用HikariCP这是目前综合表现最好的连接池Spring Boot 2.x默认就是它不需要额外配置。1.3 和商业OA系统的对比为什么要做自己的OA讲到OA系统很多人第一反应是“直接用泛微、致远不就行了干嘛自己开发”这个问题的答案恰恰是我做这套源码的出发点。商业OA的优势是功能全面、开箱即用但问题也很突出。最核心的问题是定制成本高。商业OA虽然提供表单设计和流程配置但一旦遇到公司特有的业务逻辑比如“部门主管审批后需要抄送财务和HR”“合同金额超过50万需要走专项会签”这些规则在商业OA里实现起来非常痛苦。定制开发按人天收费价格不菲而且升级后定制代码可能被覆盖。第二是系统集成难。现在企业越来越依赖企业微信、钉钉这类的办公平台需要把OA的待办消息、公告通知直接推送到企微或钉钉上。商业OA虽然也支持但接口文档复杂、权限模型封闭对接周期往往比预期长很多。而自研OA在消息推送、单点登录这些集成点上完全自主可控实现一次就能长期受益。我见过太多公司在商业OA上投入大量预算最后用的还是最基础的审批和公告功能真正有价值的定制需求全卡在售后和成本上。自研OA虽然初期投入大但系统是完全属于自己的资产数据不绑死、功能可演进、代码可审计。对于有一定技术团队的公司来说这个账其实是划算的。2. 核心功能实现与实操要点2.1 RBAC权限模型从表设计到接口鉴权权限系统是OA系统的地基也是面试中最高频的考点。这套源码用的是经典的五表RBAC模型用户表、角色表、菜单表、用户角色关联表、角色菜单关联表。在此基础上我额外加了一张部门表通过“用户所属部门”来实现数据权限的控制。表设计的关键在于菜单表必须支持树形结构即菜单可以有多级子菜单而且类型要区分目录、菜单、按钮三级。这就涉及到“按钮级权限”的概念比如同样是“审批管理”菜单A角色只能查看列表B角色可以点击“通过”按钮这就是通过按钮权限进行细粒度控制的。后端接口的权限控制我分了两个层面。第一层是身份认证所有请求先走JWT过滤器校验token是否有效、是否过期第二层是请求授权使用Spring Security的PreAuthorize注解配合自定义权限表达式在方法级别控制“谁可以访问这个接口”。这样一来权限控制的粒度可以精确到任何一个按钮、任何一个接口。这里分享一个我在实际项目中踩过的坑JWT的过期时间设置。如果你把token过期时间设成7天用户登录后超过7天没有操作系统会强制退出这在OA这种需要长期在线的场景里非常影响体验。但设置过长又有安全隐患。我的方案是“双token机制”一个短期token负责正常业务一个长期refresh token负责刷新。这样既保证了安全用户登录一次能一直用不用反复输密码。2.2 工作流审批Flowable在OA中的落地细节工作流是OA系统最硬核的部分也是拉开项目和项目之间差距的分水岭。我用的Flowable引擎它是Activity 5/6的延续版本API更简洁、社区更活跃而且是国内企业级项目中使用率最高的流程引擎。Flowable的核心思路是“流程定义驱动业务”。流程定义用一个BPMN 2.0标准的XML文件描述里面定义了节点、连线、条件、任务分配规则。在实际业务中你只需要在管理后台里维护好这个流程定义文件业务代码完全不用改。举个例子请假审批流程定义如下发起申请 → 直属领导审批 → 部门经理审批 → 抄送HR。这个流程在Flowable里有清晰的任务节点定义而系统内的“新增请假”功能只需要调用发起流程的API后续的流转全部交给Flowable管理。但流程引擎本身只是“骨架”真正的业务复杂度在于各种边界情况。比如“驳回”操作就有驳回到上一步、驳回到发起人、驳回到指定节点三种模式对应到Flowable里是对不同任务节点的处理逻辑。再比如“会签”就是一单申请需要多个人同时审批全部同意才算通过这在Flowable里需要配置多实例节点并设定AND类型的完成条件。这些细节如果不在开发前梳理清楚后期改起来会非常痛苦。注意如果项目里的审批流程很复杂建议不要过度依赖Flowable自带的设计器。它的在线流程设计器界面并不友好我一般用IntelliJ IDEA的Flowable BPMN插件画好流程文件再上传到系统里部署。这样既方便调试也便于维护。2.3 消息中心WebSocket实时推送与企业微信通知协同办公的核心在“协同”协同的核心在“消息及时触达”。这套源码里消息中心实现了两条推送链路系统内的实时推送以及系统外的第三方平台推送。系统内推送我用的是WebSocket。当前端监听到有待办审批、公告发布、日程提醒这类事件时后端通过WebSocket连接推送到对应客户端网页上不用刷新就能看到红色角标。WebSocket这层的技术难度在于鉴权HTTP协议可以带token头但WebSocket握手时的鉴权方式就得另想办法。我的做法是允许首次握手请求带token参数建立连接后立刻校验token失败则直接关闭连接。另外提醒一点Nginx层如果有代理需要配置WebSocket的Upgrade头否则连接会一直断开这个问题在线上非常常见。系统外推送主要对接企业微信。现在很多公司的办公入口已经从PC端网页转移到了企业微信所以这套OA系统为企业微信预留了完整的对接方案企业微信内置应用可以配置可信域名后端调用企业微信的API发送“应用消息”就能把审批待办、会议通知推送到员工的企业微信上。这里有一个细节推送消息的卡片里包含了审批详情页的链接员工在企业微信里点开就能直接处理审批整套链路非常顺滑。类似方案的原理网上常说的“泛微OA与企业微信集成”走的也是这套逻辑。文件消息的推送还有个常见问题“协同办公无法下载文件”。我排查过很多次这类案例绝大多数不是代码问题而是Nginx或网关层对上传/下载接口的超时时间设置太短导致大文件下载时连接被强制断开。解决方法是给文件接口单独设置更长的代理超时时间并且下载接口响应头里必须带上正确的Content-Disposition和Content-Length这样客户端才能正确触发下载行为。2.4 文件管理预览、下载与在线协同编辑OA系统的文件管理功能上分三个层次最基本的存储与下载进阶的在线预览以及高阶的多人协同编辑。存储层我用MinIO搭了私有的对象存储服务。相比直接存服务器本地磁盘MinIO的好处是支持分片上传和断点续传大文件上传体验好支持桶策略方便做权限控制数据高可用不会因为单点磁盘故障丢数据。MinIO的Java SDK集成也不复杂核心代码量不大下载上传接口封装好之后其他模块调用就好。在线预览我接的是KkFileView这是一个开源的文档预览服务支持office、PDF、图片、视频等多种格式而且代码直接可用没必要重复造轮子。预览模块部署时可以把KkFileView单独部署成独立服务这样预览功能出问题时不会影响主业务。多人协同编辑是目前OA系统里最有技术含量的方向之一。OpenOffice的LibreOffice Online配合WOPI协议可以实现Web端多人同时编辑同一个文档。但说实话这个方案部署复杂度相当高对服务器资源要求也不低如果不是公司有强需求建议优先用“在线预览 评论留言”的轻量方案替代效果差距不大但维护成本能降一个量级。想要一步到位做在线编辑的可以先把Collabora Online独立部署做技术验证再考虑接入业务系统。3. 本地搭建与上线部署完整记录3.1 环境准备与初始化配置先把环境清单列出来我建议直接用这些版本因为这套源码就是基于以下版本验证过的JDK 1.8或11都行建议11后面排查问题省心Maven 3.6用3.8.x比较稳MySQL 5.78.0更好注意驱动版本Redis 5.0Node.js 14用于前端构建Nginx 1.20拿到源码后第一步不是急着启动而是先把配置改好。后端配置在application-dev.yml文件里改动点有三个数据库连接串、Redis连接串、文件存储路径。数据库建议先用源码自带的sql/init.sql初始化脚本里面包含了建库建表和基础数据管理员账号、角色权限、测试流程模板等直接用Navicat或命令行导入即可。有个从源码头开始就容易踩的坑JDK版本和Maven编译级别不一致。源码里我设置了maven.compiler.source为1.8但你本机装了JDK 17Maven编译时会报错。解决办法是保持源码里配的编译级别和你本机安装的JDK一致或者在IDE里Override对应的编译参数否则报错排查能让你怀疑人生。前端部分更简单npm install安装依赖然后npm run dev启动开发环境浏览器访问8080端口。前端的API请求地址统一在.env.development文件里配置指向后端服务的地址即可。前后端都启动成功后用管理员账号登录系统会跳转到工作台首页。3.2 前后端打包与Nginx部署本地验证没问题后接着就是部署到服务器。后端打包用mvn clean package -Dmaven.test.skiptrue生成一个可执行的jar包。这里要注意Spring Boot的打包插件有没有配好否则打出来的jar包不能独立运行。打包成功后在服务器上运行java -Xms512m -Xmx1024m -jar oa-system.jar --spring.profiles.activeprod生产环境的配置我放在application-prod.yml里数据库和Redis的地址要改成服务器上的实际地址日志级别建议调整为WARN避免生产环境日志量过大。前端部署稍微麻烦一点。npm run build会生成dist目录把这个目录下所有文件上传到服务器然后通过Nginx做静态资源服务。核心Nginx配置如下server { listen 80; server_name oa.example.com; # 前端静态资源 root /opt/oa-frontend/dist; index index.html; # 前端history路由防止刷新404 location / { try_files $uri $uri/ /index.html; } # 后端API反向代理 location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } # WebSocket代理 location /ws/ { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; } }这个配置里有几个关键点。第一是try_files $uri $uri/ /index.html如果这行不写前端页面刷新时会出现404因为Vue Router的history模式在刷新时会去真实路径找文件而这个路径并不存在。第二是8080端口的API地址生产环境你不想暴露服务端口必须用反向代理。第三是WebSocket要更换协议头并设置长连接超时否则协同编辑和待办通知功能会间歇性失灵。3.3 二次开发扩展点如何快速新增业务模块源码的价值除了直接用更在于二次开发。我在这套源码里预留了一个biz包路径专门放新开发的业务模块。比如公司需要一套“会议室预订”功能开发路径是这样的先在MySQL里建一张meeting_room_booking表然后在后端biz包下新建meeting模块按“Controller → Service → Mapper”结构写好增删改查接口权限部分只需要在菜单管理后台挂一个新的菜单和对应的按钮权限即可。前端在src/views下新建一个meeting页面用Element Plus的表格加表单组件几十行代码就能搞定一个像样的预订列表页面。一个值得提的扩展点是OA系统和第三方系统的单点登录集成。源码里预留了SsoFilter的代码位内部走JWT登录外部系统只要实现一个回调接口再依赖JWT生成token就能实现一次登录、多处共享Session的效果。这个网上关于“泛微OA单点登录”的讨论很多但自研实现其实也不复杂核心就是信任链和token传递。4. 常见问题排查与实战避坑清单4.1 典型问题排查速查表基于这套源码在实际使用中的高频问题我整理了一张排查速查表涵盖了从前端到后端、从部署到运行的各类场景。这张表建议直接收藏遇到问题先查一遍大概率能省下大量排查时间。问题现象大概率原因解决方案前端页面刷新后404Nginx未配置history路由回退在location /中添加try_files配置登录成功但接口返回401JWT过期或Redis中token信息丢失检查refreshToken刷新机制确认Redis持久化配置文件上传失败或文件大小为0Nginx限制上传大小在Nginx配置中增加client_max_body_size 50m文件下载时浏览器一直转圈代理超时时间过短为文件接口单独配置proxy_read_timeoutWebSocket连接不断断开Nginx未配置Upgrade头按上文配置Upgrade和Connection请求头审批流程发起后找不到下一步人流程模板任务分配表达式配置错误检查BPMN文件中candidateGroups和assignee的配置列表查询慢或数据库连接池耗尽连接池大小配置不合理按并发量调整maximum-pool-size检查慢SQL日志系统内存持续增长最终OOMJVM堆设置过小或代码缓存未清理设置-Xms和-Xmx用jstat检查GC情况时间显示比正常时间慢8小时数据库时区与服务器时区不一致JDBC URL添加serverTimezoneAsia/Shanghai下载的文件名中文乱码响应头未做编码处理使用URLEncoder.encode(fileName, UTF-8)处理文件名上述问题里前四个是部署期最容易踩的后几个是长期运行过程中逐渐暴露的。尤其“时间慢8小时”这个问题看起来问题不大但审批记录里的时间错乱会直接影响业务判断一定要在数据库初始化阶段就处理时区问题。4.2 我在实际开发中踩过的坑说到真实避坑每次都忍不住先讲工作流这块。Flowable的数据库表有几十张刚开始用的时候完全不知道哪些表要先关注。踩过几次坑之后我总结出了一个经验出问题时第一时间看几张学号以ACT_RU_开头的表这是运行时数据表里面全是当前正在执行的任务。而历史数据在ACT_HI_表里已经结束的流程实例都在那里。分清“运行时”和“历史”这两类表排查流程问题能少走好几条弯路。第二个坑是Redis缓存和数据库的一致性。OA系统里角色的权限变更、菜单修改这类操作会直接影响到token校验的结果。如果只改数据库不清理Redis缓存用户刷新页面的权限还是旧的。我的方案比较简单粗暴在修改角色或菜单的接口里主动调用Redis删除对应缓存宁可下次查询时重建也要确保变更即时生效。这个问题还牵扯到多台服务器时缓存需要广播但单体部署时直接删就够了不用过度设计。第三个坑跟定时任务有关。日程提醒、审批超时提醒这些功能都用到了Quartz定时任务。在本地开发时定时任务跑得很正常但生产环境是集群部署时每个节点都会同时触发任务导致重复发送提醒用户被各种重复通知烦到崩溃。我的解决办法是在定时任务里加一个分布式锁用Redis实现每次任务执行前先尝试加锁拿到锁的节点才执行任务。代码量不大但能避免一个非常影响体验的问题。第四个坑其实是个容易被忽略的“小点”报错日志。系统上线初期经常出现用户报告“页面打不开”但后端日志没有明显异常。排查了很长时间才发现是接口返回的JSON里包含了大量的空值字段前端在解析时NPE抛异常。这个问题的根治办法是全局配置Jackson对所有字段统一做空值处理并且约定后端接口必须用统一响应体返回错误信息要携带明确的状态码。这套规范建立起来后联调效率提升非常明显。也顺便说说Java版本这个老生常谈的话题。网上关于“Java环境变量配置”的教程一搜一大把但总有人绕不开这个坑。Windows环境下配置JAVA_HOME和PATH最关键的坑是系统变量和用户变量会同时生效如果两边都配了一个不同版本的JDK命令行输出java -version的结果会跟预期完全不一致。遇到这种情况把用户变量里的Java相关配置清掉只保留系统变量那一份问题立刻解决。另外Mac用户直接在~/.zshrc里配置即可Linux服务器装Java也建议用sudo apt install openjdk-11-jdk这类包管理器方式比自己解压配置省心很多。最后我想聊一下代码学习路径的问题。这段时间经常有人问我Java的OA系统源码应该怎么学我的建议是不要按顺序从头到尾硬啃而是“带着问题学”。你先跑起来然后用实际工作里的需求去逼自己改代码。比如公司要求“审批驳回时允许选择驳回到任何一步”你就去Flowable文档里查怎么实现完整驳回要求“文件上传时自动压缩图片”你就去研究Thumbnailator集成。当你把七八个这样的真实需求逐一落地后这套源码里的绝大部分逻辑就都吃透了。我个人认为这种“需求驱动式学习”比任何结构化的教程都管用。如果你打算用这套源码做二次开发最后再分享一个我个人的习惯不管系统多忙每一次上线前必须把数据库备份做完整。OA系统里的审批数据、日志数据一旦丢失找回的代价是不可想象的。自己搭一套简单的备份脚本每天定时备份看起来是个很基础的事但不出问题的人永远不会理解备份有多重要直到真正的故障发生时。希望这篇分享能帮你少走些弯路。本文还有配套的精品资源点击获取