Skip to main content

Deploy and Migrate NextCloud AIO behind GFW | 在隔阂之后部署和迁移NextCloud-AIO实例

· 18 min read
Ferdinand Su
Ferdinand Su
PhD Student @ HIT-ICES, Founder & Manager @ HIT-ReFreSH, C# developer.

这是一篇双语博客，因为我同时想主要面向汉语使用者，因为实际上非常缺少使用汉语的NextCloudAIO部署相关文章。请原谅我我不想使用docusaurus的i18n，它太繁琐而不适用我的个人博客。 This is a bilingual blog post, as I primarily want to cater to Chinese-speaking users, given the significant lack of NextCloudAIO deployment articles in Chinese. Please forgive me for not using Docusaurus i18n, as it's too complicated for my personal blog needs. English translated by Claude

本文将会介绍我在Windows->Linux上部署和迁移NextCloudAIO，其中包含了不少过程中的难点（尤其是在GFW后无法直接访问ghcr的情况下），我首先在Windows上部署，然后从部署导出备份数据，最终在Ubuntu 24.04下重新部署，全程利用docker compose启动，以及caddy进行反代（我使用cloudflare解析自己的域名）。

This article will cover my experience deploying and migrating NextCloudAIO (https://github.com/nextcloud/all-in-one) from Windows to Linux, including several challenging aspects encountered during the process (especially accessing ghcr.io from behind the GFW). I firstly deployed on Windows, and then export backup data for redeployment on Ubuntu 24.04. Throughout the process, we'll be using Docker Compose for launching the services and Caddy for reverse proxying (with Cloudflare handling my domain name resolution).

引言 Introduction​

NextCloud是我用过最舒适的网盘软件，没有之一。（其它网盘软件包括Onedrive，iCloud，百度网盘，Cloudreve，Alist等）。但是非常遗憾的是，我真的不认为NextCloud-AIO是一个好用的东西。它的开发者很聪明，很想创建一个方便、快捷、一站式、开箱即用的NextCloud部署方法，但是很遗憾，我认为它非常非常非常难用，是我用过最难用的部署---第一次我部署一个开源软件（OSS）花费了超过两天。我会在文章最后详细描述为什么我觉得它难用/或者说不好。因此，如果你对使用完整、最新的nextcloud没有兴趣，只是想部署一个优秀的网盘，无论你是否能访问ghcr，我真心推荐你试试其它的部署方法，比如linuxserver/nextcloud，那将会节省你许多宝贵的时间。

NextCloud is the most comfortable cloud storage software I've ever used, bar none. (Other cloud storage options include Onedrive, iCloud, Baidu Netdisk, Cloudreve, Alist, etc.). Unfortunately, I really don't consider NextCloud-AIO to be a user-friendly solution. Its developers are clever and aimed to create a convenient, quick, all-in-one, out-of-the-box NextCloud deployment method, but regrettably, I find it extremely difficult to use - it's the most challenging deployment I've ever experienced, taking me over two days to deploy an open source software (OSS) for the first time. I will describe in detail why I find it difficult/problematic at the end of this article. Therefore, if you're not particularly interested in using the complete, latest version of NextCloud and just want to deploy an excellent cloud storage solution, regardless of whether you can access ghcr or not, I sincerely recommend trying other deployment methods, such as linuxserver/nextcloud, which will save you a considerable amount of valuable time.

在Windows上利用docker-desktop进行部署 Deployment with Windows Docker-Desktop​

首先，我非常希望你能直接跳过这一节，前往linux下部署的那一部分。我非常不推荐你在windows/wsl下部署这个，因为你会遇到性能问题、数据安全、大小写区分等各种各样的问题。我在windows下部署单纯是为了试用----那时我完全没想到迁移居然会这么的麻烦。

First, I strongly recommend skipping this section and going directly to the Linux deployment part. I highly discourage deploying this on Windows/WSL as you will encounter various issues with performance, data security, case sensitivity, and more. I deployed it on Windows merely for testing—at that time, I had no idea migration would be so troublesome.

实际上，官方提供了在windows下部署的文档(https://nextcloud.com/blog/your-guide-to-the-nextcloud-all-in-one-on-windows-10-11/)，写的比较详细，但是没有人提及ghcr.io不能访问时该怎么办----他们给出的建议是"使用手动安装"，然后在那里，我们就会看到过于多的配置项（尽管大部分是密码，我相信一个shell脚本其实就可以生成它们，那样就会显著地降低不适感，但是显然，没有人提供这个脚本，然后我就不想用那个了）。

In fact, official documentation for Windows deployment is available (https://nextcloud.com/blog/your-guide-to-the-nextcloud-all-in-one-on-windows-10-11/) and is quite detailed, but no one mentions what to do when ghcr.io is inaccessible. Their suggestion is to "use manual installation," which presents too many configuration options (though most are passwords that could be generated with a shell script to significantly reduce discomfort, but evidently, no one provides such a script).

我非常建议你先阅读一下官方文档，因为并不想写的很详细。因为我们需要额外做的其实只有两件事：

  1. 为docker-desktop设置真正的代理，而非更实用的镜像仓库
  2. 使用docker compose启动mastercontainer，然后按部就班的完成安装

I strongly recommend reading the official documentation first, as I don't want to write too many details. We actually only need to do two additional things:

  1. Set up a proper proxy for Docker Desktop, rather than using a more practical mirror repository
  2. Use Docker Compose to launch the mastercontainer, then follow the installation steps

首先设置代理，位于设置-Resources-Proxies。你不得不打开手动代理设置，因为自动的没有工作（至少对于我是这样的）。你可能需要打开代理软件的局域网连接。建议使用镜像原先对涉及到的镜像进行预拉取，以尽可能地节省代理流量，提高部署速度：

First, set up the proxy in Settings-Resources-Proxies. You must enable manual proxy settings as automatic ones don't work (at least they didn't for me). You may need to enable LAN connections in your proxy software. It's recommended to pre-pull the involved images using mirrors to save proxy traffic and speed up deployment:

docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-collabora:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-redis:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-docker-socket-proxy:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-notify-push:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-apache:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-whiteboard:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-whiteboardl:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-postgresql:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-imaginary:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-clamav:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-fulltextsearch:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-talk-fulltextsearch:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-talk-recording:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-talk:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/aio-nextcloud:latest
docker pull <your-own-ghcr-mirror>/nextcloud-releases/all-in-one:latest

然后，编写docker-compose.yaml，不要修改任何我标注以外的部分，除非你知道你在干什么：

Then, write your docker-compose.yaml, don't modify any parts other than what I've marked, unless you know what you're doing:

services:
  nextcloud-aio-mastercontainer:
    image: ghcr.io/nextcloud-releases/all-in-one:latest
    init: true
    restart: always
    container_name: nextcloud-aio-mastercontainer
    volumes:
      - nextcloud_aio_mastercontainer:/mnt/docker-aio-config
      - //var/run/docker.sock:/var/run/docker.sock:ro
    network_mode: bridge
    ports:
      - 8088:8080 # 改成你喜欢的端口号，但是后面我会一直使用8088.8080是过于常用的端口（很可能已经被占用），不建议使用 Change to your preferred port, but I'll use 8088 throughout. 8080 is too commonly used (likely already occupied), not recommended
      - 8089:8443 # 其实没用 Actually useless
    environment:
      - APACHE_PORT=8086 # nextcloud工作的端口，反代的目的地 Port where nextcloud works, destination for reverse proxy
      - APACHE_IP_BINDING=127.0.0.1 # 如果你的反代在其它节点，建议直接改成0.0.0.0，因为nextcloud有安全域名检查 If your reverse proxy is on another machine, consider changing to 0.0.0.0 for convince (if it's in LAN), as nextcloud has security domain checks
      - SKIP_DOMAIN_VALIDATION=true
      - BORG_RETENTION_POLICY=--keep-within=7d --keep-weekly=4 --keep-monthly=6
      - NEXTCLOUD_UPLOAD_LIMIT=50G
      - NEXTCLOUD_MAX_TIME=3600
      - NEXTCLOUD_MEMORY_LIMIT=1024M
      - NEXTCLOUD_ADDITIONAL_PHP_EXTENSIONS=imagick
      - NEXTCLOUD_DATADIR=/run/desktop/mnt/host/e/var/lib/nextcloud # /run/desktop/mnt/host/后的部分改成windows 目录 Change the part after /run/desktop/mnt/host/ to your Windows directory
volumes: 
  nextcloud_aio_mastercontainer:
    name: nextcloud_aio_mastercontainer

然后，我们利用docker-compose启动了Nextcloud-AIO实例。记住，任何时候，你都可以通过停止所有容器-修改上面的docker-compose -删除重建mastercontainer来完成局限的配置修改，但似乎我们也只能改这么多。然后你就会惊奇的发现 http://localhost:8088 居然无法正常访问，是不是很神奇？

Now, we launch the Nextcloud-AIO instance using docker-compose. Remember, at any time, you can make limited configuration changes by stopping all containers, modifying the docker-compose file above, and deleting/rebuilding the mastercontainer. Then you'll be surprised to find that http://localhost:8088 doesn't work properly - isn't that amazing?

是的，虽然目的地是8080这一HTTP端口（并且也有8443这个理论上的HTTPS端口），但是实际上 http://localhost:8088 跑的是HTTPS协议，所以你得访问 https://localhost:8088 。我至今不理解这样设计除了给我们带来麻烦还有什么好处。同时，因为localhost显然并非真正加密了的域名，你得点浏览器的"高级-忽略风险继续访问"这种东西

Yes, although the destination is the HTTP port 8080 (and there's also the theoretical HTTPS port 8443), http://localhost:8088 actually runs on the HTTPS protocol, so you have to access https://localhost:8088 . I still don't understand what benefit this design brings us other than inconvenience. Also, since localhost is obviously not a properly encrypted domain, you'll need to click the browser's "Advanced - Proceed despite risk" option.

然后，你会遇到一个很长的密码，建议记下它，因为它只会在这出现一次。不过你总是能通过docker exec nextcloud-aio-mastercontainer grep password /mnt/docker-aio-config/data/configuration.json来获取它（难绷）。然后按照官方教程走其实就可以了，但是你会各种各样遇到莫名其妙、突如其来的卡顿（这套web-ui的交互性真的很差），一般来说你看下CPU和docker ps，如果它没有在摸鱼，一般说明你没有配置错。除非你没有听我的预先把镜像拉下来（走代理直接拉取ghcr会非常慢）。

Next, you'll encounter a very long password. I recommend writing it down as it only appears once. However, you can always retrieve it using docker exec nextcloud-aio-mastercontainer grep password /mnt/docker-aio-config/data/configuration.json (ridiculous). Then you can follow the official tutorial, but you'll encounter all kinds of inexplicable, sudden lag (the interactivity of this web UI is really poor). Generally, check your CPU and run docker ps; if it's not idle, it usually means your configuration is correct - unless you didn't follow my advice to pre-pull the images (pulling directly from ghcr via proxy will be extremely slow).

caddy反代配置非常基础，核心只有一句：

The Caddy reverse proxy configuration is very basic, with only one core line:

pan.fers.top {
	encode gzip
	import tls # DNS Challenge有关的东西，换成你自己的
	reverse_proxy localhost:8086
}

然后理论上你就能用了

Then theoretically you should be able to use it.

开始迁移：在Windows上导出备份 Starting Migration Export Backup in Windows​

我一开始以为直接迁移数据库和文件就能快速移动到linux了，但官方文档写的很复杂，看起来大概率会丢不少东西（all-in-one/migration.md at main · nextcloud/all-in-one）。所以，你也完全不需要花时间去备份数据目录--那完全没用，因为在Nextcloud-AIO，你只能使用非常不方便的Borg，而无其他选择（好用直接的mv不能用了哦） 这意味着你需要额外的磁盘空间（悲）

Initially, I thought that directly migrating the database and files would allow for a quick move to Linux, but the official documentation is complicated and suggests that we'd likely lose quite a bit of data (all-in-one/migration.md at main · nextcloud/all-in-one). Therefore, you don't need to waste time backing up the data directory—it's completely useless because in Nextcloud-AIO, you can only use the very inconvenient Borg with no other options (the convenient direct mv command is no longer available This means you need additional disk space (sigh).

首先，你需要手动停止nextcloud-aio-apache这个容器，然后打开奇怪的 https://localhost:8088 ，停止所有容器，然后利用borg创建备份。虽然这里有一个奇怪的ssh框可以填写，但是大部分时候你只需要填写一个位于docker wsl容器内的地址--其中的一些会被映射到windows上，例如/run/desktop/mnt/host/d/nextcloud-backup，这里有一个密码，别忘了记下它，这点非常重要。备份非常的慢，因为它在做完全没有意义的加密（啊？）。然后，你其实完全不需要进行打包，选择任何你喜欢的方式传送到linux上去。

First, you need to manually stop the nextcloud-aio-apache container, then open the strange https://localhost:8088 , stop all containers, and then create a backup using Borg. Although there's an odd SSH field you can fill in, most of the time you only need to enter an address located within the Docker WSL container—some of which will be mapped to Windows, such as /run/desktop/mnt/host/d/nextcloud-backup. There's a password here, don't forget to write it down, this is extremely important. The backup is very slow because it's performing completely meaningless encryption (why?). Then, you don't actually need to package anything; just transfer it to Linux using any method you prefer.

重部署：在Linux上重复刚才的操作 Redeploy: Repeat operations in Linux​

关于修改docker-ce的代理，参阅官方文档 （别担心，是docker的，不是AIO的），记得预先拉取镜像以加速部署。配置文件基本上照搬官方的即可，导入备份的时候记得输入密码，迁移过程中NEXTCLOUD_DATADIR必须在最开始是空的（也就是说你千万不要勤快地自己把备份目录移动过来），然后，不出意外的话就迁移完成了。开始享受吧（）

Regarding modifying the Docker CE proxy, refer to the official documentation (don't worry, it's Docker's documentation, not AIO's). Remember to pre-pull images to speed up deployment. The configuration file can basically copy the official one. When importing the backup, remember to enter the password. During migration, NEXTCLOUD_DATADIR must be empty at the beginning (meaning you absolutely shouldn't be diligent and move the backup directory over yourself). Then, if all goes well, the migration is complete. Start enjoying it (...)

最后，一些吐槽 Emmmm......​

Nextcloud确实很好用，但是nextcloud-AIO真的是非常非常难用。这真的是很差的设计，非要把简单的事情搞得很复杂。金玉其外，败絮其中是我对nextcloud-AIO的评价。除去前面吐槽过的https和borg两点，我还觉得

  1. Web UI完全没必要，复杂而稳定性很差，大部分时候我们无法获得即时的反馈（无法分辨是出错了还是单纯的卡顿）。考虑到自己部署NExtCloud 的大部分都是相关从业者，我认为一个开箱即用的CLI会更好用（也更好编写和维护）
  2. 官方文档也是这样，看起来很详细、面面俱到，实际上大部分时候无法解决任何问题，基于github markdown的形式也很抽象（我真觉得docusaurus、docker等等的文档好多了）
  3. 把docker套接字暴露给容器内，这是一件很危险且完全没必要的事情

Nextcloud itself is indeed excellent to use, but Nextcloud-AIO is truly extremely difficult to work with. It's a poor design that unnecessarily complicates simple things. "Beautiful on the outside, messy on the inside" (Chinese proverb) is my assessment of Nextcloud-AIO. Besides the HTTPS and Borg issues complained about earlier, I also think:

  1. The Web UI is completely unnecessary - complex with poor stability, and most of the time we can't get immediate feedback (unable to distinguish between errors and simple lag). Considering that most people who self-deploy Nextcloud are industry professionals, I believe an out-of-the-box CLI would be more useful (and easier to write and maintain).
  2. The official documentation is the same way - seemingly detailed and comprehensive, but actually unable to solve most problems. The GitHub markdown format is also rather abstract (I really think documentation from Docusaurus, Docker, etc. is much better).
  3. Exposing the Docker socket to the container is a very dangerous and completely unnecessary practice.