nixpkgs 中 Nextcloud 应用包集合:从生成 App 包到 NixOS 模块集成的完整机制

原创2026-10-08 13:55:461,961 阅读
文章标签:操作系统包管理器

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

逐行解读:

  1. 双行 shebang(nix-shell 声明):第一行 #!/usr/bin/env nix-shell,第二行声明该脚本以 nix-shell 方式运行,-I nixpkgs=../../../.. 指向仓库根,-p nc4nix jq 把 nc4nix(Helsinki Systems 开发的 Go 语言抓取工具)和 jq 放进脚本环境。因此无需手工安装任何依赖,脚本在干净环境中直接可执行。文件头注释标明其来源为 helsinki-systems/wp4nix 并经过修改(MIT 许可)。
  2. NEXTCLOUD_VERSIONS 环境变量:通过 nix-instantiate --eval 求值 nc-versions.nix,取其 e 属性。该文件的做法是对 pkgs 顶层 attrset 做 lib.filterAttrs,保留键名匹配 nextcloud[0-9]+ 且 v.version 可成功求值的条目,把版本号用逗号拼成字符串(如 33,34,35)。这样当 nixpkgs 增减 Nextcloud 大版本时,生成脚本无需任何修改。
  3. APPS 变量:用 jq 提取 nextcloud-apps.json 的全部键(即所有应用 id),再拼成逗号分隔的列表,作为 nc4nix -apps 的参数。
  4. 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 的规范

文档对"新增应用"给出了明确且带强制性提示的流程:

  1. 先更新,再添加:向 nixpkgs 提交新增应用的 PR 之前,必须先在单独的 commit 中按上文流程执行一次 ./generate.sh 更新,确保基线是最新的。

  2. 添加一行:向对应的 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} 的方式解析它,因此填错的许可证名会在求值期报错。

  3. id 的取值规则:应用必须收录在 Nextcloud 官方应用商店中;id 对应应用商店 URL 的最后一段。文档举的例子是:商店地址末段为 breezedark 的应用,其 id 就是 breezedark。从 id 命名习惯看,应用 id 保留原始连字符或下划线(如 files_markdown、twofactor_webauthn),在 Nix 侧会自动映射为属性访问名。

  4. 重新生成并做"单应用"校验:再次运行 ./generate.sh,文档特别强调——必须确认本次更新中,只有新加入 nextcloud-apps.json 的那个应用的版本发生了变化。由于 JSON 中每个应用的 url/hash/version 都随上游发版变动,这一步是避免把无关的批量版本漂移混入新应用的 PR、便于评审的关键要求。

  5. 提交:把 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 可评审性的核心约定。

登录后查看全文
nixpkgs