这是「Docker 好项目」系列的第 18 期。前面 17 期我们一个接一个地把服务搬回了自己服务器:密码库(第 3 期 Vaultwarden)、照片(第 4 期 Immich)、音乐(第 8 期 Navidrome)、代码(第 10 期 Gitea)、文档(第 14 期 Paperless-ngx)、电影(第 17 期 Jellyfin)……搬是搬回来了,但很快会遇到一个新问题:入口找不到了。十几二十个服务,端口是 3000、5230、8096、9090 这样一串谁也记不住的数字,每次访问要么翻书签,要么翻 1Panel 的容器列表。Homepage 就是来解决这个的——它本身不提供任何服务,只是把已有服务收进一个页面,顺带把每个服务的实时状态和关键数据抓回来摆在台面上。

痛点开场
自托管到一个阶段之后,几乎每个人都会掉进同一个坑:服务比入口多。
- 记不住端口。Vaultwarden 是 8090、Memos 是 5230、Navidrome 是 4533……这些数字没有任何规律,靠脑子记是不可能的。浏览器书签倒是能存,但书签栏越攒越长,翻起来比记端口还慢
- 不知道服务是死是活。容器挂了、磁盘满了、某个服务返回 500,你不主动去点开它,就不会知道。往往是要用的时候才发现"哦,昨天就崩了"
- 看一个数据要开一个后台。想知道 Immich 存了多少张照片、Jellyfin 有几部电影在转码、AdGuard 今天拦了多少次广告,得分别登录三个后台
- 给家人用不了。自己做的那套自托管服务,家里其他人根本摸不着门——没有域名、没有图标、没有统一入口,告诉他们"打开 192.168.31.194:5230"基本等于没说
- 手机上没有好的入口。浏览器书签在手机上体验极差,自建的这些服务一个个加桌面图标,二十个图标铺满好几屏
现成的方案也不是没有,但都有各自的别扭:仪表盘类项目里,Dashy 配置庞大、要写一堆 YAML 而且状态抓取弱;Heimdall 轻但基本只是"能点的大图标",没有实时数据;Flame 好看但数据能力同样有限。Homepage 是这条线上做得最均衡的那个:界面现代、配置全 YAML、内置 161 个服务组件的实时数据抓取,而且——这一点对我们这个系列特别重要——前面 17 期里有一大半项目,它都有现成的组件。
能力边界
能干什么
- 服务聚合入口:把任意多个服务按分组排进一个页面,支持分组、嵌套分组、行列布局、标签页(tab)、折叠、图标墙模式
- 实时数据组件(widget):这是它区别于普通导航页的核心。每个服务卡片可以挂一个或多个组件,直接显示那个服务的实时状态。内置 161 个服务组件,覆盖面非常广
- 信息组件:日期时间、天气、系统资源(CPU/内存/磁盘)、股票、搜索框、欢迎语等,摆在页面顶部当"仪表盘抬头"
- Docker 集成:接入 Docker socket 后,自动显示每个容器是 running 还是 stopped,点一下还能展开看实时 CPU / 内存 / 网络占用;支持用容器 label 自动发现服务,不用手写配置
- 可用性监测:每个服务可以配
siteMonitor(发 HTTP 请求测响应时间)或ping(真 ICMP ping 主机) - 书签栏:和"服务"并列的另一套条目,纯链接,适合放不常开但需要留着的地址
- 多套主题:明暗模式、22 种配色、4 种标题样式,都能在配置里钉死
- PWA:可以"安装"到手机桌面,有独立图标和启动画面,支持快捷方式直接跳到某个标签页
- 全中文界面:官方内置
zh-Hans简体中文 - 静态渲染 + 代理:前端是 Next.js 静态页,所有对外请求都由服务端代理转发,浏览器不直接访问你的内网服务
不干什么
- 不是监控告警系统。它能显示状态,但不会在服务挂掉时主动通知你。要告警还是得靠第 1 期 Uptime Kuma。两者的分工是:Uptime Kuma 负责"出事喊人",Homepage 负责"平时好看"
- 不存储业务数据。它的全部状态就是
config目录下那四个 YAML 文件,丢了重写一遍就行(当然还是建议备份) - 不提供认证以外的访问控制。v2.0 起内置了密码 / OIDC 登录,但没有细粒度权限——要么全看到,要么看不到。而且密码登录没有限流,官方明确说了要自己在反代层做
- 组件不是万能的。161 个组件看着多,但每个组件能抓的字段是固定的,抓不到你想要的指标就只能换别的办法(比如第 14 期 Paperless-ngx、第 15 期 linkding、第 16 期 Actual Budget 就没有官方组件)
- 不做反向代理。它显示链接,但不转发流量,每个服务该暴露的端口一个都不能少(或者自己用第 2 期 NPM 收口)
- 配置改完要手动刷新。改 YAML 文件后需要点页面右下角的刷新按钮重新生成静态页,不是热加载
一句话:Homepage 是"把已经跑起来的服务收拾整齐的那个页面",不是新的服务。
部署前准备
- 一台跑着 Docker 的机器。它资源占用极低(静态站点),1 核 512M 都能跑,跟你那些服务放同一台机器最合适
- 想清楚要放哪些服务。不用一开始就全上,先挑 5~8 个最常用的,跑通了再扩。每个服务需要的信息就三样:名称、访问地址、图标名
- (可选)Docker socket。想显示容器状态就必须给,但直接挂
/var/run/docker.sock等于把宿主机 root 权限交出去,生产环境建议走 socket-proxy(见配置章节) - 镜像源:主 registry 是
ghcr.io/gethomepage/homepage,Docker Hub 上也能拉到同名gethomepage/homepage(我两边都探测了,同版本 tag 都在)。国内拉不动 ghcr 的话可以换 Docker Hub 源,或者用 1Panel 默认配置的镜像加速
关于 tag,我实测了一遍(v2.4.0,2026-09-17 发布):
| tag | 结果 |
|---|---|
v2 |
200(digest sha256:643bd0be…) |
v2.4 |
200,与 v2 digest 完全相同 |
v2.4.0 |
200,与 v2、v2.4 digest 完全相同 |
latest |
200,与上面三个 digest 完全相同 |
2.4.0(不带 v) |
404,不存在 |
v2.3.0 / v2.3 |
200,两者 digest 相同(对照组,确认滚动规律稳定) |
两个结论:① tag 必须带 v 前缀,不带 v 的 2.4.0 是不存在的;② 这是"滚动次版本 tag"那一类——v2.4 就是当前 2.4 线的最新补丁,跟第 10 期 Gitea、第 13 期 ntfy 同类。所以推荐钉 :v2.4:既有明确的小版本边界,又能自动吃到 2.4.x 的修 bug 和补安全补丁。想完全锁死就写 :v2.4.0,但那样每次小更新都要手动改。
docker run 一行版
docker run -d \
--name homepage \
--restart unless-stopped \
-p 3000:3000 \
-v /opt/homepage/config:/app/config \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-e TZ=Asia/Shanghai \
-e HOMEPAGE_ALLOWED_HOSTS=192.168.31.194:3000 \
ghcr.io/gethomepage/homepage:v2.4
三个必须解释的地方:
HOMEPAGE_ALLOWED_HOSTS是必填项,不是可选优化。v1.0 起,只要你不是用localhost:3000访问,就必须把"访问时浏览器地址栏里的主机[:端口]"原样写进来,否则 API 代理会直接拒绝请求,页面能打开但所有组件都报错。localhost:3000和127.0.0.1:3000是官方内置放行的,不用写-v /opt/homepage/config:/app/config挂载前目录要先手动建好(mkdir -p /opt/homepage/config)。官方文档专门加了句 "Make sure your local config directory exists"——目录不存在时 Docker 会帮你建一个归 root 所有的空目录,等你后面想改成非 root 运行时就会踩权限坑-e TZ=Asia/Shanghai。不设的话容器里是 UTC,日期时间组件和日志时间会差 8 小时
docker-compose 推荐版
services:
homepage:
image: ghcr.io/gethomepage/homepage:v2.4
container_name: homepage
restart: unless-stopped
network_mode: bridge
ports:
- "3000:3000"
volumes:
- ./config:/app/config # 全部配置与日志
- /var/run/docker.sock:/var/run/docker.sock:ro # 只用来看容器状态;不用可删
- /mnt/data:/mnt/data:ro # 想显示磁盘占用时才需要(见下方 resources)
environment:
TZ: Asia/Shanghai
HOMEPAGE_ALLOWED_HOSTS: 192.168.31.194:3000,home.example.com
PUID: 1000 # 想以非 root 运行就填
PGID: 1000
LOG_LEVEL: warn # 排查组件问题时临时改 debug
# 安全加固:只授予读权限,容器受限于非 root
# security_opt:
# - no-new-privileges:true
# read_only: true
# tmpfs:
# - /tmp
和官方示例相比,我做了这几处调整:
- 镜像钉
:v2.4,官方写的是:latest。理由和往期一样:系列教程里的代码半年后还得能跑出同样的行为 HOMEPAGE_ALLOWED_HOSTS写了两个值:内网 IP 和域名,逗号分隔不能有空格。这样局域网直连和反代域名两条路都能用,不用改配置PUID/PGID显式写上。Homepage 官方镜像是支持这两个变量的(官方文档专门有一节 "Running as non-root"),机制是 entrypoint 脚本先以 root 起,把/app/config和/app/.next的属主改成你指定的 UID/GID,然后su-exec降权运行。注意这跟第 8 期 Navidrome、第 9 期 changedetection.io 那种"压根不支持 PUID/PGID"的情况不一样——那两个是设了也没用,Homepage 是真生效的- socket 挂了
:ro。这只是文件系统层面的只读,并不阻止容器通过 socket 发写请求,所以它是"聊胜于无"的防护,真要收口看下面那节
⚠️ 一个必须知道的限制:如果你设了 PUID/PGID 且不等于 0,同时又要用 /var/run/docker.sock 直接挂载,那容器里的进程就不在宿主机 docker 组里,读 socket 会失败。官方原话是"直接用 docker socket 不是推荐的集成方式,它要求 homepage 以 root 运行,或者运行用户属于 docker 组"。两条路选一条:要么 PUID/PGID 留 0(就是 root),要么改用下面的 socket-proxy。
配置项逐项解释
环境变量
| 环境变量 | 默认 | 说明与"为什么" |
|---|---|---|
HOMEPAGE_ALLOWED_HOSTS |
无(必填) | 允许访问的主机名/IP 列表,逗号分隔无空格。这是防 DNS 重绑定类攻击的——攻击者把某个域名的 A 记录指到你的内网 IP,诱使你浏览器访问,如果 Homepage 不做 Host 校验,页面里的组件代理就会替攻击者把内网服务的数据拉出来。写 * 能关掉(官方标注"不推荐"),公网部署不要关 |
TZ |
UTC | 时区。影响日志时间戳和日期时间组件 |
PUID / PGID |
0 / 0 |
运行 UID/GID。留 0 就是 root(镜像默认,官方 entrypoint 注释写了"默认 root,避免老安装被破坏")。填非 0 时会自动修 /app/config 与 /app/.next 属主再降权 |
HOMEPAGE_VAR_XXX |
无 | 配置里的密钥外置。值会替换所有配置文件里的 {{HOMEPAGE_VAR_XXX}}。比如 HOMEPAGE_VAR_IMMICH_KEY=abc123,YAML 里写 key: {{HOMEPAGE_VAR_IMMICH_KEY}} ——这样 API key 不进版本库、不进备份、不在截图里泄露 |
HOMEPAGE_FILE_XXX |
无 | 同上,但值是一个文件路径,用文件内容替换 {{HOMEPAGE_FILE_XXX}}。适合用 Docker secret 挂进来的场景 |
LOG_TARGETS |
both |
日志输出目标:both / stdout / file。默认既写 stdout 也写文件 |
LOG_LEVEL |
无 | 设成 debug 会打出非常详细的组件请求日志,排查组件为什么抓不到数据时必用 |
HOMEPAGE_AUTH_ENABLED |
无 | 内置登录开关,true 才启用 |
HOMEPAGE_AUTH_SECRET |
无 | 签名/加密 cookie 用的随机串,至少 32 字符,用 openssl rand -base64 32 生成 |
HOMEPAGE_AUTH_PASSWORD |
无 | 密码登录用。官方明确不做登录限流,公网暴露必须自己在反代层限制 /api/auth/callback/credentials 的 POST 频率 |
HOMEPAGE_EXTERNAL_URL |
无 | 访问 Homepage 用的绝对地址(含协议,必要时含端口)。公网/HTTPS 场景必须写 https://,否则认证 cookie 不会被标记 Secure |
HOMEPAGE_OIDC_ISSUER 等 |
无 | 接了 OIDC 就用 OIDC 登录(会覆盖密码登录)。注意 Homepage 不按 claim 做授权,OIDC 提供方授权谁能进,谁就能看到全部内容 |
四个配置文件
/app/config 目录下一共四个 YAML,职责分得很清:
| 文件 | 作用 |
|---|---|
settings.yaml |
全局外观与行为:标题、语言、主题、配色、布局、PWA、快捷启动 |
services.yaml |
服务分组与每个服务的地址、图标、组件 |
bookmarks.yaml |
书签分组(结构同 services,但条目更简单) |
docker.yaml |
Docker 实例连接方式(socket 或 IP:PORT,可多个) |
widgets.yaml |
顶部信息组件(天气、资源、搜索框等)。部分版本需要手动建 |
改完任一文件,要点击页面右下角的刷新图标重新生成静态页才生效。这个设计是 Next.js 静态站带来的限制,不是 bug。
先接 Docker,让容器自己长出来
这是 Homepage 最省事的一招,值得单独说。先建 docker.yaml:
my-docker:
socket: /var/run/docker.sock
然后任意一个 compose 服务加上 label,它会自动出现在 Homepage 上:
services:
memos:
image: neosmemo/memos:0.31
container_name: memos
ports:
- "5230:5230"
volumes:
- ./data:/var/opt/memos
labels:
- homepage.group=记录
- homepage.name=Memos
- homepage.icon=memos.png
- homepage.href=http://192.168.31.194:5230
- homepage.description=碎片笔记
- homepage.widget.type=memos
- homepage.widget.url=http://memos:5230
注意最后一行 url 用的是容器名 memos,而不是宿主 IP——只要两个容器在同一个 Docker 网络里,Homepage 就能直接用容器名访问它,请求不出宿主机,又快又稳。这是往期各篇反复提到的"同网络用容器名"在这期的具体用法。
用 label 自动发现的好处:不用在 services.yaml 里重复维护一遍,服务的部署和展示配置写在同一个地方,改端口不会两头忘。坏处是 label 语法不如 YAML 直观,字段多的组件会写得很长(多层嵌套要用点号 / 下标,见踩坑清单)。两种方式可以混用。
161 个组件里,本系列能直接用上的
我把 Homepage v2.4.0 的组件清单拉下来,和本系列前 17 期逐个比对了一遍。11 个有原生组件,这是这期最实在的收获:
| 期号 | 项目 | 组件 type |
需要准备什么 |
|---|---|---|---|
| 第 1 期 | Uptime Kuma | uptimekuma |
建一个状态页,取 URL 里 /status/ 后面那段当 slug |
| 第 2 期 | Nginx Proxy Manager | nginxproxymanager |
数据库账号密码(注意:这组件直连 NPM 的 MySQL/MariaDB,不是 NPM 的网页账号) |
| 第 4 期 | Immich | immich |
API Key(Immich 后台生成) |
| 第 8 期 | Navidrome | navidrome |
用户名 + 密码 |
| 第 9 期 | changedetection.io | changedetectionio |
API Key(设置页生成) |
| 第 10 期 | Gitea | gitea |
API token,权限需要 notifications + repository + issue |
| 第 11 期 | AdGuard Home | adguard |
用户名 + 密码(组件走 /control/stats) |
| 第 12 期 | Miniflux | miniflux |
API Key |
| 第 13 期 | ntfy | ntfy |
公开主题不需要;私有主题填 key(tk_ 开头的令牌)或用户名密码 |
| 第 14 期 | Paperless-ngx | paperlessngx |
API token |
| 第 17 期 | Jellyfin | jellyfin |
API Key |
没有原生组件的是:第 3 期 Vaultwarden、第 5 期 Stirling-PDF、第 6 期 Umami、第 7 期 Memos、第 15 期 linkding、第 16 期 Actual Budget。这些照样能放进 Homepage 当导航卡片,只是卡片上不会显示实时数字。
几个组件的真实配置长这样:
- Gitea:
icon: gitea.png
href: http://192.168.31.194:3000
description: 自建代码仓库
widget:
type: gitea
url: http://gitea:3000
key: {{HOMEPAGE_VAR_GITEA_TOKEN}}
fields: ["repositories", "notifications", "issues", "pulls"] # 只显示这几项,不写就全显示
- Uptime Kuma:
icon: uptime-kuma.png
href: http://192.168.31.194:3001
description: 可用性监控
widget:
type: uptimekuma
url: http://uptime-kuma:3001
slug: my-status-page # 状态页地址是 /status/my-status-page,这里只填 slug
两个通用坑先说在前面:
url绝对不能以/结尾,也不能带 API 路径。写http://gitea:3000,不要写http://gitea:3000/或者http://gitea:3000/api/v1。组件自己会拼路径,多写一段必然 404。这是官方排障文档列的第一条- 服务和分组都必须唯一命名。同名服务(哪怕在不同分组)会让组件数据串台。官方明确写了 "All services with a widget require a unique name as well as a unique group name"
一份可以直接用的 services.yaml
下面这份是照着"一个自托管家庭服务器"的场景写的,把本系列的服务串成四个分组,代码可以直接拿去改:
- 基础设施:
- 1Panel:
icon: 1panel.png
href: https://1panel.example.com
description: 服务器管理面板
- Nginx Proxy Manager:
icon: nginx-proxy-manager.png
href: http://192.168.31.194:81
description: 反向代理与证书
widget:
type: nginxproxymanager
url: http://nginx-proxy-manager:81
username: {{HOMEPAGE_VAR_NPM_DB_USER}}
password: {{HOMEPAGE_VAR_NPM_DB_PASS}}
- Uptime Kuma:
icon: uptime-kuma.png
href: http://192.168.31.194:3001
description: 可用性监控
widget:
type: uptimekuma
url: http://uptime-kuma:3001
slug: home
- 数据与文档:
- Immich:
icon: immich.png
href: http://192.168.31.194:2283
description: 照片与视频
widget:
type: immich
url: http://immich-server:2283
key: {{HOMEPAGE_VAR_IMMICH_KEY}}
- Paperless-ngx:
icon: paperless-ngx.png
href: http://192.168.31.194:8000
description: 票据与文档归档
widget:
type: paperlessngx
url: http://paperless-ngx:8000
key: {{HOMEPAGE_VAR_PAPERLESS_KEY}}
- Memos:
icon: memos.png
href: http://192.168.31.194:5230
description: 碎片笔记
- 媒体:
- Jellyfin:
icon: jellyfin.png
href: http://192.168.31.194:8096
description: 影视库
widget:
type: jellyfin
url: http://jellyfin:8096
key: {{HOMEPAGE_VAR_JELLYFIN_KEY}}
- Navidrome:
icon: navidrome.png
href: http://192.168.31.194:4533
description: 音乐库
widget:
type: navidrome
url: http://navidrome:4533
username: {{HOMEPAGE_VAR_ND_USER}}
password: {{HOMEPAGE_VAR_ND_PASS}}
- 工具:
- Gitea:
icon: gitea.png
href: http://192.168.31.194:3000
description: 代码仓库
widget:
type: gitea
url: http://gitea:3000
key: {{HOMEPAGE_VAR_GITEA_TOKEN}}
fields: ["repositories", "notifications", "issues", "pulls"]
- AdGuard Home:
icon: adguard-home.png
href: http://192.168.31.194:3000
description: DNS 广告拦截
widget:
type: adguard
url: http://adguardhome:3000
username: {{HOMEPAGE_VAR_AGH_USER}}
password: {{HOMEPAGE_VAR_AGH_PASS}}
- ntfy:
icon: ntfy.png
href: http://192.168.31.194:8080
description: 推送通道
widget:
type: ntfy
url: http://ntfy:80
topic: alerts
key: {{HOMEPAGE_VAR_NTFY_TOKEN}}
- Miniflux:
icon: miniflux.png
href: http://192.168.31.194:8080
description: RSS 阅读器
widget:
type: miniflux
url: http://miniflux:8080
key: {{HOMEPAGE_VAR_MINIFLUX_KEY}}
- Vaultwarden:
icon: vaultwarden.png
href: https://vault.example.com
description: 密码库
- linkding:
icon: linkding.png
href: http://192.168.31.194:9090
description: 书签收藏
配合 settings.yaml:
title: 家里那台服务器
description: 南阳 · 自托管服务入口
language: zh-Hans
theme: dark
color: slate
headerStyle: boxedWidgets
target: _blank
hideVersion: true
fullWidth: true
disableIndexing: true
layout:
- 基础设施:
style: row
columns: 3
- 数据与文档:
style: row
columns: 3
- 媒体:
style: row
columns: 3
- 工具:
style: row
columns: 4
quicklaunch:
provider: baidu
searchDescriptions: true
几个容易忽略但很值得写的点:
language: zh-Hans。官方支持列表里写的就是zh-Hans(简体),老的zh-CN会被自动映射过去,能跑但属于兼容路径,新配置直接写zh-HansdisableIndexing: true。如果 Homepage 有公网域名,这一项会往robots.txt里写 Disallow 并加noindex标签,避免你的服务清单被搜索引擎收录。自托管的入口页被搜到是很尴尬的事target: _blank。默认点服务链接是当前标签页跳走,配了它才能新开标签layout里用列表写法能精确控制分组顺序。写成映射(分组名:直接跟属性)时顺序不保证,官方注释里明确说混排场景要用列表headerStyle: boxedWidgets只是外观偏好,四种样式随便试,改完刷新即可
首次访问
浏览器打开 http://<服务器IP>:3000,第一次进来是没有配置的骨架——因为 config 目录是空的。
有两种起步方式:
方式一:让它自己生成骨架(推荐)。空目录启动后,Homepage 会把内置的示例配置复制进去(services.yaml、bookmarks.yaml、settings.yaml、widgets.yaml、docker.yaml 全套)。你可以直接在 1Panel 的文件管理器里打开 ./config/services.yaml 改,改完点页面右下角刷新,立刻看到效果。这样比自己从零手写更快建立感觉。
方式二:直接从上面的示例配置抄。把 services.yaml 和 settings.yaml 直接覆盖过去,然后逐个改地址。改完刷新。
无论哪种,第一件事都是先改 HOMEPAGE_ALLOWED_HOSTS——如果你一开始没写这个环境变量,会发现页面能开但所有组件都红着报错,日志里是 host 校验失败的提示。这不是组件坏了。
改完为什么没反应:Homepage 是静态生成的,YAML 改完必须点刷新(右上角/右下角的刷新图标),或者重启容器。如果你确认改对了却还是旧样子,先想想刷没刷。
最小可用配置
装完按这个顺序配,十分钟能到一个能用的状态:
- 先只放三个服务。挑你最常用的三个,写进
services.yaml,确认能点开、图标能显示 - 接上 docker.yaml。如果容器都在这台机器上,写
socket: /var/run/docker.sock,然后给一两个容器加 label 试试自动发现 - 加一两个组件。优先选你已经有 API Key 的服务(Immich、Gitea、Jellyfin 这三个最容易验证)
- 配
widgets.yaml的顶部信息条。加个搜索框、日期时间、系统资源,页面立刻有"仪表盘"的感觉:
- resources:
cpu: true
memory: true
disk: /mnt/data
label: 主机
expanded: true
- datetime:
text_size: xl
format:
dateStyle: short
timeStyle: short
hourCycle: h23
- search:
provider: baidu
focus: true
target: _blank
注意 resources 组件的 disk: /mnt/data 要求这个路径在容器里存在——所以 compose 里要把它挂进来(上面推荐版里 - /mnt/data:/mnt/data:ro 就是干这个的)。只显示 CPU 和内存就不需要挂。
- 钉死主题和语言。
theme: dark+language: zh-Hans,避免每次换设备都要切一遍
告警/通知配置
先说结论:Homepage 没有告警功能。 它不会主动告诉你任何事。这不是配置问题,是产品定位——它的设计目标是"打开时好看、数据准",不是"出事时喊你"。
所以这一节的正确写法是:把告警留给第 1 期 Uptime Kuma,把展示留给 Homepage,两者用同一个服务清单。具体分工:
| 需求 | 用谁 | 怎么配 |
|---|---|---|
| 服务挂了要立刻知道 | Uptime Kuma | 对每个服务建一个 HTTP(s) 监控,通知渠道用第 13 期 ntfy 的推送地址 |
| 打开页面时看到服务状态 | Homepage | siteMonitor 或组件的实时数据 |
| 想知道容器是不是还活着 | Homepage(Docker 集成) | 接 socket 后容器卡片上直接有状态点 |
| 磁盘快满了要提前知道 | Uptime Kuma(Push 监控)+ 定时脚本 | Homepage 的 resources 组件只能"看",不能"报" |
Homepage 能做的"轻监控"只有两个字段,配在服务条目上:
- Nextcloud:
icon: nextcloud.png
href: https://cloud.example.com
siteMonitor: http://nextcloud:80 # 发 HTTP HEAD(失败退化为 GET)测响应时间
statusStyle: dot # dot = 只显示绿点;basic = 显示 UP / DOWN
ping: 192.168.31.194 # 真 ICMP ping,只支持 IPv4
siteMonitor 有个必须知道的细节:它是从容器里发请求的,走的是容器网络。如果你的服务在反代后面、或者需要登录才能访问,siteMonitor 写公网域名会拿到 401/302,显示成"down"——这时候应该写内部地址(容器名或内网 IP:端口)。官方排障文档专门强调过这点。
ping 依赖容器里的 ping 命令。Homepage 官方镜像基于 alpine,Dockerfile 里已经装了 iputils-ping(我查了镜像构建记录,apk add su-exec iputils-ping shadow),所以直接就能用,不用自己加。
反向代理与 HTTPS
Homepage 本身在局域网裸跑 HTTP 完全够用。但如果你要在外面访问,反代是必须的,而且有两个坑比往期都重要。
用第 2 期的 NPM 举最短路径:
- Proxy Hosts → Add Proxy Host
- Domain:
home.example.com;Forward Hostname:homepage;Forward Port:3000 - 勾上 Websockets Support(Homepage 的页面刷新和部分组件走 WebSocket)
- SSL 标签页:申请证书,勾 Force HTTPS
坑一:HOMEPAGE_ALLOWED_HOSTS 必须同步加上反代后的域名。忘了加的表现是"内网能开、域名打开一片红"。正确的值是内网 IP 和域名都写上:
HOMEPAGE_ALLOWED_HOSTS: 192.168.31.194:3000,home.example.com
坑二:如果你启用了内置登录(HOMEPAGE_AUTH_ENABLED=true),一定要在反代层做限流。官方原话是 Homepage 不对密码尝试做应用层限流,而且每次失败只在日志里打一行 warn。公网暴露就等于把密码框交给爆破脚本。两个补救手段:
- 在 NPM 里给
/api/auth/callback/credentials加请求频率限制,或者用 NPM 的 Access List 加一层 Basic Auth - 用日志做 fail2ban / CrowdSec 过滤,匹配上面那行 warn 日志
启用内置登录需要三个环境变量同时给(缺一个都会启动失败或登录页异常):
environment:
HOMEPAGE_AUTH_ENABLED: "true"
HOMEPAGE_AUTH_SECRET: "用 openssl rand -base64 32 生成,至少 32 字符"
HOMEPAGE_AUTH_PASSWORD: "一个强密码"
HOMEPAGE_EXTERNAL_URL: "https://home.example.com" # 必须带 https://,否则 cookie 不带 Secure 标志
如果你有 OIDC 提供方(比如 Authentik、Keycloak),更推荐走 OIDC:设 HOMEPAGE_OIDC_ISSUER、HOMEPAGE_OIDC_CLIENT_ID、HOMEPAGE_OIDC_CLIENT_SECRET,回调地址填 https://home.example.com/api/auth/callback/homepage-oidc。但要清楚一点:Homepage 不做 claim 级授权——OIDC 侧授权谁能登录这个 client,谁进来就能看到全部内容,没有"只给某人看某几个服务"这种能力。加了 HOMEPAGE_OIDC_AUTO_LOGIN=true 后如果配错了登不进去,访问 /auth/signin?autologin=0 可以绕过自动跳转回到登录页——这个逃生口官方专门写在文档里,值得记住。
1Panel 的一个实操差异:1Panel 的站点反向代理默认会透传上游响应头。这对 Homepage 是好事,一般不需要手动加任何 add_header。但反过来说,不要自己去给 Homepage 加 add_header X-Frame-Options 之类——第 16 期 Actual Budget 就是在"重复设置安全头"上栽过,浏览器会判定策略无效。Homepage 自己已经设了 CSP,代理层保持默认即可。1Panel 的站点配置路径在 /opt/1panel/www/conf.d/<域名>.conf,需要微调时改这里。
踩坑清单
- 组件全红、日志报 host 校验失败。九成是
HOMEPAGE_ALLOWED_HOSTS没写或写错。注意必须跟浏览器地址栏里的主机:端口完全一致——写home.example.com但实际访问home.example.com:8443,或者反代后 Host 头带了端口,都会失败。官方建议:拿不准就先设LOG_LEVEL=debug,日志里会打印它收到的是什么 host,直接抄过来 - 组件的
url结尾多了斜杠。http://gitea:3000/不行,必须是http://gitea:3000。官方排障文档第一条就是这个 - 两个服务/分组重名。哪怕是不同分组下的同名服务,组件数据也会串。取名的时候带上用途,比如
Jellyfin-客厅、Jellyfin-备用 - 容器名解析不了。Homepage 用容器名访问其他服务,前提是两个容器在同一个 Docker 网络。
docker network inspect看一下。用了 1Panel 的话,默认都会挂在1panel-network这个外部网络上,通常没问题 - 组件从容器里连不上服务,但从宿主机能连。
siteMonitor和组件请求都是容器内发出的,网络路径和你在宿主机 curl 不一样。官方给的排查第一步很朴素但有效:docker exec homepage ping <服务地址>,容器里压根没有curl(alpine 基础镜像不带),需要的话docker exec homepage apk add curl临时装上 - 设了 PUID/PGID 之后 Docker 状态读不出来。前面说过:非 root 运行 + 直接挂 socket 是互斥的。要么 PUID 留 0,要么上 socket-proxy
- 改了 YAML 但页面没变。静态生成的,必须点刷新图标或重启容器。另外 YAML 缩进错了不会报错,只是那一段被忽略——建议改完先用在线 YAML 校验器过一遍
- 背景图加了却不显示。Next.js 静态站的限制:加新图片后必须重启容器。另外官方明确警告不要把整个
/app/public/做 bind mount,只挂/app/public/images这一个子目录就行 - 图标显示不出来。图标名走的是 Dashboard Icons 这个远程 CDN(还有
mdi-、si-、sh-三种前缀来源)。这些图标是浏览器去 CDN 拉的,不是容器内置的——国内网络下 CDN 不通就会一片空白。要离线可用就得自己下载图标文件放进/app/public/icons并在配置里指向本地路径 - 把 docker socket 直接挂进去了。这是最需要警惕的一条。挂了等于把宿主机 root 权限通过一个 HTTP API 暴露给容器。生产环境建议改成 socket-proxy,只开
CONTAINERS=1等读操作:
dockerproxy:
image: ghcr.io/tecnativa/docker-socket-proxy:latest
container_name: dockerproxy
restart: unless-stopped
environment:
CONTAINERS: 1 # 只允许查看容器
SERVICES: 1 # 用 swarm 时才需要
TASKS: 1 # 用 swarm 时才需要
POST: 0 # 禁掉所有写操作,等于只读
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
ports:
- "127.0.0.1:2375:2375" # 只监听本机,不对外
然后 docker.yaml 改成:
my-docker:
host: dockerproxy
port: 2375
这样 Homepage 拿到的是一个"只能读容器列表"的 API,即使被攻破也动不了你的容器。多花一个容器,换掉一个 root 后门,很值。
备份
Homepage 的备份是往期所有项目里最简单的——要备的只有 config 目录下的几个 YAML 文件,没有数据库、没有二进制资产、没有索引。
# 在线备份(安全,YAML 是纯文本,不存在写一半损坏的问题)
tar czf /opt/backups/homepage-$(date +%Y%m%d).tar.gz -C /opt/homepage config
# 恢复
tar xzf /opt/backups/homepage-20261002.tar.gz -C /opt/homepage
唯一要提醒的一点:如果你把 API Key 明文写在 YAML 里,那备份文件里就有明文密钥。两个应对办法——用前面说的 HOMEPAGE_VAR_XXX 环境变量把密钥外置(这样 YAML 里只有 {{HOMEPAGE_VAR_XXX}} 占位符,备份出去也不泄露),或者把备份文件权限收一下:
chmod 600 /opt/backups/homepage-*.tar.gz
推荐前者,顺手还能防住"截图发群里忘了打码"这种事。
小结
适合谁
- 已经自托管了三个以上服务的人——这是 Homepage 的价值门槛。一个服务不需要仪表盘,十个服务没有仪表盘就真的会乱
- 把这个系列从头跟下来的人。前 17 期里 11 个项目有原生组件,接进来立刻能看到实时数据,这是最爽的一种用法
- 想让家人也能用上自建服务的人——一个域名、一排图标、装成 PWA 放手机桌面,比教他们记端口靠谱得多
- 想要一个"打开就能看到全局"的首页的人:磁盘还剩多少、谁在转码、Gitea 有没有未读通知,一眼扫完
- 喜欢 YAML 配置、不想点十几次鼠标的人
不适合谁
- 只有一个服务的人。为了一个入口单独跑一个容器,收益是负的
- 想要监控告警的人。Homepage 不会主动通知你任何事,这个需求请交给第 1 期 Uptime Kuma + 第 13 期 ntfy
- 想给不同用户看不同内容的人。它没有细粒度权限,登录要么全看到要么看不到
- 讨厌 YAML 缩进的人。四个配置文件全是 YAML,缩进错了不报错、只是静默失效,对新手不友好
- 内网服务完全不想暴露的人。虽然组件请求是服务端代理、浏览器不直连内网,但 Homepage 自身一旦公网可达,就等于给出了你全部内网服务的清单和地址——公网部署一定要开内置登录 + 反代限流 +
disableIndexing
在这个系列里的位置:Homepage 是"收口"的那一期。前面 17 期都在往外扩——密码、照片、音乐、电影、文档、代码、账本……扩到一定数量,就需要一个地方把它们收拢。它不替代任何一个服务,但它让前面那 17 个服务从"一堆容器"变成"一个系统"。
项目地址
- GitHub:https://github.com/gethomepage/homepage
- 官网与文档:https://gethomepage.dev
- 配置文件文档:https://gethomepage.dev/configs/
- 组件清单(161 个):https://gethomepage.dev/widgets/
- 排障指南:https://gethomepage.dev/troubleshooting/
- Docker 镜像:
ghcr.io/gethomepage/homepage(主)/gethomepage/homepage(Docker Hub 同名可拉) - 图标库:https://github.com/homarr-labs/dashboard-icons