企业官网建设流程全解析

很多人第一次装完 OpenCms，登录进工作台之后的第一反应是——懵。左边一棵深不见底的目录树，右上角挂着 Offline 和 Online 两个切换按钮，菜单栏里还有 Sites、Modules、Accounts、Database Management 一堆入口，可页面上一个"新建网站"的大按钮都没有。于是就开始乱点，把示例站点改得面目全非，最后连原来的样子都回不去了。这篇东西就是写给卡在这一步的初学者的：从 war 包丢进容器开始，一直到能在浏览器里看到一个自己搭出来的、可编辑、可发布的站点，把 OpenCms 创建网站的整条链路按照实际操作顺序走一遍。里面没有玄学，都是界面位置、菜单路径、配置字段和踩过的坑，你完全可以对着屏幕一步一步抄。我默认你手上有基本的 Java Web 概念，知道什么是 Servlet 容器、什么是 JSP，但没用过 OpenCms，这就够了。

1. 打开 OpenCms 之前：先搞懂离线工作区与在线站点这对“双胞胎”

1.1 为什么改完页面刷新浏览器却没动静

初学者遇到的第一个"灵异事件"几乎都是这个：在后台辛辛苦苦改了标题、换了图片，回到浏览器一刷新，还是老样子。于是怀疑缓存、怀疑浏览器、怀疑人生，重装了三遍系统。真正的原因是 OpenCms 把"编辑"和"访问"切成了两个独立的世界——Offline 工作区和 Online 站点。你在工作台里做的所有编辑动作，落在 Offline 这一侧，它是一份"待发布的草稿副本"；而普通访客用浏览器访问到的，是 Online 那一侧已经发布出去的内容。你改完没点发布，Online 侧当然纹丝不动。

这个设计不是多此一举。它解决的是企业站点的核心痛点：内容编辑不能直接暴露给访客。一份稿子写一半、一张图还没配、一段话还在等审核，这些中间状态必须能安全地待在草稿区，等确认无误再统一推到线上。所以你会在工作台右上角看到那个工作区切换控件，它的作用相当于"预览"和"正式"两个频道。理解了这个模型，后面所有的操作逻辑就顺了：先在 Offline 编辑，预览确认，再发布到 Online。

提示：工作区的切换是全局的。你在 Offline 侧看到的目录树、文件内容、甚至某些配置，和 Online 侧可能是两份数据。排查问题前第一件事，永远是确认自己现在站在哪一侧。

这里还有一个容易被忽略的点：Offline 侧的编辑不是直接改文件，而是在一个"项目"（Project）里改。默认会给你开一个个人项目，你所有的改动先攒在这个项目里，点发布的时候才把整个项目的变更一次性推过去。这带来的好处是原子性——要么全上，要么全不上；坏处是你如果忘了发布，改动就一直躺在项目里。我在早期经常犯这个错，改了一堆东西，第二天上班发现线上没变，回头一看项目还挂着未发布状态。

1.2 VFS 里那几个你必须记住的目录

OpenCms 用一套虚拟文件系统（VFS）来组织资源，看起来像文件夹，但实际存的不只是磁盘文件，还有内容记录、模板、配置、模块包等等。借着工作台的目录树，你会看到几个顶层节点，初学者至少要认清下面这几个，不然之后建站会到处找不到东西。

绝大多数建站工作都发生在 /sites 下面。/sites/default 是安装时自带的示例站点，初学者最好的学习方式就是先把它翻一遍——看看里面的模板 JSP 怎么写、容器页怎么摆、内容放在哪个目录、图片资源怎么组织。这比看任何文档都直观。等你把 default 站点的结构摸清楚了，再照着建自己的站点，心里就有底了。

我的建议是：不要上来就在 default 里改。新建一个 /sites/你的站点名 目录，把模板、内容、资源全部放进去，和示例站点物理隔离。这样即使你把自己的站点搞崩了，删掉重建就行，不会牵连示例。而且做模块导出的时候，一个干净的站点目录打包起来也方便。这个习惯我在后来的项目里一直保留，节省的返工时间远超建目录那几分钟。

2. 把系统跑起来：从 war 包到后台登录页的完整链路

2.1 JDK、Servlet 容器与数据库的搭配选择

OpenCms 是纯 Java 的东西，跑起来需要三样：一个 JDK、一个 Servlet 容器（最常见的是 Tomcat）、一个关系型数据库。这三者的版本搭配是初学者第一大坑，配错了会卡在安装向导的第一步，报一堆看不懂的异常。

先说 JDK。较新的 OpenCms 版本对 Java 版本有明确要求，老版本跑在新 JDK 上、新版本跑在老 JDK 上，都可能出现类加载错误或者编译 JSP 失败。我的做法是：先确认你下载的 OpenCms 发行包对应的 Java 最低版本，然后容器和 JDK 用同一个大版本，别混搭。如果你本地同时装了多个 JDK，一定要检查容器的启动脚本里 JAVA_HOME 指向哪一个，很多"明明装了却报版本不对"的问题都出在这里。

数据库方面，MySQL 或 MariaDB 是最常见的选择，社区资料也最多。建库的时候有两个细节必须注意：字符集用 utf8mb4，排序规则选对应的通用排序规则；另外给 OpenCms 单独建一个数据库用户，授予该库的完整权限，不要图省事直接用 root。数据库连接 URL 里记得带上字符编码参数和时区参数，这两个漏掉，后面中文乱码和时间显示错乱会找上门。

Tomcat 这边，把 OpenCms 的 war 包丢进 webapps 目录，启动容器，它会自动解压。如果你希望站点跑在根路径下（访问 http://你的地址/ 直接进站点，而不是带一长串上下文路径），就把 war 包重命名成 ROOT.war。这个动作看起来小，但影响后面所有链接的生成方式，建站初期定下来就别再改，改一次要动的地方不少。

2.2 安装向导里几个一失足成千古恨的选项

容器启动成功之后，访问安装向导的地址（形如 http://localhost:8080/opencms/setup/），会进入一个分步表单。这里有几处选择一旦定下就很难回头，我按重要性排一下。

第一处是安装类型。向导通常会提供几种模式，初学者直接选工作台模式（Workplace）就好，它会把示例站点、示例模块、完整的后台界面都装上，方便你对着学。另一种精简模式装出来的东西少，看起来干净，但对新手极不友好——你连个能参考的模板都没有，等于闭着眼睛造轮子。

第二处是数据库连接信息。主机、端口、库名、用户名、密码，逐项对着填，填完先点测试连接。这一步失败最常见的原因是数据库用户没有远程权限，或者容器和数据库不在同一台机器上却用了 localhost。测试通了再往下走，别抱着"先装完再说"的心态。

第三处是管理员账号。向导会让你设置后台管理员的口令。这个账号权限极高，能改系统配置、能删站点、能装模块，务必设一个像样的口令，别用默认的。装完之后第一件事就是登录验证一下，确认能进工作台、能看到目录树。

第四处是安装完成后的收尾。向导结束时会提示你删除安装相关的资源或者锁定安装入口，这一步千万别跳过。留着安装入口，等于把系统重装的开关暴露在外面，任何人访问到那个地址都可能触发重装流程。我见过不止一个环境因为这个疏忽被清空过数据。

装完之后，工作台的访问地址通常是 http://你的地址/opencms/，登录进去你会看到一个带左侧目录树、顶部工具栏、右侧编辑区的界面。到这里，环境这一关就算过了。

3. 建站第一步：站点、站点服务器与站点地图怎么配

3.1 新建站点目录并把 URL 指过去

OpenCms 里"一个站点"和"一个目录"是两件事，初学者经常混淆。目录是资源存放的位置，站点则是一套"域名/路径 → 目录 → 默认首页"的映射规则。你光建了目录，不配站点，浏览器访问的时候系统不知道这个 URL 该对应到哪份内容，结果就是找不到页面。

操作顺序是这样的：先在工作台的文件视图里，进到 /sites 下面，新建一个文件夹，名字用你的站点标识。然后切换到管理视图，找到站点管理相关的入口，在里面新增一条站点记录。这条记录要填的核心信息包括：站点根目录（指向你刚建的那个文件夹）、绑定的域名或服务器标识、以及默认首页文件名。填完之后保存，系统会重新加载站点配置。

这里有个特别容易踩的坑：域名和服务器标识的填写方式。如果你只是本地测试，通常用 localhost 或者带端口的地址；如果你打算用真实域名访问，就要把域名填准，包括是否需要 www 前缀。这一项填错的表现是——目录里明明有首页，浏览器却给你一个空白或者默认站点。排查的时候，先看站点管理里那条记录匹配得上不，再看容器的配置文件里有没有把这个域名交给 OpenCms 处理。

还有一个细节值得说：OpenCms 支持"一个安装、多个站点"。也就是说，你完全可以在同一套系统里挂好几个站点目录，各自绑定不同的域名，共享同一批模板和模块。这对做站群或者多语言站特别有用。但对初学者来说，建议先把一个站点跑通，再考虑多站点，不然配置一多，出问题时你根本分不清是哪一层在捣乱。

3.2 站点地图决定了导航菜单的生成方式

页面能访问了，接下来就是导航。OpenCms 的导航不是靠你在模板里手写一堆链接，而是靠站点地图（Site Map）自动生成的。站点地图本质上是一份"目录结构的视图配置"，它决定了哪些目录出现在导航里、以什么顺序出现、显示什么标题、层级怎么嵌套。

打开站点地图编辑界面，你会看到一棵树，节点对应着站点里的文件夹和页面。每个节点可以设置导航标题、是否在菜单中显示、排序权重、以及是否作为入口。模板里通过相应的标签读取这棵树，就能自动渲染出导航菜单。这样做的好处是运营人员改导航不用碰代码，只要在站点地图里拖一拖、改改标题就行。

我建议在建站初期就把目录结构和导航结构对齐。比如一级栏目对应站点地图里的一级节点，二级栏目对应二级节点，不要出现"目录建了五层但导航只显示两层"这种错位。错位本身不会报错，但后期内容一多，维护起来会非常痛苦，你每次找内容都要在目录树和导航树之间来回对照。

注意：站点地图的改动同样遵循离线/在线模型。你在 Offline 侧调完顺序，要发布到 Online 访客才能看到新菜单。这也是"我明明改了导航却没变"的常见原因。

4. 模板与容器页：让页面从“静态文件”变成“可编辑页面”

4.1 JSP 模板的骨架与 cms 标签怎么用

OpenCms 的页面本质上是 JSP，但它不是普通 JSP——它通过一套自定义标签库把"可编辑区域"嵌进页面结构里，从而实现"页面布局固定、内容可替换"。理解这一点，是从"会写 JSP"跨越到"会用 OpenCms"的关键。

一个典型的模板 JSP 大致长这样（结构示意，具体参数以你所用版本的标签库为准）：

<%@ taglib prefix="cms" uri="http://www.opencms.org/taglib/cms" %> <cms:template element="head"> <html> <head><title>站点标题</title></head> <body> <div class="header">页头区域</div> </cms:template> <cms:template element="body"> <div class="main"> <cms:include element="body" editable="true" /> </div> </cms:template> <cms:template element="foot"> <div class="footer">页脚区域</div> </body> </html> </cms:template>

这套写法的核心思想是"分段"：head、body、foot 各自是一段，其中 body 段里留了一个可编辑的插槽，编辑人员在后台改内容时，改的就是插槽里那块，页头页脚保持不变。模板文件放在站点目录下的模板文件夹里，然后在页面属性里指定用哪个模板。

初学者最容易犯的错是把业务内容直接写死在模板里。今天写死一个标题，明天写死一段介绍，后天发现要改就得改代码。正确的做法是：模板只负责结构和样式，所有会变的东西都通过内容插槽或者内容列表标签取。判断标准很简单——如果一个东西运营人员可能想改，它就不该出现在模板里。

4.2 容器页：把可编辑区域插到页面上

光有模板还不够，你还需要"容器页"。容器页是一种特殊的页面类型，它的作用是声明页面上有哪些可编辑的容器区域，以及这些区域的类型和布局约束。你可以在容器页里摆一个主内容区、一个侧边栏、一个推荐位，然后编辑人员就能往这些区域里拖内容。

容器页的写法同样依赖标签库，结构上就是在页面里声明若干个容器，并给它们命名、定类型。命名很重要，因为模板和样式要按名字去定位。类型则决定了这个容器能放什么——是单篇内容、还是内容列表、还是任意资源。

实际操作中，一个站点通常只需要少量几个容器页模板，比如"首页模板容器页""列表页容器页""详情页容器页"。内容页则是在这些容器页的基础上创建出来的实例。这样做的好处是布局统一、改一处全站生效。我第一次建站的时候每个页面单独写 JSP，后来要统一改页头，改了三十多个文件，那次之后我就老老实实把所有布局收敛到三套容器页里。

5. 结构化内容：用 Schema 定义字段，让编辑表单自动长出来

5.1 资源类型与 Schema 的绑定关系

这是 OpenCms 最有价值、也最让初学者头大的部分。传统的 CMS 里，一篇"文章"就是一段富文本，编辑人员在一个大框里随便写。OpenCms 走的是结构化路线：你先定义一个内容类型（资源类型），给它规定好有哪些字段——标题、副标题、作者、发布日期、封面图、正文、标签——然后系统会根据这份定义自动生成一个编辑表单。编辑人员看到的是分门别类的输入框，而不是一个大文本框。

定义字段靠的是 Schema 文件（XML 格式），放在模块目录下。Schema 里描述字段名、字段类型、是否必填、是否多值、以及界面上的分组和排序。写完 Schema 之后，还要在模块管理里注册一个资源类型，把这个资源类型指向你的 Schema。这两步做完，你在新建内容的时候就能看到这个类型了。

这套机制的价值在于"内容复用"。一旦内容被结构化，它就能被列表页读取、被搜索索引、被推荐位筛选、被接口输出。你想想，如果文章只是富文本，你想在首页列出"最新五篇带封面的文章"，只能靠人工维护；而结构化之后，这就是一个查询的事。

我建议初学者第一个自定义类型就做"文章"：标题（单行文本，必填）、摘要（多行文本）、封面图（图片资源）、正文（富文本）、发布时间（日期）。这五个字段覆盖了八成场景，做完之后你对 Schema 的写法就基本有数了。

5.2 在容器页里挂内容与关系列表

内容建好了，还得让它显示出来。两种方式：单篇内容的插入，和内容列表的渲染。

单篇插入比较简单，在容器里放一个内容元素，编辑时选择要展示哪篇内容即可。内容列表稍微复杂一点，需要用列表标签去查询某个目录下的内容，按条件排序、限制条数，然后把结果循环渲染出来。列表标签通常支持按资源类型过滤、按目录过滤、按时间排序，这些条件组合起来就能做出"最新文章""热门推荐""某栏目下的全部内容"这些常见模块。

关系字段是另一个高级但常用的能力。比如你有一个"产品"类型，想关联若干"案例"，可以在产品类型里定义一个关系字段，指向案例类型的资源。编辑的时候可以挑选关联项，展示的时候就能顺着关系取到案例列表。这种多对多的表达能力，是结构化内容真正拉开差距的地方。

需要提醒的是：内容列表的渲染性能。列表查询如果条件太宽、目录太大，页面会明显变慢。实际项目中我会给列表加上条数限制和目录限制，避免全站扫描。另外，列表结果在离线侧是实时的，但发布到在线侧之后，如果页面是静态导出的，就需要重新导出才能看到更新——这个后面会专门讲。

6. 从离线到上线：发布、权限与静态导出的完整动作

6.1 项目、发布与权限的基本套路

前面说过，编辑动作是在项目里攒着的。发布这个动作，就是把当前项目里的变更推送到 Online 侧。工作台工具栏上有一个发布按钮，点进去会列出本次要发布的资源清单，确认无误后执行，系统就会把这批资源同步过去。

这里有个经验：不要攒太久再发布。有些同学习惯改一整个星期再统一发，结果发布的时候报错，根本不知道是哪一次改动引起的。我的做法是每完成一个小目标就发一次，出问题容易定位，回退也简单。OpenCms 的发布是有历史记录的，你可以看到每次发布了哪些资源，这在排查"线上为什么和预期不一致"时非常有用。

权限模型也值得早点理解。OpenCms 里的权限是围绕"主体"（用户、组、角色）和"资源"的访问控制列表来做的。你可以给某个目录设置只有某个组能写，其他组只读，访客不可见。站点上线前，至少要把这几件事配好：后台管理员组、内容编辑组、以及访客的只读权限。别让编辑账号有删站点的能力，也别让访客账号能进工作台。

一个常见的权限坑是"继承"。子目录默认继承父目录的权限，你在子目录上改了权限，但父目录有更严格的限制，实际生效的是两者的交集。遇到"明明给了权限却访问不了"，先顺着目录往上找，看看哪一层把口子收紧了。

6.2 静态导出与缓存导致的“发布成功但页面没变”

如果你的站点开了静态导出，那么"发布成功"和"访客看到新内容"之间还隔着一步：导出。静态导出的机制是把 JSP 渲染后的结果生成静态 HTML 文件，由前端服务器直接对外提供，这样访问速度最快、对应用服务器压力最小。代价就是内容更新之后必须重新导出，否则访客看到的还是旧文件。

所以排查"发布成功但页面没变"这个问题，顺序应该是：先确认工作区在 Online，再确认内容确实发布了，再看静态导出是否重新执行了，最后才怀疑浏览器缓存。这个顺序能帮你省掉大量无效排查。我在项目里遇到过最离谱的一次，是导出配置里的目标目录写错了，导出的文件生成在另一个路径下，前端服务器读的还是老目录，查了两个小时才发现是路径问题。

注意：静态导出会跳过一些动态能力，比如需要登录才显示的内容、实时搜索接口。做导出配置的时候，要把这些动态请求排除在外，否则导出出来的页面会有大片的空白或者报错。

7. 初学者最容易卡住的几个现场（排错链路）

7.1 空白页与 404 的分层排查

页面打不开，症状无非两种：一种是 404 找不到，一种是页面出来了但一片空白。这两种问题的排查路径完全不同，别混在一起查。

404 的排查顺序：第一，确认 URL 拼写和上下文路径对不对；第二，确认站点管理里有没有匹配这个域名或路径的站点记录；第三，确认默认首页文件是不是真的存在于对应目录；第四，确认这个资源在 Online 侧有没有发布。按这个顺序走，九成 404 都能定位。最容易被忽略的是第三步——目录建了、站点配了，但首页文件没放到正确位置，或者文件名和配置里写的默认首页对不上。

空白页的排查顺序：第一，看容器的日志和 OpenCms 自己的日志文件，JSP 编译错误、标签库找不到、Java 异常都会在那里留痕；第二，确认模板 JSP 里的标签前缀和 URI 写对了；第三，确认模板用到的资源（图片、样式、引入的片段）路径正确；第四，检查是不是权限问题导致的静默失败。空白页最麻烦的地方是它不给你任何提示，所以日志是第一手线索，别一上来就改代码。

7.2 中文乱码的三处编码点

中文乱码在 OpenCms 建站里几乎是必修课，而且往往是多处叠加，改一处不见好。我把它拆成三个编码点来看，逐个核对。

排查方法是自下而上：先确认入库数据本身对不对。你可以在数据库里直接查一条刚录入的记录，如果那里就是乱码，问题在数据库层，改连接参数和库字符集；如果数据库里正常、页面显示乱码，问题在应用层的编码声明；如果只有带中文参数的链接出问题，看容器层的 URI 编码。按这个链路走，比盲目改一堆配置高效得多。

还有一个小技巧：新建内容类型和字段的时候，尽量用英文标识符，中文只出现在界面显示名里。这样能避开一部分编码问题的干扰，也让后期的维护和排错清爽很多。

最后分享一个我自己的习惯。每次新建站点，我会先做一个"最小可发布闭环"：一个首页、一个模板、一个内容类型、一篇内容，把从编辑到发布到访问的全流程走通，再往上加栏目和功能。这个闭环大概只需要半小时，但它能提前暴露环境、权限、导出、编码四类问题，避免你在堆了二十个页面之后才发现地基是歪的。踩过几次大坑之后我越来越确信，OpenCms 这种结构化的系统，前期把地基打正，后面会顺得让你意外。