Homer 介绍与选型指南

Homer（bastienwirtz/homer）v26.08.3 认知篇：纯静态 YAML 仪表盘的定位、架构、功能特性、官方快速开始、适用场景与限制，以及与 Heimdall、Dashy、homepage 的量化选型对比（数据为 2026-11-02 GitHub API 实查）。

HomerHomer面板自托管2026/11/03

Homer 介绍与选型指南

目标：回答"Homer 是什么、怎么工作、适合不适合我"，并给出它与同类自托管仪表盘（Heimdall、Dashy、homepage）的量化选型依据。本篇为认知篇，社区数据均来自 2026-11-02 对 GitHub API 与官方仓库的实查；动手部署请转 《Homer Docker Compose 部署指南》。

一、环境信息

项目取值
软件名Homer（bastienwirtz/homer）
本文对齐版本v26.08.3（2026-08-30 发布，CalVer 版本号）
许可证Apache-2.0
主语言 / 前端框架Vue（SPA），构建工具 Vite
官方发行形态静态 HTML/JS 包 + 官方镜像 b4bz/homer（内置 lighttpd）
社区规模（2026-11-02 GitHub API 实查）11,699 stars / 931 forks / 170 open issues / 58 watchers
仓库动态created 2026-06 前（2018-06-14 建仓），pushed_at 2026-11-02，持续活跃
官方演示站https://homer-demo.netlify.app
本系列实测环境Ubuntu 22.04（x86_64），Docker Engine 29.9.2 + Compose v5.6.1，部署细节见部署篇

💡 说明：Homer 与抓包分析工具 SIPCAPTURE Homer 同名不同物，本专栏指前者（自托管仪表盘，仓库 bastienwirtz/homer）。

二、软件概述

Homer 的官方定位一句话即可概括："A dead simple static HOMepage for your servER"——用一份简单的 YAML 配置文件，为服务器 / NAS / 家庭实验室做一块"所有服务尽在掌握"的入口面板。作者 bastienwirtz（Bastien Wirtz），2018 年 6 月建仓，至今由个人主导 + 社区贡献持续维护，是 awesome-selfhosted 仪表盘类目的常客。

它的设计哲学与重量级面板相反：没有任何后端。整个产品编译后就是静态 HTML/JS/CSS，由任意 HTTP 服务器（官方镜像内置 lighttpd）直接发给浏览器；浏览器加载页面后再去拉 assets/config.yml，在客户端解析 YAML 并渲染出卡片。因此官方徽章自称 "speed: blazing 🔥"、"Low / No maintenance"——没有数据库要迁移、没有运行时依赖要打补丁，升级即换一个静态包。

两个与生俱来的约束要先知道：

  • 它是纯静态 WebApp，必须经 HTTP 服务器访问，直接双击打开 index.html（file:// 协议）无法工作；
  • 它不提供任何鉴权能力，访问控制交给前置反向代理（Nginx / Caddy / Authelia 等）或网络隔离。

三、核心架构

Homer 的运行链路短到可以画成一行：

浏览器 ──GET /──> 静态资源(Vue SPA, 由 lighttpd/nginx/任意HTTP服务器发送)
浏览器 ──GET /assets/config.yml──> YAML 配置(你维护的唯一状态文件)
浏览器 ──(可选)直连各服务 API──> 智能卡数据(PiHole/Proxmox/Ping...)

关键点逐个说明：

  1. 前端单页应用：Vue 3 编写，Vite 构建为带哈希指纹的静态 bundle（实测产物如 resources/index-C32yDzkE.js），页面骨架只有一个 <div id="app-mount">，其余全由 JS 渲染。
  2. 配置即数据：config.yml 是唯一配置来源，运行时由浏览器 fetch 后解析。改配置不需要重启任何进程，刷新浏览器即生效（热更新行为实测见配置篇）。
  3. 智能卡在浏览器端直连目标 API：type: PiHole、type: Proxmox 等卡片由浏览器直接向目标服务发请求。跨域时受 CORS 约束（这是它与服务端代理型面板的本质差异，见第七章对比）。
  4. PWA 可安装：内置 service worker 与 manifest.json，可安装为桌面/手机应用，离线时仍能显示上次缓存的面板。
  5. 发行载体极轻：官方镜像 b4bz/homer 静态包内容体积仅数 MB 级（本系列部署篇有逐层实测回显），常驻内存约 1 MiB 量级，树莓派级硬件即可承载。

💡 技术拓展：自托管仪表盘的三种典型架构路线——

路线代表特点代价
纯静态 SPA + YAML（Homer、Flame）Homer无后端无数据库，最轻、免维护智能卡受浏览器 CORS 限制，无服务端能力
服务端渲染 + 数据库（Heimdall）HeimdallGUI 配置，功能扩展走服务端需要 PHP + 数据库，升级有迁移成本
服务端代理 + YAML（homepage、Dashy 部分能力）homepage服务端代拉 API，天然绕 CORS，集成最多常驻进程重，需维护更多运行状态

本文主角 Homer 属第一路线：把"轻"和"零维护"做到极致，代价是把跨域取数问题留给使用者（反代加头或同域部署）。

四、功能特性

对照官方 README 的 Highlights 逐项展开：

特性说明
单文件 YAML 配置所有页面、分组、卡片、主题、颜色集中在一份 config.yml，支持 YAML 锚点复用（官方 tips 收录）
模糊搜索内置 fuzzy search，keywords 字段可加隐藏关键词；快捷键 / 开始搜索、Esc 退出、Enter 打开首个结果、Alt+Enter 新标签打开
多页面顶部链接 url: "#page2" 即加载 assets/page2.yml，以主配置为基底做字段覆盖，可无限扩展页面
智能卡 50+type 字段启用特定服务组件（customservices.md 列约 50 种）：PiHole、Proxmox、Portainer、Uptime Kuma、Glances、OpenWeatherMap、qBittorrent、Immich、Seerr（v26.08.3 新增）等，展示状态点、徽标计数、RTT 等
Ping 连通卡type: Ping 对任意 URL 发 HEAD/GET 探测并显示往返时延，可自定义成功状态码与超时
主题与样式定制内置 default / walkxcode / neon 主题 + 社区主题（Catppuccin、Dracula 等）；colors: 键或 CSS 变量逐色覆盖；stylesheet: 挂自定义 CSS；支持背景图
连通性检测connectivityCheck: true 周期性 HEAD 探测面板自身，VPN/隧道断开时给出提示；配合鉴权代理可在会话过期时自动重载页面
外部配置externalConfig: 指向远端 YAML URL，多实例共享同一份配置源
布局控制columns（1/2/3/4/6/12 或 auto）+ `layout: columns
PWA 安装可安装为独立应用，图标与名称在 assets/icons、assets/manifest.json 中替换
消息横幅message: 支持固定文案、HTML 内容，或从任意 JSON 端点拉取并字段映射（官方示例接 chucknorris.io 新闻/笑话）

⚠️ 注意：config.yml 会原样暴露在 http://<你的面板>/assets/config.yml。写进配置的 API Key 对所有能访问面板的人可见——官方文档明确要求：要么给面板套鉴权，要么用代理（如官方推荐的 CORSair）在服务端注入凭据。

五、快速开始（官方最小示例）

以下三种启动方式均摘自官方 README（Get started 一节），是官方推荐形态；逐参数详解见配置篇，生产级 Compose 编排见部署篇。

方式一：Docker 单命令

# 先确保本地配置目录存在
mkdir -p /opt/homer/assets
docker run -d \
  --name homer \
  -p 8080:8080 \
  --mount type=bind,source="/opt/homer/assets",target=/www/assets \
  --restart=unless-stopped \
  b4bz/homer:latest

容器默认以 uid/gid 1000 运行，需保证挂载目录属主匹配（chown -R 1000:1000 /opt/homer/assets）；INIT_ASSETS=1（默认）时会在空目录里自动落一份示例配置。

方式二：docker-compose

services:
  homer:
    image: b4bz/homer
    container_name: homer
    volumes:
      - /opt/homer/assets:/www/assets
    ports:
      - 8080:8080
    user: 1000:1000
    environment:
      - INIT_ASSETS=1
    restart: unless-stopped

方式三：静态包（无 Docker）

wget https://github.com/bastienwirtz/homer/releases/latest/download/homer.zip
unzip homer.zip -d homer
cd homer
cp assets/config.yml.dist assets/config.yml
python3 -m http.server 8010   # 或任意 Web 服务器托管

启动后访问 http://<服务器IP>:8080（或 8010），看到示例卡片即成功。三个官方环境变量补充：SUBFOLDER=/homer（子路径托管）、PORT（改内部监听端口，默认 8080）、IPV6_DISABLE=1（关闭 IPv6 监听）。

六、适用场景与限制

适合：

  • 家庭实验室 / NAS 的统一入口页：服务几十上百个，用 YAML 集中管理书签 + 状态；
  • 树莓派、小规格 VPS 等资源敏感环境：无后端进程，内存占用 MiB 级；
  • 喜欢 "配置即代码" 的人：一块面板就是一个 git 仓库里的 YAML 文件，可评审、可回滚；
  • 只读展示 + 快捷跳转为主的场景：搜索、书签、少量智能卡足够。

不适合 / 需要权衡：

  • 需要面板自带登录鉴权：Homer 无鉴权，必须外置反代；
  • 需要大量跨域实时状态：浏览器端直连 API 受 CORS 限制，服务多且域名杂时要么统一域名反代、要么逐服务开 CORS、要么上代理；
  • 需要 GUI 点选式编辑：Homer 没有配置界面（官方 tips 建议外接 code-server 远程改 YAML）；
  • 凭据敏感：写进 config.yml 的 API Key 随文件暴露，须配合访问控制；
  • 需要服务端聚合复杂指标（100+ 服务、widget 生态）：那是 homepage/Dashy 的地盘。

七、同类选型对比

2026-11-02 GitHub API 实查 + 官方文档核对，四个主流仪表盘横向对比：

维度HomerHeimdallDashyhomepage
仓库bastienwirtz/homerlinuxserver/Heimdalllissy93/dashygethomepage/homepage
Stars（实查）11,6999,38526,89533,343
Forks9316231,9652,153
Open issues170515—
主语言 / 运行时Vue（纯静态）PHP (Laravel)Vue + NodeJavaScript (Next.js)
许可证Apache-2.0MITMITGPL-3.0
建仓时间2018-062018-012021-022022-08
配置方式单文件 YAMLWeb GUI 点选YAML + UI 编辑器双轨多 YAML（services/widgets/views）
服务集成约 50 种智能卡依赖 PHP support 包50+ 预置 widget100+ 服务 API 集成
取数架构浏览器直连（受 CORS）服务端浏览器直连为主服务端代理（免 CORS，需挂 docker socket 发现）
运行时重量极轻（静态 + lighttpd）中（PHP + 数据库）重（Node 常驻）重（Next.js 服务端）
自带鉴权无有（内置用户体系）有无

版本节奏（官方 releases 实查）：Homer 采用 CalVer（YY.MM.patch），近 15 个月发布 10 个 release（v25.05.2 → v26.08.3），小版本高频、无破坏性大版本，升级心智负担低。

社区评测口径佐证（来源见参考链接）：Heimdall 胜在"零 YAML 纯 GUI"，Homer 胜在"快、简、书签"，homepage 面向 "power user + 100 服务集成"；追求外观定制选 Dashy，追求简单链接页选 Heimdall/Flame。

选型建议（如果…则…）：

  • 如果你的服务都在同一域名/反代之后、只要一块轻量入口板 → Homer；
  • 如果你完全不想碰 YAML、且需要内置登录 → Heimdall；
  • 如果你要重度外观定制与 widget 交互、不介意 Node 运行时 → Dashy；
  • 如果你要 docker label 自动发现 + 服务端聚合大量服务指标 → homepage（注意 GPL-3.0 与凭据落服务端配置文件）。

八、参考链接

Homer 介绍与选型指南 - Quzuo