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

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 是"把已经跑起来的服务收拾整齐的那个页面",不是新的服务。

部署前准备

  1. 一台跑着 Docker 的机器。它资源占用极低(静态站点),1 核 512M 都能跑,跟你那些服务放同一台机器最合适
  2. 想清楚要放哪些服务。不用一开始就全上,先挑 5~8 个最常用的,跑通了再扩。每个服务需要的信息就三样:名称、访问地址、图标名
  3. (可选)Docker socket。想显示容器状态就必须给,但直接挂 /var/run/docker.sock 等于把宿主机 root 权限交出去,生产环境建议走 socket-proxy(见配置章节)
  4. 镜像源:主 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

两个通用坑先说在前面:

  1. url 绝对不能以 / 结尾,也不能带 API 路径。写 http://gitea:3000,不要写 http://gitea:3000/ 或者 http://gitea:3000/api/v1。组件自己会拼路径,多写一段必然 404。这是官方排障文档列的第一条
  2. 服务和分组都必须唯一命名。同名服务(哪怕在不同分组)会让组件数据串台。官方明确写了 "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-Hans
  • disableIndexing: 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 改完必须点刷新(右上角/右下角的刷新图标),或者重启容器。如果你确认改对了却还是旧样子,先想想刷没刷。

最小可用配置

装完按这个顺序配,十分钟能到一个能用的状态:

  1. 先只放三个服务。挑你最常用的三个,写进 services.yaml,确认能点开、图标能显示
  2. 接上 docker.yaml。如果容器都在这台机器上,写 socket: /var/run/docker.sock,然后给一两个容器加 label 试试自动发现
  3. 加一两个组件。优先选你已经有 API Key 的服务(Immich、Gitea、Jellyfin 这三个最容易验证)
  4. 配 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 和内存就不需要挂。

  1. 钉死主题和语言。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 举最短路径:

  1. Proxy Hosts → Add Proxy Host
  2. Domain:home.example.com;Forward Hostname:homepage;Forward Port:3000
  3. 勾上 Websockets Support(Homepage 的页面刷新和部分组件走 WebSocket)
  4. 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