简介这套JFinalOA办公系统 v1.0 基础版是一份基于Java JFinal框架的轻量级OA项目源码面向Java Web初学者、毕业设计者以及需要快速搭建内部办公系统的小型团队。系统涵盖用户管理、工作流审批、公文、日程、会议、文件管理等常见OA模块包含用户角色权限、通知发布等基础能力便于理解真实业务系统如何组织分层与权限控制。压缩包共2000个文件以775个html页面、675个js脚本和254个java源码为主另有160个css、SQL数据库脚本及properties等配置整体大小仅34.06MB结构清晰、便于本地部署与二次开发。目前已有158人学习下载。通过学习整套代码可掌握JFinal的ActiveRecord数据库操作、MVC分层设计、模板引擎与前端交互方式同时还能参考工作流引擎集成思路是一份适合实战练习和毕业设计的完整参考工程。1. JFinalOA v1.0 基础版到底是什么为什么值得自己跑一遍先把结论放在前面JFinalOA 不是那种装完就能给全公司开 account 的商业产品它是一个基于 JFinal 框架、面向中小团队二次开发的 OA 源码包。v1.0 基础版意味着它只包含办公系统最核心的那几块——用户与部门管理、权限控制、流程审批、公告通知这类刚需功能工作流引擎、报表中心这些重模块通常不在这个版本里。正因为功能少代码路径短反而适合用来把「从一份 zip 到一套可用的 OA 系统」这件事完整走通。很多人在本地部署这类项目时第一步就死在环境上JDK 版本不对、MySQL 编码不对、Tomcat 版本过高导致类加载报错。JFinalOA 恰好能把这些坑全部暴露出来因为 JFinal 框架本身对运行环境的要求很具体。这篇文我会按自己的落地顺序来写——先讲 JFinal 框架里 JFinalOA 真正用到的核心机制再讲 zip 包解压后怎么配置数据库和 Tomcat然后把基础版里最有代表性的审批流程代码从头捋一遍最后说清楚从「本地能跑」到「生成环境敢用」之间还差哪些必调的参数。整个过程不需要你先懂 JFinal但走完一遍你对 JFinal 的路由和 ActiveRecord 的认知会比看十篇教程都深。2. 认识 JFinal 框架JFinalOA 能跑起来依赖的三件套JFinal 在国内 Java 圈里算是一股清流它不依赖 Spring整个框架的核心就三个东西JFinalConfig 配置类、路由表和 ActiveRecord。JFinalOA v1.0 的代码里你能看到的所有 Controller 和 Service 都没有 Spring 的 Autowired 注解取而代之的是 JFinal 自己的依赖注入和静态方法调用。2.1 JFinalConfig 是唯一入口三个方法缺一不可打开 JFinalOA 源码包里的核心配置类一般叫JFinalOaConfig.java你会看到它继承了JFinalConfig并重写了三个方法configConstant、configRoute、configPlugin。这三个方法各有分工缺一个项目就起不来。public class JFinalOaConfig extends JFinalConfig { // 1. 配置常量端口、开发模式、上传目录等 public void configConstant(Constants me) { me.setDevMode(true); // 开发模式改代码不重启 me.setEncoding(UTF-8); // 全局编码 me.setUploadedFileSavePath(/data/oa/upload); // 上传文件保存路径 } // 2. 配置路由把 URL 映射到 Controller public void configRoute(Routes me) { me.add(/login, LoginController.class); // 登录页 me.add(/user, UserController.class); // 用户管理 me.add(/flow, FlowController.class); // 审批流程 } // 3. 配置插件数据库连接池、ActiveRecord 插件 public void configPlugin(Plugins me) { DruidPlugin dp new DruidPlugin(jdbcUrl, userName, password); me.add(dp); ActiveRecordPlugin arp new ActiveRecordPlugin(dp); arp.addMapping(sys_user, SysUser.class); // 表 sys_user 映射到模型 me.add(arp); } }这段代码的逻辑很清楚configConstant决定运行模式生产环境必须把setDevMode(false)否则每改一次文件就自动扫一遍模板浪费性能不说还有安全风险。configRoute是整个 OA 系统的路由表所有页面跳转都靠这里配置的映射关系。configPlugin里最关键的是addMapping它把数据库表和 Java 模型类绑在一起之后你操作数据库就不再写 JDBC 代码而是直接操作模型对象。注意JFinalOA 的数据库连接参数一般写在configPlugin方法里或者是通过loadPropertyFile加载外部配置文件。你可以看到源码里经常出现getProperty(jdbcUrl)这种写法意思是优先从配置文件中读取读不到才用默认值。改数据库配置时优先找.properties文件别直接改 Java 代码。2.2 路由表就是 OA 的「菜单地图」看懂它就能摸清系统功能JFinal 的路由配置比 Spring MVC 的注解式路由更集中。在 JFinalOA 里所有功能入口都在configRoute里登记比如上面代码中的/login就对应登录功能。如果你拿到源码后一头雾水不知道该从哪里看起我建议你第一步就是打开路由配置文件把每个 URL 对应的 Controller 用 Excel 列一遍系统有哪些功能就一目了然了。JFinal 路由还支持me.add(/flow, FlowController.class, /views/flow)这种三参数写法第三个参数是模板文件的基础路径。这意味着/flow/index会去找/views/flow/index.html渲染页面。很多 JFinal 新手在这里犯迷糊——Controller 返回的字符串是逻辑视图名实际文件位置要看路由里的第三个参数。JFinalOA 的目录结构一般是这样src/main/java └── com.oa ├── config # JFinalConfig 配置类 ├── controller # 控制器处理 HTTP 请求 ├── model # ActiveRecord 模型对应数据库表 ├── service # 业务逻辑层 └── interceptor # 拦截器做权限控制 src/main/webapp └── views # HTML 页面模板2.3 ActiveRecord 让 JFinalOA 不用写 SQL 也能操作数据库JFinalOA 不是用 MyBatis 也不是用 Hibernate它用的是 JFinal 自带的 ActiveRecord 插件。这个插件最直观的体验是数据库表结构变了Java 模型类也跟着改但不需要写 XML 映射文件。比如说sys_user表对应的模型类就是一个继承ModelSysUser的空类public class SysUser extends ModelSysUser { public static final SysUser dao new SysUser().dao(); // 查询某个用户名对应的用户 public SysUser findByUsername(String username) { return dao.findFirst(select * from sys_user where username ?, username); } // 获取该用户的角色列表 public ListSysRole getRoles() { return SysRole.dao.find(select r.* from sys_role r inner join sys_user_role ur on r.id ur.role_id where ur.user_id ?, getInt(id)); } }这里重点是dao这个静态对象它是数据库操作的入口。findFirst返回单条记录find返回列表问号是占位符后续参数按顺序传入有效防止 SQL 注入。getInt(id)是从当前模型实例中取值对应数据库里id字段。如果 JFinalOA 的某个功能要改查询逻辑你只需要在这类方法里调整 SQL不需要去碰 XML mapper这就是 ActiveRecord 带来的便利。JFinal 的 Model 还有一个特性如果表的主键名不是id需要在addMapping里指定主键名否则findById这类方法会失效。JFinalOA 基础版里大部分表主键都叫id但像角色权限关联表经常会用联合主键这类表就不会映射成 Model而是直接在 Service 里写 SQL 操作。3. 解压部署 JFinalOA从 zip 包到本地可访问的完整步骤拿到 JFinalOA v1.0 基础版.zip 后你面对的是一个包含源码和数据库脚本的压缩包。部署思路很明确解压源码到 IDE、建数据库、导入 SQL 脚本、配置连接参数、启动 Tomcat。下面按顺序走每一步我会说明为什么这么做以及常见的坑在哪里。3.1 环境准备与目录解压JFinalOA 是典型的 Java Web 项目最稳妥的组合是 JDK 1.8 Maven 3.6 Tomcat 8.5 MySQL 5.7。之所以不用 JDK 11 或 Tomcat 9是因为 JFinal 早版本对高版本 Tomcat 的兼容性不好Tomcat 9 默认使用 Jakarta 命名空间而 JFinal 4.x 之前的版本还是基于 javax.servlet 编译的硬跑会报ClassNotFoundException: javax.servlet.Filter。用 JDK 8 配合 Tomcat 8.5 最省心。解压后先看目录结构重点确认两点第一根目录有没有pom.xml有就说明是 Maven 项目可以直接用 IDEA 导入第二有没有doc或者sql文件夹数据库初始化脚本基本都在里面。如果找到的是.sql文件就用命令行导入后面会写。# 解压 zip 包Linux/MacWindows 直接右键解压即可 unzip JFinalOA办公系统_v1.0_基础版.zip -d /workspace/oa # 查看解压后的目录结构 cd /workspace/oa find . -maxdepth 2 -type d | sort参数说明-d指定解压目标目录建议路径不要带中文和空格否则 Maven 编译时会有一些隐性的编码和路径问题。find命令里-maxdepth 2限制只往下看两层目录主要是为了快速定位src、webapp、sql这类关键目录层数太深会输出大量无关文件。3.2 导入数据库脚本注意字符集和 SQL 版本创建数据库时字符集选utf8mb4排序规则选utf8mb4_general_ci。很多 OA 系统的数据库脚本里包含表情符号比如审批意见里可能有 Emojiutf8mb4才能正常存储。用命令行导入时一定要指定--default-character-setutf8mb4否则历史遗留的utf8注释里特殊字符可能会报错。-- 创建一个独立的 OA 数据库用户口令自己设 CREATE DATABASE jfinal_oa DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; -- 创建专用账号避免直接用 root 跑应用生产环境尤其重要 CREATE USER oa_userlocalhost IDENTIFIED BY Oa2025#Local; GRANT ALL PRIVILEGES ON jfinal_oa.* TO oa_userlocalhost; FLUSH PRIVILEGES;# 导入核心数据表结构注意路径换成你的设计稿里的实际文件名 mysql -uoa_user -p --default-character-setutf8mb4 jfinal_oa /workspace/oa/sql/jfinal_oa_init.sql mysql -uoa_user -p --default-character-setutf8mb4 jfinal_oa /workspace/oa/sql/jfinal_oa_data.sql上面两个文件的拆分逻辑是第一个建表结构第二个插初始化数据。如果只有单文件init.sql那初始化数据一般就在同一个文件里。导入后先验证一下表数量mysql -uoa_user -p -e use jfinal_oa; show tables;正常会有 20 张以上的表。如果一张表都没有检查是不是导入到了别的数据库或者 SQL 脚本里有USE语句被注释掉了。3.3 修改 JFinalOA 的数据库连接和端口配置JFinalOA 的数据库配置隐藏在src/main/resources下的jfinal.properties或者直接在configPlugin里写死。找到后改成这样# 数据库连接配置 jdbcUrl jdbc:mysql://localhost:3306/jfinal_oa?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai user oa_user password Oa2025#Local # 开发模式开关 devMode true # 上传文件保存路径本地时用绝对路径 uploadPath /workspace/oa_upload参数逐个说useSSLfalse是因为本地测试不需要 SSL 加密MySQL 8.0 默认开 SSL不关会有一堆警告日志serverTimezoneAsia/Shanghai是因为新版驱动要求显式指定时区否则日期查询比你本地时间慢 8 小时uploadPath是用户上传头像和附件保存的位置Tomcat 重启不会丢千万别放到 Tomcat 的 webapps 目录里。改完这些在 IDEA 里配置 Tomcat 时要留意Application context设置为/不要是/jfinaloa_war_exploded否则所有路由访问都要带前缀和configRoute里配置的路径对不上。如果是在 Tomcat 的server.xml里配Context同理。3.4 启动项目并验证登录功能启动后访问http://localhost:8080/login看到登录页面说明框架本身没问题。此时先别急着登录观察 IDEA 控制台输出。JFinalOA 启动成功后控制台会打印路由表每一行格式类似GET /login LoginController.login()如果路由表为空八成是 Controller 扫描路径配置错了。用基础版自带的初始账号登录常见的是admin/admin123或者admin/123456具体看jfinal_oa_data.sql里sys_user表插入的初始记录。登录进去后第一件事是看“系统管理”菜单下有没有角色管理和权限分配这是判断基础版功能边界的最快方式。如果登录后点击菜单报 404先别怀疑路由问题打开浏览器开发者工具的 Network 面板看失败请求的 URL再去configRoute里找对应的映射路径90% 是大小写不匹配。4. 基础版核心功能实现拆解用户权限与审批流程跑通部署只是第一步真正有价值的是看懂 JFinalOA 基础版里权限和审批是怎么实现的。这两块是所有 OA 系统的地基理解了它们往里面加模块就是复制粘贴改改表的熟练工活。4.1 用户权限控制的实现方式Shiro 拦截器加权限注解JFinalOA 的权限控制不走 Spring Security它用的是 JFinal 的拦截器机制配合一套简单的权限注解。在 JFinal 里拦截器分全局、Controller 级和方法级三种。JFinalOA 的做法是定义一个AuthInterceptor作为全局拦截器每个 Controller 的方法上标一个RequiresPermissions(user:add)这样的注解拦截器解析注解判断当前登录用户有没有对应权限。Before(AuthInterceptor.class) public class UserController extends Controller { // 添加用户需要 user:add 权限 RequiresPermissions(user:add) public void add() { SysUser user getModel(SysUser.class, ); // 接收表单参数并封装成模型 boolean ok userService.createUser(user, getPara(roles)); if (ok) { renderJson(Result.success()); } else { renderJson(Result.error(用户名已存在)); } } // 删除用户需要 user:delete 权限 RequiresPermissions(user:delete) public void delete() { int userId getParaToInt(id); userService.deleteUser(userId); renderJson(Result.success()); } }这段代码的关键点在Before(AuthInterceptor.class)和RequiresPermissions(user:add)的配合。Before是 JFinal 的 AOP 入口指定了 Controller 里所有方法都要经过AuthInterceptor检查RequiresPermissions是自定义注解拦截器会读取当前方法上的权限标识再和数据库里该用户拥有的权限列表比对。如果用户没有权限拦截器直接renderError(403)方法体根本不会执行。JFinalOA 权限模块的数据库设计一般是三张表sys_user用户、sys_role角色、sys_permission权限中间还有sys_user_role和sys_role_permission两张关联表。新增一个权限项目的完整链路是先往sys_permission表插入一条记录比如user:export然后在角色管理页面勾选这个权限最后在 Controller 方法上加上RequiresPermissions(user:export)注解。这个设计相当直观也是绝大多数国产 OA 的标准做法。提示排查「某个用户为什么能看到某菜单」时按这个链路查用户表 →sys_user_role→ 角色表 →sys_role_permission→ 权限表 → 菜单表。任何一个环节断了菜单或按钮就不会显示。4.2 审批流程的状态机实现一张表单加一个状态字段基础版里的审批流程不会用 Activiti 或 Flowable 这种重量级工作流引擎它通常是自研的「状态机 任务表」方案。拿「请假申请」举例数据库里会有一张oa_leave表核心字段就是applicant_id申请人、current_approver_id当前审批人、status(0待提交1审批中2通过3驳回)、approval_history审批历史 JSON这几个。业务层代码会按当前状态决定下一步操作public class LeaveService { // 提交申请状态从待提交变成审批中 public void submit(int leaveId) { OaLeave leave OaLeave.dao.findById(leaveId); if (leave.getInt(status) ! 0) { throw new RuntimeException(只有待提交状态才能提交); } leave.set(status, 1); // 审批中 leave.set(current_approver_id, findManager(leave.getInt(applicant_id))); leave.update(); } // 审批操作通过或驳回 public void approve(int leaveId, boolean approved, String comment) { OaLeave leave OaLeave.dao.findById(leaveId); if (approved) { leave.set(status, 2); // 审批通过 } else { leave.set(status, 3); // 驳回 leave.set(current_approver_id, leave.getInt(applicant_id)); // 退回给申请人 } // 追加审批历史到 JSON 字段里 ListMapString, Object history JSON.parseArray(leave.getStr(approval_history)); history.add(buildHistoryEntry(comment)); leave.set(approval_history, JSON.toJSONString(history)); leave.update(); } }这段代码胜在逻辑短但涵盖了审批流最基本的动作状态校验、状态流转、任务指派人变更和历史留痕。findManager方法是查审批链路上的上级一般是从部门表里找部门负责人的 ID如果部门负责人为空就往上级部门找直到找到为止。它的局限也很明显不支持条件分支和会签、或签。比如「请假超过 3 天需要总经理审批」这种规则submit方法里就得硬编码一段if (days 3) findManager...else findDeptLeader...逻辑。JFinalOA 基础版这么做可以理解——它是让你先跑通流程理解状态流转的核心思路而不是一上来就把 BPMN 2.0 规范搬进来。4.3 前端菜单是怎么根据权限渲染出来的基础版的后台页面通常是 JFinal 自带的模板引擎加上 Bootstrap 或 Layui 这类前端 UI 库。登录成功后后台框架页会有一个异步请求去拉取当前用户的可见菜单。这个逻辑不在 Controller 的方法里直接返回 HTML而是返回一个 JSON 数组由前端动态拼接菜单 DOM。// 加载当前用户可见的一级菜单 $.ajax({ url: /menu/list, type: GET, dataType: json, success: function (result) { var menuHtml ; $.each(result.data, function (index, menu) { menuHtml li classnav-item a href menu.url classnav-link i class menu.icon /i span menu.name /span/a/li; }); $(#sidebar-menu).html(menuHtml); } });对应的后端 Controller 会查询当前用户关联的角色再取这些角色拥有的菜单权限最后过滤掉is_show0的隐藏菜单按sort_no排序返回。这段逻辑常见的问题是缓存修改了角色的菜单权限后用户重新登录菜单还是旧的。JFinal 的 Session 和缓存机制在 JFinalOA 里往往会把菜单列表缓存起来排查时需要找到缓存工具类调用CacheKit.remove(menuCache, userId)手动清理。5. 从基础版到生产部署前必须过一遍的参数和改造点v1.0 基础版能跑通业务但离上生产还差几步。按我自己的经验把部署层次从「本机能开」提到「运维能接手」至少要把下面这几项调完否则等线上出了安全问题再改就是给全员加班。5.1 必改的 5 个参数对应你踩到的最常见生产问题配置项开发环境值生产环境建议值原因devModetruefalse开发模式会自动重载模板且异常页面暴露类名和方法名jdbcUrllocalhost:3306内网数据库域名 useSSLtrue明文连接数据库有被截获的风险上传路径/workspace/oa_upload独立挂载盘如/data/oa_upload避免 Tomcat 重装导致上传文件丢失session 超时默认 30 分钟具体业务定如 120 分钟超时过短导致用户在写单时被强制下线Tomcat maxThreads默认 200看压测结果一般 400-600线程太少高峰期请求排队太多内存吃紧这里重点说devModefalse的价值。JFinal 在开发模式下每次请求都会检查模板文件是否变化同时把报错堆栈完整打印在页面上。生产环境开 devMode用户能直接看到你的数据库表名和类名这是给攻击者送情报。5.2 Nginx 反代加静态资源缓存顺手解决附件下载问题JFinalOA 的附件下载接口如果直接用 Tomcat 处理大文件会占满 Tomcat 线程。生产环境最常见的做法是 Nginx 直接托管上传目录下载请求不经过 Java 应用。下面是一个可以抄的配置server { listen 80; server_name oa.example.com; # 上传附件静态化处理 location /upload/ { alias /data/oa_upload/; expires 7d; add_header Cache-Control public; break; } # 动态请求转发到 Tomcat location / { 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 支持如果 JFinalOA 用了即时消息模块 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }这样改动后/upload/开头的请求直接由 Nginx 读磁盘返回Tomcat 只处理/login、/flow这类需要走 Java 代码的请求。注意alias路径末尾必须有/否则 URL 拼接时会多一层目录。生产环境如果用了 HTTPS还需要把 80 端口重写到 443再在 443 的 server 块里加同样配置。5.3 验证部署是否达到可发布状态的三条命令部署完成后别急着宣告成功。以下三条命令是我每次验收必跑的专门用来暴露隐藏问题# 1. 检查数据库连接池是否稳定重启后能正常连库 curl -I -s http://localhost:8080/login | head -n 3 # 2. 确认 devMode 已关闭错误页面不再输出堆栈信息 # 故意访问一个不存在的地址观察响应里有没有 Java 类名 curl -s http://localhost:8080/nonexist-page | grep -i Controller # 3. 模拟本地上传验证附件目录可写 echo test /data/oa_upload/write_test.txt # 4. 观察 Tomcat 日志有无异常堆栈 tail -f /opt/tomcat/logs/catalina.out | grep -E ERROR|Exception第二点尤其值得注意开发模式下devModetrue访问不存在的 URLJFinal 会返回包含 Controller 类名和方法名的 404 页面关闭后就是一个干净的 404 响应页。如果在生产环境的响应里还看到com.oa.controller.xxx字样说明配置没生效Tomcat 加载的还是旧的 class 文件需要clean重新编译再发布。等到这三条命令都通过JFinalOA 基础版才算真正达到可以交给别人使用的状态。本文还有配套的精品资源点击获取