banner
约 2,700 字
9 分钟

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

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 方式:

YAML
services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3000:3000
    volumes:
      - /vol2/1000/Ocotp/homepage/config:/app/config   # 配置目录,必须先建好
      - /var/run/docker.sock:/var/run/docker.sock:ro    # 可选,用于 Docker 集成(只读)
    environment:
      HOMEPAGE_ALLOWED_HOSTS: 192.168.31.10:3000        # 必填,见下方说明
      PUID: 1000                                        # 可选,以非 root 运行时的用户 ID
      PGID: 1000                                        # 可选,用户组 ID
    restart: unless-stopped

docker run 方式:

bash
docker run --name homepage \
  -e HOMEPAGE_ALLOWED_HOSTS=192.168.31.10:3000 \
  -e PUID=1000 -e PGID=1000 \
  -p 3000:3000 \
  -v /vol2/1000/Ocotp/homepage/config:/app/config \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --restart unless-stopped \
  ghcr.io/gethomepage/homepage:latest

几个必须说清的点:

  • `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 里,结构是"顶层是分组数组,组里是服务数组":

YAML
- 媒体:
    - Jellyfin:
        icon: jellyfin.png
        href: http://192.168.31.10:8096/
        description: 影音库
    - qBittorrent:
        icon: qbittorrent.png
        href: http://192.168.31.10:8080/
        description: 下载器

每条服务至少有 href(点击跳转地址),可选的 icon、description 让它更好看。分组可以嵌套,把相关服务收进子组。

给小部件(widget):服务卡片想要显示实时数据,就在服务下挂 widget,填对应服务的 API 信息。以三个常见服务为例:

YAML
- qBittorrent:
    icon: qbittorrent.png
    href: http://192.168.31.10:8080/
    description: 下载器
    widget:
      type: qbittorrent
      url: http://192.168.31.10:8080
      username: admin
      password: 你的密码

- Jellyfin:
    icon: jellyfin.png
    href: http://192.168.31.10:8096/
    description: 影音库
    widget:
      type: jellyfin
      url: http://192.168.31.10:8096
      key: 你的Jellyfin_API_Key

- Sonarr:
    icon: sonarr.png
    href: http://192.168.31.10:8989/
    description: 剧集管理
    widget:
      type: sonarr
      url: http://192.168.31.10:8989
      key: 你的Sonarr_API_Key

注意 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):比服务更轻,纯链接外跳,结构和服务类似:

YAML
- 常用:
    - GitHub:
        - abbr: GH
          href: https://github.com/
    - 路由器:
        - icon: router.png
          href: http://192.168.31.1/
          description: 主路由管理页

abbr 建议两个字母(站点按两字母设计),有 icon 时优先用图标。

信息部件(widgets.yaml):显示在页面顶部,按文件里的顺序排。一个实用的起步组合:

YAML
- resources:
    cpu: true
    memory: true
    disk: /

- search:
    provider: duckduckgo
    target: _blank

- datetime:
    text_size: xl
    format:
      dateStyle: short
      timeStyle: short

天气类部件需要 API Key。敏感信息不要硬写进 YAML,用环境变量占位:以 HOMEPAGE_VAR_ 或 HOMEPAGE_FILE_ 开头的环境变量,会替换配置里的 {{HOMEPAGE_VAR_XXX}}(HOMEPAGE_FILE_XXX 则从一个文件路径读内容)。比如:

YAML
- openweathermap:
    label: 家
    latitude: 31.23
    longitude: 121.47
    units: metric
    provider: openweathermap
    apiKey: {{HOMEPAGE_VAR_OWM_KEY}}

五、布局与外观:settings.yaml

settings.yaml 管应用级选项,改完点页面右下角的刷新图标清缓存重载即可。

YAML
title: 折腾日记 · 控制台
description: 我的自托管服务总览
theme: dark          # dark / light,固定主题并关闭切换器
color: slate         # 固定配色,如 slate / blue / emerald 等
background:
  image: https://images.unsplash.com/photo-1502790671504-542ad42d5189?auto=format&fit=crop&w=2560&q=80
  blur: sm
  saturate: 50
  brightness: 50
  opacity: 60

布局用 layout 控制每个分组是横排还是竖排、几列、要不要标签页:

YAML
layout:
  媒体:
    style: row        # row 横排 / column 竖排
    columns: 4
    icon: jellyfin.png   # 给分类加个图标
  运维工具:
    style: row
    columns: 3
    header: false        # 隐藏这个分组的标题栏

layout 里还可以给分组设 tab: 名称 做标签页视图、initiallyCollapsed: true 默认折叠;想全局换成纯图标风格,用 bookmarksStyle: icons 或分组级 iconsOnly: true。背景图除了用网络 URL,也能挂本地图片目录后用 /images/xxx.png 引用——但注意新增本地图片后要重启容器,且不要整目录挂 /app/public/。

六、Docker 集成与标签自动发现

想让卡片显示容器的状态和资源占用,先配 docker.yaml。推荐用 docker-socket-proxy 只读暴露,避免直接把宿主 socket 交给容器:

YAML
# docker-compose 片段:起一个只读代理
dockerproxy:
  image: ghcr.io/tecnativa/docker-socket-proxy:latest
  container_name: dockerproxy
  environment:
    - CONTAINERS=1
    - POST=0            # 禁止任何写操作,等价只读
  ports:
    - 127.0.0.1:2375:2375
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro
  restart: unless-stopped

然后在 docker.yaml 里登记这个实例:

YAML
my-docker:
  host: dockerproxy
  port: 2375

接着在 services.yaml 的服务上挂 server 和 container 就能显示状态:

YAML
- Jellyfin:
    icon: jellyfin.png
    href: http://192.168.31.10:8096/
    server: my-docker      # docker.yaml 里登记的实例名
    container: jellyfin    # 容器名

自动发现更省事:给容器打上 homepage.* 标签,服务会自己冒出来,连 server/container 都不用写:

YAML
labels:
  - homepage.group=媒体
  - homepage.name=Emby
  - homepage.icon=emby.png
  - homepage.href=http://emby.home/
  - homepage.description=媒体服务器
  - homepage.widget.type=emby
  - homepage.widget.url=http://emby.home
  - homepage.widget.key=你的APIKey

一个服务要挂多个部件时,用 homepage.widgets[0].xxx、homepage.widgets[1].xxx 递增索引。Swarm 部署时标签要写在 deploy.labels 下。

七、安全与反向代理(必读)

Homepage 能读到你各服务的 API 数据,所以只要它可能从不可信网络被访问,就必须放在带鉴权、TLS、并严格校验 Host 头的反向代理或 VPN 之后。从 v2.0 起它还内置了一道轻量登录闸(密码或 OIDC),按需开启:

YAML
environment:
  HOMEPAGE_AUTH_ENABLED: "true"
  HOMEPAGE_AUTH_SECRET: 至少32位随机串        # 用 openssl rand -base64 32 生成
  HOMEPAGE_EXTERNAL_URL: https://home.example.com   # 访问 Homepage 的绝对地址
  HOMEPAGE_AUTH_PASSWORD: 你的强密码          # 纯密码登录时必填
  • 走 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 错误 / 打不开

HOMEPAGE_ALLOWED_HOSTS 没配对

把日志里打印的 host(含端口)原样加进列表,逗号分隔不带空格

小部件显示 API Error

widget.url 带了结尾 / 或路径;key 错;容器连不到服务

URL 只写到主机端口;docker exec homepage ping 服务IP 验证连通;核对 API Key

改了 YAML 没生效

浏览器缓存了旧的仪表盘数据

点页面右下角刷新图标清缓存重载

本地图标 / 背景图不显示

新增本地文件后没重启容器

docker restart homepage

反代后 403 / 被 WAF 拦

请求缺浏览器 UA 或 Host 头不对

反代补正确 Host 头;确认 HOMEPAGE_ALLOWED_HOSTS 含对外域名

Docker 服务不显示状态

docker.yaml 实例名对不上,或容器名写错

核对 server 与 docker.yaml 键名、container 与容器名一致

九、写在最后

如果你手里有一台常年开机的 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

END