Jspxcms 9.0.0 Tomcat版部署全攻略：从war包安装到站点上线

简介：Jspxcms v9.0.0 Tomcat 集成版安装包，面向需要快速搭建内容管理系统的 Java 开发者、站长及 CMS 二次开发人员。该版本已将 Tomcat 一并打包，只需安装 JDK 与 MySQL 即可解压运行，省去单独配置 Web 容器的步骤，降低初始部署门槛，适合用于企业官网、政府门户及各类信息类站点。压缩包约 65.65MB，内含可运行的 Tomcat 环境与程序代码，解压后按提示即可完成安装，部署说明与 v9.0.0 更新日志随包提供；已有 437 人学习下载。相比旧版，此版本在站点设置中新增手机模板直接修改功能，升级 MySQL 驱动以兼容 5.7，并针对文档管理上传、文件管理搜索、后台菜单权限、页面静态化更新等场景修复了多项缺陷，可明显提升日常维护效率。读者最终可得到一套完整可部署的 Java CMS 环境，既能用于生产建站，也能作为学习 Jspxcms 架构与 JSP 开发的最佳样本。 拿到这个Jspxcms 网站内容管理系统 安装包 v9.0.0 tomcat版.zip的时候，我第一反应是：这年头还在用 zip 包分发 Java Web 项目的团队不多了，但 Jspxcms 恰恰就是这么干的。这个 CMS 在国产开源里算老牌角色，基于 Java 技术栈，默认打包成 war 包，配合 Tomcat 就能跑起来。它的价值在于，你不用在服务器上额外装什么复杂的中间件，只要有一台能跑 JDK 的机器，把 Tomcat 装好，war 包往里一扔，数据库初始化完，一个企业级站点就能上线。适合谁？想快速搭一个政府、学校、企业内部门户，或者做二次开发的 Java 工程师，都能从这个包里省下不少从零造轮子的时间。

我这次拿它在本地环境完整跑了一遍，从解压、装 Tomcat、配数据库到进后台，整个过程踩了几个典型的坑。这篇就把整个部署链路拆开讲清楚，包括版本匹配逻辑、Tomcat 配置细节、war 包部署的标准化步骤，以及排查问题的思路。照着做，你十分钟内应该能看到安装向导页面。

1. 拿到安装包先看什么：Jspxcms 9.0.0 的版本特性与部署形态

1.1 Jspxcms 是什么，为什么选择 Tomcat 版

Jspxcms 是一个基于 Java 的网站内容管理系统，核心功能涵盖栏目管理、文章发布、静态页生成、模板管理、会员系统和权限控制。9.0.0 这个版本属于比较新的迭代，在后台界面上做了不少现代化改动，内容模型也更灵活，支持自定义字段和多种文档类型。Tomcat 版和集成版最大的区别在于，它在交付时是一个标准的 Java Web 应用，没有捆绑任何应用服务器，部署方式回归 Java Web 项目最传统的那一套：war 包 + Tomcat + 关系型数据库。

选 Tomcat 版，通常意味着你对服务器环境有一定掌控力，不需要那种双击安装的傻瓜式一键包。公司内部如果有统一的运维规范，比如都用 Tomcat 来跑 Java 服务，那用这个版本就非常合适，维护成本低，排查问题也方便。另一个场景是二次开发——你大概率需要改源码或者加依赖，Tomcat 版给了你完整的 web 应用结构，你可以直接用 IDE（比如 IDEA 或 Eclipse）打开，调试、热部署、替换 JAR 都很灵活。

1.2 安装包目录结构与版本兼容性预判

很多人一上来就急着解压，我建议你先把 zip 里的东西捋清楚。Jspxcms 的安装包内部一般包含以下内容：jspxcms-x.x.x.war（核心程序包，这正是要部署到 Tomcat 里的东西）、doc或docs目录（里面有数据库初始化 SQL 脚本、安装说明、部署文档）、可能还有src目录（如果是源码版）和许可证文件。

这个v9.0.0的 tomcat 版，war 包内部依赖的 Servlet 版本是 3.1 起步的，也就是说，Tomcat 8.5 以及更高版本是稳妥的。别用 Tomcat 7 去试，接口版本差太远，启动时八成会被NoSuchMethodError或者 ClassNotFoundException 糊脸。JSP 编译器方面，Tomcat 9 用的 Eclipse JDT 编译器对新语法支持得更好，如果考虑以后升级 Java 版本，Tomcat 9 也比 8.5 省心。内存方面，Jspxcms 默认的 JVM 堆内存稍微给大一点，后面我会说具体怎么配。

2. 环境准备：JDK、Tomcat 与基础配置

2.1 JDK 与 Tomcat 版本匹配关系

这是老生常谈但特别容易出错的地方。Tomcat 不同的主版本对 JDK 的要求不一样，Jspxcms 9.0.0 官方标注支持 Java 8 以上。我的建议是直接用JDK 8（最好是 8u202 之后的版本）或者JDK 11，这两个版本在 Tomcat 9 下运行得最稳。JDK 17 能不能用？能，但前提是你用的是 Tomcat 10.1 以上的版本，否则会报java.lang.reflect.InaccessibleObjectException这类模块化访问报错。

这里有个匹配表格你可以直接存下来：

检查你机器上 Java 版本的方法很简单，终端敲java -version。如果你机器上装了多个 JDK，一定确保JAVA_HOME环境变量指向你希望 Tomcat 使用的那一个，因为 Tomcat 启动脚本里对 JAVA_HOME 的优先级极高。

2.2 Tomcat 下载、环境变量与内存参数

Tomcat 去官网下载 zip 版本就行，不用装安装版。Windows 下解压到纯英文路径，比如D:\apache-tomcat-9.0.85，避免中文目录和空格导致的各种诡异问题。Linux 下推荐解压到/opt/tomcat或/usr/local/tomcat。

环境变量这一块，需要配两个：JAVA_HOME指向 JDK 安装目录（不是 bin 目录），CATALINA_HOME指向 Tomcat 解压目录。配完别急着开心，在命令行里输入catalina.bat version（Windows）或catalina.sh version（Linux/macOS），如果能正常输出版本信息，说明 Tomcat 已经正确识别了 JDK。

内存参数要提前调。Jspxcms 跑起来后，后台的树形栏目加载、静态页面生成都比较吃内存，默认的-Xms128m -Xmx512m对中型站点来说偏小了。打开 Tomcat 的bin目录下catalina.bat（或catalina.sh），在文件开头追加JAVA_OPTS配置。我配置的是-Xms256m -Xmx1024m -XX:MaxMetaspaceSize=256m，实测跑了一个几千篇文章的站点没什么压力。额外加一个-Dfile.encoding=UTF-8也很有必要，可以避免一些中文乱码问题。

2.3 端口、本地路径与基础配置检查

Tomcat 默认占用 8080 端口，如果你机器上 8080 已经被占用了，打开conf/server.xml，找到<Connector port="8080"这一行，改成其他端口，比如 8088。改完端口记得同步到 Jspxcms 后台的站点域名设置里，否则后台上传的静态资源 URL 还是旧端口，浏览器打开会加载失败。

这里有个小细节：server.xml里<Host name="localhost" appBase="webapps"的配置决定了你的 war 包应该放到哪里。默认是解压到webapps目录下，你直接扔 war 包进去，Tomcat 会自动解压并部署。如果你希望 war 包放在别的路径，可以通过<Context>元素去指定docBase，但对新手来说，用默认方式最省事。

另外，无论 Windows 还是 Linux，都建议你把conf/web.xml里的listings参数设置为false，防止目录列表泄露文件结构。默认其实也是 false，但你值得确认一下。

3. 部署实操：从 zip 包到站点可访问

3.1 初始化数据库

Jspxcms 默认支持 MySQL 和 PostgreSQL，国内用户用得最多的就是 MySQL。你需要在 MySQL 里先创建一个空的数据库，字符集选择utf8mb4，排序规则选utf8mb4_general_ci或utf8mb4_unicode_ci都行。这一步用命令行操作：

CREATE DATABASE jspxcms DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

如果你的 MySQL 是 8.0 以上，还要注意连接驱动的版本。Jspxcms 9.0.0 默认自带的 MySQL 驱动应该是 5.1.x 或 8.0.x，如果你使用的是 MySQL 8.0 以上的数据库，建议去官方仓库把mysql-connector-java换成 8.0.33 版本，并替换到WEB-INF/lib目录下。不换的话，经常会出现Public Key Retrieval is not allowed这样的连接报错。

初始化数据有两种方式。第一种，如果你下载的是含 SQL 脚本的完整包，直接用命令行导入：

mysql -u root -p jspxcms < /path/to/jspxcms-schema.sql

第二种，也是更省心的方式，就是先启动 Tomcat，访问安装向导（后面会说），在安装页面里填数据库账号密码，系统会自动建表。两种方式我建议用第二种，因为向导里会顺带创建管理员账号，一步到位。

3.2 部署 war 包到 Tomcat

这一步就非常“所见即所得”了。把jspxcms-x.x.x.war复制到webapps目录下，然后启动 Tomcat。Windows 下运行bin/startup.bat，Linux/macOS 下运行bin/startup.sh。也可以用catalina.sh run（或catalina.bat run）在前台方式启动，这样控制台会直接输出日志，方便定位启动期问题。

启动后 Tomcat 会创建一个同名的目录作为应用上下文，比如webapps/jspxcms。如果你希望用根路径访问（即输入 IP 就能打开系统，不用带 jspxcms 二级路径），可以把 war 包改名为ROOT.war再部署，或者删掉原有的 ROOT 目录，把解压后的 jspxcms 目录改名为 ROOT。这种部署方式需要重启 Tomcat 才能生效。

看启动是否成功，还是绕不开日志。Tail 一下logs/catalina.out（Linux）或logs/catalina.<date>.log（Windows），看到类似Deployment of web application archive [jspxcms.war] has finished的日志，就说明部署成功了。如果中途报错，停住，先看最后的异常堆栈，不要盲目重启。

3.3 运行安装向导与后台初始化

浏览器访问http://localhost:8080/jspxcms/（如果改过端口，就用新端口），Jspxcms 会自动跳转到安装引导页面。这里要填数据库信息，包括数据库地址、端口、库名、用户名密码。如果你数据库和 Tomcat 在同一台机，地址用localhost就行。

安装向导里还会让你设置管理员账号和密码，以及系统初始化的基本信息，比如站点名称、域名。填完后点击安装，系统会执行建表操作并写入初始化数据。这一步通常需要十几秒到一分钟时间，取决于服务器性能和数据库响应速度。页面提示安装成功之后，立即删除服务器上的install目录（通常在 webapps 下），或者对install相关 URL 做访问限制，否则存在被重新安装覆盖数据的风险。这一点容易被忽略，但一旦出事故就很尴尬。

重新访问系统首页，能看到一个默认的演示站点页面，说明前端渲染正常。输入后台地址/jspxcms/下的登录入口，用刚才创建的管理员账号登录，就能看到完整的后台管理界面。到了这一步，部署就算正式完成了。

4. 部署后的配置与上线前检查

4.1 站点域名、静态资源与系统参数设置

进入后台后的第一件事，是去“系统管理 -> 站点管理”里核对站点域名和部署路径。如果你是通过http://localhost:8080/jspxcms访问的，站点地址一般会自动识别，但如果后续要用域名访问，强烈建议先把域名填上，并设置为“静态资源域名”或“全站 URL 前缀”。这一步没做好，会导致生成的页面里图片、CSS、JS 全部是本机 localhost 地址，换台机器访问就全部打不开。

Jspxcms 支持将站点发布为纯静态页面，也就是生成 HTML 文件直接以静态方式访问，这是它性能好的核心原因之一。如果你需要让访客访问的页面全部静态化，进入“生成 -> 站点静态化”，把首页、栏目页、文章页的静态化开关打开，再设置生成路径。默认生成的路径可能在 webapps 外的某个目录，这时候要保证 Tomcat 对那个目录有读写权限。以生产环境为例，很多人会把静态文件直接输出到 Nginx 的根目录下，再由 Nginx 直接命中静态文件，Tomcat 只负责动态请求，这是比较经典的动静分离方案。

4.2 模板与资源文件的目录权限

模板文件一般放在WEB-INF/views或 webapp 下的某个模板目录中。Jspxcms 允许通过后台在线编辑模板，这意味着 Tomcat 运行账号必须对模板目录有写权限。Windows 下通常没这个问题，但 Linux 服务器上，如果你用root启动 Tomcat，反而容易引发权限问题——因为后续用其他账号上传模板或附件时，文件属主是 root，其他进程就写不进去了。规范做法是创建一个专门的系统账号（比如tomcat）来运行 Tomcat，并将整个 Tomcat 安装目录以及静态资源输出目录chown给这个账号。

文件上传目录同样要注意。Jspxcms 默认会把上传的图片和附件存放到配置的上传目录中，这个路径通常在后台可配置。建议把它指定到 webapps 之外的绝对路径，避免因为应用重新部署把用户上传的文件清掉。实测下来，部署升级时忘记备份上传目录，导致历史图片大面积失效的案例，真不在少数。

4.3 定时任务与服务器时区

定时任务是 CMS 里常用的功能，比如定时发布文章、定时生成静态页。Jspxcms 的定时任务功能依赖于服务端的调度，默认是通过 Spring 的调度器实现的，在集群环境下需要额外处理，单机部署则不需要操心。部署时注意到一个小细节：如果 Linux 服务器的时区不是 Asia/Shanghai，创建的文章发布时间会和本地时间差 8 小时。解决方式是在启动 Tomcat 时加上-Duser.timezone=Asia/Shanghai，或者确保系统时区已设置正确：

timedatectl set-timezone Asia/Shanghai

5. 老鸟踩坑实录：常见问题与排查技巧

5.1 Tomcat 启动慢、APR warning 与端口占用

Tomcat 启动慢是个高频问题，最典型的原因有两个。一是/dev/random熵不足导致 SecureRandom 阻塞。Linux 下如果你发现启动日志卡在Creation of SecureRandom instance很久，可以在catalina.sh的JAVA_OPTS里加入-Djava.security.egd=file:/dev/./urandom，能明显加快启动速度。

第二个常见启动问题是日志里出现一行The APR based Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path。这句话看着吓人，但其实不是致命错误，意思是你没装 Tomcat Native 库，Tomcat 会退回到纯 Java 的 NIO 模式运行。不装也能正常工作，只是性能上略逊；如果坚持要装，需要单独编译tomcat-native.tar.gz。个人建议初次部署不用理会，先保证系统能跑起来。

端口占用的排查思路要形成肌肉记忆。Tomcat 启动立刻报java.net.BindException: Address already in use，直接用系统命令看端口：

netstat -ano | grep 8080

Windows 下记下 PID 后去任务管理器结束对应进程；Linux 下可以lsof -i:8080查看，然后kill对应进程。改了端口还不行？记得清掉浏览器缓存，或者用无痕窗口访问。

5.2 数据库连接失败与编码问题

部署过程中数据库相关的报错，大概率集中在这几个场景里。第一是 JDBC 驱动版本和 MySQL 版本不匹配，报错形如Communications link failure或Public Key Retrieval is not allowed。前者先检查 MySQL 地址端口是否通，后者直接换 8.0.x 新版驱动。第二是数据库连接池初始化失败，查看日志里的 Caused by 部分，很多是密码错误或权限不足导致的Access denied for user。

第三类问题是编码导致的，虽然 MySQL 建库时用了 utf8mb4，但如果 JDBC 连接串里没有显式指定characterEncoding=utf8，部分字符会变成问号。Jspxcms 的数据库连接池配置文件，通常在WEB-INF/classes下的 properties 文件里，检查一下连接串是否存在下面的参数：

jdbc.url=jdbc:mysql://localhost:3306/jspxcms?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai

另外，很多人在后台添加文章时发现中文标题变成???，这大概率是数据库表本身不是 utf8mb4，而不是程序问题。用下面的语句核对一下库和表的字符集：

SHOW CREATE DATABASE jspxcms; SHOW CREATE TABLE jspxcms_content;

5.3 部署路径与静态资源 404 排查

一个非常迷惑的问题：后台登录正常，但浏览器打开站点首页，CSS、JS 全部 404。如果你没有改过 war 包名称，这类问题通常出在“站点路径”配置上。Jspxcms 后台的站点管理里有一个“部署路径”字段，如果之前被改成了/jspxcms或者空字符串，它会影响前端资源 URL 的拼装。正确值应该和你的访问上下文保持一致。如果不确定，先全部清空，保存后再试一次访问。很多时候改完就能解决所有静态资源加载失败的问题。

还有一类静态资源异常是 Nginx 反代配置导致的。如果你用 Nginx 把 80 端口转发到 Tomcat，需要确认 Nginx 里有没有正确传递 Host 头，否则后台上传图片后，自动拼出来的 URL 可能是内网 IP。Nginx 转发时补一句：

proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme;

这词儿敲黑板，尤其在你把系统放到生产环境用域名访问的时候。

5.4 JVM 内存溢出与线程问题

如果你在后台执行“生成静态页”操作时，Tomcat 直接卡死或抛出java.lang.OutOfMemoryError: Java heap space，那就别再去调 Tomcat 的并发参数了，先把堆内存加上来。一台 4G 内存的机器，给 Tomcat 分配 2G 堆是合理的。具体在catalina.sh里改成：

JAVA_OPTS="-Xms1g -Xmx2g -XX:MaxMetaspaceSize=512m"

改完一定要重启 Tomcat，并且通过jvisualvm或者jstat确认 JVM 实际启动参数生效了。很多人改了配置没重启，或者配到了错误的脚本文件里，结果白忙活一场。还有一个小技巧，Jspxcms 后台的日志目录可以开启 DEBUG 级别，遇到那些“页面报错但不明所以”的问题，直接在log4j2.xml里把 logger 级别调成 DEBUG，定位效率会高很多。

我在实际部署中还遇到过 Java 线程与 Linux 线程对应关系的疑惑，比如后台线程池里明明配了 200，但ps -L看到的线程数远不止这些。这其实是正常现象——Tomcat 自身有若干后台线程（如Catalina utility、ContainerBackgroundProcessor），JVM 也有 GC 线程和编译器线程，再加上数据库连接池的保活线程，总数自然会大于你配置的业务线程数。不用慌，先观察 CPU 和内存占用，真正异常的表现是线程数持续暴涨且内存暴涨，这时候就要去看是不是有连接泄漏了。

最后说一个不算技巧但很重要的习惯：每次部署升级之前，不要只备份数据库，整个 webapps 下的应用目录、上传目录、以及conf/server.xml一并备份。Jspxcms 有很多配置存在数据库里，但也有少量环境相关的配置在文件里。我就吃过一次亏，升级版本时只备份了数据库，结果配置文件里自定义的端口和路径全丢了，恢复环境花了不少时间。这些经验本质上不是 Jspxcms 独有，做任何 Java Web 项目部署，摸清以下几个变量——JDK 版本、Tomcat 版本、数据库驱动、路径权限、日志位置——你就已经解决了至少一半的疑难杂症。

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