Homarr 介绍与选型指南

目标：回答「Homarr 是什么、架构与功能边界如何、与 Heimdall/Homer/Homepage 等同类面板怎么选」，全部结论以 2026-11-02 实查的官方仓库、发布记录与徽章数据为准，并附本批次部署实测中的架构观察佐证。

一、环境信息

本文不落地部署，只给出溯源口径与版本基准：

⚠️ 网络情况：本批次溯源当日 GitHub 页面直连 GET 超时，releases.atom 与 LICENSE 原文经代理通道获取成功；星数与版本徽章走 shields.io 公开接口。引用数据均可按上表 URL 复核。

二、软件概述

Homarr 是 homarr-labs 维护的自托管服务器面板 / 起始页（dashboard & startpage）：把散落在家庭实验室或小型机房里的自托管服务（下载器、媒体服务器、监控、容器本身）聚合到一个可拖拽的看板页面上，提供应用卡片、状态探活、搜索入口、服务集成与轻量管理操作。

与「只读起始页」类工具不同，Homarr 是一个带用户体系与后端 API 的完整 Web 应用：

• 内核：TypeScript + Next.js 16.4.2（standalone 模式），内置 nginx 1.30.6 反向代理与 Redis 8.8.0（实测首启日志可见三者依次拉起）；
• 存储：默认 SQLite（/appdata/db/db.sqlite），可选外部 PostgreSQL；
• 接口面：tRPC（应用内部全量）+ REST API（规范版本 1.1.0，实测 /api/openapi 返回 42 个路径）+ MCP 端点；
• 恢复工具：镜像内置 homarr recovery CLI（版本 1.0.0），处理 Web 界面无法完成的账号/集成恢复操作；
• 许可：Apache-2.0，可自由商用与二次分发。

一句话定位：给「跑了一堆 Docker 服务、有家人/团队共用需求」的自托管用户，提供一个带权限体系的可管理面板，而不是又一张静态书签页。

三、核心架构

实测部署（Ubuntu 24.04.5 + Docker Compose，v2.10.1）观察到的进程结构：

entrypoint.sh → run.sh
  ├─ 1. DB 迁移（drizzle，按 $DB_DIALECT 选择 sqlite/postgresql 迁移包）+ 种子数据
  ├─ 2. nginx（监听 7575，按 IPv6/可信代理配置生成）
  ├─ 3. 内置 Redis 8.8.0（standalone, 6379；可换外部 Redis）
  └─ 4. Next.js server.js（监听 3000）+ WebSocket（3001）

配置模型是选型时最需要理解的取舍：

• 启动行为由环境变量控制（加密密钥、日志级别、数据库/Redis 驱动、Docker 端点等，详见《Homarr 2.10.1 配置参数详解》）；
• 业务配置（看板布局、应用、集成、用户、分组、服务器设置）全部存数据库、走 GUI 管理，没有业务配置文件；
• 集成里的凭据用 SECRET_ENCRYPTION_KEY 加密落库，该密钥丢失则已存集成凭据不可解。

💡 技术拓展：自托管面板的配置存储形态主要有三类——

形态	代表	特点	取舍
YAML 文件	Homer、Homepage	改文件即生效，git 友好	无多用户/权限，改错 YAML 整站不可用
数据库 + GUI	Homarr、Heimdall	在线编辑、权限体系、API 可自动化	备份要导数据库，配置文件不可读
纯环境变量	部分极简单页工具	部署最简	表达能力弱

Homarr 选择「数据库 + GUI」，换来多用户、细粒度权限与 REST/tRPC 自动化能力，代价是业务配置没有可手改的文件。

四、功能特性

实测首启种子日志（全新数据目录）确认的出厂内容：

Created group 'everyone' through seed
Created 3 default search engines through seeding process
Created 4 default apps through seeding process
Created 5 bundled custom widgets through seeding process
Placed 7 widgets on board

在此之上的主要能力（官方文档 + 本批次实测）：

1. 多看板与拖拽编辑：v2 采用 200×200 逻辑像素网格整板缩放，每板含 Base 与 Mobile 两套布局与断点体系；
2. 用户/分组/权限：细粒度权限位（board-create、integration-use-all 等 20+ 项，实测 session 接口返回），默认 everyone 组；支持 credentials 登录、LDAP 与 OIDC 单点登录（实测 /api/auth/providers 返回 credentials/ldap）；
3. 服务集成：面向 Sonarr/Radarr/qBittorrent/Immich/Pi-hole 等自托管服务的 integration 体系，保存凭据、连接验证、widget 数据源与统一代理调用（POST /api/integrations/request）；
4. Docker/Kubernetes 集成：挂载 socket 或配置 TCP 端点后自动发现服务、面板内启停容器（ENABLE_DOCKER/ENABLE_KUBERNETES 控制）；
5. 搜索：默认 3 个搜索引擎、DDG bangs、可配置默认引擎；
6. Workshop 与自定义组件：内置 5 个 bundled 自定义组件，Workshop 生态提供社区组件仓库与 AI 辅助编写（Custom Widget authoring）；
7. 备份与恢复：Management → Tools → Backup 一键导出 zip（实测导出 2 457 332 字节完整包），支持导入迁移；
8. 自动化接口：REST API（ApiKey 头 <id>.<token> 认证）+ tRPC + MCP 端点；
9. onboarding 向导：start → user →（group）→ setup → finish 五步初始化，创建首位管理员与首个看板。

五、快速开始（最小可用示例）

官方推荐的 Docker Compose 最小形态（完整实测流程、secrets 注入、自定义网络与排障实录见《Homarr Docker Compose 部署指南》）：

# 1. 生成 64 位 hex 加密密钥（必需，官方指定生成方式）
$ openssl rand -hex 32
f7fdf89ffeec565651c15cd0908000bfe8b33a133e6ad427f439554a86da4ab4

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:v2.10.1
    restart: unless-stopped
    ports:
      - '7575:7575'
    volumes:
      - ./appdata:/appdata
    environment:
      - SECRET_ENCRYPTION_KEY=<上一步生成的 64 位 hex>

# 2. 启动后浏览器访问 http://<服务器>:7575，跟随向导创建管理员与首个看板
$ docker compose up -d

首启自动完成迁移与种子（实测约 2 秒健康检查通过），无需任何手工初始化数据库。

六、适用场景与限制

适用：

• 家庭实验室 / NAS 上 10~100 个自托管服务的统一入口与状态看板；
• 需要多用户（家人、团队）分权查看/编辑看板的场景——同类工具里几乎唯一内置用户/分组/权限模型的；
• 需要在面板里直接管理 Docker 容器（启停、查看日志）的运维入口；
• 需要 API/MCP 自动化批量建板、建集成的场景。

限制（选型前必读，均来自官方文档或实测确认）：

1. v2 不支持 MySQL：v1 的 MySQL 安装必须先转换到 SQLite 才能升级 v2（启动脚本对 mysql 直接拒绝并退出）；
2. SECRET_ENCRYPTION_KEY 必需且不可更换：缺失时应用报环境变量校验错误、页面 500（实测行为，官方文档描述为「容器退出」，实际进程存活但服务不可用）；更换密钥后已存集成凭据无法解密；
3. v1→v2 布局迁移有代价：v2 固定 200×200 逻辑像素网格，迁移后的 12 列布局组件会变小；调整列数可能重排/位移组件，官方建议改列数前先备份；
4. 外部 Redis 不被 Proxmox 社区脚本支持（官方文档明示，Docker/Compose 形态不受影响）；
5. recovery CLI 定位是「恢复」不是「自动化」：官方明确它不是应用 API，批量操作应走 REST/MCP；且访问数据库的子命令存在输出后进程不退出的怪癖（实测，见《Homarr 2.10.1 常用 CLI 命令与工具详解》）；
6. 单实例架构：无集群/多活模式，高可用需外部数据库+外部 Redis 配合编排层自愈，官方未提供集群方案。

七、同类选型对比

四个主流自托管面板量化对比（星数/版本/发布时间/许可证均 2026-11-02 实查 shields.io 徽章与 GitHub releases.atom/LICENSE 原文；技术栈与配置形态来自各自官方文档）：

解读与选择建议：

• 星数与功能完备度在本组里不成正比：Homepage/Homer 星数高，是因为「零后端、打开即用」的静态起始页受众更大；Homarr 星数最少但发版最勤（17 天 5 版）、功能面最宽。
• 只要一张书签页、单用户 → Homer（改 YAML 最直观）或 Homepage（widget 生态最丰富）；
• PHP/Laravel 栈、接受无认证 → Heimdall（老牌，但迭代明显放缓，2025-09→2026-09 才两个小版本）；
• 需要多用户分权、面板内管 Docker、要 REST/MCP 自动化 → Homarr 是本组唯一同时满足三项的；
• 企业/合规分发注意许可证差异：Homepage 为 GPL-3.0，其余三者均为宽松许可（Apache-2.0/MIT）。

八、参考链接

• 官网与文档：https://homarr.dev
• GitHub 仓库：https://github.com/homarr-labs/homarr
• 发布记录（Atom）：https://github.com/homarr-labs/homarr/releases.atom
• Docker 安装文档：https://homarr.dev/docs/getting-started/installation/docker
• 环境变量文档：https://homarr.dev/docs/advanced/configuration/environment-variables
• CLI 文档：https://homarr.dev/docs/develop-and-automate/command-line-interface
• API 文档：https://homarr.dev/docs/management/api
• 星数/版本徽章接口：https://img.shields.io/github/stars/homarr-labs/homarr.json 、https://img.shields.io/github/v/release/homarr-labs/homarr.json
• 对比项目仓库：https://github.com/linuxserver/heimdall 、https://github.com/bastienwirtz/homer 、https://github.com/gethomepage/homepage
• 站内相关：《Homarr Docker Compose 部署指南》、《Homarr 2.10.1 配置参数详解》、《Homarr 2.10.1 常用 CLI 命令与工具详解》