给 Nextcloud 加备案号:不改程序文件,用自定义主题写进页脚

国内服务器上跑 Nextcloud,工信部备案要求网站底部展示备案号。很多人第一反应是去改翻译文件 apps/theming/l10n/zh_CN.json,结果一改,后台「安全与设置警告」里的代码完整性立刻红一片。

这篇讲一个干净的做法:用 Nextcloud 自带的自定义主题机制,覆盖页脚模板。不改任何签名文件,随时可回滚。

先看效果

页脚显示备案号并验证站点状态
页脚出现备案号,同时站点各项状态正常

三种做法,先选对路子

做法改哪里问题
写进站点口号(slogan)后台主题设置和公司口号挤在同一行,不能做成链接
自定义主题覆盖模板themes/ 目录无(推荐)
改翻译文件 zh_CN.json应用目录属于签名文件,改了完整性检查就报错

为什么自定义主题是安全的?看 Nextcloud 的完整性检查源码,它遍历文件时会跳过这些目录:

data / themes / config / apps / assets / lost+found / updater

themes 就在里面,而且官方签名清单里 themes 的条目数是 0。所以放进去的文件不会被当成”篡改”。

动手前准备

  • SSH 能登录服务器(root)
  • 知道站点目录,本文以 /www/wwwroot/www.hello0564.com 为例
  • 准备好你的备案号,例如 皖ICP备2021009418号-5
切换站点 PHP 版本并重载 nginx
切换 PHP 版本时,vhost 改一行、nginx 重载、再验证

第 1 步:建主题目录,复制官方模板

创建主题目录并插入备案号
建目录、复制模板、插入备案号,一条条来
# 进入 Nextcloud 安装目录
cd /www/wwwroot/www.hello0564.com

# 建主题目录(icp 是主题名,可以自己起)
mkdir -p themes/icp/core/templates

# 把官方登录页模板复制过来,我们只改这一份副本
cp -a core/templates/layout.guest.php themes/icp/core/templates/

layout.guest.php 就是”访客页面”的布局模板,登录页用的就是它。

第 2 步:在页脚插入备案号

打开刚复制的文件,找到文件末尾的 </footer>,在它前面插入这段:

<!-- 备案号单独占一行,并链接到工信部备案系统 -->
<p class="info footer__icp">
  <a href="https://beian.miit.gov.cn/" target="_blank"
     rel="noreferrer noopener">皖ICP备2021009418号-5</a>
</p>

改完可以验证一下有没有插对:

# 看文件里有没有这行备案号
grep -n '皖ICP' themes/icp/core/templates/layout.guest.php

第 3 步:启用这个主题

# 告诉 Nextcloud 使用 icp 这个主题
sudo -u www php occ config:system:set theme --value=icp

看到 System config value theme set to string icp 就成功了。

第 4 步:验证效果

# 抓取登录页,看能不能找到备案号
curl -sk https://你的域名/index.php/login | grep -o '皖ICP备[^<]*'

# 顺便确认站点各路径状态码
for u in / /index.php/login /status.php /data/; do
  echo "$u $(curl -sk -o /dev/null -w '%{http_code}' https://你的域名$u)"
done

正常结果:备案号能抓到;/ 返回 302(跳登录)、登录页 200、/status.php 200、/data/ 返回 403(数据目录被挡住,这是对的)。

第 5 步:确认没破坏完整性检查

完整性检查干净
没有任何输出、返回 0,就是干净
# 跑一遍核心文件完整性检查
sudo -u www php occ integrity:check-core
# 没有任何输出 = 全部文件与官方签名一致
echo $?

几个真实的坑

完整性告警长什么样
改了签名文件之后,告警长这样
  1. 文件名是 zh_CN.json,不是 zh-CN.json。网上很多教程写错,会找不到文件。
  2. 别改 apps/ 下的任何文件。那是签名范围,改一个字节,后台就多一条”某些文件未通过完整性检查”。
  3. Nextcloud 的签名哈希是 SHA-512(128 位十六进制)。用 sha256sum 去比对,数值永远对不上,别被自己误导。
  4. 如果你同时切换过 PHP 版本,注意模板里如果有硬编码 socket 路径(如 /tmp/php-cgi-82.sock),要跟着改成新版本。

补充:路径怎么找,为什么换 PHP 版本会踩坑

官方模板的实际路径

前面写的 core/templates/layout.guest.php 是相对路径,因为那行命令之前已经 cd 进了站点目录。如果你在别的目录执行,就得用绝对路径:

/www/wwwroot/www.hello0564.com/core/templates/layout.guest.php

实测对比:

文件大小时间
官方原件 core/templates/layout.guest.php2821 字节10-15
我们的副本 themes/icp/core/templates/layout.guest.php2963 字节11-04

副本多出来的 142 字节,就是插入的那段备案号——原件一个字节都没动。

保险做法:脚本和定时任务里一律用绝对路径,永远不依赖”当前在哪个目录”。

它和”切换 PHP 版本”到底是什么关系

这里要拆成两件事,很多人混在一起:

第一件:模板文件本身跟 PHP 版本无关。 layout.guest.php 就是个普通 PHP 模板,8.2 能跑、8.3 也能跑,换版本不需要为它做任何事。

第二件:真正相关的是”写死的路径”。 比如 nginx 里如果有这么一行:

fastcgi_pass unix:/tmp/php-cgi-82.sock;   # 写死了 82

站点切到 PHP 8.3 之后,socket 变成了 /tmp/php-cgi-83.sock。配置没跟着改,相关路由立刻失效。所以:换 PHP 版本本身不麻烦,麻烦的是别处写死了旧版本号。

举一反三

1. themes/ 是一层”影子目录”。 Nextcloud 找文件时先看 themes/主题名/,有就用,没有才回落到官方目录:

themes/icp/core/templates/layout.guest.php   ← 优先
core/templates/layout.guest.php              ← 兜底

这套机制不只对模板有效,core/css/、core/img/、core/fonts/ 也一样。所以想改外观,永远优先往 themes 里放,别碰 core/ 和 apps/。

2. 怎么判断”哪个文件真在生效”:

# 看大小和时间:副本应该更新、可能更大
ls -l core/templates/layout.guest.php
ls -l themes/icp/core/templates/layout.guest.php

# 或者直接看网页输出,最快最准
curl -sk https://你的域名/index.php/login | grep 备案号

3. 换环境之前,先列一份”写死清单”:

类型例子换版本/换机会不会坏
socket 路径/tmp/php-cgi-82.sock会
PHP 版本号enable-php-82.conf会
绝对路径/www/wwwroot/旧域名/会
数据库地址localhost:3306可能
证书路径/www/server/panel/vhost/cert/旧域名/会

判断标准:这个值里有没有”会变的东西”(版本号、域名、端口、路径)。有,就单独记一笔。

4. 改文件的三条铁律:先备份、只改副本、留回滚命令。改之前就想好怎么退回去。

5. 验证技巧:想确认”是不是我改的这个文件起作用”,最快的办法是改一个肉眼可见的字,刷新页面看变没变——比读十遍配置都快。

一句话总结:模板路径要写对,是因为你要找对文件;PHP 版本要跟着改,是因为别处写死了旧版本号。两者不是一回事——前者是”找对文件”,后者是”别留后患”。

想撤销怎么办

# 删掉主题目录
rm -rf /www/wwwroot/www.hello0564.com/themes/icp

# 取消主题设置
cd /www/wwwroot/www.hello0564.com
sudo -u www php occ config:system:delete theme

页面立刻恢复原样,不影响任何用户数据。

附:本文用到的两个文件

把文中提到的两个模板打包成 7z,方便对照:

两个压缩包解压后文件名都是 layout.guest.php,可以直接放到 themes/icp/core/templates/ 目录下使用。

小结

  • 备案号这类”外观需求”,优先走 themes/ 自定义主题,别动签名文件
  • 只覆盖需要改的那一个模板,其它保持官方原样
  • 改完必查三件事:页面能看到、站点状态码正常、完整性检查还是干净的

按这个流程,我给两个站点(Nextcloud 33 和 34)都加上了各自的备案号,完整性检查保持 0 告警。

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注