nixpkgs 中 Nextcloud 应用包集合:从生成 App 包到 NixOS 模块集成的完整机制
nixpkgs 中 Nextcloud 应用包集合:从生成 App 包到 NixOS 模块集成的完整机制
本文围绕 nixpkgs 仓库中 Nextcloud 服务器包的配套文档 pkgs/servers/nextcloud/packages/README.md 展开,系统讲解 nextcloudPackages 应用包集合的目录结构与数据来源、generate.sh 重新生成全部应用包的完整流程、向 nextcloud-apps.json 添加新应用的操作规范,以及如何在 NixOS 的 Nextcloud 服务模块中通过 extraApps / extraAppsEnable 选项把 Nix 构建的应用安装进部署实例。读完本文,你将能够独立维护 nixpkgs 的 Nextcloud 应用集合,并把仓库中的应用包接入自己的 NixOS 配置。
nextcloudPackages 是什么:目录结构与版本集合
Nextcloud 服务器本身由 pkgs/servers/nextcloud/default.nix 定义,它按大版本提供 nextcloud33、nextcloud34、nextcloud35 三个包(当前仓库中分别为 33.0.9、34.0.4、35.0.1),并通过顶层导出进入 nixpkgs:pkgs/top-level/all-packages.nix 中可以看到:
inherit (callPackages ../servers/nextcloud { })
nextcloud33
nextcloud34
nextcloud35
;
nextcloud33Packages = callPackage ../servers/nextcloud/packages { ncVersion = "33"; };
nextcloud34Packages = callPackage ../servers/nextcloud/packages { ncVersion = "34"; };
nextcloud35Packages = callPackage ../servers/nextcloud/packages { ncVersion = "35"; };
关键点在于 ncVersion 参数:同一个 packages 构建文件会被以不同的大版本号分别调用一次,从而为每个受支持的 Nextcloud 大版本各生成一套应用包集合(如 pkgs.nextcloud35Packages.apps 命名空间)。旧的 nextcloud32 已因 EOL 被移除,pkgs/top-level/aliases.nix 中保留了别名,访问时会 throw 并提示改用 nextcloud33。
packages 目录下的文件分工如下(见 pkgs/servers/nextcloud/packages):
| 文件 | 作用 |
|---|---|
nextcloud-apps.json |
手工维护的清单:应用 id → 许可证 映射,是添加应用的唯一入口 |
33.json / 34.json / 35.json |
工具生成的每版本数据:url、hash、version、description、homepage、licenses |
generate.sh |
重新生成上述三个 JSON 的入口脚本 |
default.nix |
读取生成的 JSON,构建应用 derivation 集合 |
nc-versions.nix |
自动探测 nixpkgs 中当前存在哪些 Nextcloud 大版本 |
thirdparty.nix |
扩展第三方手写应用包(memories、recognize、hmr_enabler) |
apps/ |
上述第三方应用的 Nix 定义与补丁 |
| README.md | 本篇所依据的维护/使用文档 |
重新生成应用包:./generate.sh 做了什么
文档给出的第一步操作是:要重新生成 nixpkgs 的 nextcloudPackages 集合,运行
./generate.sh
然后提交变更、发起 pull request。
generate.sh 的完整内容很短,但每一步都揭示了生成机制(见 pkgs/servers/nextcloud/packages/generate.sh):
#!/usr/bin/env nix-shell
#! nix-shell -I nixpkgs=../../../.. -i bash -p nc4nix jq
set -e
set -u
set -o pipefail
set -x
export NEXTCLOUD_VERSIONS=$(nix-instantiate --eval -E 'import ./nc-versions.nix {}' -A e)
APPS=`cat nextcloud-apps.json | jq -r 'keys|.[]' | sed -z 's/\n/,/g;s/,$/\n/'`
nc4nix -apps $APPS
rm *.log
逐行解读:
- 双行 shebang(nix-shell 声明):第一行
#!/usr/bin/env nix-shell,第二行声明该脚本以 nix-shell 方式运行,-I nixpkgs=../../../..指向仓库根,-p nc4nix jq把nc4nix(Helsinki Systems 开发的 Go 语言抓取工具)和jq放进脚本环境。因此无需手工安装任何依赖,脚本在干净环境中直接可执行。文件头注释标明其来源为helsinki-systems/wp4nix并经过修改(MIT 许可)。 NEXTCLOUD_VERSIONS环境变量:通过nix-instantiate --eval求值 nc-versions.nix,取其e属性。该文件的做法是对pkgs顶层 attrset 做lib.filterAttrs,保留键名匹配nextcloud[0-9]+且v.version可成功求值的条目,把版本号用逗号拼成字符串(如33,34,35)。这样当 nixpkgs 增减 Nextcloud 大版本时,生成脚本无需任何修改。APPS变量:用jq提取nextcloud-apps.json的全部键(即所有应用 id),再拼成逗号分隔的列表,作为nc4nix -apps的参数。nc4nix -apps $APPS:Go 工具读取NEXTCLOUD_VERSIONS环境变量,逐个向 Nextcloud 官方应用商店查询这些应用的下载地址与校验和,写出33.json、34.json、35.json(每个版本一个文件),运行日志写入*.log,最后一行rm *.log负责清理,保证不残留临时文件进提交。
生成后的 JSON 以 35.json 为例,每个应用包含完整元数据:
"calendar": {
"hash": "sha256-foNjLUQ20wN6NNHHPLwG1cy26PwQ8JaoakOgUVWIUpw=",
"url": "https://github.com/nextcloud-releases/calendar/releases/download/v6.6.2/calendar-v6.6.2.tar.gz",
"version": "6.6.2",
"description": "A Calendar app for Nextcloud. ...",
"homepage": "https://github.com/nextcloud/calendar/",
"licenses": [ "agpl" ]
}
这些文件是构建系统的直接输入,packages/default.nix 头部的注释也印证了这一点:# This takes the data generated from the go tool.
添加新应用:修改 nextcloud-apps.json 的规范
文档对"新增应用"给出了明确且带强制性提示的流程:
-
先更新,再添加:向 nixpkgs 提交新增应用的 PR 之前,必须先在单独的 commit 中按上文流程执行一次
./generate.sh更新,确保基线是最新的。 -
添加一行:向对应的 JSON 清单文件追加一行,即
nextcloud-apps.json(针对应用)。该文件的格式是应用 id → 许可证的对象,例如现有条目(见 nextcloud-apps.json):"mail" : "agpl3Plus" , "calendar" : "agpl3Plus" , "onlyoffice" : "asl20" , "user_saml" : "agpl3Plus"许可证字段取的是
lib.licenses中的名字(如agpl3Plus、agpl3Only、asl20),packages/default.nix中会直接以lib.licenses.${license}的方式解析它,因此填错的许可证名会在求值期报错。 -
id 的取值规则:应用必须收录在 Nextcloud 官方应用商店中;id 对应应用商店 URL 的最后一段。文档举的例子是:商店地址末段为
breezedark的应用,其 id 就是breezedark。从 id 命名习惯看,应用 id 保留原始连字符或下划线(如files_markdown、twofactor_webauthn),在 Nix 侧会自动映射为属性访问名。 -
重新生成并做"单应用"校验:再次运行
./generate.sh,文档特别强调——必须确认本次更新中,只有新加入nextcloud-apps.json的那个应用的版本发生了变化。由于 JSON 中每个应用的 url/hash/version 都随上游发版变动,这一步是避免把无关的批量版本漂移混入新应用的 PR、便于评审的关键要求。 -
提交:把 JSON 清单与重新生成的三个版本 JSON 一起提交并发 pull request。
生成数据的消费端:packages/default.nix 如何构建应用集合
packages/default.nix 是整套机制的收口(见 pkgs/servers/nextcloud/packages/default.nix),几个值得注意的实现细节:
- 按
ncVersion读取对应 JSON:apps ? lib.importJSON (./. + "/${ncVersion}.json")。这正是顶层用ncVersion = "33"/"34"/"35"分别调用它的消费端。把默认值放在参数里还允许 out-of-tree override(文件内注释# Support out-of-tree overrides)——外部调用方可以传入自己的应用数据 attrset,而不必触碰仓库内的 JSON。 mkNextcloudDerivation:对每个应用调用pkgs.fetchNextcloudApp,把appName、data.version、许可证(来自nextcloud-apps.json的appBaseDefs)以及 JSON 里的url、hash、description、homepage传入,并统一挂上lib.teams.nextcloud维护团队。lib.makeScope与 extend:整个集合用lib.makeScope newScope packages包裹成可扩展的作用域,随后.extend (import ./thirdparty.nix { inherit ncVersion; }),把第三方应用并入apps命名空间。- 额外的
notify_push:官方应用之外,集合中还内置了nextcloud-notify_push.app(由 pkgs/servers/nextcloud/notify_push.nix 构建),用于支持通知推送。 - 第三方应用扩展:thirdparty.nix 通过
apps.extend注入三个手写应用:hmr_enabler、memories(其构建目录内附带 memories-paths.diff 补丁)、recognize,说明当官方商店数据不足以表达构建需求(需要补丁、版本约束等)时,可以绕过生成流程直接callPackage。
fetchNextcloudApp 本身的实现在 pkgs/build-support/fetchnextcloudapp/default.nix(由 pkgs/top-level/all-packages.nix#L558 导出为 pkgs.fetchNextcloudApp)。它支持 hash / sha256 / sha512 三种校验形式,unpack = true 时改用 fetchzip;prePatch 阶段会强制检查 appinfo/info.xml 是否存在,缺失即中止构建——这是对"下载物确实是合法的 Nextcloud 应用"的最小结构校验;sourceProvenance 标注为 fromSource 加 binaryBytecode,如实声明应用包内含有已编译的 vendored 依赖与编译好的前端模板。
在 NixOS 模块中使用:extraApps 与 extraAppsEnable
文档给出的 NixOS 配置示例如下(版本编号已按当前仓库受支持的大版本适配为 nextcloud35,实际应选用你需要的 nextcloud33 / nextcloud34 / nextcloud35 之一):
{
services.nextcloud = {
enable = true;
package = pkgs.nextcloud35;
hostName = "localhost";
config.adminpassFile = "${pkgs.writeText "adminpass" "hunter2"}";
extraApps = with pkgs.nextcloud35Packages.apps; {
inherit mail calendar contacts;
};
extraAppsEnable = true;
};
}
应用包位于 nextcloudXXPackages.apps 命名空间(XX 为当前受支持的大版本号),与所选服务器包版本保持一致。
对照 NixOS 模块源码 nixos/modules/services/web-apps/nextcloud.nix,这些选项的精确语义是:
extraApps(定义处):类型为attrsOf package,默认{}。注释明确要求 attrset 的键(appid)必须与应用appinfo/info.xml中的id完全一致,值应是fetchNextcloudApp生成的包。extraAppsEnable(定义处):布尔型,默认true,表示每次 Nextcloud 启动时自动occ app:enable全部extraApps;设为false时则需通过 Web 界面或nextcloud-occ app:enable手工启用。appstoreEnable的联动行为(定义处):默认null。一旦配置了非空的extraApps,模块会自动禁用应用商店,防止 Nextcloud 在运行期更新这些由 Nix 管理的应用——这是模块注释中写明"Using this will disable the appstore to prevent Nextcloud from updating these apps"的行为;若确需两者并存,可显式设置appstoreEnable = true强制开启。
模块内部如何落地这些包:在 web 根下创建两个子目录(见 nextcloud.nix)——nix-apps 目录由 pkgs.linkFarm 把 extraApps 各包软链进去且标记为不可写;store-apps 目录指向 ${cfg.home}/store-apps 且可写,供商店安装使用。两者随后都被渲染进 appstore.php 的 OC_App::getAppStores 配置(相关代码)。初始化阶段还会在 systemd oneshot 服务里执行 app:enable 批量启用(nextcloud.nix)。模块文档页面见 nixos/modules/services/web-apps/nextcloud.md。
验证与测试
仓库为 Nextcloud 服务保留了专门的集成测试目录 nixos/tests/nextcloud(10 个测试文件)。另外 packages/default.nix 的服务器 derivation 通过 passthru.tests 把 nixosTests.nextcloud 按 version 的主版本号过滤后挂载(见 pkgs/servers/nextcloud/default.nix#L40-L43),即 nextcloud35 的 passthru.tests 只包含以 35 结尾的测试名,可用 nix-build -A nextcloud35.passthru.tests 之类的路径检索并按需运行。meta.knownVulnerabilities 还会对 EOL 版本自动追加"Nextcloud version X is EOL"的已知漏洞提示。
小结
pkgs/servers/nextcloud/packages/README.md 所描述的维护闭环可以归纳为:nextcloud-apps.json 是唯一手工维护的输入(应用 id 到许可证的映射),nc4nix 工具结合自动探测的版本列表产出每个大版本的数据 JSON,packages/default.nix 将其转换为基于 fetchNextcloudApp 的可复用 derivation 集合,再由 NixOS 模块的 extraApps / extraAppsEnable / appstoreEnable 选项完成部署与商店联动。新增应用前务必先单独提交一次全量更新,并验证生成结果中只有新增应用发生了变化,这是保证 PR 可评审性的核心约定。