Homepage：用 YAML 和 Docker 标签搭一个自托管导航页

它解决什么问题

自托管用户通常有十几个服务，每个都有独立的 IP 和端口，记不住也懒得记。Homepage 把所有这些入口收敛到一个页面，同时显示容器运行状态、资源占用和天气等辅助信息。它面向的是已经熟悉 Docker 和 YAML 的用户，而不是普通家庭用户。项目定位是“application dashboard”，不是简单的书签页，它通过集成把外部服务的状态拉进来，比如 Radarr 的待下载数量或 Plex 的播放信息。

静态生成与代理架构

Homepage 用 Next.js 构建，但最终产物是静态文件，这意味着页面加载时不需要后端渲染，速度自然快。所有对后端服务的 API 请求都经过 Homepage 自己的代理，而不是浏览器直接请求，这样 API 密钥不会暴露在前端代码里。这是一个重要的设计选择：你把自己的 API key 配置在服务端，浏览器只看到相对路径。代价是每个小部件的数据都要经过 Homepage 进程转发，如果集成很多，这个 Node 服务就成了瓶颈。文档没有给出性能上限，但静态页面和代理是两种不同的负载，后者才是真正的运行时成本。

Docker 自动发现机制

Docker 集成是 Homepage 最吸引人的点。只要把 /var/run/docker.sock 以只读方式挂载进容器，它就能读取所有容器的状态和标签。你在 docker-compose 里给某个容器加上 homepage 相关的 label，Homepage 就会自动把它显示为服务，并附带状态信息。这个机制省去了手动编辑 YAML 的步骤，但前提是你愿意在 compose 文件里维护标签。标签的格式和可用键值需要查阅文档，README 只给了方向，没有具体例子。另一个隐含要求是 Docker socket 的挂载，这在安全上是一个敏感操作，等于把宿主机的 Docker 控制权交给了 Homepage 容器。

配置方式：YAML 与目录结构

配置全部通过 YAML 文件完成，放在 /app/config 目录下。首次启动时可以从 src/skeleton 复制示例文件。项目文档位于 gethomepage.dev，涵盖了设置、服务、小部件和布局等所有方面。从 README 的提示看，大多数用户问题都源于 YAML 缩进错误或键名拼写，这说明配置虽然灵活但有学习曲线。服务集成超过 100 种，每个服务的配置字段不同，你需要为每个服务查一次文档。相比之下，Docker 标签发现可以减少一部分手工配置，但标签本身的语法仍要学习。

运行与构建命令

最简单的部署方式是 Docker。compose 文件里需要设置 HOMEPAGE_ALLOWED_HOSTS 环境变量，这是必填项，用于校验 Host 头，防止 DNS rebinding 攻击。示例中设置为 gethomepage.dev，实际使用要换成你自己的域名，可能还要带端口。从源码运行时，先用 pnpm install 安装依赖，再 pnpm build 构建生产包，最后用 HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev:1234 pnpm start 启动。开发模式用 pnpm dev，监听 3000 端口。文档站点本身用 Zensical 构建，需要 uv 工具链，但这与主程序无关。

安全边界与错误使用场景

README 的安全提示非常直接：如果 Homepage 暴露在不可信网络，必须放在强制认证和 TLS 的反向代理后面。内置的 OIDC 和密码登录只是可选的“已认证或未认证”守卫，没有用户管理、角色或权限区分。这意味着任何能登录的人都看到所有服务，包括家庭自动化系统的信息。另一个限制是它依赖 Docker socket，如果不挂载 socket，Docker 集成和自动发现就完全失效，只剩手动配置的静态服务。对于不想给容器宿主机权限的用户，Homepage 不是合适的选择。

替代方案与差异

同类项目有 Heimdall 和 Organizr，但它们的思路不同。Heimdall 更侧重静态书签和简单的应用图标，集成深度不如 Homepage。Organizr 则强调权限管理和多用户，可以把不同标签页分配给不同用户，而 Homepage 的认证只是全局开关。Homepage 的差异化在于 Docker 标签发现和大量服务小部件，这是它最花功夫的部分。如果你只需要一个好看的书签页，Heimdall 可能更轻量；如果需要多用户权限，Organizr 更匹配。Homepage 站在中间，偏向单用户或家庭小团队。

维护与升级成本

项目使用 GPL-3.0 许可证，这意味着如果你修改并分发它，必须开源你的修改。对于个人自托管，这个限制通常不构成问题，但企业内部使用时要留意。更新频率不低，示例中一天内发布了三个小版本，说明开发活跃。升级成本主要在于配置文件兼容性，因为 YAML 结构可能随版本变化，你需要关注 release notes。文档站点和主程序分开维护，文档用 Zensical，主程序是 Next.js，这对贡献者来说多了一套工具链，但对普通用户没有影响。

编辑结论

Homepage 适合已经用 Docker 管理自托管服务、希望用一个统一入口查看状态并快速跳转的用户，尤其是那些愿意花时间写 YAML 和阅读文档的人。它不适合需要复杂权限控制或不想暴露 Docker socket 的场景，因为内置的 OIDC 和密码登录只是简单的“已认证或未认证”守卫，无法做细粒度授权。在采用前，先确认你的反向代理能强制 TLS 和 Host 头校验，并仔细阅读 gethomepage.dev 上关于 HOMEPAGE_ALLOWED_HOSTS 的说明，否则未授权访问可能泄露家庭自动化等敏感数据。如果你不想把 Docker socket 挂载给容器，可以改用 Docker API 代理或仅使用静态书签功能，但那样会失去自动发现和容器状态显示。

官方来源

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