1. 项目概述与定位如果你和我一样家里或者公司里跑着一堆自托管服务从媒体库的Plex、Jellyfin到自动化下载的Sonarr、Radarr再到网络管理的Pi-hole那么你肯定也面临过同一个烦恼管理入口太分散了。每次想检查下载进度、看看媒体库状态或者重启某个容器都得在浏览器里打开一堆标签页记住一堆不同的IP和端口。Homarr的出现就是为了解决这个痛点。它本质上是一个现代化的、高度可定制的仪表盘或者叫“主页”旨在把你所有的自托管应用和服务集中到一个美观、统一的Web界面里进行管理和监控。这个项目最初由开发者ajnart发起在社区获得了相当高的关注度。不过根据你提供的资料这个初始仓库ajnart/homarr目前已经归档项目已经整体迁移到了新的组织homarr-labs/homarr下并进入了v1.0及以上的新版本时代。这意味着虽然旧版本理论上还能用但已经不再维护和更新了。任何新用户或者老用户想要获得新功能、安全补丁和持续支持都应该转向新的官方仓库。这其实是一个开源项目走向成熟和正规化的常见路径由一个个人项目演变为一个由团队维护的社区项目。Homarr的核心价值在于“聚合”与“交互”。它不仅仅是一个简单的书签导航页。通过其丰富的“集成”功能Homarr能够与你后端的应用进行API通信实时获取数据并允许你执行一些操作。比如你可以在Homarr的界面上直接看到Sonarr里正在排队的下载任务或者Pi-hole今天拦截了多少广告请求甚至可以直接点击按钮触发Radarr搜索电影。这种深度集成让它从一个静态的“门户”变成了一个动态的“控制中心”。2. 核心架构与技术栈解析要理解Homarr为什么强大以及如何工作我们需要拆解一下它的技术构成。这不仅能帮助我们更好地部署和维护它也能在遇到问题时知道从哪里入手排查。2.1 前端框架React与Next.js的组合拳Homarr的界面是基于React和Next.js构建的。React负责构建用户界面的组件提供了高效的UI渲染和状态管理能力。而Next.js作为React的框架为Homarr带来了几个关键优势服务端渲染与静态生成Next.js允许在服务器端预先渲染页面这对于提升首屏加载速度、改善SEO虽然对内部仪表盘意义不大以及提供更稳定的初始体验非常有帮助。当用户打开Homarr仪表盘时页面结构已经由服务器生成好然后再由浏览器接管进行交互体验上会感觉更快。API路由Next.js内置了创建API端点的能力。这意味着Homarr的后端逻辑比如代理请求到你的Sonarr、Radarr或者处理认证可以直接用TypeScript/JavaScript编写并与前端代码共存在同一个项目中简化了部署和架构。开发体验集成了热重载、路由系统等提升了开发效率。选择这个技术栈说明Homarr追求的是一个现代、高性能且开发体验良好的前端应用这与它想要呈现的“ sleek, modern dashboard ”时尚、现代的仪表盘定位是吻合的。2.2 UI组件库Mantine的魅力如果你仔细看过Homarr的界面会发现它的设计非常协调、美观组件风格统一。这很大程度上归功于它使用了Mantine这个React组件库。Mantine不是一个简单的UI套件它提供了一整套包括组件、钩子hooks和工具在内的完整体系。对于Homarr这样的项目使用Mantine带来了以下好处开发效率丰富的预制组件按钮、模态框、网格、卡片等让开发者可以快速搭建界面无需从零开始写样式和交互逻辑。可定制性与主题Mantine支持深色/浅色主题切换并且定制化能力很强。这解释了为什么Homarr本身也拥有强大的主题自定义选项用户可以根据喜好调整配色、圆角等。可访问性Mantine内置了对可访问性a11y的支持这对于任何希望更普适的Web应用来说都是一个加分项。与Next.js集成良好两者都是现代React生态中的佼佼者配合起来很顺畅。所以当你拖动Homarr的小部件Widget时那种流畅感或者切换主题时整个界面瞬间变换的协调性底层都有Mantine的功劳。2.3 后端与部署核心Docker化与无状态设计Homarr强烈推荐并通过Docker进行部署这几乎是当前自托管服务的事实标准。它的Docker镜像通常基于轻量的Node.js Alpine镜像包含了运行Next.js应用所需的所有环境。这里有一个关键设计理念Homarr本身基本上是一个“无状态”的应用。它的主要状态是什么是你的仪表盘布局、你添加了哪些应用、每个应用的配置如URL、API密钥以及小部件的排列方式。这些数据需要被持久化保存。在Docker部署中这是通过“卷映射”来实现的。你需要将宿主机上的一个目录例如./homarr/data或./homarr/config映射到容器内的数据存储路径通常是/app/data或/app/configs。这样即使你删除并重新创建容器只要卷还在你的所有配置和自定义设置都不会丢失。这种设计也意味着Homarr本身不直接“运行”你的Sonarr或qBittorrent它只是一个“客户端”或“控制面板”。它通过HTTP调用这些服务的API来获取信息和发送指令。因此网络连通性Homarr的容器能否访问到你其他服务的网络是部署时需要重点考虑的问题通常通过Docker自定义网络或主机网络模式来解决。2.4 集成原理API与Widget系统这是Homarr的“智能”所在。它的集成并非魔法而是基于目标应用提供的公开API。配置连接你在Homarr中添加一个“应用”比如Sonarr需要提供其访问地址URL和API密钥。API密钥是Homarr代表你与Sonarr通信的凭证。数据获取Homarr的后端Next.js API路由会定期或在页面加载时向Sonarr的API发送请求例如GET /api/v3/queue来获取下载队列。数据处理与展示收到JSON格式的响应后Homarr的前端逻辑会解析这些数据并将其填充到预先设计好的“Sonarr队列小部件”的模板中渲染出进度条、标题、状态等信息。反向操作同样当你在Homarr的小部件上点击“搜索电影”时前端会触发一个动作后端会向Radarr的API发送相应的POST请求。每个集成都需要Homarr的开发团队针对目标应用的API文档进行适配和开发这就是为什么它的支持列表是逐步扩大的。项目资料中列举了从下载工具、媒体服务器到DNS广告过滤器的广泛支持这正是其核心竞争力的体现。3. 从零开始部署与配置实战了解了原理我们动手把它跑起来。这里我会以最常见的Docker Compose方式为例因为它清晰、可重复并且方便管理多个服务之间的依赖。3.1 基础环境准备首先确保你的服务器上已经安装了Docker和Docker Compose。如果你用的是Synology DSM、unRAID或者QNAP等NAS系统它们通常提供了图形化的Docker管理工具如Container Manager原理相通只是操作界面不同。创建一个专门的工作目录比如~/homarr所有相关文件都放在这里。mkdir -p ~/homarr cd ~/homarr3.2 编写Docker Compose配置文件在~/homarr目录下创建一个名为docker-compose.yml的文件。请注意这里我们使用新的官方镜像ghcr.io/homarr-labs/homarr:latest。version: 3.8 services: homarr: image: ghcr.io/homarr-labs/homarr:latest container_name: homarr restart: unless-stopped ports: - 7575:7575 # 将宿主机的7575端口映射到容器的7575端口 volumes: - ./data:/app/data # 持久化配置数据 # 如果你想自定义图标可以挂载一个图标目录 # - ./icons:/app/public/icons environment: - PUID1000 # 设置容器内运行进程的用户ID请改为你宿主机的用户ID - PGID1000 # 设置容器内运行进程的组ID请改为你宿主机的组ID - TZAsia/Shanghai # 设置时区非常重要保证日志和时间显示正确 # 如果你需要让Homarr访问宿主机网络上的其他服务非Docker服务可以使用host网络模式 # network_mode: host # 更常见的做法是创建一个自定义Docker网络让所有相关容器加入同一网络 networks: - homarr-network # 定义一个自定义网络便于容器间通信 networks: homarr-network: driver: bridge关键参数解析image: 使用新的官方镜像源。ghcr.io是GitHub Container Registry正逐步成为GitHub官方推荐的容器镜像托管地。ports:7575是Homarr默认的Web访问端口。你可以按需修改冒号前的端口号如8080:7575但容器内的端口通常不建议改。volumes:./data:/app/data这是最重要的映射。./data是宿主机当前目录下的data文件夹/app/data是容器内Homarr存放所有配置、数据库文件的地方。务必确保这个目录存在且Docker有读写权限。environment:PUID/PGID: 这用于指定容器以哪个用户/组身份运行防止生成的文件权限混乱。在Linux上可以通过id $USER命令查看你的UID和GID。TZ: 时区必须设置正确否则计划任务、日志时间等都会错乱。networks: 我们创建了一个名为homarr-network的自定义桥接网络。之后你可以将Sonarr、Radarr等其他服务的Docker容器也加入到这个网络中这样它们之间就可以通过容器名直接互相访问例如Homarr容器内可以通过http://sonarr:8989访问Sonarr服务无需知道宿主机的IP更加安全和方便。3.3 启动Homarr服务保存好docker-compose.yml文件后在终端中执行docker-compose up -d-d参数代表“后台运行”。Docker会拉取镜像如果本地没有并启动容器。你可以用以下命令查看日志确认启动是否成功docker-compose logs -f homarr看到没有报错并且有类似Ready on http://localhost:7575的日志输出时就说明启动成功了。现在打开浏览器访问http://你的服务器IP:7575。你应该能看到Homarr的初始化设置界面。3.4 初始设置与基础配置第一次访问Homarr会引导你进行一些基本设置创建管理员账户设置一个用户名和强密码。这是你管理Homarr仪表盘本身的凭证请务必牢记。仪表盘名称给你的这个仪表盘起个名字比如“我的家庭服务器控制台”。初步向导完成账户创建后通常会有一个快速向导让你添加第一个应用或小部件。你可以先跳过我们稍后详细配置。登录后你会看到一个空白的、带有网格线的仪表盘界面。这就是你可以自由发挥的画布。3.5 添加你的第一个应用以Sonarr为例让我们把Sonarr添加到Homarr中并创建一个显示下载队列的小部件。打开侧边栏菜单点击左上角的菜单按钮通常是三条横线或Homarr图标。进入“应用”管理找到并点击“应用”或“Apps”。添加新应用点击“添加应用”按钮。填写应用信息名称Sonarr你可以自定义URL这是关键。如果你的Sonarr也运行在Docker中并且和Homarr在同一个自定义网络homarr-network里你可以直接使用容器名和内部端口例如http://sonarr:8989。这种方式最优雅不依赖宿主机IP且不受防火墙限制。外部URL如果你希望通过Homarr界面点击应用图标后在新标签页打开Sonarr的原生界面可以在这里填写你从外部网络访问Sonarr的地址例如http://nas.local:8989。这是可选的。图标Homarr内置了海量图标库搜索“sonarr”就能找到官方图标。网络保持默认或根据你的网络环境选择。行为可以设置点击图标是打开新标签页External还是在当前页面内嵌打开Iframe后者体验更统一但可能遇到某些网站的X-Frame限制。保存点击保存Sonarr应用图标就会出现在你的仪表盘上。但此时它还只是一个书签。3.6 配置集成与小部件要让Homarr“读懂”Sonarr的数据需要配置集成。编辑Sonarr应用在“应用”列表里找到刚刚添加的Sonarr点击编辑铅笔图标。找到“集成”设置在编辑界面中找到“集成”或“Integration”选项卡。输入API密钥你需要从Sonarr的Web界面获取API密钥。在Sonarr中进入设置 - 通用找到API密钥并复制。将复制的API密钥粘贴到Homarr的对应输入框中。URL字段通常会自动填充为你之前填写的应用URL确保正确。测试连接保存集成设置前通常会有个“测试连接”按钮。点击它如果Homarr能成功通过API密钥访问到Sonarr会显示连接成功的提示。这一步非常重要能避免后续小部件不工作的困扰。保存集成测试成功后保存Sonarr应用的更改。现在Sonarr的集成已经激活。你可以回到仪表盘主界面。添加小部件在仪表盘空白处点击“添加小部件”或类似的按钮。选择小部件类型在部件库中找到“Sonarr”相关的部件例如“Sonarr - 下载队列”、“Sonarr - 即将播出”等。配置小部件将小部件拖放到网格上后可能需要你选择这个小部件关联哪个应用选择你刚配置的Sonarr实例并可以设置一些显示选项如刷新间隔、显示条目数量等。完成保存后这个小部件就会开始从Sonarr拉取数据并动态显示了。你可以看到当前正在下载的任务列表、进度和状态。重要提示对于Radarr、Lidarr、qBittorrent等服务的添加和集成配置流程完全类似先添加应用填写正确的内部URL然后在应用的集成设置里填入对应的API密钥。每个服务的API密钥获取位置略有不同但通常都在其Web界面的设置菜单里。4. 高级配置与深度定制技巧基础功能用起来后你可以通过Homarr丰富的设置把它打造成完全属于你的控制中心。4.1 仪表盘布局与网格系统Homarr采用了一个灵活的拖放网格系统。你可以自由拖拽任何应用图标或小部件都可以用鼠标拖拽到任意位置。调整大小将鼠标悬停在小部件边缘会出现拖拽手柄可以调整其占用的网格宽度和高度。多页面支持你可以创建多个仪表盘页面比如一个“媒体中心”页面放Plex、Sonarr、Radarr一个“网络工具”页面放Pi-hole、路由器管理。通过顶部的标签页或侧边栏进行切换。网格密度调整在设置中可以调整整个仪表盘的网格密度即每个网格单元的像素大小从而控制整体的紧凑或宽松程度。4.2 主题与外观定制进入“设置” - “外观”你可以进行深度定制颜色主题在预置的浅色、深色主题间切换或者开启“跟随系统”自动切换。自定义主题高级选项允许你自定义主色调、强调色、背景色、文字颜色等打造独一无二的视觉风格。背景图像支持上传图片或设置网络图片作为仪表盘背景提升美观度。界面元素可以隐藏侧边栏、调整边框圆角、阴影等细节。4.3 安全性增强配置虽然Homarr是内部服务但安全依然重要。反向代理与HTTPS强烈建议不要直接暴露7575端口到公网。应该使用Nginx、Caddy或Traefik等反向代理工具为Homarr配置一个子域名如homarr.yourdomain.com并启用HTTPS使用Let‘s Encrypt免费证书。这能加密通信防止中间人攻击。在反向代理配置中需要正确代理WebSocket连接如果Homarr有实时功能并设置好正确的Host头。环境变量配置在Docker Compose中可以通过环境变量设置一些安全相关的选项例如NEXTAUTH_SECRET用于NextAuth.js的加密密钥确保其值足够复杂且唯一。新版本的Homarr可能会在首次运行时提示你生成。访问控制Homarr自身的管理员账户是基础防护。确保密码强壮。如果你的反向代理支持如Nginx的auth_basic可以额外增加一层HTTP基础认证提供双重保护。4.4 与其他服务的网络互通策略这是部署中最容易出问题的环节。Homarr需要能访问到你其他服务的API。最佳实践Docker自定义网络如前面Compose文件所示创建一个自定义网络如homarr-network让Homarr和所有需要集成的服务Sonarr, Radarr, qBittorrent等都加入这个网络。这样在Homarr的应用配置中URL就可以直接使用http://容器名:端口。如果服务不在Docker中如果你的某些服务是直接安装在宿主机上的如Windows上的Plex或者运行在另一个独立的Docker环境中。你需要确保Homarr的容器能访问到那个服务的IP和端口。如果Homarr使用host网络模式那么它可以直接访问localhost:端口。如果Homarr在默认的bridge网络它需要访问宿主机的IP。在Linux Docker中可以使用特殊的DNS名称host.docker.internal来指向宿主机Docker Desktop for Windows/Mac原生支持Linux需高版本Docker或额外配置。或者直接使用宿主机的局域网IP如http://192.168.1.100:32400。注意防火墙确保宿主机的防火墙允许从Docker网桥或Homarr容器IP来的入站连接。4.5 数据备份与迁移你的所有Homarr配置都保存在映射出来的./data目录里。定期备份这个目录就备份了你的整个仪表盘。备份直接打包复制~/homarr/data目录即可。迁移在新服务器上部署Homarr时将备份的data目录放到新的Compose文件同级位置启动容器所有配置就会恢复。版本升级由于项目已迁移到homarr-labs未来升级应使用新镜像。通常小版本升级如1.1到1.2直接拉取新镜像重启容器即可配置是向前兼容的。但如遇大版本升级如从旧的ajnart版本迁移到v1.0必须严格遵循官方发布的迁移指南因为数据库结构或配置格式可能有重大变化。盲目替换容器可能导致服务无法启动。5. 常见问题排查与实战心得在实际使用中你可能会遇到一些问题。这里我总结了一些常见坑点和解决方法。5.1 小部件显示“无法连接”或“加载失败”这是最常见的问题根本原因在于Homarr无法访问目标服务的API。检查应用配置中的URL这是第一步也是最容易出错的地方。确认Homarr容器内是否能访问这个URL。在Homarr容器内执行命令测试docker exec -it homarr curl http://sonarr:8989/api/v3/system/status?apikeyYOUR_API_KEY请替换为你的真实API密钥。如果返回错误或超时说明网络不通。如果使用容器名确保目标服务如Sonarr和Homarr在同一个Docker网络中并且容器名正确。如果使用IP地址确保IP和端口正确并且从Homarr容器内部可以路由到该地址。检查API密钥确认在Homarr的集成设置中输入的API密钥完全正确没有多余的空格。可以尝试在浏览器中手动访问http://服务地址/api/v3/system/status?apikey你的密钥来验证API密钥是否有效。检查目标服务的API访问限制有些服务如qBittorrent默认只允许来自localhost的API访问。你需要在目标服务的设置中将Homarr容器所在的IP地址或网络段添加到“允许的IP列表”中或者直接关闭IP过滤。检查防火墙确保宿主机和容器网络层面的防火墙没有阻止相关端口的通信。5.2 应用图标点击后无法打开空白或错误Iframe嵌入问题如果你在应用设置中选择了“Iframe”打开方式但目标网站设置了X-Frame-Options: DENY或Content-Security-Policy禁止被嵌入那么页面就会空白。解决方案是改用“External”新标签页打开或者尝试在反向代理层面修改响应头不推荐可能违反安全策略。URL路径问题确保应用配置的“URL”和“外部URL”填写正确。如果服务本身有子路径例如通过反向代理访问URL需要包含完整的路径。5.3 部署后访问非常缓慢首次加载慢Next.js应用在首次冷启动时可能需要一点时间进行构建和优化属于正常现象。后续访问会利用缓存速度很快。小部件数据拉取慢检查每个小部件的刷新间隔是否设置得过短如每秒给后端服务造成压力。对于不常变化的数据如媒体库统计可以设置为30分钟或1小时刷新一次。网络延迟如果Homarr和它要集成的服务物理距离很远或者网络质量差API调用就会慢。尽量让它们部署在同一个局域网内。资源不足检查服务器CPU和内存使用情况。如果资源紧张Docker容器可能会变慢。可以为Homarr容器分配适量的资源限制。5.4 从旧版本ajnart/homarr迁移到新版本homarr-labs/homarr根据项目说明这是一个重要的迁移。切勿直接替换镜像标签。停止并备份旧容器首先停止旧的Homarr容器并完整备份其数据卷整个配置目录。仔细阅读官方迁移指南前往homarr.dev官网找到针对从旧版本迁移到v1.0的专门指南Migration Guide。里面会列出所有破坏性变更Breaking Changes和必须执行的手动步骤。准备新环境按照本文前面所述使用新的docker-compose.yml文件指向ghcr.io/homarr-labs/homarr:latest镜像。处理数据迁移官方指南可能会要求你运行一个数据迁移脚本或者手动修改某些配置文件格式。务必按步骤操作。启动新容器完成数据迁移后启动新的Homarr容器。验证登录后仔细检查所有已配置的应用、集成和小部件是否工作正常。由于API可能发生变化某些旧的集成配置可能需要调整。5.5 我的个人使用心得与建议从简开始初次部署不要试图一口气添加所有服务。先成功集成1-2个核心服务如Sonarr和Radarr摸清流程和网络配置再逐步添加其他。善用“分类”和“页面”当应用越来越多时管理会变乱。在添加应用时就为其分配好分类如“下载”、“媒体”、“监控”。然后创建不同的仪表盘页面将同类应用放在一起界面会清晰很多。API密钥安全Homarr需要存储众多服务的API密钥。虽然它声称有“高级秘密管理系统”但本质上这些密钥是加密后存在你的数据库文件里的。请确保你的./data目录权限安全仅限运行Docker的用户可读写并且整个服务器环境是可信的。不要将包含这些配置的目录上传到公开的Git仓库。关注更新订阅新仓库的Release页面或Discord频道。活跃的更新意味着新功能、性能改进和安全修复。在更新前养成备份./data目录的习惯。性能考量小部件不是越多越好。每个活动的小部件都会定期向后端服务发起API请求。如果同时监控几十个服务且刷新间隔短可能会对Homarr服务器本身以及你的后端服务造成不必要的负载。只添加你真正需要实时关注的小部件。Homarr的生态还在不断成长新的集成和小部件会陆续加入。把它当作一个需要持续维护和调优的工具花点时间配置好它能极大地提升你管理复杂自托管环境的效率和体验。当所有服务状态一目了然关键操作触手可及时你会觉得这一切的折腾都是值得的。