企业官网建设流程全解析

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

本文面向希望脱离 Nextcloud AIO Mastercontainer 管理界面、直接用docker compose掌控全部容器配置的运维人员，讲解基于仓库 manual-install 目录的完整安装、配置、按需启用可选服务、更新与备份实践。读完本文，你将掌握手动安装模式的利弊边界、sample.conf全部环境变量的含义与取值、Docker profiles 的用法，以及官方推荐的安全更新流程。

手动安装是什么

Nextcloud All-in-One（AIO）的默认安装方式是由一个 Mastercontainer 负责编排、监控和更新所有子容器，用户通过 Web 界面完成安装与维护。而仓库 manual-install/readme.md 提供了另一种官方支持的部署路径：把 AIO 面向各功能构建的容器镜像直接用 docker-compose 跑起来，无需任何容器持有 Docker socket 访问权，也不依赖 Mastercontainer。

这种方式下，你需要自己维护两个文件：

• manual-install/sample.conf：环境变量定义文件，安装时需复制为.env；
• manual-install/latest.yml：完整的 Compose 服务定义，安装时需复制为compose.yaml。

这两个文件不是手写的，而是由 manual-install/update-yaml.sh 从 AIO 界面程序使用的容器定义源 php/containers.json 自动生成（脚本会删除container_name、internal_port、backup_volumes、nextcloud_exec_commands等仅 Mastercontainer 需要的字段，并为镜像补上:latest标签）。也就是说，手动安装用的镜像与默认 AIO 安装完全同源，只是编排方式从"Mastercontainer 自动编排"变成了"你自己执行 docker compose"。

优点与代价：先看清楚再决定

优点

• 无需 Docker socket 访问：默认 AIO 安装中 Mastercontainer 需要挂载 Docker socket 才能创建、更新其他容器；手动安装模式下没有任何容器需要访问 Docker socket，安全边界更清晰。
• 所有值都可自行修改：环境变量、端口、卷、挂载点全部由你掌控，不必受 Mastercontainer 内部逻辑约束。
• 支持 Docker Swarm：Compose 文件可以被 Swarm 编排，这是默认安装方式做不到的。
• 可在无法访问 ghcr.io 的环境运行：当你的环境无法直接拉取 GitHub Container Registry 镜像时，可以通过手动方式结合镜像代理等方案完成部署。

代价：失去的能力清单

选择手动安装意味着放弃以下由 Mastercontainer 提供的自动化能力，需要逐条评估后再做决定：

• 失去 AIO 界面：不再有:8080/:8443的图形化管理面板；
• 失去更新通知与自动更新：容器是否过期、是否有新版本，都需要自己跟踪；
• 失去全部备份与恢复功能：默认安装内置的 BorgBackup 每日备份、从备份归档恢复实例等能力均不可用（仓库 php/src/Cron 下的CreateBackup.php、CheckBackup.php等备份链路都依赖 Mastercontainer 调度）；
• 失去内置的 Docker Socket Proxy 与 HaRP 容器：这两个容器分别位于 Containers/docker-socket-proxy 与 Containers/harp，是 Nextcloud App API 正常工作所必需的组件；
• 失去所有社区容器（community containers）：社区容器（见 community-containers 目录，如 vaultwarden、pi-hole、jellyfin 等）依赖 AIO 界面的"附加容器"机制加载，手动模式无法使用；
• 需要你清楚自己在做什么：尤其是修改compose.yaml时，任何错误都可能影响整个栈；
• 更新必须严格遵循下文规定的更新流程，不能随手docker compose pull了事；
• 其他未列出的隐性代价。

安装前置准备

• 安装 Docker 与 docker-compose v2（Compose 插件）；
• 准备一个域名（对应NC_DOMAIN），并确保其 DNS 可解析到本机（AIO 默认通过 Apache 容器内置的 Caddy 自动申请 Let's Encrypt 证书，需要公网可达）；
• 若需要 IPv6 支持，先参照 docker-ipv6-support.md 完成 Docker 侧配置（详见下文"更新与 IPv6"小节）。

一步步完成安装

第 1 步：克隆仓库并进入 manual-install 目录

git clone https://github.com/nextcloud/all-in-one.git cd all-in-one/manual-install

第 2 步：从 sample.conf 生成 .env 并填写

cp sample.conf .env nano .env

编辑原则：所有标注# TODO!的值都必须修改。sample.conf的结构分三块：

1. 必须修改的密码与基础信息（带# TODO!注释）；
2. 可选服务启用开关（*_ENABLED="no"，按需改为"yes"，注意必须带引号）；
3. 可选的调优参数（带默认值与注释，按需调整）。

⚠️密码字符警告（原文档强调）：不要在密码中使用@和:两个符号。它们被用来拼接数据库连接字符串，使用这两个符号会导致连接串解析错误，引发难以排查的问题。例如DATABASE_PASSWORD最终会以POSTGRES_PASSWORD=${DATABASE_PASSWORD}的形式传入数据库容器（见 manual-install/latest.yml 中nextcloud-aio-database服务的定义）。

⚠️ 另一个重要提醒：latest.yml中未以变量形式暴露的值，官方不保证支持修改。也就是说，只有sample.conf里出现的变量才属于官方支持的定制面，直接改动 yaml 中硬编码的环境变量、镜像标签或卷名属于自担风险的操作。

第 3 步：生成 compose.yaml

cp latest.yml compose.yaml

第 4 步：启动

sudo docker compose up

首次启动会自动完成 Nextcloud 初始化（latest.yml中nextcloud-aio-nextcloud服务通过ADMIN_USER=admin与ADMIN_PASSWORD=${NEXTCLOUD_PASSWORD}创建初始管理员），随后即可通过https://你的域名访问。

sample.conf 环境变量全解析

以下按sample.conf的实际结构分组说明，默认值与取值范围均以仓库文件为准。

必须填写（# TODO!）

可选服务启用开关

以下变量统一为"no"默认值，改为"yes"（必须带引号）后，会同时完成两件事：启用对应的 Compose profile 服务，并在 Nextcloud 侧自动开启该功能：

• CLAMAV_ENABLED：启用 ClamAV 病毒扫描（latest.yml中nextcloud-aio-clamav服务同时挂载nextcloud_aio_clamav卷保存病毒库）；
• COLLABORA_ENABLED：启用 Collabora Online（Nextcloud Office）；
• EUROOFFICE_ENABLED：启用 EuroOffice；
• FULLTEXTSEARCH_ENABLED：启用全文搜索；
• HARP_ENABLED：启用 HaRP（App API 所需，同时需要 Docker socket）；
• IMAGINARY_ENABLED：启用 Imaginary（为 heic、heif、pdf、svg、tiff、webp 等格式生成预览）；
• ONLYOFFICE_ENABLED：启用 OnlyOffice；
• TALK_ENABLED：启用 Talk（高性能后端与 TURN）；
• TALK_RECORDING_ENABLED：启用 Talk 录制；
• WHITEBOARD_ENABLED：启用白板。

以CLAMAV_ENABLED为例，它在latest.yml中同时出现在nextcloud-aio-clamav服务的profiles关联之外，还以环境变量形式传给nextcloud-aio-nextcloud，Nextcloud 容器据此自动开启 Antivirus 应用配置——这就是注释"enables the option in Nextcloud automatically"的底层含义。

可调优参数

Docker profiles：按需启用可选服务

latest.yml的默认 profile 只提供最小必要服务：nextcloud、database（PostgreSQL）、redis与apache。这也是manual-install/readme.md明确说明的"minimum necessary services"。

其余服务都挂在不同 profile 下（见latest.yml中各服务段的profiles字段）：

用法示例——启用 Collabora：

sudo docker compose --profile collabora up

一次拉起完整的 all-in-one 全家桶（原文档给出的完整命令）：

sudo docker compose --profile collabora --profile talk --profile talk-recording --profile clamav --profile imaginary --profile fulltextsearch --profile whiteboard up

实践中应与sample.conf中对应的*_ENABLED="yes"配合：profile 决定容器是否启动，*_ENABLED决定 Nextcloud 是否在应用层启用该功能。例如启用 Collabora 需要同时满足COLLABORA_ENABLED="yes"与--profile collabora两者。

更新流程：必须严格遵循

原文档明确强调：AIO 容器可能在未来发生变化，每次升级都必须严格按以下步骤执行，跳过任何一步都可能造成配置漂移或数据损坏。

1. 若你之前的配置文件不叫.env（例如叫my.conf），先重命名：

   mv -vn my.conf .env

2. 停止所有正在运行的容器：

   sudo docker compose down

3. 备份所有重要文件与目录（数据库卷、Nextcloud 数据卷、.env、自定义后的compose.yaml）；
4. 若 Compose 文件仍叫docker-compose.yml，重命名为compose.yaml：

   mv -vn docker-compose.yml compose.yaml

5. 拉取仓库更新，并将你的compose.yaml与新版对齐：

   git pull diff compose.yaml latest.yml

   ⚠️IPv6 注意（自 AIO v5.1.0 起）：新版latest.yml默认启用 IPv6 网络。升级前请二选一：要么先按 docker-ipv6-support.md 的第 1、2 步在 Docker 侧启用 IPv6，再继续后续步骤；要么编辑compose.yaml，从网络定义中移除 IPv6 配置以保持现状。

6. 同样检查sample.conf是否有新增或重命名的变量，用diff对比后把变更同步进你的.env；
7. 拉取新镜像：

   sudo docker compose pull

8. 最后用新配置启动并完成容器更新：

   sudo docker compose up

备份与恢复 FAQ

问：手动安装模式下如何备份？

• 若.env中NEXTCLOUD_DATADIR保持默认值nextcloud_aio_nextcloud_data且未改动compose.yaml，则所有数据都存放在 Docker 卷中。Linux 默认路径为/var/lib/docker/volumes，直接备份该目录即可视为一份有效备份，出问题时也能据此恢复。
• 若把NEXTCLOUD_DATADIR改成了类似/mnt/ncdata的宿主机路径，那么 Nextcloud 数据会存放在该目录，这个位置也必须纳入备份。
• 对compose.yaml的任何修改同理——凡是偏离默认配置的部分（自定义卷、额外挂载、改动的环境变量），都要找到对应的宿主机位置单独备份。
• 此外.env与（修改过的）compose.yaml两个文件本身也必须在备份清单中：没有它们，卷里的数据无法被正确挂载与启动。

由于手动模式失去了内置 BorgBackup 备份，建议自行借助宿主机 cron 对上述位置做定时快照或异地同步。恢复时，只需在新环境上还原.env、compose.yaml与各卷/目录数据，再执行sudo docker compose up即可。

底层机制：update-yaml.sh 如何生成这些文件

理解文件来源有助于判断"什么能改、什么不能改"。仓库 php/containers.json 是 AIO 界面编排的真实容器定义源（aio_services_v1键下定义了从nextcloud-aio-apache到nextcloud-aio-whiteboard的全部内置服务）；PHP 侧由 php/src/ContainerDefinitionFetcher.php 读取并转成容器对象，供 Mastercontainer 使用。

而 manual-install/update-yaml.sh 则从同一份containers.json反向生成面向 docker compose 的产物，关键转换逻辑包括：

• 将aio_services_v1重命名为services键，把"destination"、"writeable"、"port_number"、"protocol"等 JSON 字段拼装成 compose 的卷挂载、端口映射语法；
• 剔除仅 Mastercontainer 需要的字段：internal_port、secrets、backup_volumes、nextcloud_exec_commands、networks、documentation等；
• 移除依赖 Docker socket 的服务：nextcloud-aio-watchtower、nextcloud-aio-domaincheck、nextcloud-aio-borgbackup、nextcloud-aio-docker-socket-proxy——这正是前文"失去 Docker Socket Proxy 与备份功能"的机制原因；
• 把 JSON 中形如%VARIABLE%的占位符统一改写为${VARIABLE}，同时从占位符反向提取变量名生成sample.conf，并补上默认值与注释；
• 最后为每个服务镜像追加:latest标签，生成 manual-install/latest.yml。

这意味着：只要升级到包含新update-yaml.sh的仓库版本，git pull后重新生成的latest.yml/sample.conf就会自动带上新增服务与变量——这也是更新流程第 5、6 步要求用diff对齐文件的原因。

补充实践建议

• 反向代理场景：若 Apache 前还有 Nginx、Caddy 或 Cloudflare Tunnel，参考 reverse-proxy.md，并将APACHE_IP_BINDING收紧为127.0.0.1、APACHE_PORT改为非 443 端口；
• Docker rootless 场景：手动安装同样适用，需将 socket 相关路径改为$XDG_RUNTIME_DIR/docker.sock，详见 docker-rootless.md；
• IPv6 场景：按 docker-ipv6-support.md 在daemon.json添加"default-network-opts": {"bridge":{"com.docker.network.enable_ipv6":"true"}}并重启 Docker，再确认内部nextcloud-aio网络的EnableIPv6为true；
• 多实例：手动安装天然支持在同一台主机上通过不同.env/compose.yaml目录部署多套实例，参照 multiple-instances.md 的端口隔离思路即可。

总结

手动安装是 Nextcloud AIO 官方提供的一条"去中心化"部署路径：它以同一套官方镜像为基础，把编排权完全交还给使用者，适合对容器配置有强定制需求、需要 Swarm 编排、或无法信任 Docker socket 挂载的环境。它的核心代价是失去 AIO 界面、自动更新、内置备份与社区容器生态。选择这条路线的运维者，务必把sample.conf的每个# TODO!变量填对、把latest.yml中未暴露为变量的值视为不可改、并在每次升级时严格执行本文的八步更新流程。

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