Homarr HomeLab 仪表板部署教程

Homarr 是一款现代化的 HomeLab 仪表板，专为自托管爱好者设计。它提供了直观的拖拽式界面，可以方便地组织和管理所有自托管服务。Homarr 最大的特色是与 Docker 的深度集成，能够直接在仪表板上管理容器，同时还支持丰富的小部件和应用集成。本文将介绍如何在搬瓦工 VPS 上使用 Docker 部署 Homarr。部署前请确保已安装好 Docker 和 Docker Compose。

一、系统要求

操作系统：Ubuntu 20.04+ 或 Debian 11+。
内存：至少 512MB，建议 1GB。
磁盘：至少 2GB 可用空间。

二、Docker Compose 部署

mkdir -p /opt/homarr/{configs,icons,data}
cd /opt/homarr

cat > /opt/homarr/docker-compose.yml <<'EOF'
version: '3.8'

services:
  homarr:
    image: ghcr.io/ajnart/homarr:latest
    restart: always
    ports:
      - "7575:7575"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /opt/homarr/configs:/app/data/configs
      - /opt/homarr/icons:/app/public/icons
      - /opt/homarr/data:/data
    environment:
      - TZ=Asia/Shanghai
EOF

docker compose up -d

注意：挂载 Docker Socket 是为了让 Homarr 能够读取和管理容器状态。:ro 表示只读挂载，如果需要通过 Homarr 管理容器（启动/停止/重启），则需要去掉 :ro。

三、配置 Nginx 反向代理

cat > /etc/nginx/sites-available/homarr <<'EOF'
server {
    listen 80;
    server_name dash.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:7575;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
EOF

ln -s /etc/nginx/sites-available/homarr /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d dash.yourdomain.com

四、初始化与基本设置

访问 https://dash.yourdomain.com，Homarr 会显示一个空白的仪表板。点击右上角的编辑按钮进入编辑模式，然后可以开始添加应用和小部件。

五、添加应用

在编辑模式下点击 "Add a tile" > "App"，填写应用信息：

App Name：应用显示名称。
Internal URL：应用的内网地址（用于状态检查）。
External URL：点击后跳转的外网地址。
Icon：支持搜索内置图标或上传自定义图标。

Homarr 内置了数百个常见自托管应用的图标，添加应用时只需搜索应用名即可自动匹配图标。

六、Docker 集成

Homarr 与 Docker 深度集成，提供以下功能：

容器状态显示：在应用图标上显示容器运行状态。
容器管理：直接在仪表板上启动、停止、重启容器。
自动发现：自动检测已运行的 Docker 容器并建议添加。

要关联应用与 Docker 容器，在应用设置的 "Integration" 标签中选择对应的容器名称。

七、小部件功能

Homarr 提供了丰富的小部件，在编辑模式中通过 "Add a tile" > "Widget" 添加：

时钟：显示当前时间和日期。
天气：显示当地天气信息。
搜索栏：集成搜索引擎快速搜索。
Docker 状态：显示所有容器的运行状态概览。
系统资源：显示 CPU、内存和磁盘使用率。
RSS 订阅：显示 RSS 源的最新内容。
日历：集成日历显示。

八、拖拽布局

Homarr 的一大亮点是拖拽式布局。在编辑模式下，你可以自由拖动应用和小部件的位置，调整大小，创建分组区域。布局会自动保存，并且支持响应式设计，在不同尺寸的屏幕上自动适配。

九、多面板与用户管理

Homarr 支持创建多个面板（Board），每个面板可以有不同的布局和应用列表。你可以为不同用途创建不同的面板，例如一个用于开发工具，一个用于媒体服务。同时还支持多用户，不同用户可以看到不同的面板。

十、数据备份

Homarr 的配置数据存储在挂载的目录中，备份非常简单：

tar -czf /opt/homarr/backup_$(date +%Y%m%d).tar.gz /opt/homarr/configs/ /opt/homarr/data/ /opt/homarr/icons/

十一、常见问题

Docker 容器状态无法显示

确认 Docker Socket 已正确挂载。检查 Compose 文件中是否有 /var/run/docker.sock:/var/run/docker.sock 这一行。

页面加载缓慢

如果添加了大量应用并启用了状态检查，页面可能加载较慢。可以适当增加状态检查间隔或禁用不需要的应用状态检查。

总结

Homarr 是一款功能丰富且交互友好的 HomeLab 仪表板，拖拽式布局和 Docker 集成让它成为管理自托管服务的得力助手。与 Homer 的极简风格和 Dashy 的配置文件驱动不同，Homarr 更注重可视化操作体验。更多教程请参考：Docker 安装教程、n8n 自动化部署。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的循环折扣。