homepage 介绍与选型指南

目标：面向正在为自托管环境挑选「仪表盘/起始页」的工程师，梳理 homepage（gethomepage/homepage，下文简称 homepage）的产品定位、核心架构、功能边界，并给出与 Glance、Dashy、Homarr、Heimdall 的量化选型对比。本文为 A1 认知篇（联网溯源），全部事实性内容均于 2026-10-25 从官方渠道（GitHub 仓库 gethomepage/homepage、官方文档站 gethomepage.dev、releases.atom 订阅源、shields.io 徽章）实查取得并标注来源；部署、配置与运维的实测内容见本专栏后续各篇。

一、环境信息

本文为 A1 认知篇（联网溯源），写作时不依赖本地环境，所有版本、星数、许可与功能口径均于 2026-10-25 从下列官方渠道实查：

💡 说明：homepage 更新节奏很快（近期基本每周一个 minor 版本），本文版本口径截至 2026-10-25；latest 标签会持续滚动，生产环境建议锁定精确版本号（本专栏《homepage v2.7.0 Docker Compose 部署指南》即以 v2.7.0 标签实测）。

二、软件概述

2.1 定位与身份

homepage 的官方自我定位只有一句：「一个现代、快速、安全、完全可代理、高度可定制的应用仪表盘，带有 100+ 服务集成与多语言翻译，可通过 YAML 文件或 Docker 标签发现轻松配置」（A modern, fast, secure, fully proxied, highly customizable application dashboard…，来源：GitHub README，查询日期 2026-10-25）。

它解决的核心痛点是：自托管了越来越多的 Web 应用（下载器、媒体库、监控、网关、NAS 工具……）之后，没有一个统一的入口页来看「我有哪些服务、它们活没活着、关键指标是多少」。homepage 把三件事做在一页里：

1. 导航与书签：服务卡片 + 书签分组，点击直达各应用；
2. 状态与指标展示：每个服务卡片可挂 widget，实时显示 Plex 的媒体会话数、qBittorrent 的上下行速率、Docker 容器的 CPU/内存占用等；
3. 信息面板：页头可放天气、时间、搜索框、系统信息（Glances）等信息组件。

一句话理解它的产品逻辑：在「纯书签页」和「重型可视化面板平台」之间，homepage 选择用纯 YAML 配置把「导航 + 状态展示」做到又快又稳——不需要数据库、不需要注册账号、没有管理后台，改 YAML 即所见即所得。

💡 技术拓展：自托管「仪表盘/起始页」并非只有一种形态，选型前应先分清三大流派——

流派	代表产品	核心形态	适合谁
导航型仪表盘	homepage、Dashy、Homarr	以「服务卡片 + 书签」为主体，挂轻量状态指标	应用多、想一页直达并看关键状态
信息流聚合型	Glance	以「RSS/HN/Reddit/天气/监控」等信息流卡片为主体	想把起始页当「每日信息看板」用
轻量书签页	Heimdall	简洁的应用卡片，功能克制	只想要一张漂亮的「应用桌面」

homepage 属于第一种流派的头部项目，同时通过 info widgets 借鉴了第二种的「信息聚合」能力。

2.2 版本与许可

• 当前稳定版：v2.7.0，2026-10-23 发布（来源：GitHub Releases / releases.atom，查询日期 2026-10-25）。
• 许可证：GPL-3.0（来源：shields.io github/license 徽章，查询日期 2026-10-25）。按 GPL-3.0 条款，个人自托管、内部使用与修改不受影响；若修改源码后对外分发或提供网络服务，需按 GPL 开源修改部分。对「拿 homepage 二次开发后做成商业托管面板」的场景有约束，普通家庭/团队自托管无感。
• 治理与社区：社区主导的开源项目（gethomepage 组织），配套 Discord 社区、Crowdin 多语言翻译平台（项目名 gethomepage），README 致谢超过 200 名贡献者；问题支持走 GitHub Discussions（来源：GitHub README，查询日期 2026-10-25）。
• 安全声明：README「Security Notice」明确提示——widget 会读取个人敏感信息（如家庭自动化数据），若仪表盘可从不可信网络访问，必须置于强制认证、TLS 并严格校验 Host 头的反向代理（和/或 VPN）之后；v2.0 起提供可选的内置 OIDC 或简单密码登录门控。

2.3 版本节奏（量化）

近期发布记录（来源：GitHub releases.atom，查询日期 2026-10-25）：

v2.7.0 的代表性变更：新增 NetBird 服务 widget、修复 prometheusmetric 组件只渲染四个指标的问题（来源：v2.7.0 Release Notes，查询日期 2026-10-25）。整体节奏约为每周到每月一个 minor 版本，以「新 widget + 修复」为主，无破坏性大版本切换的迹象（v2 大版本内的迭代平滑）。

三、核心架构

3.1 运行时构成

homepage 是单进程单体 Web 应用（Next.js 编写），无外部数据库依赖，运行时外围依赖最少：

没有 SQLite、没有 Redis、没有独立数据库——所有「状态」要么是配置文件，要么是对其他服务的实时/缓存读取，这使它的备份与迁移成本几乎为零（复制一个目录即可，本专栏《homepage v2.7.0 日常运维手册》有实测步骤）。

3.2 关键设计：服务端代理与 Host 校验

homepage 有两条安全设计主线（来源：官方文档站 Installation 与 README，查询日期 2026-10-25）：

1. API Key 不出服务端：widget 请求（如 Sonarr、Plex 的 API）由 homepage 服务端代理发起，浏览器只见渲染结果。因此各服务的 API Key 只需写在服务端配置里，配合 HOMEPAGE_VAR_XXX 环境变量占位符还可避免明文落盘。
2. Host 头白名单：自 v1.0 起，HOMEPAGE_ALLOWED_HOSTS 为必填环境变量（逗号分隔的允许访问主机列表，localhost:3000 与 127.0.0.1:3000 恒定内置），用于防止针对 API 代理的 Host 混淆类攻击；* 可关闭校验但官方明确不建议。NextAuth 路由（/api/auth/*）与登录页（/auth/*）豁免该校验，保证登录流程可用。

v2.0 起的认证门控默认关闭（opt-in），开启后所有页面与 /api 路由（除 /api/healthcheck 与 /api/config/custom.css）都要求登录会话——/api/healthcheck 保持免认证正是为了探活探测可用。

3.3 部署形态

官方支持的部署形态（来源：官方文档站 Installation，查询日期 2026-10-25）：

四、功能特性

4.1 服务卡片与服务集成（Service Widgets）

services.yaml 里按分组声明服务，每个服务 = 图标 + 链接 + 描述，可再挂 0~N 个服务 widget 显示实时指标。官方 README 列举的集成覆盖：Radarr、Sonarr、Lidarr、Bazarr、Ombi、Tautulli、Plex、Jellyfin、Emby、Transmission、qBittorrent、Deluge、Jackett、NZBGet、SABnzbd 等 100+ 服务（来源：GitHub README，查询日期 2026-10-25）。widget 数据支持多 widget 并挂、字段筛选（fields）、自定义请求头（headers）与指标阈值高亮（highlight，按数值/字符串规则把指标块染成 good/warn/danger 三色）。

💡 技术拓展：widget 拿到的指标块高亮依赖「阈值规则引擎」，homepage 支持的规则写法对比——

规则类型	可用操作符	典型用途
数值规则（numeric）	gt / gte / lt / lte / eq / ne / between / outside	下载队列 ≥5 变黄、≥20 变红
字符串规则（string）	equals / includes / startsWith / endsWith / regex	状态含 "failed" 变红
反向与大小写	negate: true / caseSensitive: true	取反、精确匹配

阈值染色是「被动可视化」里成本最低的告警形态，本方案在《homepage v2.7.0 配置参数详解》有实测示例。

4.2 Docker 集成与自动发现

homepage 对 Docker 有两个层次的支持（来源：GitHub README 与官方文档站 Docker Configuration，查询日期 2026-10-25）：

1. 容器状态与统计：配置 Docker 实例（docker.yaml，支持 socket 直连、HTTP API、TLS、socket proxy 四种接入）后，服务卡片可显示对应容器的运行状态，点开状态标签能看到 CPU、内存、网络活动实时曲线；
2. 标签自动发现：任何容器只要带上 homepage.group、homepage.name、homepage.icon、homepage.href 等标签，就会被自动发现并加进仪表盘，无需手写 services.yaml——widget 配置同样支持标签点号写法（homepage.widget.type=xxx）。

官方明确提示：直接挂载 docker socket 不是推荐的接入方式（需要 root 或 docker 组权限），更稳妥的是 tecnomativa/docker-socket-proxy 一类的只读代理，官方文档给出了参考配置。

4.3 信息组件（Info Widgets）与书签

• 信息组件：widgets.yaml 定义页头信息组件，覆盖天气（openmeteo/openweathermap）、时间、日期、搜索框、Glances 系统信息、关键资源监控等（来源：官方文档站 Widgets / Info Widgets，查询日期 2026-10-25）；
• 书签：bookmarks.yaml 定义书签分组，每条书签支持缩写（abbr，默认两字母）、图标与描述，与服务分组共用布局系统（layout）排版；
• 快捷搜索（Quick Launch）：页面内直接键入即可搜索服务、执行 Web 搜索或打开 URL，支持搜索建议与描述匹配。

4.4 主题定制与多语言

• 主题：暗/亮主题切换可锁定（theme: dark），22 种色板（slate、emerald、rose……）可锁定（color: xxx），支持自定义 CSS 与 JS（custom.css / custom.js）；页头 4 种样式（underlined/boxed/clean/boxedWidgets），卡片布局支持行/列、多页签（tab）、嵌套分组、等高卡片、折叠分组等（来源：官方文档站 Settings，查询日期 2026-10-25）；
• 多语言：40+ 界面语言，language: zh-Hans 即简体中文（官方文档站列明 zh-Hans 简体、zh-Hant 繁体均受支持）；
• PWA：内置 PWA 支持，可安装为「桌面应用」，图标/快捷方式可自定义。

4.5 认证门控（v2.0+）

homepage 自身的认证是 v2.0 引入的可选门控（来源：官方文档站 Installation「Security & Authentication」，查询日期 2026-10-25）：

💡 技术拓展：仪表盘这类「聚合入口」的访问控制有三种常见做法，homepage 三种都能配合——

做法	原理	取舍
应用内登录门控（homepage v2.0+）	应用自身校验密码/OIDC 会话	零外部依赖；但仅保护这一层，widget 数据仍经应用读取
反向代理认证层	Authelia/tinyauth 等在代理层统一拦截	全站统一登录，可保护一切后端应用
VPN 内网隔离	Tailscale/WireGuard，公网根本摸不到入口	最省心的公网安全方案

官方安全声明的建议是「反代/VPN 必配，内置门控作纵深防御」。本文后续各篇实测采用内置密码门控 + 反代两条路径。

4.6 可观测与健康检查

• 健康检查端点：/api/healthcheck（认证开启时仍豁免），可用于负载均衡器/监控系统的探活；
• 状态展示：Docker 集成的容器状态标签、ping（ICMP 真探针，IPv4）与 siteMonitor（HTTP HEAD 探测并显示响应时间）两个服务级探针属性（来源：官方文档站 Services，查询日期 2026-10-25）；
• 日志：标准输出日志（密码登录失败等安全事件落 warn 级），排障路径见官方 Troubleshooting 指南。

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

以下为官方 README 给出的最小路径（来源：GitHub README Getting Started，查询日期 2026-10-25；完整步骤与本机实测回显见本专栏《homepage v2.7.0 Docker Compose 部署指南》）：

第 1 步：准备配置目录（官方要求本地配置目录必须先存在）：

mkdir -p /opt/homepage/config

第 2 步：编写 docker-compose.yml（官方示例，HOMEPAGE_ALLOWED_HOSTS 为必填项）：

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3000:3000
    volumes:
      - /opt/homepage/config:/app/config
    environment:
      HOMEPAGE_ALLOWED_HOSTS: gethomepage.dev # 必填，按实际访问域名/IP:端口填写

第 3 步：启动并访问：

docker compose up -d

首次启动时 homepage 会把初始示例配置（src/skeleton 内置骨架）写入挂载的配置目录，浏览器打开 http://<服务器IP>:3000 即见默认仪表盘；之后所有界面调整都是改 YAML 文件，保存即生效。注意 HOMEPAGE_ALLOWED_HOSTS 必须包含你实际访问用的 IP:端口 或域名，否则页面能开但 API 请求会因 Host 校验失败而无数据——这是 v1.0 之后最高频的部署问题（官方安装文档明确说明）。

六、适用场景与限制

6.1 适用场景

1. 家庭实验室统一入口：Plex/Jellyfin、*arr 全家桶、qBittorrent、Home Assistant、NAS 工具……几十个应用的「一页直达 + 状态速览」，homepage 的 YAML 配置与 Docker 自动发现是最低摩擦的组合。
2. 小团队内部工具门户：Git、CI、监控、Wiki 等内部系统按分组排布，用密码/OIDC 门控保护，Docker 集成直接显示各服务容器健康状态。
3. 运维速览面板：配合 Glances 信息组件与 Docker 容器统计，把「服务器是否健康」做成浏览器主页；再叠加书签与快捷搜索当日常起始页。
4. 多环境聚合：docker.yaml 支持多个 Docker 实例（远程 HTTP API/TLS），一台 homepage 可以聚合多台服务器的容器状态。

6.2 资源参考

• 官方未给出硬性资源下限；架构上为单 Next.js 进程、无外部数据库，属轻量 Web 应用形态。widget 数据有服务端缓存，刷新周期内不会反复打后端服务。
• 每次页面刷新会触发 widget 数据代理请求与 Docker API 查询，服务/集成数量极大时建议拉开 cache 时长。

6.3 限制（评估前必须知道）

1. 无多用户体系：内置门控是「一个密码 / 一个 OIDC 会话」的准入闸，没有用户管理、个人书签、权限分级；需要「每个成员自己的面板」要选 Homarr 这类带用户系统的产品。
2. 无在线编辑器：一切配置走 YAML 文件，没有拖拽编辑界面（官方立场是 "Easily configured via YAML files or through docker label discovery"）；介意手写 YAML 的话选 Dashy/Homarr。
3. GPL-3.0：修改后对外分发/提供网络服务需开源修改（对比 MIT/Apache 竞品更严格，个人自托管无影响）。
4. 公网暴露需自建边界：内置认证较年轻（v2.0 引入），官方自己都把「反代 + TLS + Host 校验」写成硬性建议；不要裸奔 3000 端口到公网。
5. 版本节奏快：每周级 minor 发布，跟进升级需看 Release Notes；锁定版本号部署可规避。

七、同类选型对比

7.1 竞品对照表

以下星数与许可证均来自 shields.io 徽章实查（查询日期 2026-10-25）；定性维度来自各项目官方 README/文档站的定位描述（同日期实查）：

关键差异解读：五者星数都在同一量级（5k~38k），都是活跃的自托管项目，真正的分野在「配置哲学」与「多用户」——Glance 把起始页做成了信息聚合器（它的星数最高，但定位与导航型仪表盘不完全重叠）；Dashy 功能最全但配置复杂度也最高；Homarr 是唯一内置完整用户系统的；Heimdall 最简但功能面最窄；homepage 卡位在「纯 YAML、服务端代理、Docker 原生集成」的均衡点。

7.2 选型建议（「如果…则…」）

• 如果应用多、想一页直达并看各服务关键指标，且接受手写 YAML → homepage。
• 如果更想要「每天打开就是 RSS/新闻/天气/监控信息流」的看板 → Glance。
• 如果需要在线拖拽编辑、2FA、云同步等重度自定义功能 → Dashy。
• 如果家庭成员/团队多人使用，需要每人独立账号与权限 → Homarr。
• 如果只想给一两个应用做一张极简卡片页 → Heimdall。
• 如果 GPL/AGPL 传染性不可接受 → 选 MIT 的 Dashy/Heimdall 或 Apache-2.0 的 Homarr。

八、参考链接

• GitHub 仓库：https://github.com/gethomepage/homepage
• 官方文档站：https://gethomepage.dev/
• Installation（含 HOMEPAGE_ALLOWED_HOSTS 与认证门控）：https://gethomepage.dev/installation/
• Docker Installation：https://gethomepage.dev/installation/docker/
• Configuration（settings/services/bookmarks/docker 等）：https://gethomepage.dev/configs/
• Widgets（服务/信息组件索引）：https://gethomepage.dev/widgets/
• Troubleshooting：https://gethomepage.dev/troubleshooting/
• Docker 标签自动发现：https://gethomepage.dev/configs/docker/#automatic-service-discovery