Nextcloud AIO 可选附加组件（Optional Addons）功能验收与配置验证指南

• 云原生
• 运维
• 后端
• 容器编排

本指南以 Nextcloud All-in-One 仓库中的手动 QA 测试计划 050-optional-addons.md 为主体，完整讲解 AIO 界面中"可选附加组件"区域的验证流程：如何在不同状态下启停组件、如何逐一验证 ClamAV、Collabora、Nextcloud Talk、Imaginary、Fulltextsearch、Talk Recording 等组件的真实生效情况，以及 Collabora 专属的字典与附加命令行选项的输入校验规则。读完本文，你将掌握一套可直接照做的功能验收清单，并理解这些规则在 optional-containers.twig 界面与 ConfigurationManager.php 校验逻辑中的底层实现。

一、这份 QA 文档在项目中的定位

仓库的 tests/QA/readme.md 明确说明：tests/QA目录存放的是手动 QA 测试计划，用于在干净的测试实例上逐步验证功能是否符合预期。测试环境的搭建要求是：合并所有可能破坏性变更后，按 develop.md 的说明构建新容器，停掉旧实例、删除旧实例并清理全部卷，再启动一个全新的干净测试实例，且最好从 001-initial-setup.md 开始按顺序执行。

050-optional-addons.md正是这条 QA 序列中的一环，它验证的是 AIO 界面中"Optional addons（可选附加组件）"模块的完整生命周期：查看、变更、启动新容器、逐项功能验收、Collabora 专属配置校验，最后衔接 055-community-containers.md 的社区容器测试。

二、可选附加组件区域在哪里，包含哪些组件

QA 计划的第一步是：在 AIO 界面中滚动到页面底部，找到 Optional addons 区域。该区域在代码中对应模板 optional-containers.twig，由 containers.twig 在备份容器未运行时引入。从模板可见，该区域包含两类内容：

1. Office Suite（办公套件）单选卡片，三选一且只能启用一个：

• Nextcloud Office（powered by Euro-Office）
• Nextcloud Office（powered by Collabora Online）
• ONLYOFFICE（模板中明确标注 deprecated，已不建议新启用）
• 另有一个"Disable office suite"选项用于完全禁用

2. Additional Optional Containers（附加可选容器）复选框列表，对应 containers.json 中通过profiles字段区分的容器：

各容器定义均可从 containers.json 的aio_services_v1数组中逐一查到，例如 ClamAV 条目位于 containers.json，其profiles为["clamav"]，内部端口 3310；Collabora 条目位于 containers.json，内部端口 9980，并通过dictionaries=%COLLABORA_DICTIONARIES%环境变量接收字典配置。

三、变更规则：仅允许在容器停止时修改

QA 计划的第二条要求验证一条关键交互规则：容器停止时可以更改可选附加组件，容器运行中则不允许更改。

这一规则在模板中有双重保障：

• 当任一容器处于运行状态时（isAnyRunning == true），模板顶部会显示提示"只能在容器停止时启用或禁用以下选项"，同时加载 disable-containers.js 禁用表单控件；
• 当容器全部停止时，模板则提示用户必须点击列表下方的 "Save changes" 按钮保存，变更不会自动保存（见 optional-containers.twig）。

前端交互细节在 containers-form-submit.js 中实现：提交按钮默认被隐藏，只有检测到复选框勾选状态或 Office Suite 单选值相比初始状态发生变化时才显示（containers-form-submit.js）。该脚本还封装了几条联动规则，可作为验收时的预期行为：

• Talk Recording 依赖 Talk：Talk 未勾选时，Talk Recording 复选框被强制取消并禁用（containers-form-submit.js）；
• Docker Socket Proxy 已弃用：勾选会弹出弃用警告并回滚勾选（containers-form-submit.js）；
• ONLYOFFICE 已弃用：勾选会弹出弃用警告并回滚（containers-form-submit.js）；
• HaRP 安全警告：勾选 HaRP 会提示其暴露 Docker Socket 带来的安全风险（containers-form-submit.js）。

提交后表单以POST方式发往api/configuration，由 ConfigurationController.php 的SetConfig方法解析options-form字段，通过ConfigurationManager持久化officeSuite、isClamavEnabled、isTalkEnabled、isTalkRecordingEnabled、isImaginaryEnabled、isFulltextsearchEnabled、isDockerSocketProxyEnabled、isHarpEnabled、isWhiteboardEnabled等配置项。

四、逐项功能验收清单

QA 计划的第三条要求：启用任一选项后，应启动一个同名（或名称可比对）的新容器，并在界面的 Containers 区域中列出它。容器实际启动由 DockerController.php 的PerformRecursiveContainerStart完成：它会先按depends_on递归启动依赖容器，再删除旧容器、创建卷、拉取镜像、创建并启动容器、接入网络。由于可选容器会通过%XXX_ENABLED%占位符被注入到 Nextcloud 主容器的环境变量（如CLAMAV_ENABLED、COLLABORA_ENABLED、TALK_ENABLED、IMAGINARY_ENABLED、FULLTEXTSEARCH_ENABLED、TALK_RECORDING_ENABLED，见 containers.json），因此必须等所有容器以新配置完整启动后，再执行下列功能验证——这对应 QA 计划第四条"验证选项是否被自动激活/停用"的要求。

每个组件的验收方法与期望结果如下表（QA 文档原样保留，并补充判定要点）：

需要说明的是，Fulltextsearch 的首次索引可能耗时很长，期间 Nextcloud 会不可用（界面提示见 optional-containers.twig）；Imaginary 目前与服务器端加密不兼容；Talk 需要保证对应端口的 TCP 与 UDP 在防火墙/路由器上已开放并转发（界面提示见 optional-containers.twig）。这些都是在验收前应确认的前提条件。

五、Collabora 专属配置：字典（Dictionaries）验证

QA 文档第五条专门针对 Collabora：启用 Collabora 后，Optional Addons 区域下方应出现一个可修改 Collabora 字典的区块。对应模板代码见 optional-containers.twig，其渲染条件为office_suite == 'collabora'且容器未运行、已点击过启动按钮。

验收要点有两项：

1. 合法值校验：de_DE en_GB en_US es_ES fr_FR it nl pt_BR pt_PT ru是合法设置；而de.De这类写法不合法，应被拒绝。
2. 重置按钮：若已设置过字典，区块应显示一个按钮，允许一键删除该设置（对应模板中的Reset Nextcloud Office dictionaries表单与delete_collabora_dictionaries字段）。

底层校验实现：提交的collabora_dictionaries字段由 ConfigurationController.php 交给ConfigurationManager的collaboraDictionaries属性，其 setter 调用validateCollaboraDictionaries（ConfigurationManager.php）：

if (!preg_match("#^[a-zA-Z_ ]+$#", $CollaboraDictionaries)) { throw new InvalidSettingConfigurationException("The entered dictionaries do not seem to be a valid!"); }

正则^[a-zA-Z_ ]+$只允许字母、下划线与空格——这正好解释了为什么de_DE en_GB en_US es_ES fr_FR it nl pt_BR pt_PT ru合法（全为字母/下划线/空格），而de.De非法（含点号.）。校验失败会抛出InvalidSettingConfigurationException，由控制器返回 HTTP 422 并携带错误信息（ConfigurationController.php）。

默认值行为：若用户未设置字典，配置管理器在生成 Collabora 容器环境变量时会将COLLABORA_DICTIONARIES回退为默认值de_DE en_GB en_US es_ES fr_FR it nl pt_BR pt_PT ru（见 ConfigurationManager.php），与模板输入框的 placeholder 完全一致。

六、Collabora 专属配置：附加选项（Additional Options）验证

QA 文档第六条要求验证附加 Collabora 选项输入框的合法性校验：net.content_security_policy=false不应被接受，而--o:net.content_security_policy="frame-ancestors *.example.com:*;"应该被接受。界面位于 optional-containers.twig，同样只在 Collabora 启用、容器停止且已点击启动后渲染，示例值在模板第 304 行。

底层校验实现：字段collabora_additional_options经 ConfigurationController.php 进入ConfigurationManager，setter 调用validateCollaboraAdditionalOptions（ConfigurationManager.php）：

if (!preg_match("#^--o:#", $additionalCollaboraOptions)) { throw new InvalidSettingConfigurationException("The entered options must start with '--o:'. So the config does not seem to be a valid!"); }

校验规则只有一个核心约束：必须以--o:前缀开头。这正是两份测试样例一拒一收的原因：net.content_security_policy=false缺少--o:前缀，被拒绝；--o:net.content_security_policy="frame-ancestors *.example.com:*;"以--o:开头，被接受。该值的用途是向 Collabora 的coolwsd进程追加启动参数，例如自定义net.content_security_policy等高级选项；模板中同样提供了Reset additional Nextcloud Office options按钮（对应delete_collabora_additional_options字段与 ConfigurationManager.php 的deleteAdditionalCollaboraOptions方法）用于清除设置。

两个字段的删除分支（delete_collabora_dictionaries、delete_collabora_additional_options）在 ConfigurationController.php 中统一处理，且整个配置写入过程包在startTransaction()/commitTransaction()之间，保证多字段更新一次性落盘（ConfigurationManager.php）。

七、系统资源要求（验收前置条件）

模板底部明确列出了启用可选组件时的最低系统要求（optional-containers.twig），这是验收环境必须满足的硬性条件：

• 启用任意可选容器：至少2GB RAM、双核 CPU、40GB 系统存储；
• 启用 ClamAV、Nextcloud Talk Recording-server 或 Fulltextsearch：至少3GB RAM；
• 启用 Talk Recording-server：额外需要2 个 vCPU；
• 全部启用：至少5GB RAM 和四核 CPU；
• 官方建议：在最低要求基础上再预留至少1GB 内存。

若测试实例资源不足，容器可能反复重启或启动失败，因此建议在干净且满足上述配置的环境中执行本验收清单。

八、验证完成后的衔接

当以上所有条目（界面位置、停止态可改/运行态不可改、新容器启动并列出、六个组件的功能生效、Collabora 字典与附加选项的合法/非法值校验、重置按钮）全部通过后，即可继续执行后续测试计划 055-community-containers.md，验证社区容器（community containers）的安装与运行行为。

• 云原生
• 运维
• 后端
• 容器编排