Nextcloud 通用故障排查

如果安装、配置或维护 Nextcloud 时遇到问题，可以向 Nextcloud 论坛等社区支持渠道求助。论坛的常见问题页面按主题整理了典型错误和经常遇到的问题。

请理解，这些渠道主要由与你一样的用户互相帮助。获得帮助后，也请在力所能及时帮助别人，回馈社区；这是社区保持健康、持续发展的基础。如果你在企业环境或其他大规模部署中使用 Nextcloud，Nextcloud GmbH 也提供商业支持选项。

报告缺陷

如果你认为发现了软件缺陷，请先搜索已有解决办法，并再次检查配置。仍然找不到解决办法时，再使用 Nextcloud 的缺陷跟踪系统。occ 配置命令可以生成配置报告，并自动遮蔽密码。

通用检查

核对 Nextcloud 系统要求，尤其是受支持的浏览器版本。遇到 code integrity 警告时，参阅代码签名说明。

禁用第三方应用和非随附应用

第三方应用或没有随系统提供的应用，可能引起各种问题。在升级以及排查故障前，应先禁用第三方应用。如何从命令行禁用应用，参阅 occ 应用命令。

内部服务器错误

内部服务器错误也叫“500 错误”，表示 Web 服务器遇到了意外情况，无法完成请求。这是一种通用的错误响应。要定位真正原因，需要查看 Nextcloud 日志，默认在 data/nextcloud.log，还可能需要查看 Web 服务器错误日志，具体取决于错误发生的位置。

Nextcloud 日志

默认日志位于数据目录，例如 data/nextcloud.log。Web 界面仍能访问时，也可以在“管理设置 → 日志”中查看。求助时，通常需要提供完整的原始日志条目；共享前应脱敏私人数据和凭据。

某些情况需要在 config.php 中调整日志级别，详见日志配置。部分日志，例如 JavaScript 控制台日志，需要启用调试：把 config/config.php 中的 'debug' => false, 改为 'debug' => true,，完成排查后务必改回。

排查 JavaScript 问题时，还需要查看浏览器的 JavaScript 控制台。主流浏览器都有开发者工具，通常可以按 F12 打开。

PHP 版本和环境信息

需要确定 Nextcloud 服务器实际使用的 PHP 版本和配置。这不一定与命令行可见的 PHP 版本和配置相同。常用的信息收集方式是 phpinfo()。

最准确也最方便的方式，是在 Nextcloud 内部查看。前提是系统仍能运行到足以让管理员登录并访问“管理设置 → 系统”。可以通过 occ 启用 phpinfo 信息展示：

./occ config:app:set --value=yes serverinfo phpinfo

之后，“管理设置 → 系统”中会出现“Show phpinfo”按钮。点击它，即可查看 PHP 环境的详细信息。

如果无法访问 Web 界面，可以在 Web 根目录创建名为 phpinfo.php 的纯文本文件，例如 /var/www/html/phpinfo.php。你的 Web 根目录可能不同，应查阅所用发行版的文档。文件只包含这一行：

<?php phpinfo(); ?>

在浏览器中打开 localhost/phpinfo.php。页面顶部显示 PHP 版本，其余部分包含已启用模块、正在使用的 .ini 文件等大量环境信息。查看完后必须删除 phpinfo.php，或把它移出 Web 目录；公开暴露这些敏感环境信息存在安全风险。

排查同步问题

如果需要从同一台服务器直接上传文件，请使用 cadaver 等 WebDAV 命令行客户端，通过 WebDAV 接口上传：

https://example.com/nextcloud/remote.php/dav

常见问题和错误消息

• SQLSTATE[HY000] [1040] Too many connections：需要提高数据库的连接数上限，详情查阅所用数据库的手册。
• SQLSTATE[HY000]: General error: 5 database is locked：SQLite 无法处理大量并发请求，可以考虑按数据库类型转换指南迁移到其他数据库。
• SQLSTATE[HY000]: General error: 2006 MySQL server has gone away：参阅数据库配置中的故障排查。
• SQLSTATE[HY000] [2002] No such file or directory：可能无法访问数据目录中的 SQLite 数据库文件 data/nextcloud.db。检查文件和目录是否存在，以及访问权限。如果使用 MySQL，则检查并启动数据库服务。
• Connection closed / Operation cancelled：可能与 Apache 的 KeepAlive 配置不正确有关。确认 KeepAlive 为 On，也可尝试提高 KeepAliveTimeout 和 MaxKeepAliveRequests 的限制。
• No basic authentication headers were found：此错误会出现在 Nextcloud 日志中。某些 Apache 模块，如 mod_fastcgi、mod_fcgid、mod_proxy_fcgi，可能没有把所需认证头传递给 PHP，导致 WebDAV、CalDAV 或 CardDAV 客户端无法登录。

排查 Web 服务器和 PHP 问题

日志文件

遇到问题，第一步应查看 PHP、Web 服务器和 Nextcloud 的日志。以下路径以默认 Debian 安装、Apache2 配合 mod_php 为例；其他 Web 服务器、发行版或操作系统可能不同。

• Apache2 日志：/var/log/apache2/error.log。
• PHP 日志可在 /etc/php/8.3/apache2/php.ini 中配置。把 log_errors 设为 On，用 error_log 指定日志路径；修改后需要重启 Web 服务器。
• Nextcloud 日志位于数据目录，例如 /var/www/nextcloud/data/nextcloud.log。

Web 服务器和 PHP 模块

Nextcloud 不支持 Lighttpd，部分功能可能完全不能在其上运行。有些 Web 服务器或 PHP 模块已知可能导致上传、下载等异常。以下是原文提供的初步清单：

• Apache：mod_pagespeed、mod_evasive、mod_security、mod_reqtimeout、mod_deflate、mod_spdy、mod_dav，以及配置错误时会造成下载异常的 mod_xsendfile / X-Sendfile。
• Nginx：ngx_pagespeed、HttpDavModule，以及配置错误时会造成下载异常的 X-Sendfile。
• PHP：Tideways、eAccelerator。

排查 WebDAV

Nextcloud 使用 SabreDAV。SabreDAV 文档提供了详尽的说明，可查阅常见问题、Web 服务器、处理大文件、零字节文件、客户端，以及 Finder 这个 macOS 内置 WebDAV 客户端等主题。Web 服务器说明不推荐 Lighttpd；大文件说明涉及旧版 SabreDAV 中的 PHP 缺陷及 mod_security 问题；客户端说明列出多种客户端的已知问题。

此外，ownCloud 论坛中维护的 WebDAV 常见问题讨论，也提供了额外的故障排查信息。

服务发现

一些客户端，特别是 iOS/macOS 客户端，即使明确配置了同步 URL，也可能无法找到正确地址。要与 Nextcloud 一起使用 CalDAV、CardDAV 或其他依赖服务发现的客户端，以下地址必须正确工作：

https://example.com/.well-known/carddav
https://example.com/.well-known/caldav

它们需要把客户端重定向到正确端点。如果 Nextcloud 安装在 Web 服务器的 DocumentRoot，CardDAV 和 CalDAV 端点为 https://example.com/remote.php/dav；如果安装在 nextcloud 等子目录，则为 https://example.com/nextcloud/remote.php/dav。

Debian/Ubuntu 上，Apache 的 DocumentRoot 默认是 /var/www/html；其他发行版可能不同，请相应调整示例路径。

对于安装在根目录的第一种情况，Nextcloud 随附的 .htaccess 通常会完成重定向。必须确认 Apache 正在使用此文件，安装了 mod_rewrite，并在 apache2.conf 或虚拟主机配置中设置了 AllowOverride All。使用 Nginx 时，参阅Nginx 配置。

对于安装在子目录的第二种情况，向 /etc/apache2/apache2.conf 加入以下配置。实际根目录若不同，请替换 /var/www/html：

<Directory /var/www/html>
    AllowOverride FileInfo
</Directory>

AllowOverride FileInfo 足以处理服务发现所用的重写指令。如果已为此目录设置 AllowOverride All，则不必修改。随后，在 Web 根目录中的 .htaccess 加入：

<IfModule mod_rewrite.c>
  RewriteEngine on
  RewriteRule ^\.well-known/carddav /nextcloud/remote.php/dav [R=301,L]
  RewriteRule ^\.well-known/caldav /nextcloud/remote.php/dav [R=301,L]
  RewriteRule ^\.well-known/webfinger /nextcloud/index.php/.well-known/webfinger [R=301,L]
  RewriteRule ^\.well-known/nodeinfo /nextcloud/index.php/.well-known/nodeinfo [R=301,L]
</IfModule>

务必把 /nextcloud 改为实际安装的子目录。如果把这些指令直接放入 Apache 主配置文件而非 .htaccess，每个 RewriteRule 的第一个参数需要增加前导斜杠，例如 ^/\.well-known/carddav。Apache 会在处理 .htaccess 时去掉前导斜杠，但处理主配置时不会这样做。

Nginx 需要按官方配置正确设置 location = /.well-known/carddav { 和 location = /.well-known/caldav {，必要时适配子目录。

完成后，客户端中的 URL 可以只填 https://example.com，不再填 https://example.com/nextcloud/remote.php/dav/principals/username 这类完整地址。SabreDAV 网站还介绍了其他处理方法。

排查共享问题

域名变更后，用户的 Federated Cloud ID 没有更新

1. 执行下面的数据库查询：

DELETE FROM oc_cards_properties WHERE name = 'CLOUD' AND addressbookid = (select id from oc_addressbooks where principaluri = 'principals/system/system' AND uri = 'system');

2. 运行以下 occ 命令：

occ dav:sync-system-addressbook

occ federation:sync-addressbooks

排查联系人和日历

参阅群件章节的故障排查文章。

排查数据目录

移动数据目录或更改 datadirectory 路径

对于本地存储，Nextcloud 用磁盘上的绝对路径识别存储。理想情况下，部署后不应更改数据目录位置。如果是新安装，可以在投入生产前，考虑直接以期望的目录重新安装。

安全移动数据目录时，原文推荐：

1. 确认没有 cron 任务正在运行；使用系统 cron 时，先禁用 Nextcloud 的 crontab 条目。
2. 停止 Web 服务器和应用服务器。
3. 把 /data 移到新位置，务必包含 .ncdata 等隐藏文件。
4. 创建从旧位置指向新位置的符号链接。
5. 确认权限仍然正确，包括父目录权限。
6. 重新启动 Web 服务器和应用服务器。
7. 如果使用系统 cron，重新启用 Nextcloud 的 crontab 条目。

可能需要配置 Web 服务器，使其支持符号链接。

不使用符号链接也可以移动数据目录，但需要手工修改内部 oc_storages 数据表：

1. 确认没有 cron 任务正在运行；使用系统 cron 时，禁用 Nextcloud 的 crontab 条目。
2. 停止 Web 服务器和应用服务器。
3. 把 /data 移到新位置，包含隐藏文件。
4. 修改 config.php 中的 datadirectory 值。
5. 在 oc_storages 中，找到 id 以 local::/old-data-dir/ 开头的记录，只更新其中的路径部分，例如改为 local::/new-data-dir/。
6. 确认权限正确，包括父目录权限。
7. 重启 Web 服务器和应用服务器。
8. 重新启用 Nextcloud 的系统 crontab 条目。

排查配额和容量问题

Web 界面或 occ user:info $userId 显示的已用空间，有时与 data/$userId/files 中实际存储的数据不一致。这里的已用空间不计入元数据、文件版本、回收站和加密密钥；详见存储配额文档。

以下命令可以帮助修正指定用户的容量和配额信息：

sudo -E -u www-data php occ files:scan -vvv <user-id>

如果实例以前启用过加密、后来又关闭，数据库中的部分容量值可能没有在解密后正确重置。备份数据库后，可执行下面的 SQL 重置这些值：

UPDATE oc_filecache SET unencrypted_size=0 WHERE encrypted=0;

排查加密文件

参阅服务器端加密章节中的故障排查部分。

合理使用政策

Nextcloud 是开源软件，可以免费部署在自己的服务器或服务提供商处。原文建议超过 500 名用户的实例使用 Nextcloud Enterprise。在这一规模下，服务器损坏或数据泄露会带来严重后果：故障可能让 500 人无法工作，泄露也会危及大量用户的数据，因此服务器应被视为关键业务系统。

Nextcloud Enterprise 为专业组织预先配置并优化，提供支持、安全和扩展能力、合规专业知识，以及运行 Nextcloud 的经验，帮助用户和管理员获得更好的使用体验；这也减轻了家庭用户论坛处理大规模部署特有问题的负担。

Nextcloud 为服务器稳定运行提供通知、应用商店等基础设施。原文说明，为防止没有提供相应财务支持的大型实例过度使用资源，这些组件设有限制，不能用于超过 500 名用户的实例。

Nextcloud 认为拥有数百名用户的组织应获得官方支持；对于预算有限的非营利组织、小型学校等，提供特别方案。详情应通过官方联系表或由系统管理员咨询。此处保留原文政策说明，具体服务条件以官方为准。

其他问题

某些服务，如 Cloudflare，会压缩 JavaScript，并按需加载。遇到登录按钮不能工作、无法创建用户等问题时，应先停用这类服务来排查。