Skip to content

🚀 使用 Docker Compose 部署 Homarr（轻量级服务仪表盘）

🚀 使用 Docker Compose 部署 Homarr

Homarr 是一个现代化、自托管的导航仪表板，它通过简洁直观的界面帮助您整合和管理所有的自托管服务与应用。使用 Docker Compose 部署可以大大简化安装过程，并确保环境一致性。

📝 项目简介

Homarr 是一个轻量级、高度可定制的浏览器主页，专为家庭服务器和自托管环境设计。它允许您通过一个统一的仪表板访问和管理所有服务。

核心特点：

  • 高度可定制：通过广泛的拖放网格系统，可以自由调整布局
  • 应用集成：与您喜爱的自托管应用程序无缝集成，支持状态监控
  • 丰富的组件：提供应用、小组件和分类容器，满足不同展示需求
  • 安全管理：提供先进的密钥管理系统，增强安全性
  • 图标丰富：内置图标选择器包含 7000 多个图标
  • 多平台支持：与任何主要消费类硬件兼容（x86、Raspberry Pi 等）

🔧 部署前准备

系统环境要求

  • 操作系统：支持 Linux、Windows、macOS
  • Docker 引擎：版本 20.10+
  • Docker Compose：版本 2.0+
  • 硬件资源：
  • 内存：至少 512MB
  • 存储空间：至少 1GB 可用空间

环境检查

  1. 检查 Docker 服务状态 bash systemctl status docker 确保 Docker 服务处于 active (running) 状态

  2. 检查 Docker 版本 bash docker --version

  3. 创建部署目录

   mkdir -p /home/compose/homarr && cd /home/compose/homarr

⚙️ 配置 Docker Compose

准备配置文件

创建 docker-compose.yml 文件：

#version: "3.8"

services:
  homarr:
    container_name: homarr  # 容器名称，便于管理（如停止/查看日志）
    # Homarr 官方最新镜像（ghcr 仓库，稳定更新，推荐使用）
    image: ghcr.io/homarr-labs/homarr:latest
    volumes:
      # 1. Docker 集成（可选）：挂载宿主机 docker.sock，用于识别本地 Docker 容器
      - /var/run/docker.sock:/var/run/docker.sock  # 可选，用于 Docker 集成
      # 2. 配置存储（必需）：本地 ./appdata → 容器 /appdata，存储仪表盘配置
      - ./appdata:/appdata
    environment:
      # 安全加密密钥（必需！替换为自己生成的密钥，用于加密敏感配置）
      - SECRET_ENCRYPTION_KEY=cf9f05673b0107add5be486501dec970657f3ddaa5598e82648801a1e410702c
      # 注释：PUID/PGID 用于指定容器用户权限，新手无需配置，避免权限冲突 #不建议上权限
      #- PUID=1000
      #- PGID=1000
    ports:
      # 端口映射：主机 7575 → 容器 7575（Web 仪表盘访问端口）
      - '7575:7575' 
    restart: unless-stopped  # 容器退出后自动重启（除非手动停止，保障服务稳定）

关键配置说明

  1. 镜像选择：使用官方 ghcr.io/homarr-labs/homarr:latest 镜像

  2. 端口映射：7575:7575 将容器内的 7575 端口映射到宿主机的 7575 端口

  3. 数据持久化：

  4. ./appdata:/appdata：Homarr 配置数据目录

  5. /var/run/docker.sock:/var/run/docker.sock：可选，用于 Docker 集成

  6. 安全配置：

  7. SECRET_ENCRYPTION_KEY：用于加密敏感数据的密钥，可以使用 openssl rand -hex 32 生成

🚀 启动与验证

启动服务

docker compose up -d

验证服务状态

  1. 检查容器运行状态 bash docker ps 应该看到 homarr 容器处于 Up 状态

  2. 查看服务日志 bash docker compose logs -f

  3. 访问 Web 界面 在浏览器中访问 http://你的服务器IP:7575

🔌 基础配置与使用

初始界面熟悉

成功访问后，您将看到 Homarr 的默认界面，通常包含： - 顶部搜索栏 - 时间与天气小组件（如已启用） - 空的应用程序区域等待配置

添加应用程序

  1. 进入编辑模式

  2. 点击界面右上角的编辑图标进入编辑模式

  3. 添加应用磁贴

  4. 点击添加磁铁图标，在弹出框中选择"应用"

  5. 填写应用信息：

    • 通用：应用名称、描述
    • 行为：应用URL、在新标签页打开
    • 外观：图标URL或从图标库选择
    • 集成：API设置（如支持）

  6. 图标选择技巧

  7. Homarr 集成了图标库搜索功能
  8. 可以输入关键词自动搜索并下载图标
  9. 支持自定义图标URL

添加小组件

Homarr 提供多种内置小组件： - 日期时间显示 - 天气信息 - 系统状态 - 搜索栏

添加方法：编辑模式下点击添加磁铁，选择组件类型。

创建分类容器

分类可以理解为容器，用于组织相关应用和小组件： 1. 编辑模式下点击添加磁铁 2. 选择分类类型 3. 输入分类名称 4. 将应用拖放到分类中

界面个性化设置

Homarr 支持多种个性化选项： - 主题选择：明亮/暗黑模式 - 布局调整：网格大小、间距 - 搜索引擎：自定义默认搜索引擎

🛠️ 维护与管理

日常维护操作

1.服务启停

   # 停止服务
   docker compose down

   # 启动服务
   docker compose up -d

2.数据备份

   # 备份 Homarr 配置数据
   tar -czf homarr-backup-$(date +%Y%m%d).tar.gz ./appdata

3.服务更新

   # 进入部署目录
   cd /home/compose/homarr

   # 拉取最新镜像并重启
   docker compose pull
   docker compose down
   docker compose up -d

监控与日志

  1. 查看实时日志 bash docker compose logs -f

  2. 监控资源使用 bash docker stats homarr

🐛 常见问题排查

1. 无法访问 Web 界面

问题现象：浏览器访问 http://IP:7575 无响应

解决方案： - 检查防火墙设置： bash # 开放 7575 端口 ufw allow 7575 - 验证容器状态：docker ps - 查看服务日志：docker compose logs

2. 应用图标无法显示

问题现象：添加的应用图标显示为默认图标或无法加载

解决方案： - 检查图标URL是否可访问 - 尝试使用 Homarr 内置图标库搜索替换 - 确认网络连接正常

3. Docker 集成不工作

问题现象：无法获取 Docker 容器状态信息

解决方案： - 确认 /var/run/docker.sock 挂载正确 - 检查 Docker 守护进程状态 - 验证文件权限

4. 配置丢失问题

问题现象：重启后配置恢复默认

解决方案： - 确认数据卷挂载正确 - 检查 ./appdata 目录权限 - 验证磁盘空间充足

通过本教程，您应该已经成功部署并配置了 Homarr 个人导航页。Homarr 的直观界面和丰富定制功能将极大提升您的自托管服务管理体验。如果在使用过程中遇到其他问题，可以参考 Homarr 官方文档或社区支持资源。