如何在 VPS 上安装 Cloudron

在 VPS 上安装 Cloudron：简要步骤

要在 VPS 上安装 Cloudron，您需要一台全新的 Ubuntu 服务器、至少 2 GB 内存，以及一个可以编辑其 DNS 记录的域名。安装过程只需执行 3 条命令并重启 1 次。大多数问题都发生在此步骤之前（基础镜像错误、虚拟化类型错误）或之后（DNS、邮件、备份）。

wget https://cloudron.io/cloudron-setup
chmod +x cloudron-setup
sudo ./cloudron-setup

Cloudron 会为自托管应用安装、更新和备份，并签发 TLS（传输层安全）证书。每个应用都运行在 Docker 中，nginx 位于所有应用前端，并且每个应用都会使用您域名下的独立子域名。正因为如此，DNS 配置必须先完成。

Cloudron 对基础操作系统要求严格的原因

安装任何内容前，安装脚本会先检查服务器。检查失败意味着需要重新购买服务器。选择镜像前，请先阅读这些要求。

• 仅支持 Ubuntu，并且只支持 3 个版本。其他系统会以 Cloudron requires Ubuntu 20.04, 22.04, 24.04 退出。不支持 Debian、Rocky 和 Alpine。Ubuntu 24.04 需要 Cloudron 8 或更高版本，脚本会自动检查这一点。
• 仅支持 64 位 Intel 或 AMD：Error: Cloudron only supports amd64/x86_64。ARM VPS 无法运行 Cloudron。
• 仅支持完整硬件虚拟化。在基于容器的 VPS 上，脚本会以 Error: Cloudron does not support lxc, only runs on bare metal or with full hardware virtualization 停止，因为它会通过 systemd-detect-virt --container 检测到当前运行在容器中。KVM 可以使用。不支持 OpenVZ 和 LXC。
• 根文件系统必须是 ext4 或 xfs。其他文件系统会产生 Error: Cloudron requires '/' to be ext4 or xfs，btrfs 和 zfs 镜像失败时就是这种情况。
• 至少需要 941 MB RAM，并且 / 上至少有 20 GB 可用空间。脚本通过 free -m 和根文件系统大小进行测量。
• 服务器必须是真正的全新环境。如果已安装 nginx、docker 或 node，脚本会以 Error: Some packages like nginx/docker/nodejs are already installed. 拒绝继续。

最后一项检查最容易引发争议，原因如下。Cloudron 会安装固定版本的 Docker、nginx、Node.js 和 MySQL，为它托管的每个应用写入 nginx 配置，并自行管理 iptables 防火墙规则。您昨天安装的 Docker 版本可能不正确，现有的 nginx 站点文件也会被替换。Cloudron 会接管整台机器，因此应为它提供专用 VPS。

还有一项检查很容易被忽略。在不支持 AVX（高级矢量扩展）的旧 CPU 上，脚本会输出 CPU has no AVX support. MongoDB will be disabled，所有需要 MongoDB 的应用都会变为无法安装。购买服务器前，使用 grep -m1 -o avx /proc/cpuinfo 检查 CPU。支持 AVX 的主机会输出 avx，旧主机则不会输出任何内容。

Cloudron 需要多少 RAM？

该脚本在低于 941 MB 时会拒绝运行，并显示 Error: Cloudron requires atleast 1GB physical memory；文档要求 2 GB RAM 和 20 GB 磁盘空间。这两个数值只是平台本身的最低要求，不包括平台上运行的应用。安装任何应用之前，Cloudron 已经在运行 Docker、nginx、自带的 box 服务、供应用使用的数据库容器（MySQL、PostgreSQL、MongoDB）、Redis 和邮件服务栈。在全新安装上运行 docker ps 并统计这些进程。

应用的内存限制是在上述基础开销之上的额外需求。每个应用包都有一个较低的默认限制，您可以在应用的 Resources 视图中使用滑块提高该限制。应用超过限制后会重启，并向您发送 OOM（内存不足）通知。因此，一台服务器如果反复重启某个应用，通常是内存限制问题，而不是程序错误。

以下是我会采用的容量规划。这些建议适用于您不希望下个月就重装的服务器。它们不是实测基准结果。

[
  {
    "label": "2 apps (free tier)",
    "vcpu": 2,
    "ram_gb": 4,
    "disk_gb": 60
  },
  {
    "label": "5 apps",
    "vcpu": 4,
    "ram_gb": 8,
    "disk_gb": 120
  },
  {
    "label": "10 apps",
    "vcpu": 6,
    "ram_gb": 16,
    "disk_gb": 240
  }
]

运行两个应用时，4 GB RAM 和 60 GB 磁盘空间即可保持稳定。运行约十个应用时，需要 16 GB RAM 和 240 GB 磁盘空间，因为平台基础开销不会减少，而每个应用都会增加一个 Docker 镜像、一个数据库和自身的数据。磁盘空间的消耗速度通常超出预期：镜像、应用数据和本地备份会一直共用同一个卷，直到您将备份移出该服务器。

Cloudron 为每个应用提供无限制的 swap，因此您设置的内存限制只适用于 RAM。在没有 swap 文件的 VPS 镜像上，swapon --show 完全不会输出内容，内存压力会直接导致 OOM 重启，而不是使应用变慢。增加 2 GB swap 是一种成本较低的保险措施，但不能替代实际内存。VPS 方案之间的价差通常小于您调试内存限制所需的时间，因此请参阅VPS 的实际成本，并购买更高一级的方案。

DNS：让应用子域名正常工作的通配符记录

Cloudron 将控制面板放在 my.example.com 上，并为每个应用使用独立的子域名，因此 DNS 是前置条件，而不是后续步骤。首次打开控制面板前，请将以下记录指向服务器的公网 IP 地址：

• 将 my.example.com 添加为 A 记录。这是控制面板。
• 将 *.example.com 添加为 A 记录。该记录用于让应用子域名正常工作，因此安装这些应用后，wiki.example.com 和 git.example.com 会立即解析。
• 仅当您希望在裸域名上运行应用时，才将 example.com 添加为 A 记录。

通配符记录的优先级低于显式记录，因此已有的 www.example.com 即使指向其他位置，也会继续生效。

在设置过程中，您需要选择 Cloudron 后续处理 DNS 的方式：

• API 提供商。Cloudron 会保存 Cloudflare、DigitalOcean、Route53、Hetzner、Porkbun、Linode、deSEC、Gandi、Namecheap 以及大约二十个其他提供商的令牌，然后自行写入所有记录，包括邮件记录。
• Wildcard。您手动添加 * 记录，Cloudron 不会写入任何记录。
• Manual。每次安装应用前，Cloudron 都会显示所需的每条记录，并等待您手动添加。

DNS 通配符记录不是通配符证书。 默认的证书提供商是 Let's Encrypt Prod - Wildcard，它通过 DNS 验证域名所有权，因此只能与 API 提供商配合使用。在 Wildcard 或 Manual 后端中，系统会改为为每个应用申请一个通过 HTTP 验证的独立证书，这意味着入站端口 80 必须永久保持开放。如果您的注册商或 DNS 托管商在 API 列表中，请使用它：邮件记录和证书都无需再由您处理。

继续操作前请先验证。dig +short my.example.com 和 dig +short anything.example.com 都应输出服务器的 IP 地址。如果通配符查询没有输出内容，后续应用将安装失败，而控制面板仍可能正常工作。

如果域名位于 Cloudflare 后面，请将记录设置为仅 DNS。Cloudflare 的代理只转发 HTTP 和 HTTPS，因此邮件端口会失效，并且每个应用看到的都是 Cloudflare 地址，而不是访问者的地址。

运行安装脚本

wget https://cloudron.io/cloudron-setup
chmod +x cloudron-setup
sudo ./cloudron-setup

请以 root 身份运行，或通过 sudo 运行。否则，脚本首先会输出 This script should be run as root.。安装需要几分钟。安装过程中不会显示太多信息，因为 apt 输出和 Docker 拉取内容会写入日志文件。请通过第二个 SSH 会话查看日志：

tail -f /var/log/cloudron-setup.log

安装结束时，脚本会输出 After reboot, visit one of the following URLs and accept the self-signed certificate to finish setup.，后面跟着服务器地址，然后询问 The server has to be rebooted to apply all the settings. Reboot now ? [Y/n]。请输入 yes。如果需要安排重启，可以使用 --skip-reboot 标志。但在服务器重新启动前，Cloudron 无法使用。

首次启动：域名、DNS 后端和管理员账户

打开 https://<server-ip>，然后接受浏览器警告。证书是自签名证书，因为 Cloudron 还不知道您的域名，因此无法向证书颁发机构申请证书。在 Chrome 中点击 Advanced，然后点击 Proceed to <ip> (unsafe)。在 Firefox 中点击 Advanced，然后点击 Accept the Risk and Continue。

首个页面会要求您输入域名。输入 example.com，然后控制面板会固定在 my.example.com。您也可以改用 cloudron.example.com 这样的子域名，此时控制面板地址为 my.cloudron.example.com。选择 DNS 后端；如果有 API token，请粘贴它。然后使用一个您确实会查看的电子邮件地址创建管理员账户：Let's Encrypt 注册和所有平台告警都会使用该地址。

保存后，Cloudron 会申请证书，并将控制面板迁移到 https://my.example.com。此时通过 IP 地址访问的 URL 将停止工作，请将新的 URL 加入书签。

证书：续期内容和停止时间

证书续期是自动执行的，并遵循 ACME Renewal Information (ARI)，也就是证书颁发机构发布的续期计划。实际续期时间通常在证书到期前约 1 个月。续期失败时，系统会向管理员账户发送电子邮件；证书过期后，系统会回退到内置的自签名证书。网站昨天还能正常访问，今天浏览器却显示警告，实际指的就是这种回退情况。

大多数问题都由以下两个原因造成。HTTP 验证需要入站端口 80。因此，如果因为“反正所有流量都使用 HTTPS”而关闭端口 80，基于 Wildcard 或 Manual DNS 后端的所有应用都会无法续期。DNS 验证需要一个仍具有写入权限的 API token。因此，轮换或收紧该 token 的权限会导致续期静默失败，直到管理员收到警告电子邮件。

Domains 视图中有一个 Renew All 按钮，可立即强制执行续期尝试。该视图还提供 Let's Encrypt Staging provider，用于测试。Staging 证书有意不受浏览器信任，这正是其用途所在：您可以根据需要反复重试，而不会消耗生产环境的速率限制。

是否应使用内置邮件服务器？

Cloudron 提供完整的邮件堆栈，包括 IMAP 邮箱、submission、sieve 过滤器和 DKIM（domainkeys identified mail）签名。您可以在控制面板的 Email 中按域名启用它。邮件能否成功投递才是难点，而这些问题都不是 Cloudron 造成的。

• 大多数 VPS 提供商会阻止出站端口 25，以控制垃圾邮件。提交支持工单后，有些提供商会解除限制。使用 nc -zv aspmx.l.google.com 25 从服务器测试（如果缺少该命令，请安装 netcat-openbsd）。开放端口会报告 succeeded；被阻止的端口会一直等待，直到超时。
• PTR 记录（反向 DNS）由 VPS 提供商设置，而不是由 DNS 托管商设置，并且必须与邮件主机名匹配。来自具有通用 PTR 的地址的邮件会进入垃圾邮件文件夹。
• 如果使用 API DNS 后端，系统会为您写入 SPF、DKIM 和 DMARC 记录。使用 Wildcard 或 Manual 后端时，您需要手动添加这些记录；缺少 DKIM 记录意味着您签名的每封邮件都无法验证。

对大多数用户有效的方案是：在 Cloudron 上接收邮件，并通过 SendGrid、Postmark、Mailgun 或 Amazon SES 等中继服务发送邮件，在 Email 视图中完成配置。中继服务必须允许使用您域名上的任意地址发送邮件，否则来自不同发件人的应用通知会被拒收。如果购买服务器的主要原因是邮件服务，请在独立服务器上运行专用邮件服务器，例如 Mailcow，并为其使用独立 IP 声誉。

如果您完全不使用 Cloudron Email，请在提供商的防火墙中阻止端口 25、465、587、993 和 4190。应在提供商处执行此操作，而不是在服务器上执行，因为 Cloudron 会自行写入 iptables 规则，并且要求独占管理这些规则。这与普通 VPS 相反；在普通 VPS 上，您需要自行管理 ufw 规则。

在需要备份之前配置备份目标

备份默认保存到 /var/backups 的本地文件系统，与其他数据位于同一块磁盘上。文档对此有明确说明：“让备份与平台服务器位于同一块物理磁盘上非常危险。”磁盘发生故障时，应用和备份会同时丢失。

打开 Backups，然后进入 Backup Sites，在第一天就将备份指向其他位置。S3 兼容对象存储通常是首选方案（Backblaze B2、Wasabi、Cloudflare R2、DigitalOcean Spaces，或第二台服务器上的 MinIO 存储桶）。同时也支持 SSHFS、NFS、CIFS 和普通文件系统目标。

以下三个设置决定备份是否真正有用：

• 格式。tgz 为每个应用写入一个压缩归档，并在每次运行时重新上传整个归档。rsync 只上传发生更改的文件。对于大型 Nextcloud，这样可以大幅降低成本，但会向存储 API 发起更多请求。
• 加密。可选的 AES-256 加密，同时保护文件内容和文件名。Cloudron 不会保留密码副本，因此密码丢失后，包括您在内的任何人都无法解密备份。点击保存之前，请将密码存储在自行托管的密码管理器中。
• 保留期限。使用数量表示，例如 7 个每日备份和 4 个每周备份。在对象存储中长期保留备份会产生每月费用，因此请选择您愿意持续支付的数量。

然后测试恢复。安装一个小型应用，从控制面板恢复该应用，并确认其数据能够一并恢复。任何从未恢复过的备份都只是猜测。

免费套餐的限制

截至 August 2026，免费套餐最多可安装两个应用。以下功能均包含在内：应用更新、按应用备份、防火墙、邮件服务器和单点登录。安装第三个应用时，就需要许可证。付费套餐会取消应用数量限制；更高一级的套餐还提供用户组和角色、目录服务器以及多个备份站点。价格会变化，因此请查看Cloudron 定价页面，不要以教程中的某个数字为准。

一个许可证对应一个 Cloudron 安装，因此两台小型服务器的费用是单台大型服务器的两倍。这种定价会使大多数用户选择一台更大的 VPS，而不是按照通常建议将服务分散到多台机器上。规划服务器规格时应考虑这一点，因为之后再拆分服务意味着需要支付两份费用。

发生故障时

先运行内置检查。它会依次检查 DNS、证书、磁盘、内存和各项服务，并告知失败的测试：

sudo cloudron-support --troubleshoot

然后使用常规的 systemd（系统和服务管理器）工具。systemctl status box用于查看 Cloudron 服务本身的状态，journalctl -u box -n 100用于查看其最近的日志，journalctl -u docker用于检查底层的容器运行时。安装过程中发生的任何错误都会记录在 /var/log/cloudron-setup.log 中。

无法加载的控制面板通常是 DNS 或服务提供商防火墙的问题，而不是 Cloudron 本身的问题。在笔记本电脑上运行 dig +short my.example.com，并确认服务提供商网络防火墙中已开放 80 和 443 端口。该防火墙与服务器自身的防火墙规则是两个独立的控制层。如果要重新开始，脚本会通过 Error: Cloudron is already installed. To reinstall, start afresh 拒绝第二次运行；此时重建服务器是最干净的解决方案。

Cloudron 不适合的情况

如果您只想部署应用，而不想管理基础设施，Cloudron 很合适。如果您想按自己的方式运行容器，Cloudron 就不太合适，因为它会接管 nginx、Docker 和防火墙，并覆盖您对这些组件所做的配置。如果您的计划是维护一组 compose 文件，那么在自己的 Docker Compose 堆栈前使用 Traefik，即可获得相同的自动 TLS 和子域名路由功能，同时不需要在其上再运行一个平台。如果您还没有做出选择，Cloudron、CasaOS 和 Coolify 对比会并列介绍这几个方案；相比直接查看安装指南，更完整的自托管项目列表更适合作为起点。

FAQ

Cloudron 在 VPS 上需要多少 RAM？

安装脚本在 RAM 少于 941 MB 时会拒绝运行，文档要求 2 GB，但这只是平台在未安装任何应用时的最低配置。Cloudron 从首次启动起就会运行 Docker、nginx、自带的 box 服务、数据库容器和邮件堆栈。为两个应用预留 4 GB，为大约十个应用预留 16 GB，并添加 swap 文件，因为 Cloudron 会为应用提供不受限制的 swap；没有 swap 的服务器会因内存压力触发服务重启。

可以在 Debian 上安装 Cloudron，或安装在已经运行 Docker 的服务器上吗？

这两种情况都不支持。脚本会检查发行版，并因 Cloudron requires Ubuntu 20.04, 22.04, 24.04 停止运行，因此 Debian、Rocky 和 Alpine 都不支持。如果 nginx、docker 或 node 已存在，脚本也会停止，因为它会安装这些组件的固定版本，并自行写入 nginx 配置和 iptables 规则。请从 KVM VPS 上全新的 Ubuntu 镜像开始。

为什么应用子域名无法访问，而控制面板可以访问？

缺少通配符 DNS 记录。安装程序会创建或要求为 my.example.com 配置 A 记录，因此控制面板可以解析；而 wiki.example.com 会返回 NXDOMAIN，浏览器会提示找不到该网站。为 *.example.com 添加指向服务器 IP 的 A 记录，然后在安装应用前使用 dig +short wiki.example.com 确认。

必须使用 Cloudron 邮件服务器吗？

不必。您可以关闭入站邮件，并通过 Postmark、Mailgun 或 Amazon SES 等外部中继发送邮件。当服务商阻止出站 25 端口，或 IP 地址没有邮件信誉时，这是更安全的选择。如果完全跳过 Cloudron Email，请在服务商防火墙中关闭 25、465、587、993 和 4190 端口，而不是在服务器上关闭。

免费计划达到两个应用的限制后会发生什么？

控制面板会阻止安装第三个应用，并要求输入许可证密钥。已经运行的应用不受影响：它们会继续更新、继续备份，证书也会继续保留。添加许可证后即可解除限制，无需重新安装任何内容。因此，免费计划适合先在真实域名上测试该平台。