Homer：一个用 YAML 文件驱动的极简服务器首页

Homer 解决的是什么问题

自托管用户通常有多个服务，比如 NAS、监控面板、媒体服务器，每个服务的地址和端口都不一样。记住这些地址很麻烦，每次访问都要输入 IP 和端口。Homer 把所有这些入口集中到一个静态页面上，你只需要维护一个 YAML 文件，就能生成一个可搜索、可分组、可定制的导航页。它不连接任何后端，不读写数据库，所有数据都来自一个配置文件。这个定位决定了它的目标用户：那些不想折腾复杂仪表盘的人，只想要一个能用浏览器打开、能快速找到服务的页面。

工作机制：YAML 到静态页面

Homer 的核心机制非常简单。它读取 assets/config.yml 文件，根据其中的内容生成 HTML 页面。这个文件定义了页面标题、服务分组、每个服务的名称、地址和图标。前端使用 Vue 框架，但构建后的产物是纯静态文件，不需要服务器端渲染。这意味着你部署时只需要一个静态文件服务器，比如 nginx 或 python -m http.server。文档明确指出，直接打开 index.html 不会工作，因为浏览器会阻止 file:// 协议下的某些请求。所以你必须把构建好的 dist 目录放到 HTTP 服务器后面。这种设计让 Homer 几乎没有运行时依赖，也意味着它无法动态更新内容，每次修改配置都需要重新构建或者重新加载页面。

部署方式：Docker 与预构建包

Homer 提供两种主要部署方式。第一种是 Docker 容器，命令是 docker run -d --name homer -p 8080:8080 --mount type=bind,source="/path/to/config/dir",target=/www/assets b4bz/homer:latest。这里的关键是把本地配置目录挂载到容器的 /www/assets 目录。容器默认以 uid 和 gid 1000 运行，如果你的配置文件权限不匹配，需要加 --user 参数调整。环境变量 INIT_ASSETS 默认为 1，会在配置目录为空时写入示例配置和图标，方便初次使用。第二种方式是直接下载 release 页面的 homer.zip，解压后把 assets/config.yml.dist 重命名为 config.yml，然后用任意静态服务器托管。这种方式适合不想用 Docker 的用户，比如在 OpenWrt 或树莓派上直接运行。

配置与搜索：日常使用的核心

配置文件 assets/config.yml 是 Homer 的唯一数据源。它支持多页面和分组，你可以在一个文件里定义多个页面，每个页面下再分多个组，每组放若干服务。搜索功能是模糊搜索，按 / 键开始，Escape 停止，Enter 打开第一个匹配结果，Alt+Enter 在新标签页打开。这个搜索是纯前端的，不需要后端索引，所以响应速度很快。对于每个服务，你可以设置 _target 属性来控制打开方式，搜索结果的打开行为会尊重这个属性。配置的复杂度上限就是 YAML 的嵌套结构，不支持条件判断或变量引用。这意味着如果你有几十个服务，配置文件会变得很长，但每个条目的格式是固定的，复制粘贴修改即可。

定制与主题：有限但够用

Homer 支持主题定制，文档里有专门的 theming 页面。你可以调整颜色、字体、布局等样式，但定制范围限于预定义的 CSS 变量，不能随意改 HTML 结构。智能卡片（smart cards）功能在 docs/customservices.md 中有说明，它允许某些服务类型显示额外信息，比如显示系统状态或天气预报，但前提是服务提供相应的 API 接口。这种设计保持了简单性，但也意味着如果你想展示一个不在预设列表中的服务类型，你无法直接添加，除非修改源码重新构建。对于大多数导航页需求，这已经足够，但如果你想要高度自定义的仪表盘，Homer 会显得束手束脚。

局限：静态配置的代价

Homer 最明显的局限是它无法动态感知服务状态。它不会自动检测某个服务是否在线，也不会显示 CPU 使用率或磁盘空间，除非你配置了智能卡片且服务提供 API。另一个问题是多用户支持完全缺失，没有登录、没有权限控制，任何能访问页面的人都能看到所有链接。对于家庭环境这不是问题，但如果是团队共享或面向公网，这就不合适了。还有一点，配置变更后需要手动刷新浏览器或重新构建，没有热重载机制。如果你经常添加或删除服务，这个流程会显得繁琐。最后，官方文档明确说它不会在 file:// 协议下工作，这意味着你不能直接双击 index.html 预览，必须起一个本地 HTTP 服务器。

替代方案：Homepage 与 Dashy 的差异

与 Homer 最接近的替代品是 Homepage 和 Dashy。Homepage 同样使用 YAML 配置，但它内置了服务状态检测，能显示每个服务的在线状态和资源使用率，因为它会主动向服务发送请求。Dashy 则提供了更丰富的界面定制和组件系统，支持拖拽布局，但配置复杂度更高，学习曲线更陡。Homer 的优势在于极简：没有状态检测，没有组件库，只有链接和分组。如果你只需要一个静态链接页，Homer 的配置负担最小；如果你需要看到服务是否活着，Homepage 更合适；如果你想要高度定制且愿意花时间配置，Dashy 更强大。选择的关键在于你愿意为多少功能付出多少配置成本。

维护成本与许可证

Homer 的维护成本很低，这是它的设计目标之一。它使用 Apache-2.0 许可证，你可以自由使用、修改和分发，包括商用，但需要保留版权声明。项目更新频率不高，最近的 release 是 v26.8.1，但版本号没有语义化版本的含义，只是日期加序号。由于是静态页面，没有运行时依赖，所以安全更新主要涉及前端依赖，而 Docker 镜像会定期重建。升级时通常只需要拉取新镜像或下载新 zip，然后覆盖旧文件，配置文件一般兼容，但最好先备份。如果你自己修改了源码，升级时可能需要合并冲突，但大多数人直接用预构建包，升级成本几乎可以忽略。

编辑结论

Homer 适合那些已经有一台服务器、希望用最小成本维护一个服务导航页的个人或小团队。它不适合需要动态内容、用户认证或复杂权限控制的场景，因为 YAML 文件无法承载这些逻辑。如果你需要与现有系统深度集成，或者希望界面能随数据实时变化，应该考虑其他方案。在采用前，先确认你的服务地址和图标资源能否整理成 YAML 结构，并检查 Docker 镜像的 uid/gid 设置是否与你的配置文件目录权限匹配。Homer 的价值在于它的简单性，一旦你开始往里面塞复杂逻辑，它就不再是合适的工具。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes