Nextcloud 服务器端加密指南

概述

Nextcloud 提供多种加密方法，在不同系统层面保护数据，应对不同安全需求。本文重点介绍内置服务器端加密（Server-Side Encryption，SSE）。

注意：加密与风险管理复杂且有很多细节。除非已经是专家，否则建议咨询专业人士或深入研究，确认方案针对实际威胁。Nextcloud 博客 Nextcloud 中的数据加密方法 提供了常见方法的总体介绍。

定义

• SSE：由 Nextcloud 服务器执行，保护本地或外部存储中的静态文件，密钥保存在服务器。
• 端到端加密 E2EE：桌面或移动客户端上传前加密，只有客户端可解密，服务器管理员与外部存储商都无法读取。
• 主密钥：服务器控制的中央密钥，用于加密所有文件。
• 用户密钥：每个用户拥有自己的密钥，由其密码保护，用于加密自己的文件。
• 恢复密钥：管理员定义的密钥，在用户丢失密码时恢复文件。
• 磁盘／块设备加密：在硬件或文件系统层面对存储设备上的全部数据加密，例如 Linux 的 LUKS。只有用正确密钥或密码解锁后，数据才可访问。

加密方式比较

方式	加密位置	谁能解密	防护对象
SSE 主密钥	服务器	管理员与用户	外部存储提供商
SSE 用户密钥	服务器	用户，以及恶意管理员	外部存储提供商
SSE 用户密钥加恢复密钥	服务器	用户，以及持恢复密钥的管理员	外部存储提供商
E2EE	客户端	仅用户	管理员、外部存储提供商
磁盘／块加密	服务器	操作系统管理员	物理篡改、盗窃

要点与限制

• 这些方式不可互相替代，各自针对特定风险。
• SSE 主要用于保护第三方外部存储中的文件。
• 不允许服务器管理员访问数据时，应使用 E2EE。
• SSE 只加密文件内容，不加密文件名或目录结构。
• SSE 无法抵御已经受侵的 Nextcloud 服务器或恶意管理员；这一威胁应采用 E2EE。
• 不能通过 Web 界面撤销 SSE。
• 排查 SSE 通常需要 occ 命令访问权限，启用前务必确认具备。
• 丢失加密密钥或实例 secret 会导致永久数据丢失。
• 配额按未加密文件大小计算。SSE 加密后文件可能增大约 1%；Nextcloud 25 之前约为 35%。
• HTTPS 的 TLS 在文件加密前终止，因此从 TLS 解密到 SSE 加密之间，文件可能以明文存在于内存中。
• 外部存储文件经过 SSE 加密后，不能直接通过存储商分享，只能通过 Nextcloud 分享，因为解密密钥从不离开 Nextcloud 服务器。
• 本地存储可能更适合操作系统提供的磁盘／块设备加密，例如 LUKS，以应对服务器被盗等 SSE 不针对的风险。

警告：SSE 只加密内容，不隐藏文件名和目录结构。不要将 Nextcloud SSE 与同样受支持的 S3 SSE-C 混淆。

从 9.0.0 起，新加密文件支持认证加密。技术细节见 相关报告。

提示：为了获得最强保护，外部存储可设置“Check for changes: Never”，让 Nextcloud 忽略未通过自身添加的新文件，阻止外部存储管理员擅自添加内容。但如果存储确实存在合法的外部变更，不要这样配置。

启用前的准备

1. 完整阅读本指南并理解风险。
2. 将实例配置与全部加密密钥备份到安全位置。
3. 选择适合的密钥管理模式。

密钥管理模式

主密钥，默认模式

• 所有文件由服务器控制的中央密钥加密。
• 管理员能解密任意用户文件。
• 此模式不提供恢复密钥。用户忘记密码后，文件仍可访问，因为加密依赖主密钥，而不是用户密码。
• 推荐大多数部署使用。

用户密钥

• 每个用户的文件由其密码保护的密钥加密。
• 没有用户密码时，管理员不能轻易解密，除非设置了恢复密钥。
• 用户忘记密码又没有恢复密钥，文件就会丢失。
• 并非兼容所有认证方式，例如应用密码或单点登录；仅建议为兼容旧部署保留。

信任服务器管理员时，选择主密钥；需要防止管理员读取文件时，使用 E2EE。用户密钥对恶意管理员提供一定阻碍，但存在限制。

选择用户密钥模式时，在启用加密前运行：

occ encryption:disable-master-key

逐步启用加密

1. 进入管理员页面的“Server-side encryption”。
2. 勾选“Enable server-side encryption”。
3. 此时显示“No encryption module loaded”。
4. 进入 Apps，启用“Nextcloud Default Encryption Module”。
5. 返回管理员页面，模块会出现并自动选中。
6. 退出并重新登录，初始化加密密钥。
7. 可选：取消加密 home storage，保持本地文件不加密。

备份

密钥保存在：

• data/<user>/files_encryption：用户密钥。
• data/files_encryption：系统级及外部存储密钥。

加密外部挂载与团队文件夹

管理员与用户都可以加密外部挂载点，在各外部存储的挂载配置中设置加密选项，详见外部存储的 Mount Options。

团队文件夹加密使用：

occ config:app:set groupfolders enable_encryption --value=true

注意：只会加密团队文件夹中新建或更新的文件。

通过 occ 管理加密

命令	作用
occ encryption:status	显示加密状态和模块
occ encryption:enable	启用 SSE
occ encryption:list-modules	列出模块
occ encryption:set-default-module [Module ID]	选择默认模块
occ encryption:encrypt-all	加密所有用户文件
occ encryption:decrypt-all [user]	解密全部或某一用户文件
occ encryption:show-key-storage-root	显示密钥位置
occ encryption:change-key-storage-root [dir]	移动密钥目录
occ encryption:enable-master-key	启用主密钥
occ encryption:disable-master-key	禁用主密钥
occ encryption:fix-encrypted-version	修复签名错误
occ encryption:fix-key-location [user]	修复找不到密钥的问题

更多示例见 occ 参考指南的加密命令部分。以下是在 Ubuntu 上移动密钥目录的示例：

cd /your/nextcloud/data
mkdir keys
chown -R root:www-data keys
chmod -R 0770 keys
occ encryption:change-key-storage-root keys

加密全部文件

启用 SSE 后，默认只加密新增或修改的文件。要加密所有用户的全部文件：

occ encryption:encrypt-all

执行前务必备份。该命令为每个用户创建密钥对并加密文件，显示进度直到完成。过程中不要让用户访问文件。

解密文件与禁用加密

只能通过 occ 完成。首先解密全部文件：

occ encryption:decrypt-all

执行前备份。服务器会进入维护模式；中断后重新运行，直到完成。如果仍有文件加密，先解决相关问题，再运行一次。

警告：未解密全部文件就禁用加密，会导致不可预期的错误。

也可以只解密指定用户：

occ encryption:decrypt-all <user-id>

哪些数据不加密

SSE 仅加密文件内容。以下不加密：文件名和目录结构、已存在的回收站文件、已存在的历史版本、图片缩略图、图片预览、全文搜索索引，以及非文件型应用数据，例如 Deck、Tables。

用户密钥：分享与恢复

分享加密文件

启用用户密钥后，用户必须退出再登录以生成密钥。看到“Encryption App is enabled but your keys are not initialized…”时，同样需要重新登录。

已有分享可能需要重新建立。个人分享先取消再分享；群组分享中，有人无法访问时，先单独分享给这些用户，再移除个人分享。

启用恢复密钥

恢复密钥只适用于用户密钥模式，不适用于默认主密钥模式。

用户密钥模式下，丢失 Nextcloud 密码就会失去文件访问权限；除非事先启用恢复密钥，否则无法恢复。

管理员在 Encryption 设置中配置恢复密钥密码。用户还必须在个人设置中启用密码恢复，恢复密钥才对该用户生效。之后，管理员就能用恢复密钥重置密码、恢复文件。

警告：恢复可能很慢并占用大量资源，特别是加密数据较多时。在生产中依赖它之前，应先试验恢复流程。

LDAP 与外部用户后端

使用 LDAP／Samba 且在后端修改密码时，用户下次登录需要同时提供新旧密码。如果已启用恢复密钥，管理员可通过 Nextcloud 重置密码并通知用户。

故障排查

为什么设置中没有恢复密钥

恢复密钥只适用于用户密钥模式。从 Nextcloud 13 起，默认使用系统级主密钥。主密钥模式无需恢复密钥：管理员重置密码后，文件仍可访问，所以管理页面不显示相关选项。

默认且推荐的主密钥模式不需要恢复密钥；用户密钥模式主要为旧部署兼容而保留。设计背景见 GitHub Issue #8283。

Invalid private key for encryption app

请参阅原文链接的 GitHub Issue #8546 和临时解决办法。

Bad signature 错误

少数情况下，加密文件无法下载，返回 500。若日志出现 Bad Signature，运行：

occ encryption:fix-encrypted-version userId --path=/path/to/broken/file.txt

替换 userId 与路径。命令会尝试解密相关文件，并自动修复签名错误。

找不到加密密钥

日志提示找不到密钥时，可以在数据目录搜索与文件同名的目录。例如 example.md 无法解密：

find path/to/datadir -name example.md -type d

检查位于 files_encryption 下的结果。如果密钥目录位置错误，移到正确位置再试。data/files_encryption 保存群组文件夹和系统级外部存储密钥；data/$userid/files_encryption 保存用户存储的密钥。

注意：曾禁用加密却未运行 decrypt-all，随后又移动文件，就可能造成文件移动而密钥未移动。

外部存储或群组文件夹找不到密钥

运行：

sudo -E -u www-data php occ encryption:fix-key-location <user-id>

它尝试恢复没有正确移动的密钥。仍无法解决时，使用上一节的手动处理方法。

已有两个相关问题：在加密与未加密存储之间移动文件时，没有同步移动密钥；向系统级外部存储写入文件时，密钥保存到了错误位置。

进一步阅读

• occ 命令参考：加密。
• Nextcloud 如何使用加密保护数据。
• 认证加密的技术影响。
• Nextcloud SSE 实现细节。
• Nextcloud SSE 与 E2EE 恢复工具。
• 使用 E2EE 所需的 Nextcloud E2EE Server API 应用。

---

原文：Server-side Encryption。作者／维护者：Nextcloud 文档贡献者。本文为原文的中文译文；代码保留原文内容。