内容中心(cms)
文章、页面、分类标签与站点导航怎么管,前台 /site/** 那几屏由谁直出,改主题时要守哪几条。
应用编码 cms,本页对应应用版本 1.0.1(引擎要求 >=5.6.2 <6.0.0),清单 license 为 UNLICENSED、licenseRequired 为 true,装与加载都要先有一枚覆盖本应用的凭证,档位口径见 授权档位,仓库 wujies-cms-plugin。
这个应用管两摊,分开看:一份内容台账(文章、页面、分类、标签、前台导航菜单),一套前台整页直出能力(/site/** 的 HTML、主题模板、样式与脚本)。后一摊牵动别的应用:图床、商城、报价自己出 /site/** 那一屏的内容,头尾、导航、SEO 标签、404 版式向这里借,走 SDK 契约 SiteRenderApi,实现方是 CmsSiteRenderService。
因此 app.json 的 dependencies 虽然是空的,别的应用却在前台这一层依赖它。没装 cms 时,图床管理 与商城的后台页面、/open/**、/portal/** 接口照常可用,/site/** 那几屏取不到:GallerySiteRender 反查不到渲染契约时给一个 404 加空响应体,日志留一行「前台页要渲染但没有主题壳」。
装它
先确认许可证覆盖 cms,其余没有前置,任何部署都能直接装。装之前看一眼宿主 application.yml 里两处,这两处不归本应用管:
open-api.tenant.path-patterns要含/site/**。公开页靠这条匿名租户带认出当前租户,少了它前台读到的是空列表(口径见 部署配置)。xss.excludeUrls要含/cms/post/**、/cms/page/**、/portal/cms/post/**三条。正文的消毒闸门在保存链路里,全局 XssFilter 若还拦这几条 URL,富文本在进插件之前就被清成纯文本。
安装过程与「装完菜单为什么没立刻出现」见 在部署里使用应用,菜单键的归属规则见 菜单归属。装成功后侧栏多一个「内容中心」,下面七项:
| 菜单 | 路由 | 需要的权限码 |
|---|---|---|
| 概览 | overview | cms:post:list |
| 文章 | post/list | cms:post:list |
| 页面 | page/list | cms:page:list |
| 菜单 | menu | cms:menu:list |
| 分类 | category | cms:category:list |
| 标签 | tag | cms:tag:list |
| 配置 | settings | cms:settings:list |
概览没有独立的权限码,它复用 cms:post:list:能看到文章列表就能看到各状态计数、分类与标签总数、最近文章和前台首页地址。
配它
「配置」那一页两个页签(网站配置、业务配置),组件来自宿主共享包(ModuleWebsiteSettings / ModuleBusinessSettings),本应用只把分类 cms 传进去。值都落在 sys_config:config_category = 'cms',键名一律带 cms. 前缀。读是 GET /system/config/list?configCategory=cms,保存按改动过的键逐条 PUT /system/config/updateByKey。C 端读同一批键走宿主的泛化端点 GET /open/{code}/config(OpenWebsiteConfigController),于是 /open/cms/config 不用写一行宿主代码就能用。
每个公开页渲染前现读一次(CmsThemeConfigReader.load()),改完刷新前台页面就是新值。sys_config 是租户表,一个部署服务多个租户时每个租户一份,所以它不能被做成启动期读一次的单例。库里没有 cms.* 那几行时用代码里的默认值,前台照样出得来;值存在但为空串按空串处理,界面上清空就是不显示。
| 键 | 默认值 | 什么时候要改 |
|---|---|---|
cms.name / cms.description | 站点名 / 一句兜底描述 | 标题、页脚、OG 站点名都取前者;后者是文章既没 SEO 描述又没摘要时 meta description 用的那一句 |
cms.icp / cms.police | 空 | 对外服务要填自己主体的备案号。police 填整段展示文本,拼查询链接时只取里面的数字,一个数字都没有就只印文本 |
cms.themeCode | default | 主题目录名,只认 [a-z0-9][a-z0-9-]{0,63},非法值回落 default。换一套新目录要先把 templates/cms/<编码>/ 与 themes/<编码>/ 打进包并热加载一次,理由见下面「改主题前守这几条」 |
cms.siteUrl | 空 | canonical 与 og:url 的域名,留空这两个标签一起不出。给一个错域名的 canonical 会把整站收录送到别的域名上去 |
cms.consoleUrl | 空 | 后台 SPA 的绝对地址。公开页由后端直出、后台是另一份 SPA,两边不同 origin,登录/注册/会员中心只能拼绝对地址;留空整块入口不渲染。回环别名(localhost / 127.0.0.1 / ::1)会被归一成访客正在用的那一个,真域名之间故意不猜 |
cms.heroTitle / cms.heroSubtitle | 「没有边界」加一句副标 | 首页 Hero 两行大字,副标清空这一行就不出 |
cms.regionName / cms.regionUrl | 「中国」/ 空 | 通知条最左那一格。regionUrl 留空印纯文本:地球图标是「可点」的暗示,没链接就不该摆出来 |
cms.noticeOne / noticeOneUrl / cms.noticeTwo / noticeTwoUrl | 两条本站文案 | 公告会过期,活动上线后要回来改。文字留空的那条不进轮播(留着会让轮播翻到一张空白页停两秒),链接留空只印文本 |
cms.helpName / cms.helpUrl | 「帮助」/ https://docs.wujies.cn | 通知条最右那一格,给没登录的访客看。留空印纯文本,故意不回落到后台地址 |
cms.contactEmail / contactQq / contactWechat / contactPhone | 空 | 页脚「联系我们」四行,代码里不给示例值(种一个编出来的号码等于把访客送到别人那里)。四项全空整列不渲染;手机号可以写成带分隔符的样子,tel: 里只留数字与开头的 + |
⚠️ updateByKey 只改已经存在的行:SysConfigServiceImpl#updateConfig 走 update ... where config_key = ?,影响 0 行时直接抛「操作失败」。这台部署缺哪个键的行(老环境常见于通知条那 8 个、cms.police 和 cms.contact*),界面上保存就会失败,先在「系统管理 → 参数设置」补一行,或等一次升级让迁移脚本补跑。
用它
管理员在「文章」里写正文、批量改状态,在「页面」里管关于、联系、落地页那类不进列表的独立页面,「分类」「标签」是两本词表,「菜单」拼前台导航。
内容生命周期四个值,公开页那几条 SQL 只认 status = 'published' 加 visibility = 'public' 加未删除:
| 状态 | 怎么进 | 前台 |
|---|---|---|
draft | 新建的初始值;从任何状态转回草稿都会清掉 published_at | 不可见 |
published | 点「发布」,或批量改状态 | 可见 |
scheduled | 点「定时发布」并给一个晚于当前时刻的时点,时点为空或早于现在保存就报错 | 到点前不可见 |
archived | 点「归档」 | 不可见 |
定时发布没有自己的列:目标时点就存在 published_at 里,状态是 scheduled。首次发布时 published_at 只在为空处回填(一条单独的 UPDATE),为的是不覆盖已经排定的时点。到点由 CmsPublishTask 翻牌,cron 0 */1 * * * ? 每分钟一轮,整段套 TenantHelper.ignore:调度线程没有租户上下文,而每个站点排定的文章都得各自到点发出去。把 scheduled 翻成 published 就是发布本身,没有第二个写入方。插件子上下文里的 @Scheduled 靠宿主装载时补注册的 ScheduledAnnotationBeanPostProcessor 驱动(PluginRuntimeManager#registerInfrastructure),这条链路未联机验证。
页面没有 scheduled 这一档:CmsPage 只有 draft、published、archived 三个常量,翻牌任务只查 cms_post。
正文的消毒在保存链路里做一次:CmsPostServiceImpl#toEntity 与 CmsPageServiceImpl 各调 HtmlSanitizer.clean。模板侧不做过滤,th:utext 只准出现在正文那三处(post.html、page.html 的 article__body,加商城商品详情那一份)。第三处方向相反:mall_product.detail 由商城后台写,本应用管不到它的保存链路,闸门改在读取侧(CmsMallProduct 里过一次 clean)。
两本稿子的列表查询都不选正文列:content 是 longtext,一屏十几行只要标题、状态和时间。别名在提交前先查一次重,撞上了报一句人话(「这个别名已被使用」);库里那个生成列 uniq_slug 是最后防线,靠它兜底会抛一个访客看不懂的 SQL 异常。
会员在会员中心「我的文章」(/member/posts,编辑器在 /member/posts/edit/:id?)里写自己的稿子,接口一律走 /portal/cms/post/**,只有 @SaCheckLogin、没有权限码,每条读写都先过归属校验。查别人的 id、改别人的稿子、删别人的稿子,得到的都是同一句话「文章不存在或无权操作」,不泄露那个 id 存不存在。分类与标签的下拉取自 /portal/cms/term/options。列表页那几个状态页签带条数,排序三档(最新、最早、最多阅读),「定时发布」在行尾那个下拉里,选完时点提交 PUT /portal/cms/post/mine/status。
游客读到的每一屏都是服务端直出的整页 HTML:/site/ 首页(Hero + 精选 3 篇 + 最新 6 篇 + 装了商城时的精选商品 + 会员区)、/site/p/{slug} 文章、/site/category/{slug} 与 /site/tag/{slug} 两族列表、/site/{slug} 独立页面。资源端点在 /site/themes/{code}/{file},账号区读 GET /site/account、退出打 POST /site/account/logout。取不到内容时渲染主题自己的 error 模板并带 404 状态:抛异常会被宿主的 GlobalExceptionHandler 接走,返回一段 JSON 给浏览器。
账号区那一小条的身份由浏览器自己问出来。宿主管线里 is-read-cookie: false(cookie 鉴权关掉,CSRF 就没有入口),直出那一屏时服务端不知道访客是谁,整页先按未登录印;页面拿着 localStorage 里的 token 打 GET /site/account 再问一次。四种认不出(没带 token、token 过期、账号已删、宿主没提供账号能力)对前台是同一个画法:R.ok() 带 data: null,不报 401,前端按未登录继续渲染。判「还活着」要调 LoginHelper.isLogin(),getUserId() 只解 JWT 载荷,注销过的旧 token 仍读得出 loginId。这一族端点挂 /site 而 /cms 用不了:/cms/** 每个接口都要过登录加 clientid 校验,公开页脚本拿不到那个头。退出同理在这侧做,StpUtil.logout() 只注销当前这一个 token、不需要权限位。
公开页只列不写。要改数据的动作(下单、领券、上传)一律出站去后台 SPA,地址由 CmsThemeProperties 里那几个 xxxUrl() 拼成绝对链接;cms.consoleUrl 留空时这些方法返回 null,模板改印一句提示,宁可少一个入口也不给一条指回本站的假链接。服务端渲染的那一份请求没有登录身份,写动作放不进这一屏。
文章正文的目录在渲染前由 CmsToc 补:锚点写在标题上、条目同时进上下文,库里存的还是编辑器产出的原文,老文章不用重存一次就有目录。锚点取标题文字(重名往后补 -2、-3),取序号的话目录一增删标题,之前分享出去的链接会集体失效。独立页面不做目录,page.html 那一屏通篇一两行,右侧挂一列锚点反而挡正文。
首页商品栏那张卡(CmsMallCard)与商城自己商品页用的 MallSiteCard 是两份实现、同一把尺子:现价取活动价还是划线价、is_new 按 0/1 判新、「省多少」怎么算,两边都要一致。改一边去对另一边,否则同一件商品在首页与商品页给出两个价格。
前台导航那两张表是 cms_menu 与 cms_menu_item,主导航那条编码为 main。菜单项存来源、存引用,只有一种情况存字面地址:来源取 home、post、page、category、plugin、url 六种,url 那一支只收 http://、https://、/ 三种开头(挡掉 javascript: 这类),plugin 那一支借用 href 列存 mall:shop 这样的引用,渲染时回 CmsSitePageFinder 现问那个应用要地址。候选清单从 GET /cms/menu/site-pages?appCode=mall 读,各应用经 SDK 契约 SitePagesApi 报上来。那个应用没装、没实现契约、页面标识已不在清单上,三种情况一律当没有这一页,那条导航整条摘掉且不报 ERROR:一个站不装商城是完全正常的配置。层级最多 5 级,主导航为空时回落成前 6 个分类。
改主题前守这几条
模板在 src/main/resources/templates/cms/<主题编码>/,样式与脚本在 src/main/resources/themes/<主题编码>/,两份都在应用产物里,不会被静态目录吐出去。要改它们,先过这五条:
- 判空写
X != null and X != ''。模板走 SpEL,SpEL 按参数类型找方法,#strings.isNotEmpty(null)报EL1004E: Method isNotEmpty(null) cannot be found,整页 500。常为空的字段用实体上的零参方法(post.hasCover())。 - 片段引用只写主题目录内的相对名(
~{modules/head :: head}),不写default/modules/head。一个主题一套引擎、解析前缀就是那个目录,整份拷贝两个目录再改cms.themeCode就是换主题;前缀收到templates/cms/那一层,模板就得写自己的编码,「主题等于一个自包含目录」当场破掉。 th:utext只出现在上面说的那三处,其余一律th:text。SEO 那几项的回落链(seo → 摘要 → 站点默认描述)在 Java 侧算完再塞进上下文,模板只管印字。- 动效只用
theme.css里那两个令牌:--dur与--motion。四处各写一遍ease的站,比没有动效更显眼。 - 应用自己那一屏的样式不在这个仓库里。
modules/head.html里那条th:each="${appStyles}"是唯一口子:链接清单由那个应用的控制器作为页面变量塞进来,文件与端点都在它的插件里(图床那一份是/site/apps/gallery/gallery.css)。端点必须跟着插件走:插件各自的类加载器,CmsThemeAssetController显式按自己的加载器取资源,读不到兄弟插件的产物;模板能跨过去是因为渲染时应用把加载器交了过来,静态资源是一次独立请求,没有那次交接。<link>排在theme.css之后才盖得动基元,所以清单顺序不能让主题去猜。搬与留的判据是「几个模板在渲染这一族」,不看类名前缀:只有一个使用者的整族跟着插件走,多个模板共用的(shop__list、filter__chip、pager这些)留下,共享件的变体跟着基元留下。搬过去的规则只准用主题的 CSS 变量,否则换主题时骨架换了肤、那一屏还是旧配色。appStyles的缺省值必须是空列表,th:each遇到 null 会把整页 500 掉。
出问题查什么
| 现象 | 先看 |
|---|---|
| 公开页样式一片空白,或进去就 500 | cms.themeCode 指的目录在不在当前这一代产物里;模板里有没有 #strings.isNotEmpty(...) 这种写法 |
别的应用装了,它的 /site/xxx 打不开 | 是否装了 cms;那边日志里应有一行「前台页要渲染但没有主题壳」 |
| 前台少了一条导航项 | 那一项来源是 plugin 还是 category;plugin 那一支问不到清单就整条摘掉,故意不报错 |
| 正文的标签在前台不见了,后台看着是对的 | 三条 xss.excludeUrls 少了哪一条,对应那条路径的请求体在进插件前就被清了标签 |
| 「配置」页某个框保存报「操作失败」 | sys_config 里有没有这一行,updateByKey 只更新已有行 |
| 定时文章到点没出现在前台 | 状态还是 scheduled 吗、published_at 是否已不晚于当前时间;翻牌每分钟一轮,插件子上下文的调度见上文那句「未联机验证」 |
| 前台点「登录」跳过去还要再登一次 | cms.consoleUrl 的主机名与访客正在用的那一个不一致;登录态在 localStorage 里,按 origin 隔离 |
| 页面别名保存报「这个别名是系统保留的」 | p、category、tag、themes、shop、store、activity、coupon、account、mall、search、error、index、page、post、rss、sitemap 都被占了,独立页面抢的就是根那一级 |
| 前台首页的商品栏空着 | 商城没装或问不到 MallCatalogApi,这一栏整块不渲染,首页照出(降级口径见 CmsPublicController) |
| 装完侧栏没有「内容中心」 | 菜单树在登录时生成,重建入口见 在部署里使用应用,远程应用怎么加载见 远程应用 |
实现索引
| 项 | 值 |
|---|---|
| 数据表 | cms_post、cms_page、cms_category、cms_tag、cms_post_category、cms_post_tag、cms_menu、cms_menu_item、cms_theme、cms_site |
| 后台接口前缀 | /cms/post(含 PUT /cms/post/status)、/cms/page、/cms/category、/cms/tag、/cms/menu、/cms/overview |
| 会员端 | /portal/cms/post/**、/portal/cms/term/options(@SaCheckLogin,无权限码,一律按归属过滤) |
| 公开端 | /site、/site/p/{slug}、/site/category/{slug}、/site/tag/{slug}、/site/{slug}、/site/themes/{code}/{*path}、/site/account、POST /site/account/logout |
| 对外契约 | 出:SiteRenderApi(壳、变量、404);入:SitePagesApi(问别的应用要前台页清单)。两份都在 wujies-common-plugin-sdk,写法见 插件开发 |
| 配置键 | sys_config 里 config_category = 'cms' 的 cms.*,共 21 个键由迁移脚本落库 |
| 迁移脚本 | migrations/01-create-cms-tables.sql 到 15-add-cms-post-copyright.sql,15 个 |
| 主题产物 | 模板 index、list、post、page、error 加 modules/ 六个片段;资源 theme.css、site.js、toc.js、lightbox.js、beian.png、comment-widget.{js,css}(后两个是 wujies-ui 里 pnpm run build:widget 的生成物,别手改) |
| 源码 | cn/wujies/cms,模板与资源见同仓库 src/main/resources |
那十张表同时是卸载时「彻底删除」的 DROP 依据:平台从迁移脚本里解析 CREATE TABLE 得到本应用声明的表。其中 cms_theme、cms_site 只有 02-create-cms-seed-data.sql 写过种子行,代码里没有实体也没有 mapper,留着等阶段 B 按 Host 定站点。app.json 里的 migrations 数组是空的,这不影响建表:装载时扫 <pluginDir>/migrations/<appCode>/ 目录按文件名顺序执行(AppMigrationService),脚本一经执行内容不能再改,同一脚本名跑出两种结果就无法回溯。仓库分工见 仓库布局,接口口径见 接口约定。