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

December 6, 2025

Homarr 是一个设计简洁、轻量级的服务器主页应用，它能将您所有的自托管服务集中在一个界面中，实现便捷的访问与管理。本指南将带你从零开始，轻松完成部署与个性化配置。

Homarr 的核心目标是简化您的数字工作台。它提供了一个高度可定制的仪表盘，让你无需记忆复杂的IP地址与端口，即可快速跳转到常用的服务页面。

该应用拥有以下主要特性：

🖌️ 极致定制化：基于强大的拖放网格系统，自由布局你的桌面。
✨ 无缝集成：与众多流行的自托管应用程序深度连接。
📌 简易管理：通过直观的图形界面管理应用，告别繁琐的YAML配置文件。
👤 精细权限控制：提供完善的用户、权限与用户组管理体系。
👥 企业级认证：支持通过 OIDC / LDAP 实现单点登录。
🙊 安全保障：使用 BCrypt 和 AES-256-CBC 加密技术保护你的敏感数据。
🕔 实时更新：借助 WebSockets、tRPC 和 Redis，小部件信息实时刷新。
🔍 全局搜索：内置快速搜索引擎，可查找集成服务内的数据或Homarr本身的内容。
🦞 海量图标库：图标选择器内含超过 11，000 个图标，满足个性化需求。
🚀 广泛兼容：支持 x86、树莓派等多种硬件，以及 Windows、Linux、TrueNAS、Unraid 等操作系统。
🖥️ 云原生支持：通过 Helm chart 提供对 Kubernetes 的广泛支持，便于扩展与维护。

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

推荐使用 Docker Compose 部署，这是最便捷的方式。创建一个 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（环境变量）：用于数据加密的密钥，请替换为你自己生成的64位十六进制字符串。
./appdata:/appdata（卷映射）：用于持久化保存Homarr的配置文件。
/var/run/docker.sock（可选映射）：将此套接字文件映射入容器，可使Homarr直接管理主机上的其他Docker容器（需注意安全风险）。

配置完成后，在终端中运行 docker-compose up -d 命令即可启动服务。

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

初始访问 在浏览器地址栏中输入 http://你的服务器IP:7575，即可看到Homarr的初始化界面。
创建管理员账户 首次进入会提示设置语言，为了更好的视觉体验，这里先切换为暗黑主题。接着，系统会引导你创建第一个管理员用户，请按要求填写用户名、邮箱和密码。

隐私设置中，可以取消勾选“分享匿名分析数据”，其余保持默认，点击“继续”。

如有需要，可以点击“阅读文档”深入了解。之后，点击“创建面板”进入核心管理界面。
基础设置 进入管理面板后，首先点击左侧齿轮图标进入“设置”。将默认语言修改为“简体中文”，这样后续在任何浏览器打开都会默认显示中文界面。
创建导航面板 返回面板主页，点击“新建”按钮创建一个导航面板，为其命名后点击创建。

创建成功后，可以点击面板卡片打开它。由于尚未添加任何内容，目前面板是空白的。
添加应用与集成
- 添加应用（快捷方式）：点击左上角头像返回“管理中心”，进入“应用”页面。点击“新建应用”来创建快捷图标。你需要填写应用名称、URL地址（指向你的服务），并可以利用内置的图标搜索功能为其选择一个美观的图标。这里可以创建多个应用作为演示。
- 配置集成（可选）：在“集成”页面，可以连接如Sonarr、Radarr、Plex等容器，使面板能显示这些服务的实时状态和信息卡片，这需要相应的服务已在运行并正确配置。
自定义搜索引擎 在“搜索引擎”下点击“创建搜索引擎”，可以添加如百度等常用搜索。模板URL可参考：https://www.baidu.com/s?ie=UTF-8&wd=%s，其中 %s 代表搜索关键词。

创建后，可以在“设置”中将默认搜索引擎更改为百度。
编辑与美化面板
- 添加元素：回到之前创建的空面板，点击“编辑”按钮，然后选择“添加应用”或“添加项目”。将之前创建的应用拖入面板中，也可以在此处直接创建新应用。
- 调整布局：点击应用右下角可以调整其尺寸，长按并拖动可以自由移动位置。如果长按无法移动，尝试先调整一下大小。
- 添加项目组件：除了应用，还可以添加各种“项目”组件，如日期、天气、系统状态等，部分组件需要对应集成支持。
添加组件后，务必点击“保存”按钮。
- 个性化设置：点击面板上的“设置”按钮，可以修改面板标题、LOGO图标。
- 更换背景：上传喜欢的壁纸作为背景，并可以调整背景的透明度以达到最佳视觉效果。
这是切换到浅色主题并美化后的效果。
- 用户偏好：点击右上角用户头像打开“偏好设置”，可以在此设定个人默认的搜索引擎等选项。