Homarr部署与配置全攻略：打造一站式个人导航仪表盘

December 6, 2025

你是否厌倦了在浏览器书签和服务器IP地址之间来回切换？Homarr或许正是你需要的解决方案。它是一个设计简洁、轻量级的自托管服务器主页应用，能将你所有的服务集中在一个清爽的界面中，实现一键访问与统一管理。本指南将带你从零开始，手把手完成Homarr的部署与个性化配置，帮你打造一个既美观又高效的个人数字工作台。

Homarr的核心设计理念就是“简化”。它提供了一个高度可定制的仪表盘，让你彻底告别记忆复杂IP和端口的烦恼。无论是家庭实验室的媒体服务器、开发工具，还是各类网络应用，都能在这里找到一席之地。

在开始动手之前，我们先快速了解一下Homarr的主要特性，这能帮助你更好地规划自己的仪表盘：

🖌️ 极致定制化：基于强大的拖放网格系统，你可以像拼图一样自由布局桌面上的每一个元素。
✨ 无缝集成：与Sonarr、Radarr、Plex、Jellyfin等众多流行的自托管应用深度连接，实时显示状态信息。
📌 简易管理：所有配置都通过直观的图形界面完成，无需手动编写繁琐的YAML配置文件。
👤 精细权限控制：内置完善的用户、权限与用户组管理体系，适合团队协作。
👥 企业级认证：支持通过OIDC或LDAP实现单点登录（SSO），方便集成到现有身份体系中。
🙊 安全保障：使用BCrypt和AES-256-CBC加密技术保护你的密码、API密钥等敏感数据。
🕔 实时更新：借助WebSockets、tRPC和Redis，小部件信息（如下载进度、系统状态）可以实时刷新。
🔍 全局搜索：内置快速搜索引擎，不仅能查找Homarr内的应用，未来还能搜索集成服务内的数据。
🦞 海量图标库：内置图标选择器拥有超过11，000个图标，轻松为每个服务找到最匹配的视觉标识。
🚀 广泛兼容：支持x86、ARM（如树莓派）等多种硬件架构，可在Windows、Linux、TrueNAS、Unraid等系统上运行。
🖥️ 云原生支持：通过官方提供的Helm chart，可以轻松在Kubernetes集群中部署和扩展，便于运维。

部署指南：使用Docker Compose快速安装

对于大多数用户而言，使用Docker Compose是部署Homarr最快捷、最推荐的方式。你只需要一个简单的配置文件，即可完成所有环境搭建。

首先，在你希望安装的目录下（例如 ~/homarr），创建一个名为 docker-compose.yml 的文件，并将以下配置内容复制进去。

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    container_name: homarr
    ports:
      - 7575:7575
    environment:
      - SECRET_ENCRYPTION_KEY=7a2f4d8c1e3b596d0a8f2c4e6b0d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d
    volumes:
      - ./appdata:/appdata
    restart: unless-stopped

关键配置参数说明（更多高级选项请查阅官方文档）：

SECRET_ENCRYPTION_KEY（环境变量）：这是用于加密Homarr内部敏感数据的密钥。请务必将其替换为你自己生成的、安全的64位十六进制字符串。你可以使用命令行工具（如 openssl rand -hex 32）来生成一个。
./appdata:/appdata（卷映射）：这个映射至关重要，它将容器内的配置数据持久化保存到宿主机的 ./appdata 目录下。即使容器被删除或重建，你的所有设置（如面板、应用、用户）都不会丢失。
/var/run/docker.sock（可选映射）：如果你希望Homarr能够直接查看和管理宿主机上的其他Docker容器（例如在面板中显示容器状态），可以将此套接字文件映射进容器。请注意，这会带来一定的安全风险，因为它赋予了Homarr容器很高的Docker守护进程权限，请仅在可信环境中考虑使用。

配置文件准备就绪后，打开终端，进入该文件所在目录，运行以下命令即可启动Homarr服务：

docker-compose up -d

看到“Done”提示后，部署就完成了，整个过程通常只需几秒钟。

配置与美化：从零开始设置你的导航页

服务启动后，真正的乐趣才刚刚开始。下面我们一步步完成初始设置，打造属于你的专属导航页。

初始访问 打开浏览器，在地址栏输入 http://你的服务器IP地址:7575，就能看到Homarr的欢迎界面了。
创建管理员账户
- 语言与主题：首次进入会提示选择语言。为了获得更舒适的视觉体验，建议先点击右上角的主题图标，切换到“暗黑”模式。
- 注册账户：系统会引导你创建第一个管理员用户。请按要求填写用户名、邮箱和密码，这个账户将拥有最高管理权限。
- 隐私设置：在接下来的隐私设置页面，你可以根据个人意愿，取消勾选“分享匿名分析数据以帮助改进Homarr”选项，其余保持默认，然后点击“继续”。
- 完成引导：如果有兴趣，可以点击“阅读文档”深入了解。最后，点击“创建面板”按钮，正式进入Homarr的核心管理界面。
基础设置（切换为中文） 进入后，首先点击左侧边栏底部的齿轮图标进入“设置”。在“常规”选项卡中，将“默认语言”修改为“简体中文”。这样，以后在任何浏览器中打开你的Homarr，都会默认显示中文界面，使用起来更加顺手。
创建第一个导航面板 点击左上角的Homarr logo或“返回”箭头，回到面板管理中心。点击“新建”按钮，为你的导航面板起一个名字（例如“家庭服务器”、“工作台”），然后点击创建。

创建成功后，点击这个面板卡片即可打开它。目前它还是一片空白，等待我们添加内容。
添加应用与配置集成
- 添加应用（快捷方式）：点击左上角头像返回“管理中心”，进入“应用”页面。点击“新建应用”来创建一个服务快捷方式。你需要填写：
  - 名称：如“Jellyfin”、“Portainer”。
  - URL：你的服务访问地址，如 http://192.168.1.100:8096。
  - 图标：利用强大的内置图标搜索，输入关键词（如“media”、“docker”）即可找到心仪的图标。
- 配置集成（进阶功能）：在“集成”页面，你可以连接如Sonarr、Radarr、Plex等已部署的服务。成功连接后，Homarr面板上不仅能显示快捷方式，还能展示这些服务的实时状态卡片（如下载队列、最近添加等）。这需要你的对应服务已在运行，并提供了正确的API密钥和地址。
自定义搜索引擎 除了跳转应用，Homarr的顶部搜索栏也非常实用。在“搜索引擎”设置下，点击“创建搜索引擎”。例如添加百度搜索：
- 名称：百度
- 模板URL：https://www.baidu.com/s?ie=UTF-8&wd=%s （其中的 %s 是占位符，代表你输入的搜索关键词）
创建后，记得在“设置” -> “常规”中，将“默认搜索引擎”更改为你刚添加的“百度”。
编辑与美化你的面板 现在，回到我们之前创建的那个空面板，开始真正的布局和美化工作。
- 进入编辑模式：点击面板上的“编辑”按钮，然后选择“添加应用”或“添加项目”。你可以将之前在“应用”页面创建好的快捷方式拖拽到面板的任意位置，也可以在这里直接创建新的应用。
- 自由调整布局：
  - 调整大小：鼠标悬停在应用卡片的右下角，会出现拖拽手柄，拖动即可改变卡片尺寸。
  - 移动位置：长按卡片并拖动，可以将其放置到网格的任何位置。如果发现长按无法移动，先尝试拖动调整一下卡片大小，然后再进行移动操作，这个交互逻辑有时需要适应一下。
- 添加功能组件：除了应用快捷方式，Homarr还提供了丰富的“项目”组件来增强仪表盘功能。例如，你可以添加“日期与时间”、“天气”（需要配置API）、“系统资源监控”等小部件。部分高级组件（如媒体库统计）需要先配置好对应的集成。
重要提示：完成所有编辑后，务必点击页面上的“保存”按钮，否则更改会丢失。
- 个性化面板设置：点击面板上的“设置”按钮（齿轮图标），你可以：
  - 修改面板的标题和描述。
  - 上传自定义的LOGO图标，让面板更具个人特色。
- 更换背景壁纸：在面板设置中，找到“背景”选项。你可以上传自己喜欢的图片作为壁纸，并实时调整背景的透明度、模糊度，以达到最佳的视觉效果，让实用性与美观性并存。
下图展示了一个切换到浅色主题，并经过简单美化后的面板效果，看起来已经相当专业了。
- 设置个人偏好：最后，点击右上角的用户头像，进入“偏好设置”。在这里，你可以设定仅对自己生效的选项，例如个人默认的搜索引擎、主题等。