CasaOS：十分钟搭建个人家庭云，旧电脑变全能服务器

这次我们来看一个开源的轻量级家庭云操作系统——CasaOS。它来自 IceWhaleTech 团队，核心目标是把任何一台能跑 Linux 的旧电脑、开发板或 NAS 设备，快速变成一个功能强大、界面友好的个人云服务中心。如果你手头有闲置的硬件，或者想摆脱对商业云服务的依赖，自己搭建一个集文件管理、应用商店、Docker 管理于一体的家庭服务器，那么这个项目值得你花十分钟了解一下。

CasaOS 最吸引人的地方在于它的“轻量”和“易用”。它不是一个需要你从零开始配置 Linux 和 Docker 的复杂系统，而是一个基于 Docker 的 Web 管理面板，通过极简的安装命令就能部署。部署完成后，你获得的是一个直观的类桌面操作系统界面，可以像在手机上安装 App 一样，一键部署 Nextcloud、Jellyfin、Home Assistant、qBittorrent 等数十种常用服务。对于家庭用户和小型工作室来说，它极大地降低了自建云服务的门槛。

本文将带你快速了解 CasaOS 的核心能力、硬件门槛，并完成从环境准备、一键安装、基础功能配置到常见问题排查的全过程。无论你是想用树莓派搭建一个媒体中心，还是用旧笔记本做一个家庭文件备份服务器，都能从这篇文章中找到可落地的操作步骤。

1. 核心能力速览

在深入部署之前，我们先通过一个表格快速了解 CasaOS 的核心特性，判断它是否符合你的需求。

2. 适用场景与使用边界

CasaOS 的设计初衷是让家庭和个人用户能轻松享受自建服务的乐趣和掌控感。它非常适合以下几类场景：

• 家庭媒体中心：在树莓派或旧电脑上安装 CasaOS，然后通过应用商店一键部署 Jellyfin 或 Plex，将本地电影、音乐库串流到电视、手机和平板上。
• 个人私有云盘：部署 Nextcloud 或 ownCloud，替代公有云盘，实现文件同步、分享和备份，数据完全掌握在自己手中。
• 智能家居网关：安装 Home Assistant，统一管理各类智能家居设备，实现自动化场景，且所有数据本地运行，隐私性更高。
• 下载与内容管理：集成 qBittorrent、Transmission 进行下载，配合 Jellyfin 或 Tiny Tiny RSS 管理影视和 RSS 订阅。
• 轻量级开发/测试环境：利用其 Docker 管理能力，快速拉起 MySQL、Redis、Nginx 等服务，用于学习或测试。

然而，它也有明确的使用边界：

1. 非企业级：CasaOS 侧重于易用性和个人/家庭场景，在高并发、多用户、企业级权限管理和高可用性方面并非其强项。
2. 依赖 Docker：所有应用都基于 Docker 容器。如果你对 Docker 完全陌生，需要先了解容器的基础概念（但 CasaOS 的安装过程屏蔽了大部分复杂性）。
3. 硬件性能限制：应用的性能取决于底层硬件的 CPU、内存和 I/O 能力。在树莓派等 ARM 设备上运行多个重型服务（如同时转码和数据库服务）可能会遇到瓶颈。
4. 数据安全责任自负：自建服务意味着你需要自行负责系统的安全更新、数据备份和灾难恢复。暴露服务到公网需格外谨慎，做好防火墙和密码安全设置。

3. 环境准备与前置条件

在运行安装命令前，请确保你的设备满足以下基本条件。

1. 操作系统要求

• 首选：一个干净的Debian 11/12或Ubuntu 20.04/22.04系统。这是官方测试最充分的环境。
• 其他：理论上其他基于 Debian/Ubuntu 的发行版（如 Raspberry Pi OS）也可运行，但兼容性需要自行测试。
• 务必全新：建议在新安装的系统或打算专用于 CasaOS 的设备上操作，避免与现有服务产生端口或依赖冲突。

2. 硬件与网络

• 设备：一台 x86 架构的旧电脑、迷你主机，或 ARM 架构的开发板（如树莓派 4B 及以上）。
• 内存：至少 1GB，推荐 2GB 或以上。
• 存储：系统盘预留 10GB 以上空间。如果用于存储媒体文件，需要额外准备大容量硬盘，并规划好挂载点。
• 网络：设备需要连接网络，并能通过局域网 IP 被访问。为设备设置一个静态局域网 IP 地址是最佳实践，可以避免 IP 变化后无法访问。

3. 权限与依赖

• 你需要拥有设备的root 权限（或能使用sudo的用户）。
• 系统需要能够正常访问互联网，以下载安装脚本和 Docker 镜像。
• 确保系统已安装curl和wget工具，通常它们默认存在。

4. 安装部署与启动方式

CasaOS 的安装过程极其简单，这是它“一键部署”理念的体现。整个过程由安装脚本自动完成，包括 Docker 的安装和配置。

步骤 1：通过官方脚本安装通过 SSH 连接到你的目标设备，然后执行以下命令：

curl -fsSL https://get.casaos.io | sudo bash

或者使用备用命令：

wget -qO- https://get.casaos.io | sudo bash

这个命令会自动化完成以下工作：

1. 检测系统架构（x86_64/arm64/armhf）。
2. 安装 Docker 和 Docker Compose（如果系统中没有）。
3. 下载并安装 CasaOS 的核心组件及 WebUI。
4. 将 CasaOS 注册为系统服务，并设置开机自启。

安装过程会在终端显示进度。如果网络通畅，几分钟内即可完成。

步骤 2：访问 CasaOS 管理界面安装成功后，脚本会输出类似以下的信息：

CasaOS 安装成功！ 请通过以下地址访问： http://你的设备IP地址:80

在局域网内的任何一台电脑或手机的浏览器中，输入上述地址（将“你的设备IP地址”替换为实际 IP），即可看到 CasaOS 的初始化设置界面。

步骤 3：初始化设置首次访问会进入一个简单的设置向导：

1. 选择语言：支持中文。
2. 创建管理员账户：设置用户名、邮箱和密码。请务必使用强密码。
3. 配置存储路径：设置 CasaOS 默认的应用数据和用户文件的存储位置。建议指向你准备好的大容量数据盘路径（例如/mnt/sda1）。如果暂时不确认，可以使用默认路径，后续可在设置中更改。

完成设置后，你就正式进入了 CasaOS 的主界面。

5. 功能测试与效果验证

安装完成只是第一步，我们来实际验证几个核心功能是否工作正常。

5.1 系统状态监控验证

测试目的：确认 CasaOS 能正确读取并显示底层设备的硬件状态。操作步骤：

1. 登录 CasaOS 主界面。
2. 观察桌面顶部或侧边栏的仪表盘部件。通常会有系统信息卡片。预期结果：

• 能正确显示 CPU 使用率、温度（如果硬件支持）。
• 能正确显示内存总量及已用比例。
• 能正确显示存储设备的总容量、已用空间和可用空间。
• 网络流量图有动态变化。判断成功：所有监控数据非空且看起来合理（例如，CPU 使用率在空闲时应较低）。常见问题：存储信息未识别。请检查在初始化设置或系统设置中，存储路径是否指向了已挂载的有效磁盘。

5.2 应用商店与一键部署验证

测试目的：验证从应用商店查找、安装 Docker 应用的功能。操作步骤：

1. 点击左侧导航栏或桌面上的 “App Store” 图标。
2. 在应用商店中，找到一个轻量级应用进行测试，例如 “Hello World” 或 “Webtop”（一个基于浏览器的桌面环境）。
3. 点击该应用卡片，然后点击“安装”。
4. 在安装配置页面，通常可以保持默认设置（端口、卷映射等），直接点击“安装”。预期结果：

• 应用开始部署，界面显示拉取镜像和创建容器的进度。
• 部署完成后，该应用的图标会出现在 CasaOS 桌面上。
• 点击该图标，浏览器会打开一个新标签页，显示该应用的 Web 界面。判断成功：应用图标出现在桌面，且能正常打开其 Web 界面。常见问题：
• 拉取镜像慢：这通常是因为 Docker Hub 在国内访问速度慢。解决方法见第 8 节。
• 端口冲突：如果默认端口被占用，安装时会提示失败。需要在安装配置页面修改为其他未占用的端口。

5.3 文件管理器与 SMB 共享验证

测试目的：验证 CasaOS 内置文件管理器的基本操作和局域网文件共享功能。操作步骤 - 本地管理：

1. 点击左侧导航栏的“文件”图标。
2. 尝试创建新文件夹、上传本地文件、在线预览图片/文本文件。操作步骤 - 网络共享：
3. 在文件管理器界面，找到你想要共享的文件夹（例如/DATA目录下的Public）。
4. 右键点击该文件夹，选择“属性”或“共享”选项。
5. 启用 SMB 共享，并设置共享名称和权限（只读/读写）。预期结果：

• 在局域网内的 Windows 电脑上，打开文件资源管理器，在地址栏输入\\<你的设备IP地址>，按回车。
• 可以看到你共享的文件夹，并能进行读写操作（取决于权限）。
• 在 macOS 上，可以在 Finder 中通过“连接服务器”输入smb://<你的设备IP地址>进行访问。判断成功：能从局域网内其他设备访问到共享文件夹中的文件。

5.4 Docker 管理功能验证

测试目的：验证 CasaOS 对底层 Docker 引擎的管理能力。操作步骤：

1. 从应用商店安装一个应用（如上面的验证步骤）。
2. 点击 CasaOS 左上角菜单，进入“系统设置”。
3. 找到“Docker”或“容器”管理页面。预期结果：

• 在“容器”列表中，能看到刚刚安装的应用对应的容器，并显示其状态（运行中/已停止）、使用的镜像、创建时间等信息。
• 可以对容器进行停止、启动、重启、移除操作。
• 在“镜像”列表中，能看到已下载的 Docker 镜像。
• 在“Compose”列表中，能看到 CasaOS 为每个应用生成的 Docker Compose 配置文件。判断成功：能通过 CasaOS 的界面完成对容器的基本生命周期管理，无需使用命令行。

6. 接口 API 与批量任务

虽然 CasaOS 的强项在于 WebUI，但它也提供了 API 接口，方便进行自动化管理和集成。

6.1 API 接口概览

CasaOS 的 API 遵循 RESTful 风格。你可以在安装 CasaOS 的设备上，访问http://<设备IP>:80/api/docs来查看完整的 Swagger API 文档。这里列举几个关键端点：

• 系统信息：GET /v1/sys/version获取 CasaOS 版本。
• 用户信息：GET /v1/users获取用户列表。
• 存储信息：GET /v1/storage获取存储设备列表。
• 容器管理：GET /v1/containers获取容器列表；POST /v1/containers/{id}/start启动容器。
• 应用管理：POST /v1/apps/install通过应用 ID 安装应用。

6.2 使用 cURL 测试 API

你可以通过命令行工具curl来测试 API 是否正常工作。首先，你需要获取一个认证令牌。通常 CasaOS 的 API 使用 Header 中的Authorization字段进行认证，令牌可以在 WebUI 的某个设置页面找到（具体请查阅官方文档）。以下是一个获取系统信息的示例（假设令牌为your_token_here）：

curl -X GET "http://你的设备IP:80/v1/sys/version" \ -H "Authorization: Bearer your_token_here" \ -H "Content-Type: application/json"

如果成功，会返回包含版本号的 JSON 数据。

6.3 批量任务与 Compose 管理

CasaOS 本身不提供图形化的批量应用部署功能，但它为每个通过应用商店安装的应用都生成了一个标准的 Docker Compose 文件。这为批量任务提供了基础。

实现批量部署的思路：

1. 定位 Compose 文件：CasaOS 的 Compose 文件通常存储在/var/lib/casaos/apps或用户数据目录下的特定位置。你可以通过 SSH 登录设备找到它们。
2. 编写总 Compose 文件：你可以创建一个总的docker-compose.yml文件，使用include指令（Compose V2.20+ 特性）或手动合并的方式，将多个应用的配置整合在一起。
3. 使用命令行批量操作：在包含总 Compose 文件的目录下，使用docker-compose up -d命令一次性启动所有服务。

示例：手动管理多个服务假设你通过 CasaOS 安装了 Jellyfin 和 Nextcloud，之后想用命令行统一管理。

# 1. 找到 CasaOS 为这两个应用生成的 compose 文件路径 # 例如：/var/lib/casaos/apps/jellyfin/docker-compose.yml # 和：/var/lib/casaos/apps/nextcloud/docker-compose.yml # 2. 创建一个总目录和总 compose 文件 mkdir ~/my-casaos-stack cd ~/my-casaos-stack # 3. 创建 docker-compose.yml，引用或复制原有配置 cat > docker-compose.yml <<EOF version: '3.8' services: jellyfin: # 复制或引用原 jellyfin 的 service 配置 image: jellyfin/jellyfin:latest container_name: jellyfin volumes: - /path/to/config:/config - /path/to/media:/media ports: - "8096:8096" restart: unless-stopped nextcloud: # 复制或引用原 nextcloud 的 service 配置 image: nextcloud:latest container_name: nextcloud volumes: - /path/to/nextcloud/data:/var/www/html/data - /path/to/nextcloud/config:/var/www/html/config ports: - "8080:80" restart: unless-stopped EOF # 4. 启动整个栈 docker-compose up -d # 5. 查看状态 docker-compose ps

注意：此操作会创建独立于 CasaOS WebUI 管理之外的容器。两者同时管理同一套服务可能导致冲突，建议仅作为一种高级备份或迁移手段。

7. 资源占用与性能观察

CasaOS 本身作为一个 Web 管理面板，资源消耗非常低。主要的资源占用来自于你通过它部署的 Docker 应用。

1. CasaOS 本体资源占用

• 内存：CasaOS 的核心服务进程通常占用 100-300 MB 内存。
• CPU：在空闲状态下几乎不占用 CPU，仅在页面操作或后台检查更新时有轻微波动。
• 存储：系统本身占用约 500MB - 1GB 的磁盘空间。

2. 观察方法

• 通过 CasaOS 仪表盘：最直接的方式就是查看 CasaOS 主界面的系统监控部件。
• 通过命令行：通过 SSH 连接到设备，使用htop、docker stats等命令可以更详细地查看所有容器和进程的资源使用情况。

  # 查看所有 Docker 容器的实时资源占用 docker stats # 查看系统整体资源使用 htop

3. 性能影响因素与优化

• 存储 I/O：这是家庭服务器最常见的瓶颈。如果你部署了媒体库（如 Jellyfin）并开启视频转码，或者运行数据库（如 Nextcloud 的数据库），请确保数据存储在速度较快的硬盘（如 SSD）上，而非 USB 2.0 连接的移动硬盘。
• 内存：每个 Docker 容器都会占用一定内存。在树莓派等内存有限的设备上，需控制同时运行的应用数量。对于内存消耗大的应用（如大型数据库），可以考虑增加交换空间（swap）作为缓冲，但这会影响性能。

  # 检查当前 swap 大小 sudo swapon --show # 如果太小，可以创建并启用一个 2GB 的 swap 文件（操作有风险，请先备份数据） sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 使其永久生效，需编辑 /etc/fstab

• 网络：内网传输速度受路由器、网线、设备网卡影响。确保所有设备都在千兆局域网内，并使用有线连接以获得最佳文件共享和媒体串流体验。

8. 常见问题与排查方法

在部署和使用 CasaOS 过程中，你可能会遇到以下问题。这里提供通用的排查思路。

重点问题解决方案详解：

配置 CasaOS 国内源（解决应用商店问题）：

1. SSH 登录到 CasaOS 设备。
2. 编辑 CasaOS 的配置文件，路径可能为/etc/casaos/casaos.conf或/usr/local/casaos/conf/conf.ini，请根据实际安装查找。
3. 找到与app_store_url或repository相关的配置项。
4. 将其值修改为可用的国内镜像源地址（请注意，官方可能不提供固定镜像，此地址需要自行寻找可靠来源，以下为示例格式）：

   # 示例，实际URL需替换 app_store_url = "https://mirror.example.com/casaos/appstore"

5. 保存文件并重启 CasaOS 服务。

   sudo systemctl restart casaos

配置 Docker 镜像加速器：

1. 创建或编辑 Docker 守护进程配置文件：

   sudo nano /etc/docker/daemon.json

2. 输入以下内容（以阿里云镜像加速器为例，你需要注册阿里云容器镜像服务获取专属加速地址）：

   { "registry-mirrors": ["https://your_id.mirror.aliyuncs.com"] }

   也可使用其他公共镜像源，如中科大https://docker.mirrors.ustc.edu.cn（请注意可用性）。
3. 保存并退出编辑器。
4. 重新加载配置并重启 Docker：

   sudo systemctl daemon-reload sudo systemctl restart docker

5. 运行docker info，在输出中查看Registry Mirrors是否包含你设置的地址，确认配置生效。

9. 最佳实践与使用建议

为了让你的 CasaOS 体验更稳定、高效，遵循以下实践建议：

1. 先规划，后安装：在安装 CasaOS 前，规划好数据存储路径。建议将系统装在 SSD 上以保证响应速度，将媒体库、文件备份等大量数据存储在大容量 HDD 上，并通过 CasaOS 设置正确的数据盘挂载点。
2. 善用应用商店的“已安装”分类：应用商店里应用众多，安装过的应用会在“已安装”分类中显示，方便管理。
3. 定期更新系统和应用：定期通过 CasaOS 的“系统设置”检查更新，及时更新 CasaOS 本身以及已安装的应用（容器镜像），以获取新功能和安全补丁。
4. 重视数据备份：CasaOS 管理着你的应用配置和数据。定期备份以下内容：
   • Docker Compose 文件：位于/var/lib/casaos/apps或你自定义的存储路径下，这些文件定义了你的服务配置。
   • 应用数据卷：即你在安装每个应用时映射到宿主机的目录（如/path/to/config,/path/to/data）。这是最核心的数据。
   • CasaOS 配置文件：如/etc/casaos/casaos.conf。
5. 安全第一：
   • 强密码：为 CasaOS 管理员账户设置强密码，并定期更换。
   • 局域网访问：如无特殊需求，不要将 CasaOS 的管理端口（默认80）暴露到公网。如果必须暴露，务必使用反向代理（如 Nginx Proxy Manager，也可在应用商店安装）并配置 HTTPS 证书。
   • 单独用户：考虑为文件共享等服务创建独立的、权限受限的系统用户或 Samba 用户，而非直接使用高权限账户。
6. 性能监控：将 CasaOS 的系统监控部件放在桌面显眼位置，定期观察资源使用情况，及时发现潜在瓶颈（如磁盘将满、内存持续过高）。
7. 社区与文档：遇到复杂问题时，优先查阅 CasaOS 官方文档 和 GitHub 项目页面 的 Issues 讨论区，很多常见问题已有解决方案。

10. 总结与下一步

CasaOS 成功地将 Docker 容器技术的强大功能封装在一个对新手极其友好的 Web 界面之后。它最大的价值在于极大地简化了家庭级服务的部署和管理流程，让不具备深厚 Linux 和 Docker 知识的用户也能轻松搭建属于自己的云应用生态。

你最应该首先验证的功能就是应用商店的一键安装和文件共享。这两个功能最能体现其“开箱即用”的特性。最容易踩的坑通常是网络问题导致的安装失败或镜像拉取缓慢，按照本文第 8 节的方法配置国内源和 Docker 加速器能解决大部分此类问题。

部署稳定后，你可以进一步探索：

• 集成更多服务：尝试部署 Bitwarden 密码管理器、PhotoPrism 照片管理、Vaultwarden 密码库等，打造更全面的数字生活中心。
• 探索 API 自动化：利用 CasaOS 的 API，结合脚本实现定时任务、状态监控报警等自动化功能。
• 研究高可用方案：虽然 CasaOS 本身不直接提供，但你可以学习如何使用 Docker Swarm 或 Kubernetes 管理多台设备上的容器，向更高级的部署模式迈进。

无论是让旧硬件焕发新生，还是构建一个完全受自己掌控的数字家园，CasaOS 都是一个非常出色的起点。建议收藏本文，在部署和配置过程中随时参考。