Nextcloud Docker镜像文档

重要说明

⚠️⚠️⚠️ 此镜像由社区志愿者维护，专为专家使用设计。如需快速轻松部署并支持全套Nextcloud Hub功能，请使用由Nextcloud GmbH维护的Nextcloud All-in-One docker容器。

快速参考

• 维护者：
  Nextcloud社区

• 获取帮助：
  Docker社区Slack、Server Fault、Unix & Linux 或 Stack Overflow

支持的标签及对应Dockerfile链接

• 30.0.16-apache, 30.0-apache, 30-apache, 30.0.16, 30.0, 30
• 30.0.16-fpm, 30.0-fpm, 30-fpm
• 30.0.16-fpm-alpine, 30.0-fpm-alpine, 30-fpm-alpine
• 31.0.9-apache, 31.0-apache, 31-apache, stable-apache, production-apache, 31.0.9, 31.0, 31, stable, production
• 31.0.9-fpm, 31.0-fpm, 31-fpm, stable-fpm, production-fpm
• 31.0.9-fpm-alpine, 31.0-fpm-alpine, 31-fpm-alpine, stable-fpm-alpine, production-fpm-alpine
• 32.0.0-apache, 32.0-apache, 32-apache, apache, 32.0.0, 32.0, 32, latest
• 32.0.0-fpm, 32.0-fpm, 32-fpm, fpm
• 32.0.0-fpm-alpine, 32.0-fpm-alpine, 32-fpm-alpine, fpm-alpine

快速参考（续）

• 问题反馈地址：
  [***]

• 支持的架构：(更多信息)
  amd64, arm32v5, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x

• 镜像 artifact 详情：
  repo-info 仓库的 repos/nextcloud/ 目录（历史记录）
  （镜像元数据、传输大小等）

• 镜像更新：
  official-images 仓库的 library/nextcloud 标签
  official-images 仓库的 library/nextcloud 文件（历史记录）

• 本文档来源：
  docs 仓库的 nextcloud/ 目录（历史记录）

什么是 Nextcloud？

Nextcloud 是一个安全的数据存储解决方案，允许您在自己的条件下从任何设备访问和共享文件、日历、联系人、邮件等数据。

Nextcloud.com

此 Docker 微服务镜像由 Nextcloud 社区开发和维护。Nextcloud GmbH 不为此 Docker 镜像提供支持。如果您需要专业支持，可以成为企业客户或使用 AIO。

如何使用此镜像

该镜像设计用于微服务环境，提供两种版本供选择：

• apache 标签：包含完整的 Nextcloud 安装和 Apache Web 服务器，易于使用，可快速启动，是 latest 标签和未指定后缀的版本标签的默认选择。
• fpm 标签：基于 php-fpm 镜像，运行 FastCGI 进程，需配合能将 HTTP 请求代理到 FastCGI 端口的 Web 服务器使用。

使用 apache 镜像

apache 镜像包含 Web 服务器并暴露 80 端口。启动容器命令如下：

$ docker run -d -p 8080:80 amd64/nextcloud

现在可通过 http://localhost:8080/ 从主机访问 Nextcloud。

使用 fpm 镜像

fpm 镜像需配合 Web 服务器（如 nginx）使用，该 Web 服务器需能将 HTTP 请求代理到容器的 FastCGI 端口（9000）。启动 fpm 容器命令如下：

$ docker run -d amd64/nextcloud:fpm

由于 FastCGI 进程无法提供静态文件（样式表、图片等），Web 服务器需能访问这些文件，可通过 volumes-from 选项实现（详见 Docker Compose 部分）。

使用外部数据库

默认情况下，容器使用 SQLite 存储数据，但 Nextcloud 安装向导（首次运行时出现）允许连接到现有 MySQL/MariaDB 或 PostgreSQL 数据库。您也可以链接数据库容器（如 --link my-mysql:mysql），然后在安装向导中使用 mysql 作为数据库主机。更多信息见 Docker Compose 部分。

持久化数据

Nextcloud 安装和所有数据库之外的数据（如文件上传等）存储在未命名 Docker 卷 /var/www/html 中。Docker 守护进程会将数据存储在 /var/lib/docker/volumes/... 目录下，即使容器崩溃、停止或删除，数据也会保留。

为便于升级和备份，建议使用命名 Docker 卷或挂载主机目录。需为数据库容器和 Nextcloud 分别配置卷：

• Nextcloud：/var/www/html/ 目录（所有 Nextcloud 数据存放位置）

$ docker run -d \
-v nextcloud:/var/www/html \
amd64/nextcloud

• 数据库：
  • MySQL/MariaDB：/var/lib/mysql
  • PostgreSQL：/var/lib/postgresql/data

$ docker run -d \
-v db:/var/lib/mysql \
mariadb:10.6

额外卷

如需精细控制文件访问，可挂载以下额外卷（均为 /var/www/html/ 的子目录）：

• /var/www/html/custom_apps：已安装/修改的应用
• /var/www/html/config：本地配置
• /var/www/html/data：Nextcloud 实际数据
• /var/www/html/themes/<YOUR_CUSTOM_THEME>：自定义主题

使用命名卷挂载所有这些目录的示例：

$ docker run -d \
-v nextcloud:/var/www/html \
-v apps:/var/www/html/custom_apps \
-v config:/var/www/html/config \
-v data:/var/www/html/data \
-v theme:/var/www/html/themes/<YOUR_CUSTOM_THEME> \
amd64/nextcloud

自定义卷注意事项

在 /var/www/html 下挂载自定义卷时，需注意：

• 确保 upgrade.exclude 包含安装和升级期间需保留的文件和文件夹；或
• 将存储卷挂载到 /var/www/html 之外的位置。

注意：/var/www/html 目录中的数据在安装和升级期间可能会被覆盖/删除，除非在 upgrade.exclude 中列出。官方支持的额外卷已包含在内，自定义卷需自行添加。建议将自定义存储卷挂载到 /var/www/html 之外，并尽可能设为只读。

使用 Nextcloud 命令行界面

要使用 Nextcloud 命令行界面（occ 命令）：

$ docker exec --user www-data CONTAINER_ID php occ

对于 docker compose：

$ docker compose exec --user www-data app php occ

通过环境变量自动配置

Nextcloud 镜像支持通过环境变量自动配置，可预配置安装页面上的所有选项。启用自动配置需通过以下环境变量指定数据库连接，且必须为所选数据库类型指定所有变量，否则默认使用 SQLite。仅支持一种数据库类型！

SQLite

• SQLITE_DATABASE：SQLite 数据库名称

MySQL/MariaDB

• MYSQL_DATABASE：MySQL/MariaDB 数据库名称
• MYSQL_USER：MySQL/MariaDB 数据库用户名
• MYSQL_PASSWORD：MySQL/MariaDB 数据库用户密码
• MYSQL_HOST：MySQL/MariaDB 数据库服务器主机名

PostgreSQL

• POSTGRES_DB：PostgreSQL 数据库名称
• POSTGRES_USER：PostgreSQL 数据库用户名
• POSTGRES_PASSWORD：PostgreSQL 数据库用户密码
• POSTGRES_HOST：PostgreSQL 数据库服务器主机名

除数据库配置外，若指定了完整的数据库环境变量，还可通过以下变量配置 Nextcloud 管理员用户（需同时设置）：

• NEXTCLOUD_ADMIN_USER：Nextcloud 管理员用户名
• NEXTCLOUD_ADMIN_PASSWORD：Nextcloud 管理员密码

可通过以下变量设置数据目录（默认值为 /var/www/html/data）：

• NEXTCLOUD_DATA_DIR：Nextcloud 存储用户文件的数据目录路径

还可通过环境变量设置一个或多个受信任域，它们将在安装后添加到配置中：

• NEXTCLOUD_TRUSTED_DOMAINS：可选，空格分隔的域名列表

安装和更新脚本仅在使用默认命令（apache-foreground 或 php-fpm）时触发。若使用自定义命令，需通过以下变量启用安装/更新：

• NEXTCLOUD_UPDATE：默认 0，设为非 0 值启用

为确保容器更新后 htaccess 配置保持最新（尤其在多 swarm 节点环境中，配置不一致会导致服务器不可用）：

• NEXTCLOUD_INIT_HTACCESS：默认未设置，设为 true 可在容器初始化后运行 occ maintenance:update:htaccess

如需使用 Redis，需在部署中创建单独的 Redis 容器，并通过以下参数告知 Nextcloud：

• REDIS_HOST：默认未设置，Redis 容器名称
• REDIS_HOST_PORT：默认 6379，Redis 端口（仅用于非标准端口的外部 Redis 服务器）
• REDIS_HOST_PASSWORD：默认未设置，Redis 密码

建议使用 Redis 以防止文件锁定问题，详见示例。

要配置 Nextcloud 使用外部 SMTP 服务器，需提供以下连接详情：

• SMTP_HOST：默认未设置，SMTP 服务器主机名
• SMTP_SECURE：默认空，设为 ssl 使用 SSL 或 tls 使用 STARTTLS
• SMTP_PORT：默认 465（SSL）或 25（非安全连接），SMTP 端口
• SMTP_AUTHTYPE：默认 LOGIN，认证方法（无需认证时设为 PLAIN）
• SMTP_NAME：默认空，认证用户名
• SMTP_PASSWORD：默认空，认证密码
• MAIL_FROM_ADDRESS：默认未设置，邮件发件人本地部分
• MAIL_DOMAIN：默认未设置，邮件域名

至少需设置 SMTP_HOST、MAIL_FROM_ADDRESS 和 MAIL_DOMAIN。更多信息见 Nextcloud 文档。

通过 hook 文件夹自动配置

提供 5 个 hook 文件夹，可在特定阶段执行脚本：

• pre-installation：Nextcloud 安装/初始化前执行
• post-installation：Nextcloud 安装/初始化后执行
• pre-upgrade：Nextcloud 升级前执行
• post-upgrade：Nextcloud 升级后执行
• before-starting：Nextcloud 启动前执行

使用方法：将脚本添加到容器内 /docker-entrypoint-hooks.d 目录下的对应子文件夹，或通过卷挂载主机脚本：

services:
  app:
    image: amd64/nextcloud:stable
    volumes:
      - ./app-hooks/pre-installation:/docker-entrypoint-hooks.d/pre-installation
      - ./app-hooks/post-installation:/docker-entrypoint-hooks.d/post-installation
      - ./app-hooks/pre-upgrade:/docker-entrypoint-hooks.d/pre-upgrade
      - ./app-hooks/post-upgrade:/docker-entrypoint-hooks.d/post-upgrade
      - ./app-hooks/before-starting:/docker-entrypoint-hooks.d/before-starting

注意：仅位于 hook 文件夹（非子目录）、以 .sh 结尾且可执行的脚本会被执行。

在反向代理后使用 apache 镜像并自动配置服务器主机和协议

默认情况下，apache 镜像会将来自 10.0.0.0/8、172.16.0.0/12 或 192.168.0.0/16 网段代理的请求的远程地址替换为 X-Real-IP。