导航页与可用性监控：Homepage 与 Uptime Kuma

完成后，打开一个网页就能看到 NAS 上所有服务的入口和在线状态（Homepage），服务挂了或者证书快到期时，你会收到通知（Uptime Kuma）。

适合谁

• 跑的服务多了，记不住哪个服务在哪个端口。
• 想在服务出问题之前，而不是家人来问「为什么相册打不开」的时候，知道它挂了。

两个工具分工不同：Homepage 是导航页和仪表盘，Uptime Kuma 是监控和告警。第一次部署的完整流程见部署第一个应用，这里直接用的就是它。要更重的监控，见外部监控：Prometheus、Grafana 与 SNMP。

监控器自己在 NAS 上，NAS 宕机时它也宕了

Uptime Kuma 跑在 OMV 上监控 OMV，整台 NAS 掉线时，监控器和它的通知一起消失，你什么也收不到。要监控「NAS 整机还活着吗」，监控方必须在 NAS 之外：另一台设备（树莓派、VPS、另一台电脑）上再跑一个 Uptime Kuma，监控这台 NAS。NAS 上的这个，监控的是容器和服务是否正常。

应用信息

项	Homepage	Uptime Kuma
示例清单	有 homepage，示例日期 2025-06-01	有 uptime-kuma，示例日期 2025-06-01
示例的问题	镜像路径是旧的	镜像还是 :1，旧的大版本
镜像	ghcr.io/gethomepage/homepage:latest	louislam/uptime-kuma:2
端口	3000	3001
数据	/app/config：一组 YAML 配置文件	/app/data：SQLite 数据库
官方文档	gethomepage.dev	Uptime Kuma 仓库

这两个示例都落后了

• Homepage：示例用 ghcr.io/benphelps/homepage:latest。截至 2026-10-23 查询 GHCR 的元数据，这个旧路径对应的是 v0.7.1，2023 年 10 月构建；官方现在的路径是 ghcr.io/gethomepage/homepage:latest，对应 v2.6.0，2026 年 10 月构建。示例里用的 HOMEPAGE_ALLOWED_HOSTS 是 v1.0 才有的变量，旧镜像用不了。
• Uptime Kuma：示例是 :1，官方 README 现在写的是 :2。v1 到 v2 是大版本更新，有破坏性改动，从 v1 升上来要先备份再迁移，新装直接用 :2。

部署 Homepage

服务 → Compose → 文件（Services → Compose → Files）→ 添加 → 从模板添加，选 homepage，添加后 编辑。示例原样是：

services:
  homepage:
    image: ghcr.io/benphelps/homepage:latest
    container_name: homepage
    environment:
      HOMEPAGE_ALLOWED_HOSTS: gethomepage.dev # required, may need port. See gethomepage.dev/installation/#homepage_allowed_hosts
      PUID: 1000 # optional, your user id
      PGID: 100 # optional, your group id
    ports:
      - 3000:3000
    volumes:
      - CHANGE_TO_COMPOSE_DATA_PATH/homepage:/app/config # Make sure your local config directory exists
      - /var/run/docker.sock:/var/run/docker.sock # (optional) For docker integrations
    restart: unless-stopped

改成这样：

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      HOMEPAGE_ALLOWED_HOSTS: "<NAS 的 IP>:3000"
      PUID: ${{ uid:"appuser" }}
      PGID: ${{ gid:"users" }}
    ports:
      - "3000:3000"
    volumes:
      - ${{ sf:"appdata" }}/homepage/config:/app/config
    restart: unless-stopped

• 镜像路径换成官方的。
• HOMEPAGE_ALLOWED_HOSTS：官方文档说这是 v1.0 起必填的变量。值是用逗号分隔、不带空格的主机列表，要写成你在浏览器里输入的样子，带端口，例如 192.168.1.10:3000。localhost:3000 和 127.0.0.1:3000 总是被允许。通过域名访问时，再加上域名。设成 * 可以关掉检查，官方不推荐。
• 去掉 docker.sock。这是 docker 集成要用的，但挂载它等于把 root 权限交给容器，见下。不需要显示容器状态，就别挂。
• PUID、PGID：Homepage 官方支持以非 root 运行。配置目录必须先建好并属于 appuser，用 服务 → Compose → 卷（Volumes）页的 创建绑定挂载路径，见容器权限。

保存，检查，上线。打开 http://<NAS 的 IP>:3000。Homepage 在配置文件不存在时，会把一套默认配置复制到配置目录里（services.yaml、settings.yaml、bookmarks.yaml、widgets.yaml、docker.yaml 等），所以目录必须是 appuser 可写的。

写 services.yaml

配置都是 YAML，appdata/homepage/config/services.yaml 里一级是分组，二级是服务。直接在 OMV 的 shell 里编辑它（这是 Homepage 自己的文件，不是 OMV 管理的配置），保存后刷新网页，不生效再重启容器：

- 管理:
    - OMV:
        href: http://<NAS 的 IP>
        description: NAS 管理界面
        siteMonitor: http://<NAS 的 IP>
- 应用:
    - Jellyfin:
        href: http://<NAS 的 IP>:8096
        description: 影音库
        siteMonitor: http://<NAS 的 IP>:8096
    - Uptime Kuma:
        href: http://<NAS 的 IP>:3001
        description: 监控
        widget:
          type: uptimekuma
          url: http://<NAS 的 IP>:3001
          slug: <状态页标识>

• siteMonitor 会对这个 URL 发 HEAD 请求（失败时退回 GET），卡片上显示状态和响应时间。它不会登录，需要认证的站点，监控的是登录页。
• widget 里的 uptimekuma 读的是 Uptime Kuma 的一个状态页，slug 是状态页地址里 /status/ 后面的那段，下面会建。

Homepage 只放在局域网

它列出了你所有服务的地址。官方文档说，对外的部署要放在反向代理或 VPN 后面。Homepage 2.0 起内置了简单的登录门：设置 HOMEPAGE_AUTH_ENABLED、HOMEPAGE_AUTH_SECRET、HOMEPAGE_EXTERNAL_URL 和 HOMEPAGE_AUTH_PASSWORD 几个环境变量，细节见官方文档。

docker 集成：要显示容器状态时

Homepage 能读 Docker 的容器状态。官方说，直接挂 docker.sock 不推荐，它要求 Homepage 以 root 运行，或者运行用户属于 docker 组。推荐的做法是用 docker-socket-proxy 容器，只开放只读的容器查询接口，Homepage 再通过网络连它。具体的配置见官方的 Docker 集成文档，本站不展开。用不到就别开。

部署 Uptime Kuma

流程和部署第一个应用完全一样。改好的版本：

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    volumes:
      - ${{ sf:"appdata" }}/uptime-kuma/data:/app/data
    ports:
      - "3001:3001"
    restart: unless-stopped

官方特别说明：数据目录不支持 NFS 这类网络文件系统，要放本地盘，所以放 appdata，别放网络挂载上。http://<NAS 的 IP>:3001 第一次打开时创建管理员账号。

监控什么

想监控	监控类型	填什么
OMV 的 Web 界面	HTTP(s)	http://<NAS 的 IP>，加上你改过的端口
SSH、SMB	TCP 端口	NAS 的 IP，端口 22 或 445
NAS 是否响应	Ping	NAS 的 IP
各个应用	HTTP(s)，或者 HTTP(s) 关键字	http://<NAS 的 IP>:端口
定时任务有没有按时跑	Push	见下
证书快到期	HTTP(s)	对 HTTPS 地址的监控里，打开证书到期提醒

Uptime Kuma 还支持 DNS、WebSocket、Docker 容器等类型。Docker 容器这一类要挂载 docker.sock，同样不推荐，改用 HTTP 或 TCP 监控应用的端口，效果差不多。

Push 监控反过来：Uptime Kuma 给你一个 URL，任务完成后去访问它，超过设定时间没收到就报警。适合监控备份任务：在 系统 → 计划任务（System → Scheduled Tasks）里，命令后面接上它：

<你的备份命令> && curl -fsS "<Push 地址>" > /dev/null

通知和误报

在设置里添加通知方式，支持 Telegram、邮件（SMTP）、Gotify 等九十多种，选一个你每天会看的。

• 重试次数：v2 里新建的监控，默认重试次数是 0，一次超时就告警，容易误报。建议调成 1 到 3 次。
• 检测间隔：家用 60 秒足够。
• 新建一个状态页（Status Pages），给它一个标识（slug），把监控项加进去，这个标识就是上面 Homepage 的 slug。

检查结果

1. http://<NAS 的 IP>:3000 能打开 Homepage，没有主机校验失败的提示，卡片的状态点是绿色。
2. 在 OMV 的 shell 里（root）运行 ls -ln 看 appdata/homepage/config，里面有 YAML 文件，属主是 appuser。
3. Uptime Kuma 里所有监控项显示正常。
4. 手动停止一个应用，一到两个检测周期内，你收到通知；再上线，收到恢复通知。
5. Homepage 里的 Uptime Kuma 小部件显示在线和离线的数量。

备份与维护

• Homepage：配置目录是一堆很小的 YAML，插件的计划备份会包含它。想保留你的布局，这就够了。
• Uptime Kuma：数据在 SQLite 里。官方说明，v2 起备份 data 目录是唯一支持的备份方式，而且要先停止服务。插件默认的「停止 → 备份 → 启动」就符合要求，别勾选跳过容器停止 / 启动，见更新与备份容器。监控项多、历史数据保留得久，数据目录可能超过插件默认的 1 GB 上限，要调大 最大尺寸 或者在卷行尾写 # BACKUP。
• 更新：Homepage 用 latest，更新前看一眼发布说明，配置项偶尔会改。Uptime Kuma 更新前先备份，大版本迁移要等它跑完，不要中途打断。

常见问题

Homepage 提示主机校验失败。HOMEPAGE_ALLOWED_HOSTS 里没有你在浏览器里输入的主机和端口。看 Homepage 的日志，把日志里输出的那个值原样加进去。

Homepage 启动报错，写不了配置目录。PUID 对应的用户对配置目录没有写权限。先用 创建绑定挂载路径 建目录，设好拥有者。

卡片的状态点是红色，服务其实是好的。siteMonitor 的 URL 在容器里访问不到，或者那个站点需要登录。用能直接返回结果的地址。

Uptime Kuma 老是误报。 检查重试次数，v2 的新监控默认是 0。

监控的服务正常，但我没收到通知。 在设置里给通知方式发送一条测试通知，并确认监控项勾选了这个通知。邮件通知依赖你的 SMTP 配置。更多通知渠道见通知扩展：Telegram 等第三方通知。

3000 或 3001 被占用。 改映射左边的数字，排查见端口冲突。

参考资料

• Homepage 文档：Docker 安装
• Homepage 文档：安装与 HOMEPAGE_ALLOWED_HOSTS
• Homepage 文档：服务配置
• Homepage 文档：Docker 集成
• Homepage 文档：Uptime Kuma 小部件
• Uptime Kuma 仓库与 README
• Uptime Kuma wiki：从 v1 迁移到 v2