1. OFCMS搭建之前这是个什么样的系统第一次接触 OFCMS 的时候我正在给一个做机械设备的企业官网重新选后台。需求很直接文章要能分类、能上传图文、能配置产品页和联系方式最好部署起来省事、不依赖太多外部组件。试了一圈之后发现OFCMS 这套基于 Java 的开源 CMS 正好踩在这些需求点上。它不像 WordPress 那样依赖 PHP 环境也不像纯手写后台那样什么都得从零开发本质上是借了 Spring Boot 的便利把常规的栏目、文章、用户、权限、模板渲染这些事情全包掉了属于给中间层用户设计的内容管理方案。OFCMS 的定位很清晰面向中小型企业官网、个人博客、行业门户以及教学演示项目。如果你是只会 Java 基础、还没接触过完整 Web 项目的初学者看这套系统能弄明白一个后台管理系统从数据库到页面的完整链路如果你是运维或全栈会关注它的部署成本和扩展方式如果你是公司里负责内容维护的运营那只要关心后台好不好用。这个覆盖面听起来很大但实际上它的设计并不臃肿核心就是能快速跑起来、能改模板、能往后继续加业务。我之所以愿意把它单独拿出来写一篇搭建文章不光是记录一次部署过程更是想把我踩过的编译坑、数据库字符集坑、静态资源加载问题都一次说清楚。网上关于 OFCMS 的资料不算多尤其是一些细节配置不少帖子只说改一下配置文件就能跑但真正跑起来之后遇到乱码、密码错误、404又得来回折腾。这篇文章面向两类读者一类是想立刻部署一套可用 CMS 的实操人群另一类是想拿它学习 Spring Boot 项目的开发者。我不会只给命令还会解释每一步为什么要这么做。先说结论OFCMS 搭建并没有特别高的门槛JDK 1.8、MySQL、Maven 三样就够。只要把环境变量配好、数据源改准确编译打包基本一次能过。真正花时间的部分在于后期模板调整和内容规划但这一块恰恰是 CMS 该做的事情也说明它已经具备一个成熟系统的基本骨架了。2. 搭建前的环境准备与版本选择2.1 运行环境与版本建议动手之前先把依赖梳理清楚。OFCMS 是 Java 技术栈的 Maven 多模块项目基于 Spring Boot 搭建所以环境准备相对简单没有 Redis、Solr 这类强依赖常规跑起来只需要 JDK、MySQL、Maven。给出我在部署时使用的推荐版本组件推荐版本说明JDK1.8兼容性最稳妥不要一上来就上 JDK 11 以上MySQL5.7字符集问题少初始化 SQL 兼容性高Maven3.6.x构建工具版本太老会有依赖下载问题Nginx1.18生产环境反向代理用本地可以跳过Git有就装方便拉取仓库和后续更新JDK 版本是我第一个要强调的坑。OFCMS 的早期版本基于较老的 Spring Boot 分支编写虽然新版本也有人验证过能在 JDK 11 上跑但没必要拿生产环境去赌兼容性。我本地用的就是 JDK 1.8配好JAVA_HOME之后一路顺畅。如果你电脑上同时装了多个 JDK建议在命令行先执行java -version确认当前默认版本避免编译时用了错误环境。MySQL 推荐 5.7 而不是 8.0原因有两个一是 8.0 默认认证插件是caching_sha2_password老版本 JDBC 驱动不认识容易报Public Key Retrieval is not allowed这类误导性错误二是 OFCMS 初始化 SQL 如果包含老的建表语法在 8.0 下偶尔会出兼容警告。当然如果你一定要用 MySQL 8.0也不是完全不行需要在连接参数里显式加上allowPublicKeyRetrievaltrueuseSSLfalse同时换成对应的最新驱动版本。这个我在后面配置部分会给出参考。2.2 本地开发与生产环境怎么搭配本地跑和服务器上跑环境策略略有差异。本地建议直接使用 IDEA 打开项目让 IDEA 自动识别 Maven 工程配合内嵌的终端执行命令改配置、看日志都方便。服务器上则不需要装 IDEA装好 JDK、Git、MySQL、Maven拉到源码后直接命令行编译打包即可。生产环境我个人的习惯是数据库单独一台或者至少独立实例Nginx 负责 80 端口和 HTTPS 证书后端应用监听内网端口比如 8080。这样的好处是后续更新不用动 Nginx 配置只需重新打一个 Jar 包替换并重启进程。如果你只是想在内网测试也可以直接java -jar跑起来用 IP 加端口访问功能上没有任何差异。2.3 MySQL 初始化与字符集设置在导入任何 SQL 之前先把数据库建好并且一定要指定字符集。这一步太重要了因为 OFCMS 默认是中文内容系统如果数据库字符集用了默认的latin1后面所有中文标题、正文都会变成问号。我通常在 MySQL 命令行执行以下操作CREATE DATABASE IF NOT EXISTS ofcms DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER ofcmslocalhost IDENTIFIED BY YourPass123; GRANT ALL PRIVILEGES ON ofcms.* TO ofcmslocalhost; FLUSH PRIVILEGES;为什么要用utf8mb4而不是utf8因为 MySQL 的utf8最多支持 3 字节而utf8mb4是完整的 4 字节 UTF-8 支持。虽然 CMS 内容表单里有生僻字或 emoji 的概率不高但一旦出现普通utf8就会报Incorrect string value到时候再去改库和表字符集比现在多花几倍时间。账号密码可以按自己习惯改但建议不要用过于简单的口令因为 CMS 后台暴露在公网上之后弱密码很容易被扫描工具盯上。建库这一步也可以先不做有些版本在配置好数据库连接后启动时会自动建库建表甚至内置初始化数据。但我不建议依赖这种自动行为显式建库可以让你对数据落点有绝对控制排查问题时心里更有底。3. 源码下载、配置与编译打包3.1 获取源码与项目结构OFCMS 在 GitHub 上有开源仓库直接以 ofcms 为关键词搜索就能找到。我建议用git clone而不是下载压缩包原因很简单后续如果官方修复了问题你git pull就能拿到更新而且克隆时自带.git历史万一改动出错还能回滚。git clone gitgithub.com:oufu/ofcms.git cd ofcms拉下来之后先花五分钟看一下目录结构。OFCMS 采用 Maven 多模块设计常见模块包括核心包、后台管理模块、前台展示模块等。第一次看的人不用纠结每个模块的全部细节重点关注application.properties或application.yml这类配置文件它们决定了系统连哪个数据库、监听哪个端口、使用什么模板路径。查看模块结构可以用 Maven 命令mvn -pl ofcms-admin -am clean package -DskipTests不过先别急着执行我通常会先打开pom.xml确认当前 Maven 构建使用的主模块名和继承关系。不同版本模块名可能有细微差异直接复制别人的命令如果模块对不上会报Could not find artifact。3.2 修改数据源与基础配置OFCMS 的核心配置集中在application.properties文件中。你要改的无非是数据库连接、端口、上下文路径这几项。下面是一份我经过多次验证的配置参考server.port8080 server.servlet.context-path/ofcms spring.datasource.urljdbc:mysql://localhost:3306/ofcms?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai spring.datasource.usernameofcms spring.datasource.passwordYourPass123 spring.datasource.driver-class-namecom.mysql.jdbc.Driver这里的关键点有三个。第一连接 URL 里必须带上characterEncodingutf8这是解决中文乱码的第一道保险和数据库字符集配合使用才能生效。第二serverTimezoneAsia/Shanghai不要省略否则新版 MySQL 驱动会报时区错误。第三context-path设置成/ofcms之后访问地址就是http://IP:8080/ofcms如果不想要这个前缀可以直接删掉这一行但从运维角度我建议保留方便和同服务器上的其他应用做区分。还有一点容易被忽略如果你准备连 MySQL 8.0driver-class-name建议改成com.mysql.cj.jdbc.Driver并在 URL 中追加allowPublicKeyRetrievaltrue。这属于版本驱动差异导致的常见问题我在第五章速查表里会再提一次。3.3 编译打包与产物说明配置改完就可以执行构建了。我习惯先跑完整构建让 Maven 把所有模块都编译一遍确认模块间没有依赖问题mvn clean install -DskipTests如果你的网络环境下载依赖很慢建议先配置阿里云 Maven 镜像。打开~/.m2/settings.xml在 mirror 节点里加入阿里云公共仓库地址。这个步骤不是必须的但国内服务器执行mvn时默认从中央仓库拉包的速度可能慢到让人怀疑人生。配置镜像后整个构建时间可能从十几分钟缩短到两三分钟。构建成功后在对应的启动模块target目录下会生成一个可执行 Jar 包例如ofcms-admin.jar。这个 Jar 是 Spring Boot 内置 Tomcat 打出来的直接java -jar就能启动不需要额外装 Tomcat。如果你公司内部规范要求部署到独立 Tomcat也可以用 Maven 配置打成 War 包然后把 War 丢到 Tomcat 的webapps目录。两种方式各有优劣Jar 方式部署简单适合快速上线War 方式便于和已有 Java Web 应用统一管理适合特定运维规范。4. 部署启动、后台初始化与模板替换4.1 一分钟后跑起来编译完成之后进入启动模块的target目录执行java -jar ofcms-admin.jar启动日志会冲刷出来看到类似Started OfcmsAdminApplication的提示就说明启动成功。第一次启动如果数据库里还没有数据OFCMS 会通过 ORM 机制自动建表并可能写入初始化数据。这个阶段多等几秒不要看到控制台卡住就认为出问题。启动之后打开浏览器访问http://localhost:8080/ofcms。如果页面正常加载出首页或后台登录页说明环境、数据库、代码三者已经打通。如果只是白屏先别急着看代码回到控制台日志里搜ERROR或Exception大多数问题日志里都会直接指明原因。4.2 后台登录与站点信息配置登录后台之前先确认默认账号密码。OFCMS 不同版本默认管理员可能不一样我看到过的常见默认值是admin / admin123也有版本初始密码是123456。为了避免记错最稳妥的办法是去源码或初始化 SQL 文件里搜admin关键词看密码字段对应的哈希值对应什么明文。如果初始化脚本里用的是明文密码那直接就能看出来如果是加密串就对照项目文档确认默认密码。登录成功之后建议立刻做三件事第一修改默认管理员密码第二完善站点名称、URL、SEO 关键词等基础设置第三创建不同权限的角色和内容编辑账号。很多做内容运营的人习惯所有人共用管理员账号这在内部测试没问题但一旦站点上线且有多个编辑人员账号权限不清会带来很大的管理混乱。后台里还需要关注菜单分类、栏目层级和模板绑定关系。OFCMS 的页面通常是由栏目绑定模板来决定的这意味着你想让某个页面长成什么样关键不是改数据库而是找到对应模板文件去调整 HTML。我第一次用的时候满后台找页面内容怎么改后来才反应过来CMS 的内容存在数据库里页面怎么展示却由模板决定。这个理解越早建立后面越顺畅。4.3 模板选择与替换模板是 OFCMS 搭建里最有价值也最容易劝退新手的部分。项目自带的默认模板通常是够用的基础风格适合测试但如果你要做正式站点一般需要定制模板。模板文件通常放在启动模块的模板目录下常见的结构是templates或webapp下的页面文件。拿到一套新模板后我习惯先复制一份默认模板的同目录结构再在后台新建一个模板方案把页面文件替换进去。这样即使改坏了切回默认模板就能立刻恢复不会把正在运行的站点搞挂。替换模板时要注意静态资源路径问题。模板里的 CSS、JS、图片引用最好使用包含上下文路径的写法否则部署到带/ofcms前缀的路径下资源可能变成 404。在模板升级时还要关注后台上传图文的存储路径OFCMS 默认会存到本地磁盘目录如果服务器有磁盘清理策略别把这些目录排除在外。5. 常见问题与排查技巧实录5.1 启动报数据库连接失败这是搭建过程中最常见的问题表现是启动日志里出现Cannot create PoolableConnectionFactory或Access denied for user。前者通常是数据库还没启动、端口不对、库名拼错后者则是用户名或密码错误。我的排查顺序是固定的先执行systemctl status mysql或ps -ef | grep mysql确认数据库在跑再手动用配置里的账号登录一次排除权限问题最后检查 URL 里的 host、port、database 三者是否和实际环境完全一致。如果开启了远程访问还要确认 MySQL 用户允许的 host 范围是不是%否则在应用服务器上连接会被拒绝。还有一个隐蔽点连接 URL 里如果把localhost写成127.0.0.1在有些环境下会走到 IPv6 的解析逻辑导致连接超时。如果应用服务器和数据库在同一台机器建议直接用localhost。5.2 中文乱码问题中文乱码我至少见过三种表现页面中文变问号、数据库表里中文变问号、后台录入英文正常但中文存不进去。对应的处理方向完全不同。页面显示乱码优先检查页面本身的字符集声明以及响应头里的Content-Type是否包含charsetutf-8。数据库表里乱码检查建库字符集和连接 URL 里的characterEncoding参数。录入中文报错多半是字段字符集问题可以用下面的 SQL 批量修正库表ALTER DATABASE ofcms CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; ALTER TABLE 表名 CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;这三类问题我都踩过最后发现根因不在同一个地方所以排查时要从浏览器、应用、数据库三端逐层排查不要一上来就改代码。5.3 静态资源加载 404后台能登录但页面上的 CSS、JS、图片都不加载打开浏览器控制台能看到大量 404。这种情况在前后端分离架构里常见在 OFCMS 这种传统模板渲染架构里也不少见。首先要排查上下文路径是否正确。模板中引用资源如果写死了/static/css/style.css而应用上下文路径是/ofcms那实际请求地址应该是/ofcms/static/css/style.css。要么在模板里加上上下文前缀要么通过 Nginx 把/static/单独做一层映射。其次是看 Spring Boot 对静态资源的处理配置。如果项目里自定义了资源映射规则默认的classpath:/static/路径可能被覆盖。检查代码或配置里是否有addResourceHandlers相关设置确保模板实际位置和映射路径一致。5.4 常见问题速查表问题现象可能原因处理办法启动报 Access denied数据库账号密码错误手动登录数据库验证账号启动报 Public Key Retrieval not allowedMySQL 8.0 驱动认证问题URL 添加 allowPublicKeyRetrievaltrue页面中文乱码数据库或连接字符集不对统一 utf8mb4检查 URL 参数登录后验证码不显示会话或静态资源路径问题检查 context-path 与静态资源映射保存文章后图片不显示上传路径或 Nginx 映射错误确认上传目录可写检查静态资源映射Maven 构建失败依赖下载失败或模块名不对配置镜像对照 pom.xml 确认模块名这个表不是一次性总结出来的是好几轮部署和答疑攒下来的。遇到新问题我建议优先记录时间和操作步骤因为同一个报错可能对应完全不同的前置条件有记录才能快速定位。6. 上线前要做的几件事6.1 Nginx 反向代理与域名配置OFCMS 默认跑在 8080 端口用户直接访问这种非标准端口体验不好域名解析到 IP 后也容易绕晕。生产环境我习惯在前面加一层 Nginx先让它监听 80 端口把请求转发到本地 8080server { listen 80; server_name www.example.com; 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; } }这里的proxy_set_header Host $host;非常重要。如果漏掉这一行后端应用拿到的主机头可能是127.0.0.1:8080在生成绝对链接或做跳转时就会出现域名丢失的情况。配置完成后记得执行nginx -t检查语法再nginx -s reload重载。如果站点要上 HTTPS我建议另外申请证书然后把 Nginx 的 443 server 块配置好而不是依赖后端直接启 HTTPS。证书续期、OCSP 这些细节交给 Nginx 处理应用代码保持简单后续运维会省心很多。6.2 数据库定期备份做内容站最怕的不是系统崩溃而是内容数据丢失。文章、图片、配置都放在数据库和磁盘里一旦误操作删除或数据库损坏恢复成本巨大。我习惯写一个简单的备份脚本每天凌晨把数据库导出一份#!/bin/bash BACKUP_DIR/data/backups/ofcms DATE$(date %Y%m%d%H%M) mkdir -p $BACKUP_DIR mysqldump -uofcms -pYourPass123 ofcms $BACKUP_DIR/ofcms_$DATE.sql find $BACKUP_DIR -type f -mtime 7 -delete脚本里-mtime 7 -delete意思是保留最近 7 天备份更早的自动清掉。这个策略适合大多数中小站点既不会让磁盘被备份文件占满也能保证一周内任何一天的数据都可以找回。如果你对数据安全要求更高可以把备份文件再同步到另一台机器或对象存储这个就看公司现有基础设施了。6.3 二次开发与扩展建议OFCMS 的模块化设计让二次开发比较清晰。如果只是想加一个简单的 联系我们 页面完全不用改核心模块直接在模板层复制页面、调整表单提交接口即可。如果要加一个完整的新业务模块比如产品询价、在线报名那就需要新增 Controller、Service、Repository并接入后台菜单权限。我的建议是在动手写代码之前先充分理解现有模块的代码风格。OFCMS 继承的是传统 JavaWeb 的分层思路Controller 里做请求分发Service 做业务逻辑Repository 负责数据库访问。先花半天时间读一遍现有代码比直接抄网上的代码片段靠谱得多。扩展功能时尽量遵循项目原有的统一返回类和异常处理方法这样后期升级维护不会把自己困在代码风格分裂的泥潭里。部署和上线做多了会发现CMS 本身只是载体真正的业务价值在内容组织和模板设计上。OFCMS 给我的感觉是刚好够用、不过度设计这让它既能承载企业官网这种标准需求也能作为学习 Spring Boot 全流程的参考项目。我在实际部署中踩过的坑大部分都集中在数据库字符集、上下文路径、静态资源映射这类配置细节上这些坑一旦摸清后面跑任何同类型的 Java CMS 都会顺手很多。如果你也在考虑用它做站点不妨先把这套环境搭起来跑通一个简单栏目再往里面填内容后续的扩展会越做越顺。