用 Docker 部署 GetHomepage：家庭服务仪表盘与书签入口

本文为环境搭建记录，配置以官方文档为准：gethomepage.dev

家里或实验室里 NAS、路由、监控、常用网页越来越多，浏览器书签和各个管理后台来回切换很费时间。GetHomepage 是一个可自托管的仪表盘：把服务卡片、Docker 状态、书签和小部件集中在一页，刷新浏览器就能总览。

本文将按顺序说明：

• 用 Docker Compose 拉起容器（端口、环境变量、权限）
• config 目录里各配置文件的分工
• settings.yaml 主题、语言与背景
• （可选）挂载本地图片 / 图标目录（不要挂载整个 /app/public）
• services.yaml 分组与卡片的最小可用写法
• bookmarks.yaml / widgets.yaml 各自管什么（仅作入门，细节见官网）
• （可选）挂载 docker.sock 做 Docker 集成（见官方 Docker 安装页）

---

为什么用 Docker Compose

Compose 把镜像、端口、卷和环境变量写进一个文件，换机器或重装时复制目录再 up 即可，便于长期备份与迁移。官方镜像托管在 ghcr.io/gethomepage/homepage。

---

1. 准备目录与 docker-compose.yaml

在服务器上新建目录（示例为 homepage），进入后创建 docker-compose.yaml，内容可参考：

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3123:3000 # 容器内 3000 → 宿主机 3123，可按需修改左侧端口
    env_file: .env
    volumes:
      - ./config:/app/config
    environment:
      # 必须设置，否则反代或域名访问可能被拒绝；含端口时写成 your-domain.com:3123
      # 说明见 https://gethomepage.dev/installation/#docker-installation
      HOMEPAGE_ALLOWED_HOSTS: your-domain.com
      PUID: $PUID
      PGID: $PGID
    restart: unless-stopped

将 your-domain.com 换成你实际访问用的主机名或 IP；若只用本机 localhost 测试，可写成 localhost:3123（与左侧映射端口一致）。

---

2. PUID / PGID 与 .env

容器内写配置、读挂载目录时，用与宿主机用户一致的 uid/gid 可减少权限问题。在宿主机执行：

id

根据输出在同目录创建 .env（示例，数值请换成你机器上的）：

PUID=1000
PGID=1000

---

3. 启动与检查

docker compose up -d
docker ps

容器健康后，用浏览器访问 http://<宿主机IP>:3123（或你的反代域名）即可看到默认仪表盘。若页面空白或 403，优先核对 HOMEPAGE_ALLOWED_HOSTS 是否与浏览器地址栏里的 Host（及端口）一致。

若要在 docker.yaml 里展示本机容器状态，需在 Compose 中额外挂载只读 Docker 套接字（更稳妥的做法见官方文档中的替代集成方式）：

volumes:
  - ./config:/app/config
  - /var/run/docker.sock:/var/run/docker.sock:ro

---

4. config 里有什么

进入 ./config，会看到 Homepage 的主要配置都是 YAML，改文件保存后，在页面右下角点 Refresh 即可重载（无需重启容器）。

config
├── bookmarks.yaml    # 书签
├── docker.yaml       # Docker 集成（常配合挂载 docker.sock）
├── kubernetes.yaml   # K8s 集成
├── logs/             # 运行后常见：日志目录（默认在 config 下，可用 logpath 调整）
├── services.yaml     # 服务分组与卡片
├── settings.yaml     # 全局设置（标题、主题、背景等）
└── widgets.yaml      # 小组件

按需修改对应文件即可：

文件	用途
bookmarks.yaml	书签分组与链接
docker.yaml	展示本机 Docker 容器状态（需挂载 docker.sock 等，见官方文档）
kubernetes.yaml	集群信息
services.yaml	对外展示的服务入口（分组、图标、链接）
settings.yaml	站点标题、语言、主题、背景图等
widgets.yaml	天气、搜索框等部件

---

5. settings.yaml 示例

例如修改站点标题、描述、主题和语言：

title: 我的仪表盘
description: 家庭服务与常用入口
theme: dark # 或 light
language: zh-Hans # 与 zh-CN 等价，官方会映射到简体

保存后在页面右下角刷新，即可看到生效。

---

6. 背景图：网络地址与本地文件

网络图片：可直接用字符串写法，或用带 image 的对象（便于同时加滤镜，见下一节）：

background: https://images.unsplash.com/photo-1502790671504-542ad42d5189?auto=format&fit=crop&w=2560&q=80

本地图片：官方要求不要把整个 /app/public 目录挂进去；只挂载放图片的子目录即可，例如：

volumes:
  - ./config:/app/config
  - ./images:/app/public/images
  # 自定义站点图标等可另挂：./icons:/app/public/icons

将背景图放到宿主机的 ./images/ 下，在 settings.yaml 里路径相对于 /app/public/images：

background:
  image: /images/background.jpg

官方说明：每次新增本地图片文件后，需要重启容器一次（Next.js 静态资源限制）；仅改 YAML 文字可点页面右下角刷新。

网络地址与本地路径二选一即可；YAML 中不能重复两个同名的 image 键。

---

7. 背景滤镜与透明度（Tailwind 风格）

Homepage 支持用类似 Tailwind 的键控制模糊、饱和度、亮度、不透明度，例如：

background:
  image: https://images.unsplash.com/photo-1502790671504-542ad42d5189?auto=format&fit=crop&w=2560&q=80
  blur: sm
  saturate: 50
  brightness: 50
  opacity: 50

各字段取值范围与含义可参考 Tailwind 文档 中 backdrop / opacity 相关说明；保存并刷新页面后查看效果。

---

8. services.yaml：分组与服务卡片

分组和服务列表都在 services.yaml 里维护。下面是一个最小可读示例（链接与图标请换成你自己的）：

- 常用入口:
    - 路由管理:
        href: http://192.168.1.1
        description: 主路由
        icon: mdi-router-wireless
    - NAS:
        href: https://nas.example.com
        description: 文件与备份
        icon: mdi-nas

- 监控:
    - Uptime:
        href: http://192.168.1.10:3001
        description: 可用性监控
        icon: mdi-heart-pulse

• 一级列表项（如 常用入口）是分组名。
• 其下的键（如 路由管理）是卡片标题；href 为点击跳转地址，description 为副标题，icon 可使用 Dashboard Icons 等命名方式，具体以 官方文档 - Service icons 为准。

纯收藏、不依赖监控/widget 的链接更适合放在 bookmarks.yaml，见下一节。

---

9. bookmarks.yaml：书签分组

bookmarks.yaml 用来按分组整理「点一下就跳转」的链接，结构和 services.yaml 一样是「分组名 → 多条书签」，适合文档、论坛、常用 SaaS 等；若还要显示 ping / Docker 状态 / 内嵌小部件，仍应使用 services.yaml 里的服务卡片。

一个最小示例（abbr 一般为两字母缩写，也可用 icon / description 覆盖默认展示，见官网）：

- 开发工具:
    - GitHub:
        - abbr: GH
          href: https://github.com/
    - MDN:
        - abbr: MD
          href: https://developer.mozilla.org/

分组顺序、是否只显示图标、与 services 分组的混排等，由 settings.yaml 里的 layout、bookmarksStyle 等控制。字段全集、嵌套分组与边界情况以官方为准：Bookmarks 配置，此处不再赘述。

---

10. widgets.yaml：全局小组件

widgets.yaml 负责页面上不依附于某一个服务卡片的公共部件，例如搜索、时间日期、天气、系统或第三方监控摘要等。另一类用法是在 services.yaml 的某条服务下写 widget，把「该服务的 API 信息」缩略展示在卡片里（如版本、请求数），与全局 widgets.yaml 互补。

不少部件需要 API Key 或自建服务地址；官方推荐在 settings.yaml 的 providers 里统一写密钥，再在具体 widget 里通过 provider 引用，避免把敏感信息散落在多个文件里。

当前版本支持哪些 widget、各自必填项与环境变量，变动较快，请直接查阅：Widgets 与各 widget 子页面，本文不再展开。

---

小结

• 用 Compose 固定镜像、端口、HOMEPAGE_ALLOWED_HOSTS 和 config 挂载，即可长期维护同一套仪表盘。
• 所有界面相关修改几乎都在 config/*.yaml 完成，改完在页面刷新即可。
• 背景、图标、本地资源通过 volume 挂到 /app/public/... 后，再用站内路径或 URL 引用。

书签与小组件的完整选项同理，以 Bookmarks、Widgets 为准。更复杂的 Docker API、代理与认证等也请查阅 GetHomepage 官方文档，避免与版本脱节。