Homepage 部署教程:把 NAS 上散落的自托管服务收进一个可监控的仪表盘

摘要
Homepage 是自托管圈最流行的应用仪表盘之一(GPL-3.0,GitHub 约 3.3 万 Star)。本文基于 v2.7.0,用 Docker 部署后讲清 services / bookmarks / widgets / settings 四份 YAML 怎么写、100+ 服务集成与 Docker 标签自动发现,附反向代理鉴权与实测排错清单。
家里 NAS 上跑着二三十个自托管服务,每个都有自己的端口和路径,用的时候翻收藏夹、记 IP、一个个敲地址,装得越多越乱。Homepage 把这件事变成一句话:用几份 YAML 把所有服务、书签和工具收进同一个首页,还能顺带显示每个服务的运行状态。
它是一款专为自托管场景设计的现代化应用仪表盘,GPL-3.0 开源,GitHub 上已有约 3.3 万 Star(本文核实为 33,359)。本文基于 v2.7.0(2026-10-23 发布),从 Docker 部署讲到 services / bookmarks / widgets / settings 四份配置怎么写、100+ 服务集成与 Docker 标签自动发现,最后附反向代理、鉴权和一份实测排错清单。
一、它能做什么
Homepage 解决的核心痛点是"入口分散、地址难记、状态难监控",能力大致分这么几层:
统一入口:把散落在各个端口、子路径下的自托管服务和外部书签,收拢成一个可分组、可搜索的首页。
服务集成与小部件:内置 100+ 服务集成,覆盖 *arr 全家桶(Sonarr、Radarr、Lidarr、Bazarr)、Plex、Jellyfin、Emby、qBittorrent、Transmission 等主流自托管应用,卡片上直接显示在线状态、下载数、队列等实时数据。
Docker 集成与自动发现:能读容器状态和资源占用;给容器打上
homepage.*标签,服务就会自动出现在首页,不用手写配置。信息部件(Info Widgets):顶部可放资源占用(CPU/内存/磁盘)、时间、搜索框、天气、股票等,开机即见系统概览。
安全的全代理:所有发往后端服务的 API 请求都经 Homepage 代理转发,API Key 留在服务端、不暴露给浏览器。
高度可定制:主题、配色、背景图、行列布局、标签页、自定义 CSS/JS、40+ 语言本地化都能调。
跨架构:官方镜像同时提供 AMD64 与 ARM64,群晖、威联通、软路由、树莓派、fnOS 都能跑。
边界提醒:Homepage 是"门户 + 即时状态"仪表盘,不做历史数据存储,也不做告警推送。想要长期趋势图和阈值告警,那是 Prometheus + Grafana 的活;Homepage 负责的是"把门面收拾干净"。
二、安装(Docker,一条 compose 起步)
前置只有两点:一台能跑 Docker 的 NAS 或服务器;给它准备一个配置目录(下文以 /vol2/1000/Ocotp/homepage/config 为例,换成你自己的路径)。
docker compose 方式:
docker run 方式:
几个必须说清的点:
`HOMEPAGE_ALLOWED_HOSTS` 是必填项。从 v1.0 起,用非
localhost的地址访问就必须设置它,值是逗号分隔(不要空格)的允许主机列表,带端口的写全(如192.168.31.10:3000)。localhost:3000和127.0.0.1:3000默认永远放行。设成*能关掉校验,但官方明确不推荐。首次启动会自动生成一份示例配置(
services.yaml、bookmarks.yaml、widgets.yaml、settings.yaml、docker.yaml等骨架),直接改这几份文件即可。容器默认以 root 运行;要降权就用
PUID/PGID,并保证挂进去的目录属主权限对得上。想接 Docker 集成才需要挂
docker.sock,且建议挂只读(:ro)。
装完浏览器打开 http://<你的IP>:3000,能看到一张自带示例分组的仪表盘,就算起来了。
三、把服务加进来:services.yaml
服务都写在 services.yaml 里,结构是"顶层是分组数组,组里是服务数组":
每条服务至少有 href(点击跳转地址),可选的 icon、description 让它更好看。分组可以嵌套,把相关服务收进子组。
给小部件(widget):服务卡片想要显示实时数据,就在服务下挂 widget,填对应服务的 API 信息。以三个常见服务为例:
注意 widget.url 不要带结尾的斜杠或额外 API 路径,Homepage 会自己拼接口路径——这是小部件报错最常见的原因。
图标:icon 直接写名字即可,默认从 Dashboard Icons 自动拉取,带不带 .png/.webp/.svg 都行。也支持前缀式图标集:mdi-XX(Material Design Icons)、si-XX(Simple Icons)、sh-XX(selfh.st)。这些图标是浏览器从 CDN 现取的,想离线用就下载后放进 /app/public/icons 挂载目录,用 /icons/xxx.png 引用(新增本地图标要重启容器)。
四、书签与顶部信息部件
书签(bookmarks.yaml):比服务更轻,纯链接外跳,结构和服务类似:
abbr 建议两个字母(站点按两字母设计),有 icon 时优先用图标。
信息部件(widgets.yaml):显示在页面顶部,按文件里的顺序排。一个实用的起步组合:
天气类部件需要 API Key。敏感信息不要硬写进 YAML,用环境变量占位:以 HOMEPAGE_VAR_ 或 HOMEPAGE_FILE_ 开头的环境变量,会替换配置里的 {{HOMEPAGE_VAR_XXX}}(HOMEPAGE_FILE_XXX 则从一个文件路径读内容)。比如:
五、布局与外观:settings.yaml
settings.yaml 管应用级选项,改完点页面右下角的刷新图标清缓存重载即可。
布局用 layout 控制每个分组是横排还是竖排、几列、要不要标签页:
layout 里还可以给分组设 tab: 名称 做标签页视图、initiallyCollapsed: true 默认折叠;想全局换成纯图标风格,用 bookmarksStyle: icons 或分组级 iconsOnly: true。背景图除了用网络 URL,也能挂本地图片目录后用 /images/xxx.png 引用——但注意新增本地图片后要重启容器,且不要整目录挂 /app/public/。
六、Docker 集成与标签自动发现
想让卡片显示容器的状态和资源占用,先配 docker.yaml。推荐用 docker-socket-proxy 只读暴露,避免直接把宿主 socket 交给容器:
然后在 docker.yaml 里登记这个实例:
接着在 services.yaml 的服务上挂 server 和 container 就能显示状态:
自动发现更省事:给容器打上 homepage.* 标签,服务会自己冒出来,连 server/container 都不用写:
一个服务要挂多个部件时,用 homepage.widgets[0].xxx、homepage.widgets[1].xxx 递增索引。Swarm 部署时标签要写在 deploy.labels 下。
七、安全与反向代理(必读)
Homepage 能读到你各服务的 API 数据,所以只要它可能从不可信网络被访问,就必须放在带鉴权、TLS、并严格校验 Host 头的反向代理或 VPN 之后。从 v2.0 起它还内置了一道轻量登录闸(密码或 OIDC),按需开启:
走 OIDC 登录时用
HOMEPAGE_OIDC_ISSUER/HOMEPAGE_OIDC_CLIENT_ID/HOMEPAGE_OIDC_CLIENT_SECRET,回调地址配成https://你的域名/api/auth/callback/homepage-oidc。公网/TLS 部署请用
https://的HOMEPAGE_EXTERNAL_URL,登录 Cookie 才会带Secure标记。Homepage 自身不做密码尝试限流,暴露在公网时要让反代或网关对
/api/auth/callback/credentials的 POST 做限流(失败会以Failed password sign-in attempt记 warn 日志,可接 fail2ban / CrowdSec)。内置登录闸只是"登没登录"的一道门,不替代反代的 TLS 与边缘防护。
八、排错清单
现象 | 常见原因 | 解法 |
|---|---|---|
页面报 host validation 错误 / 打不开 |
| 把日志里打印的 host(含端口)原样加进列表,逗号分隔不带空格 |
小部件显示 API Error |
| URL 只写到主机端口; |
改了 YAML 没生效 | 浏览器缓存了旧的仪表盘数据 | 点页面右下角刷新图标清缓存重载 |
本地图标 / 背景图不显示 | 新增本地文件后没重启容器 |
|
反代后 403 / 被 WAF 拦 | 请求缺浏览器 UA 或 Host 头不对 | 反代补正确 Host 头;确认 |
Docker 服务不显示状态 |
| 核对 |
九、写在最后
如果你手里有一台常年开机的 NAS 或家用服务器、上面跑着好几个自托管服务,Homepage 几乎是"装了就回不去"的那种工具:配置全在几份 YAML 里,改起来直观,配合 Docker 标签自动发现,新装的服务打个标签就自动上门。它不适合只想要一个静态书签页的人,也不负责历史监控和告警——把定位放对,它就是那扇最好用的"家门"。
相关链接
Homepage GitHub 仓库:https://github.com/gethomepage/homepage
官方文档:https://gethomepage.dev
Dashboard Icons 图标库:https://github.com/homarr-labs/dashboard-icons
Release 页(当前 v2.7.0):https://github.com/gethomepage/homepage/releases
