Java协同办公OA系统源码部署与二次开发实战指南

简介：这是一套基于SpringBoot的Java协同办公OA系统源码，面向需要学习企业级办公自动化开发或搭建内部管理平台的开发者，涵盖前后端完整实现。前台采用springboot+freemark+jpa+mybatis+mysql，后台以springboot为核心，持久层融合jpa与mybatis，模板引擎使用freemark，整体结构较为完整。资源包共2443个文件，包含285个java源码、301个ftl模板、172个js脚本、122个css样式及549个png、376个gif等前端素材，另有241个class、106个xml配置与13个properties文件，压缩包约25.54MB。系统覆盖系统管理、用户管理、考勤管理、流程管理、公告管理、邮件管理、任务管理、日程管理、计划管理和文件管理十大模块，可实现数据字典、角色权限、部门职位调动、考勤日报周报月报、费用报销与出差请假等审批流、内部邮件附件收发、任务状态跟踪、日历式日程计划以及文件分类归档分享。目前已有872人学习下载，适合作为毕业设计、课程实践或二次开发参考。

1. Java协同办公OA系统源码：一套能跑起来的企业级工程到底长什么样

很多团队在选型协同办公系统时，第一反应是找现成的 Java OA 系统源码，想着拿过来改改就能上线。但真正把源码拉下来跑一遍，十有八九会卡在环境配置、数据库初始化、权限模型看不懂这三道坎上。协同办公 OA 系统的本质，是把「人、事、流程、文档」四件事用一套权限体系串起来的企业级 Web 工程，典型技术栈是 Spring Boot + MyBatis-Plus + MySQL + Redis + Vue，后端负责流程引擎和权限，前端负责表单和审批流渲染。它适合两类人：一类是想自建内部办公平台的中小团队技术负责人，另一类是想通过读一套完整业务系统源码来补工程经验的 Java 工程师。这篇笔记不讲空泛概念，只讲一套 OA 源码从环境配置到流程引擎落地的完整路径，以及那些只有真正部署过才会遇到的坑。

2. 环境配置与工程结构：把源码跑起来的第一步

2.1 JDK、Maven、MySQL 的版本对齐

拿到一套 Java OA 源码，最先翻车的往往不是代码本身，而是环境版本对不上。OA 系统通常依赖 Spring Boot 2.x 或 3.x，对应的 JDK 版本要求完全不同。Spring Boot 2.7 及以下用 JDK 8 或 11 都能跑，Spring Boot 3.x 则强制要求 JDK 17 以上。我一般会先看 pom.xml 里的 parent 版本，再决定装哪个 JDK。

# 查看当前 JDK 版本，确认是否满足项目要求 java -version # 如果项目要求 JDK 17，用 SDKMAN 切换（Linux/Mac） sdk install java 17.0.9-tem sdk use java 17.0.9-tem # 配置 JAVA_HOME（Windows 示例，Linux 改 /etc/profile） # 系统变量新增 JAVA_HOME = C:\Program Files\Java\jdk-17 # Path 中追加 %JAVA_HOME%\bin

Maven 版本建议用 3.8 以上，因为部分 OA 源码会用到 Maven 3.8 才支持的镜像配置语法。MySQL 版本要和源码里application.yml的驱动匹配：com.mysql.cj.jdbc.Driver对应 MySQL 8.x，com.mysql.jdbc.Driver对应 5.7。Redis 一般用 6.x 即可，主要用来缓存登录 token 和字典数据。

提示：不要急着改代码，先把application-dev.yml里的数据库地址、账号、密码、Redis 地址改成自己本地的，再执行mvn clean install -DskipTests编译。

2.2 数据库初始化与表结构导入

OA 源码的数据库脚本通常放在sql/或doc/sql/目录下，文件名类似oa_system.sql。导入时有两个细节容易忽略：一是字符集必须用utf8mb4，否则审批意见里的 emoji 或特殊符号会报错；二是部分表有外键约束，导入顺序不能乱。

-- 创建数据库，字符集必须是 utf8mb4 CREATE DATABASE oa_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; -- 导入脚本（命令行方式） -- mysql -u root -p oa_system < oa_system.sql -- 导入后检查核心表是否齐全 USE oa_system; SHOW TABLES; -- 重点关注：sys_user（用户）、sys_role（角色）、sys_menu（菜单）、 -- oa_flow_definition（流程定义）、oa_flow_instance（流程实例）、 -- oa_leave（请假单）、oa_document（文档）

如果导入报Foreign key constraint fails，说明脚本里的建表顺序有问题，常见做法是先执行SET FOREIGN_KEY_CHECKS = 0;，导入完成后再SET FOREIGN_KEY_CHECKS = 1;。导入完成后，用SELECT COUNT(*) FROM sys_menu;确认菜单数据是否写入，菜单表为空会导致登录后左侧导航一片空白。

2.3 启动类与配置文件的关键参数

OA 系统的启动类通常叫OaApplication或AdminApplication，用@SpringBootApplication注解。启动前重点检查三个配置项：文件上传路径、JWT 密钥、跨域配置。

# application-dev.yml 关键配置片段 server: port: 8080 servlet: context-path: /oa spring: datasource: url: jdbc:mysql://localhost:3306/oa_system?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver redis: host: localhost port: 6379 database: 0 servlet: multipart: max-file-size: 50MB # 附件上传大小，OA 系统经常要传合同扫描件 max-request-size: 100MB # 文件存储路径，Windows 和 Linux 路径写法不同 file: upload-path: /data/oa/upload/ # Linux # upload-path: D:/oa/upload/ # Windows # JWT 配置，密钥长度建议 32 位以上 jwt: secret: your-32-char-secret-key-here expire: 7200 # token 过期时间，单位秒

serverTimezone=Asia/Shanghai这个参数不加，插入的时间会差 8 小时，审批记录的时间线全乱。max-file-size设太小，用户传个 PDF 合同就报MaxUploadSizeExceededException。JWT 的expire设太短，用户填一半表单就被踢出登录，设太长又有安全风险，7200 秒（2 小时）是常见折中值。

启动成功后访问http://localhost:8080/oa，默认账号密码一般在sys_user表里，常见的是admin/admin123或admin/123456。如果登录报 401，先检查 Redis 是否启动，再检查 JWT 密钥是否和源码里硬编码的一致。

3. 权限模型与流程引擎：OA 系统源码里最值钱的两块

3.1 RBAC 权限模型：用户、角色、菜单、按钮四级联动

协同办公 OA 系统的权限模型基本都是 RBAC（基于角色的访问控制）的变体，核心是五张表：sys_user、sys_role、sys_user_role、sys_menu、sys_role_menu。用户通过角色关联菜单，菜单表里用menu_type区分目录、菜单、按钮三种类型。

// 典型的权限查询 SQL（MyBatis-Plus 写法） @Select("SELECT DISTINCT m.perms FROM sys_menu m " + "LEFT JOIN sys_role_menu rm ON m.menu_id = rm.menu_id " + "LEFT JOIN sys_user_role ur ON rm.role_id = ur.role_id " + "WHERE ur.user_id = #{userId} AND m.perms IS NOT NULL") List<String> selectPermsByUserId(Long userId);

这段 SQL 返回的是权限标识字符串，比如oa:leave:add、oa:leave:approve。后端用 Spring Security 或 Shiro 的@PreAuthorize("hasAuthority('oa:leave:approve')")注解做接口级校验，前端用v-hasPermi指令控制按钮显隐。这里有个常见误区：只控制菜单不控制按钮，结果用户通过接口直接调用审批接口，绕过了前端限制。所以接口层的权限注解一个都不能省。

菜单表的parent_id字段构成树形结构，前端用递归组件渲染侧边栏。如果新增了一个菜单但左侧不显示，排查顺序是：sys_menu里visible是否为0（0 表示显示）、status是否为0（0 表示正常）、当前角色是否在sys_role_menu里关联了这个菜单。

3.2 流程引擎选型：Activiti、Flowable 还是自研

OA 系统最核心的功能是审批流，请假、报销、采购、用印都走流程。源码里常见的流程引擎有三种：Activiti 7、Flowable 6、以及轻量级自研状态机。Activiti 和 Flowable 同源，Flowable 对 Spring Boot 的集成更友好，性能也更好，新项目我一般推荐 Flowable。

// Flowable 启动一个请假流程实例的典型代码 @Autowired private RuntimeService runtimeService; public void startLeaveProcess(Long userId, String leaveDays) { // 设置流程变量，审批节点用 ${days > 3} 这样的表达式做条件分支 Map<String, Object> variables = new HashMap<>(); variables.put("initiator", userId); variables.put("days", Integer.parseInt(leaveDays)); variables.put("approveResult", null); // 按流程定义 key 启动实例 ProcessInstance instance = runtimeService.startProcessInstanceByKey( "leave_process", // 对应 oa_flow_definition 里的 key String.valueOf(userId), variables ); System.out.println("流程实例 ID：" + instance.getId()); }

流程定义文件是 BPMN 2.0 格式的 XML，放在resources/processes/目录下。一个请假流程通常包含：开始事件 → 发起人节点 → 部门经理审批 → 判断网关（天数 > 3 走总经理审批）→ 结束事件。网关条件用${days > 3}和${days <= 3}配置在连线上。

自研状态机适合流程简单、不想引入重型引擎的场景，核心是一张oa_flow_instance表加一张oa_flow_task表，用status字段驱动状态流转。优点是轻量、可控，缺点是复杂流程（会签、驳回、加签）实现起来很痛苦。如果 OA 系统只有请假和报销两种流程，自研够用；如果要支持任意流程配置，还是上 Flowable。

3.3 审批节点的驳回与加签实现

驳回是 OA 流程里最容易出 bug 的地方。Flowable 原生不支持「驳回到任意节点」，需要自己实现。常见做法是在流程变量里记录每个节点的执行历史，驳回时删除当前任务，重新创建一个指向目标节点的任务。

// 驳回到指定节点的简化实现 public void rejectToNode(String taskId, String targetActivityId) { Task task = taskService.createTaskQuery().taskId(taskId).singleResult(); if (task == null) { throw new RuntimeException("任务不存在或已处理"); } // 记录驳回原因到流程变量 taskService.setVariable(taskId, "rejectReason", "材料不完整，请补充"); taskService.setVariable(taskId, "rejectTarget", targetActivityId); // 删除当前任务 taskService.deleteTask(taskId, "驳回操作"); // 重新创建目标任务（实际项目中需要结合历史活动查询） // 这里简化处理，真实场景要用 HistoricActivityInstance 查目标节点 runtimeService.createChangeActivityStateBuilder() .processInstanceId(task.getProcessInstanceId()) .moveActivityIdTo(task.getTaskDefinitionKey(), targetActivityId) .changeState(); }

加签分前加签和后加签：前加签是在当前审批人之前插入一个节点，后加签是在当前审批人之后插入。Flowable 用addMultiInstanceExecution实现会签加签，但代码复杂度较高。如果源码里没有现成的加签实现，建议先用「转办」功能替代，转办是把任务指派给另一个人，实现简单且能满足大部分场景。

注意：流程引擎的数据库表有 20 多张，升级 Flowable 版本时表结构可能变化，生产环境升级前一定要在测试库跑一遍flowable.database-schema-update=true的自动更新，确认无误再上生产。

4. 避坑与排查：部署 OA 源码时最容易翻车的 5 个地方

4.1 登录后菜单空白，控制台报 403

现象：输入账号密码能登录成功，但左侧菜单栏一片空白，浏览器控制台报403 Forbidden，请求/system/menu/getRouters返回权限不足。

原因：菜单查询接口需要system:menu:list权限，但当前登录用户的角色没有关联这个菜单权限。常见于手动在数据库里新增了用户，但忘了在sys_user_role里关联角色，或者关联了角色但sys_role_menu里没有菜单数据。

解决：先查SELECT * FROM sys_user_role WHERE user_id = ?确认用户有角色；再查SELECT * FROM sys_role_menu WHERE role_id = ?确认角色有菜单；如果都为空，手动插入关联数据，或者用 admin 账号登录后在「角色管理」里给角色分配菜单权限。

4.2 流程启动报No process definition found

现象：调用启动流程接口时抛异常org.flowable.common.engine.api.FlowableObjectNotFoundException: no processes deployed with key 'leave_process'。

原因：BPMN 文件没有被正确部署到 Flowable 的ACT_RE_PROCDEF表。可能是文件没放在resources/processes/目录下，或者文件名和startProcessInstanceByKey里的 key 不一致，或者 Spring Boot 没有扫描到流程文件。

解决：检查application.yml里flowable.check-process-definitions: true是否开启；确认 BPMN 文件里的<process id="leave_process">和代码里的 key 完全一致；启动后查SELECT * FROM ACT_RE_PROCDEF;看有没有记录，没有的话手动调用repositoryService.createDeployment().addClasspathResource("processes/leave.bpmn20.xml").deploy();部署一次。

4.3 附件上传成功但下载 404

现象：用户上传合同附件提示成功，数据库oa_document表里也有记录，但点击下载报 404。

原因：文件存储路径配置的是相对路径，比如upload-path: ./upload/，Spring Boot 启动时的工作目录和预期不一致，文件实际存到了别的地方。或者 Nginx 反向代理时没有配置静态资源映射。

解决：把upload-path改成绝对路径，Linux 用/data/oa/upload/，Windows 用D:/oa/upload/。如果用了 Nginx，加一段location /upload/ { alias /data/oa/upload/; }。另外检查file.upload-path目录的读写权限，Linux 下用chmod 755和chown确保运行用户有权限。

4.4 审批时间线显示差 8 小时

现象：流程审批记录里的时间比实际时间早 8 小时，比如实际下午 3 点审批，记录显示早上 7 点。

原因：MySQL 连接串缺少serverTimezone=Asia/Shanghai，或者 JVM 时区不是东八区。Flowable 默认用 UTC 时间存储，读取时需要转换。

解决：JDBC URL 加上serverTimezone=Asia/Shanghai；启动参数加-Duser.timezone=Asia/Shanghai；如果历史数据已经错了，用UPDATE ACT_HI_TASKINST SET START_TIME_ = DATE_ADD(START_TIME_, INTERVAL 8 HOUR) WHERE ...修正（操作前备份）。

4.5 并发审批导致任务重复处理

现象：两个审批人同时打开同一个待办任务，都点了「同意」，结果流程走了两次，或者报乐观锁异常。

原因：Flowable 的任务表用REV_字段做乐观锁，但前端没有做防重复提交，两个请求同时到达时，第一个请求完成后REV_变了，第二个请求校验失败。

解决：前端按钮点击后立即置灰，后端在complete方法上加分布式锁（Redis 锁），key 用taskId。代码示例：

public void completeTask(String taskId, Map<String, Object> variables) { String lockKey = "flow:task:" + taskId; Boolean locked = redisTemplate.opsForValue() .setIfAbsent(lockKey, "1", 10, TimeUnit.SECONDS); if (Boolean.FALSE.equals(locked)) { throw new RuntimeException("任务正在处理中，请勿重复提交"); } try { taskService.complete(taskId, variables); } finally { redisTemplate.delete(lockKey); } }

5. 从能跑到好用：OA 源码二次开发的两个进阶技巧

5.1 用 MyBatis-Plus 代码生成器快速扩展业务模块

一套 OA 源码跑通之后，下一步就是加自己的业务模块，比如车辆管理、会议室预约。手写 Controller、Service、Mapper、XML 太慢，用 MyBatis-Plus 的代码生成器可以从数据库表直接生成全套代码。

// MyBatis-Plus 代码生成器配置 public class CodeGenerator { public static void main(String[] args) { AutoGenerator generator = new AutoGenerator(); // 全局配置 GlobalConfig globalConfig = new GlobalConfig(); globalConfig.setOutputDir(System.getProperty("user.dir") + "/src/main/java"); globalConfig.setAuthor("oa-dev"); globalConfig.setOpen(false); globalConfig.setSwagger2(true); generator.setGlobalConfig(globalConfig); // 数据源配置 DataSourceConfig dsc = new DataSourceConfig(); dsc.setUrl("jdbc:mysql://localhost:3306/oa_system?serverTimezone=Asia/Shanghai"); dsc.setUsername("root"); dsc.setPassword("your_password"); dsc.setDriverName("com.mysql.cj.jdbc.Driver"); generator.setDataSource(dsc); // 包配置 PackageConfig pc = new PackageConfig(); pc.setParent("com.oa.system"); pc.setModuleName("vehicle"); generator.setPackageInfo(pc); // 策略配置：指定要生成的表名 StrategyConfig strategy = new StrategyConfig(); strategy.setInclude("oa_vehicle", "oa_vehicle_apply"); // 表名 strategy.setNaming(NamingStrategy.underline_to_camel); strategy.setColumnNaming(NamingStrategy.underline_to_camel); strategy.setEntityLombokModel(true); strategy.setRestControllerStyle(true); generator.setStrategy(strategy); generator.execute(); } }

生成后把vehicle目录下的文件复制到项目对应位置，再在sys_menu表里插入菜单记录，在sys_role_menu里给角色授权，一个业务模块就接入了。注意生成的 Mapper XML 要放到resources/mapper/下，且application.yml里mybatis-plus.mapper-locations要包含这个路径。

5.2 用接口幂等和操作日志兜住生产环境的玄学问题

OA 系统上线后最怕的不是功能少，而是「用户说提交了但数据没保存」这种扯皮。我的习惯是在所有写接口上加幂等注解和操作日志，出问题时能查。

// 自定义幂等注解 @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface Idempotent { int expire() default 5; // 过期时间，秒 } // AOP 切面实现 @Aspect @Component public class IdempotentAspect { @Autowired private RedisTemplate<String, String> redisTemplate; @Around("@annotation(idempotent)") public Object around(ProceedingJoinPoint joinPoint, Idempotent idempotent) throws Throwable { HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder.getRequestAttributes()).getRequest(); // 用 token + 请求路径 + 参数 MD5 作为唯一 key String token = request.getHeader("Authorization"); String key = "idem:" + DigestUtils.md5DigestAsHex( (token + request.getRequestURI() + Arrays.toString(joinPoint.getArgs())).getBytes()); Boolean success = redisTemplate.opsForValue() .setIfAbsent(key, "1", idempotent.expire(), TimeUnit.SECONDS); if (Boolean.FALSE.equals(success)) { throw new RuntimeException("请勿重复提交"); } return joinPoint.proceed(); } }

操作日志用 Spring 的@EventListener监听自定义事件，把「谁在什么时间对哪个模块做了什么操作」写入sys_oper_log表。字段至少包含：操作人、操作模块、操作类型、请求方法、请求参数、返回结果、耗时、IP。生产环境排查问题时，这张表比任何日志文件都管用。

提示：幂等 key 的过期时间不要设太长，5 到 10 秒足够覆盖用户误触场景，设太长会导致正常业务被拦截。

这套 OA 源码从环境配置到流程引擎再到二次开发，真正跑通一遍大概需要两三天，但踩过的坑会记很久。我自己的习惯是每部署一套新源码，先建一个deploy-notes.md，把版本号、配置改动、报错和解决方式一条条记下来，下次换环境直接照着做，比翻聊天记录靠谱得多。希望帮到你。

本文还有配套的精品资源，点击获取