企业官网建设流程全解析

Nextcloud Server 如何基于 config.sample.php 的说明安全修改 config.php？

【免费下载链接】server☁️ Nextcloud server, a safe home for all your data项目地址: https://gitcode.com/GitHub_Trending/se/server

在部署和日常运维 Nextcloud Server 时，管理员经常需要修改config/config.php：调整trusted_domains、更换数据库类型、设置会话时长等。仓库中的 config/config.sample.php 就是这些配置项的官方说明来源。但它只是文档，不能直接当作模板使用。本文说明如何基于它的注释安全地修改工作配置文件，以及如何验证修改生效。

config.sample.php 的定位：是文档，不是模板

config/config.sample.php 文件头部（第 9–17 行）明确声明了它的用途和使用限制：

This configuration file is only provided to document the different configuration options and their usage.

DO NOT COMPLETELY BASE YOUR CONFIGURATION FILE ON THIS SAMPLE. THIS MAY BREAK YOUR INSTANCE. Instead, manually copy configuration switches that you consider important for your instance to your workingconfig.php, and apply configuration options that are pertinent for your instance.

也就是说，文件头部直接警告：不要完全基于这个样例来构建你的配置，可能会弄坏你的实例。正确做法是只把你认为重要的配置开关，手动复制到工作中的config/config.php，并只应用与你实例相关的配置项。这个文件同时用于生成配置文档，其中的值（如datadirectory的/var/www/nextcloud/data、dbname的nextcloud）都是文档示例值，不是你应该原样使用的值。

哪些配置项由安装器写入，改的时候要格外小心

样例文件的 "Default Parameters" 一节标注了安装器写入的参数，并逐条说明了限制。修改config.php前，先对照这些说明判断该项是否可以动：

真正适合在部署运维阶段手工修改的，是其余带说明和默认值的可选项，例如trusted_domains、datadirectory、dbtype、会话相关参数等。

修改步骤：按需手动复制配置项

1. 确定要修改的配置项：在 config/config.sample.php 中定位目标键。每个键上方的/** ... */注释块就是该项的说明，包括含义、可用值、默认值和副作用警告，例如dbtype一节写明可用值为sqlite3（默认）、mysql（MySQL/MariaDB）、pgsql（PostgreSQL），以及dbhost支持的格式（主机名、hostname:####指定端口、[ip]:port表示 IPv6、localhost:/path/to/socket表示 Unix socket）。
2. 只把需要的键值对复制进config/config.php：保留你实例已有的安装器参数，追加或调整你要变更的项。不要整文件替换。
3. 注意样例中显式的安全警告：例如trusted_domains一节说明该列表用于防止 host header 投毒，并明确 "Do not remove this, as it performs necessary security checks"。允许写入的形式包括：精确主机名（demo.example.org）、带端口的主机名（demo.example.org:443，会禁止该主机的其他端口）、通配符（ubos-raspberry-pi*.local）、带或不带端口的 IPv6 地址（如[2001:db8::1]:8080）。样例中的demo.example.org、10.111.112.113等只是文档示例，请替换为你实际的用户可登录域名。

一个只改动域名白名单的config/config.php片段示例（数组值需替换为你的实际域名）：

<?php $CONFIG = [ // 保留安装器写入的参数不变，这里仅示意需要调整的项 'trusted_domains' => [ 'cloud.example.org', '10.0.0.5', '[2001:db8::1]', ], ];

验证修改

样例文件自身给出了一个 CLI 验证用法（见serverid一节，第 55 行）：

NC_serverid=42 occ config:list system

其中NC_serverid=42是serverid说明中要求在多服务器共享config.php时、为 CLI 和 web server 分别覆盖该值的示例写法；occ config:list system用于列出当前系统级配置，可用来确认你刚修改的键已经生效。

另一个可直接观察的验证点是未信任域名错误页：当用户访问的域名不在白名单内时，服务端会渲染 core/templates/untrustedDomain.php，页面提示 "If you are an administrator, edit the "trusted_domains" setting in config/config.php like the example in config.sample.php."。看到该提示即说明当前请求的域名未包含在trusted_domains中，按上述步骤把该域名加入列表即可。

限制与边界

• 不要整体复制样例：文件头部警告这是唯一总原则，样例中的值是文档示例，整文件照搬可能直接弄坏实例。
• passwordsalt已废弃（9.0.0 起标注@deprecated，仅供遗留兼容），新配置不要围绕它做任何处理，也不要删除现有值。
• 会话与认证参数有配套关系：样例中remember_login_cookie_lifetime（默认 15 天）说明要求设得高于session_lifetime（默认 24 小时），以避免"记住我"意外过期；auth.bruteforce.protection.enabled、ratelimit.protection.enabled默认均为true，样例注释明确 "Disabling this is discouraged for security reasons"，没有明确理由不要关闭。
• 多服务器共享config.php时：serverid必须为 0–511 的整数，且要同时为 CLI 和 web server 分别用NC_serverid=<int>覆盖，二者缺一不可。

修改完成后，以occ config:list system的输出与访问页面（未再出现 untrusted domain 提示）作为本次变更的核对结果。

【免费下载链接】server☁️ Nextcloud server, a safe home for all your data项目地址: https://gitcode.com/GitHub_Trending/se/server