目录一、总览Homepage 是什么能做什么二、整体架构三、部署安装四、配置文件详解五、配置实战搭建你的服务导航六、界面效果与状态徽标七、核心功能使用详解八、数据持久化与备份九、常见问题十、总结与速查卡一、总览Homepage 是什么能做什么Homepage是一个自托管的服务导航首页GitHub 25k Star把你部署的各种服务Portainer、Uptime Kuma、Nextcloud、Jellyfin……集中到一个漂亮的页面上还能自动显示每个服务的运行状态。一句话总结给自己部署的一堆服务做一个门户首页——打开浏览器就是所有服务的入口谁挂了、谁正常一眼看清。能做什么说明服务导航所有服务入口集中一个页面分组管理Docker 状态徽标自动显示每个容器 RUNNING / HEALTHY / STOPPED资源监控显示 CPU、内存、磁盘使用widgets搜索框内置 Google / 百度 / DuckDuckGo 搜索书签管理常用网站书签分类存放多主题深色 / 浅色 / 自定义界面精美中文界面自带简体中文适用人群Docker 玩家服务多了需要一个入口、HomeLab 爱好者、开发者个人门户、任何装了一堆服务记不住地址的人。和本系列的关系前两篇装了 Portainer管理容器和 Uptime Kuma监控服务这一篇把它们全部收进一个导航首页——这才是个人服务中台该有的样子。二、整体架构原理说明为什么这么用浏览器 → Homepage通过 HTTP 访问http://服务器IP:3000看到导航页Homepage → Docker Socket通过挂载的docker.sock自动发现所有容器实时显示运行状态这是核心亮点Homepage → 配置文件读取/app/config下的 YAML 配置哪些服务、怎么分组、什么图标导航链接点击服务卡片跳转到对应服务Portainer:9000、Uptime Kuma:3001……核心概念Homepage 是配置驱动的——页面长什么样全由 YAML 文件决定。改配置 改页面热加载生效。三、部署安装前置准备项要求Docker19.03本文实测 29.7.2内存256MBHomepage 轻量端口3000Web UIDocker Compose 部署推荐mkdir -p homepage cd homepage mkdir -p config # 配置文件目录先建好避免权限问题 vim docker-compose.ymldocker-compose.ymlversion: 3.8 services: homepage: image: gethomepage/homepage:latest container_name: homepage restart: always ports: - 3000:3000 volumes: - /var/run/docker.sock:/var/run/docker.sock # Docker 状态检测可选但推荐 - ./config:/app/config # 配置文件目录 volumes: homepage-config:启动docker compose up -dDocker Run 方式一行命令docker run -d --name homepage --restartalways \ -p 3000:3000 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $(pwd)/config:/app/config \ gethomepage/homepage:latest⚠️关键挂载./config:/app/config是配置目录必须先创建。不挂的话容器会把配置写在容器内删容器就丢。验证部署成功docker ps | grep homepage # homepage gethomepage/homepage:latest Up (healthy) 0.0.0.0:3000-3000/tcp curl -s -o /dev/null -w HTTP状态码: %{http_code}\n http://127.0.0.1:3000/ # HTTP状态码: 200 ✅ 部署成功浏览器打开http://127.0.0.1:3000默认页面长这样还没配置只有系统信息 默认页已显示 CPU/内存/磁盘 widgets但还没有任何服务入口——下面开始配置。四、配置文件详解Homepage 的配置核心在/app/config目录最常用 3 个 YAML文件作用必填config.yaml主配置标题、语言、主题否有默认services.yaml服务组配置页面导航入口否不配则无导航docker.yamlDocker 集成自动显示容器状态否配了才有状态徽标bookmarks.yaml书签配置否widgets.yaml小组件资源监控等否4.1 config.yaml主配置# Homepage 主配置 title: 我的服务导航 # 页面标题 language: zh-CN # 中文界面 theme: dark # 深色主题4.2 services.yaml服务导航核心--- # Homepage 服务组配置 # 顶层是组列表每个组下有多个服务 - Development: # 组名页面上的分组标题 - Portainer: # 服务名卡片标题 href: http://127.0.0.1:9000 # 点击跳转地址 description: Docker 可视化管理面板 # 卡片副标题 icon: https://cdn.jsdelivr.net/gh/selfhst/icons/png/portainer.png # 图标 URL server: my-docker # 对应 docker.yaml 里的实例名 container: portainer # 对应 Docker 容器名 → 自动显示状态 - Uptime Kuma: href: http://127.0.0.1:3001 description: 网站监控 icon: https://cdn.jsdelivr.net/gh/selfhst/icons/png/uptime-kuma.png server: my-docker container: uptime-kuma - Monitoring: # 第二组 - Homepage: href: http://127.0.0.1:3000 description: 本导航页 icon: https://cdn.jsdelivr.net/gh/selfhst/icons/png/homepage.png server: my-docker container: homepage4.3 docker.yamlDocker 状态集成# Homepage Docker 集成配置 my-docker: # 实例名services.yaml 里 server 字段对应 socket: /var/run/docker.sock # Docker socket 路径 stats: true # 显示容器资源占用核心机制services.yaml里写了server: my-dockercontainer: portainerHomepage 就会通过 docker.sock 查询这个容器的状态在卡片上显示RUNNING / HEALTHY徽标。五、配置实战搭建你的服务导航以本机真实环境为例已有 Portainer:9000、Uptime Kuma:3001完整走一遍。步骤 1创建配置目录mkdir -p homepage/config步骤 2写 config.yamlvim homepage/config/config.yaml内容见 4.1 节。步骤 3写 services.yaml放你的服务把前两篇部署的 Portainer 和 Uptime Kuma 加进去内容见 4.2 节。步骤 4写 docker.yaml开启状态检测内容见 4.3 节。步骤 5重启容器让配置生效docker restart homepageHomepage 支持配置热加载但修改 docker.yaml 或首次配置后建议重启一次确保生效。步骤 6刷新页面看效果刷新http://127.0.0.1:3000——你的服务导航就出现了六、界面效果与状态徽标配置完成后页面从空壳变成完整的服务导航真实效果本次实测区域内容状态徽标Development 组Portainer 卡片 RUNNING运行中Uptime Kuma 卡片 HEALTHY健康Monitoring 组Homepage 卡片 HEALTHY顶部 widgetsCPU / 内存 / 磁盘实时刷新状态徽标说明状态含义颜色RUNNING容器运行中绿/蓝HEALTHY运行且健康检查通过绿STOPPED / EXITED容器已停止红/灰RESTARTING正在重启黄最有价值的点哪个服务挂了打开 Homepage 一眼看到红色状态不用一个个docker ps。这就是自托管导航首页和普通网址收藏夹的本质区别。点击View container stats还能展开看每个容器的 CPU/内存占用。七、核心功能使用详解7.1 分组与布局services.yaml 顶层每个- 组名:就是一个分组页面按顺序排列。常用分组- 开发工具: - Portainer: ... - Code Server: ... - 媒体娱乐: - Jellyfin: ... - Navidrome: ... - AI 服务: - Ollama: ... - Open WebUI: ...7.2 自定义服务图标icon字段支持方式示例说明URLhttps://cdn.jsdelivr.net/gh/selfhst/icons/png/portainer.png在线图标推荐本地路径/icons/xxx.png放在 /app/config/icons 下无需图标省略显示服务名首字母 selfh.st/icons 有常用开源服务图标库直接引用 CDN 即可。7.3 Docker 状态集成docker.yaml 里配置实例后任何服务只要在 services.yaml 里写server: 实例名container: 容器名就自动显示状态。支持多 Docker 实例# docker.yaml 本地Docker: socket: /var/run/docker.sock 远程服务器: host: tcp://192.168.1.10:2375 # 远程 Docker API7.4 Widgets小组件默认已显示 CPU/内存/磁盘。settings.yaml 可加更多# settings.yaml 示例 providers: openweathermap: your-api-key # 天气组件常用 widgets系统资源、天气预报、搜索结果、日期时间。7.5 搜索框页面顶部内置搜索框settings.yaml 可选搜索引擎# settings.yaml search: provider: baidu # google / baidu / duckduckgo / bing 等八、数据持久化与备份Homepage 的数据就是配置文件全部在config/目录# 备份其实就是复制配置文件 tar czf homepage-config-backup.tar.gz config/ # 迁移到新机器 # 1. 新机器建 config 目录并解压备份 tar xzf homepage-config-backup.tar.gz # 2. 重新 docker run挂载同一目录 # 3. 页面配置全部还原 相比其他服务数据库在卷里Homepage 备份异常简单——配置即全部改坏了改回来也容易。九、常见问题Q1: 页面空白 / 服务卡片不显示检查 services.yaml 格式顶层必须是- 组名:带连字符看容器日志docker logs homepage | grep error确认 config 目录挂载正确docker exec homepage ls /app/configQ2: 状态徽标不显示没有 RUNNING/HEALTHY确认 docker.yaml 存在且格式正确socket:不是host:确认 services.yaml 里服务写了server: my-dockercontainer: 容器名容器名要完全一致docker ps看 NamesQ3: 配置改了没生效先试热加载等 10 秒刷新页面不行就docker restart homepage还不行查日志有无 YAML 解析错误Q4: 服务图标显示不出来破图CDN 图标库可能被墙 → 换 selfh.st 其他 CDN 或本地图标国内网络建议下载图标到/app/config/icons/后用本地路径Q5: 如何加一个不在 Docker 里的服务如外部网站services.yaml 里不写 server/container即可只保留 href/description- 外部服务: - 百度: href: https://www.baidu.com description: 搜索引擎Q6: 端口冲突3000 被占改映射端口- 8080:3000访问http://IP:8080。注意 services.yaml 里的 href 也要同步改。十、总结与速查卡回到总Homepage 把分散的服务入口收拢成一个带实时状态的可视化门户——配一次天天用。配合本系列Portainer 管容器、Uptime Kuma 盯故障、Homepage 做门户三件套齐活你的 HomeLab 体验直接上一个大台阶。速查卡项值镜像gethomepage/homepage:latest端口3000Web UI配置目录/app/config挂载本地 ./config核心文件config.yaml / services.yaml / docker.yaml关键挂载/var/run/docker.sock状态检测访问地址http://服务器IP:3000版本本文实测 v2.2.0一键部署mkdir -p homepage/config cd homepage docker run -d --name homepage --restartalways \ -p 3000:3000 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $(pwd)/config:/app/config \ gethomepage/homepage:latest三步上手部署一条命令 → 写 services.yaml放服务 → 加 docker.yaml开状态本文为《Docker 可部署项目清单》系列第三篇。第一篇Portainer 可视化面板第二篇Uptime Kuma 监控后续Ollama Open WebUI 本地 AI 等欢迎关注。如果本文对你有帮助欢迎点赞收藏。评论区可以交流 Homepage 使用中遇到的问题。 
长河君 · 2026/9/6 2:29:13 · 阅读 1.2k Homepage 自托管导航首页部署与使用教程
目录一、总览Homepage 是什么能做什么二、整体架构三、部署安装四、配置文件详解五、配置实战搭建你的服务导航六、界面效果与状态徽标七、核心功能使用详解八、数据持久化与备份九、常见问题十、总结与速查卡一、总览Homepage 是什么能做什么Homepage是一个自托管的服务导航首页GitHub 25k Star把你部署的各种服务Portainer、Uptime Kuma、Nextcloud、Jellyfin……集中到一个漂亮的页面上还能自动显示每个服务的运行状态。一句话总结给自己部署的一堆服务做一个门户首页——打开浏览器就是所有服务的入口谁挂了、谁正常一眼看清。能做什么说明服务导航所有服务入口集中一个页面分组管理Docker 状态徽标自动显示每个容器 RUNNING / HEALTHY / STOPPED资源监控显示 CPU、内存、磁盘使用widgets搜索框内置 Google / 百度 / DuckDuckGo 搜索书签管理常用网站书签分类存放多主题深色 / 浅色 / 自定义界面精美中文界面自带简体中文适用人群Docker 玩家服务多了需要一个入口、HomeLab 爱好者、开发者个人门户、任何装了一堆服务记不住地址的人。和本系列的关系前两篇装了 Portainer管理容器和 Uptime Kuma监控服务这一篇把它们全部收进一个导航首页——这才是个人服务中台该有的样子。二、整体架构原理说明为什么这么用浏览器 → Homepage通过 HTTP 访问http://服务器IP:3000看到导航页Homepage → Docker Socket通过挂载的docker.sock自动发现所有容器实时显示运行状态这是核心亮点Homepage → 配置文件读取/app/config下的 YAML 配置哪些服务、怎么分组、什么图标导航链接点击服务卡片跳转到对应服务Portainer:9000、Uptime Kuma:3001……核心概念Homepage 是配置驱动的——页面长什么样全由 YAML 文件决定。改配置 改页面热加载生效。三、部署安装前置准备项要求Docker19.03本文实测 29.7.2内存256MBHomepage 轻量端口3000Web UIDocker Compose 部署推荐mkdir -p homepage cd homepage mkdir -p config # 配置文件目录先建好避免权限问题 vim docker-compose.ymldocker-compose.ymlversion: 3.8 services: homepage: image: gethomepage/homepage:latest container_name: homepage restart: always ports: - 3000:3000 volumes: - /var/run/docker.sock:/var/run/docker.sock # Docker 状态检测可选但推荐 - ./config:/app/config # 配置文件目录 volumes: homepage-config:启动docker compose up -dDocker Run 方式一行命令docker run -d --name homepage --restartalways \ -p 3000:3000 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $(pwd)/config:/app/config \ gethomepage/homepage:latest⚠️关键挂载./config:/app/config是配置目录必须先创建。不挂的话容器会把配置写在容器内删容器就丢。验证部署成功docker ps | grep homepage # homepage gethomepage/homepage:latest Up (healthy) 0.0.0.0:3000-3000/tcp curl -s -o /dev/null -w HTTP状态码: %{http_code}\n http://127.0.0.1:3000/ # HTTP状态码: 200 ✅ 部署成功浏览器打开http://127.0.0.1:3000默认页面长这样还没配置只有系统信息 默认页已显示 CPU/内存/磁盘 widgets但还没有任何服务入口——下面开始配置。四、配置文件详解Homepage 的配置核心在/app/config目录最常用 3 个 YAML文件作用必填config.yaml主配置标题、语言、主题否有默认services.yaml服务组配置页面导航入口否不配则无导航docker.yamlDocker 集成自动显示容器状态否配了才有状态徽标bookmarks.yaml书签配置否widgets.yaml小组件资源监控等否4.1 config.yaml主配置# Homepage 主配置 title: 我的服务导航 # 页面标题 language: zh-CN # 中文界面 theme: dark # 深色主题4.2 services.yaml服务导航核心--- # Homepage 服务组配置 # 顶层是组列表每个组下有多个服务 - Development: # 组名页面上的分组标题 - Portainer: # 服务名卡片标题 href: http://127.0.0.1:9000 # 点击跳转地址 description: Docker 可视化管理面板 # 卡片副标题 icon: https://cdn.jsdelivr.net/gh/selfhst/icons/png/portainer.png # 图标 URL server: my-docker # 对应 docker.yaml 里的实例名 container: portainer # 对应 Docker 容器名 → 自动显示状态 - Uptime Kuma: href: http://127.0.0.1:3001 description: 网站监控 icon: https://cdn.jsdelivr.net/gh/selfhst/icons/png/uptime-kuma.png server: my-docker container: uptime-kuma - Monitoring: # 第二组 - Homepage: href: http://127.0.0.1:3000 description: 本导航页 icon: https://cdn.jsdelivr.net/gh/selfhst/icons/png/homepage.png server: my-docker container: homepage4.3 docker.yamlDocker 状态集成# Homepage Docker 集成配置 my-docker: # 实例名services.yaml 里 server 字段对应 socket: /var/run/docker.sock # Docker socket 路径 stats: true # 显示容器资源占用核心机制services.yaml里写了server: my-dockercontainer: portainerHomepage 就会通过 docker.sock 查询这个容器的状态在卡片上显示RUNNING / HEALTHY徽标。五、配置实战搭建你的服务导航以本机真实环境为例已有 Portainer:9000、Uptime Kuma:3001完整走一遍。步骤 1创建配置目录mkdir -p homepage/config步骤 2写 config.yamlvim homepage/config/config.yaml内容见 4.1 节。步骤 3写 services.yaml放你的服务把前两篇部署的 Portainer 和 Uptime Kuma 加进去内容见 4.2 节。步骤 4写 docker.yaml开启状态检测内容见 4.3 节。步骤 5重启容器让配置生效docker restart homepageHomepage 支持配置热加载但修改 docker.yaml 或首次配置后建议重启一次确保生效。步骤 6刷新页面看效果刷新http://127.0.0.1:3000——你的服务导航就出现了六、界面效果与状态徽标配置完成后页面从空壳变成完整的服务导航真实效果本次实测区域内容状态徽标Development 组Portainer 卡片 RUNNING运行中Uptime Kuma 卡片 HEALTHY健康Monitoring 组Homepage 卡片 HEALTHY顶部 widgetsCPU / 内存 / 磁盘实时刷新状态徽标说明状态含义颜色RUNNING容器运行中绿/蓝HEALTHY运行且健康检查通过绿STOPPED / EXITED容器已停止红/灰RESTARTING正在重启黄最有价值的点哪个服务挂了打开 Homepage 一眼看到红色状态不用一个个docker ps。这就是自托管导航首页和普通网址收藏夹的本质区别。点击View container stats还能展开看每个容器的 CPU/内存占用。七、核心功能使用详解7.1 分组与布局services.yaml 顶层每个- 组名:就是一个分组页面按顺序排列。常用分组- 开发工具: - Portainer: ... - Code Server: ... - 媒体娱乐: - Jellyfin: ... - Navidrome: ... - AI 服务: - Ollama: ... - Open WebUI: ...7.2 自定义服务图标icon字段支持方式示例说明URLhttps://cdn.jsdelivr.net/gh/selfhst/icons/png/portainer.png在线图标推荐本地路径/icons/xxx.png放在 /app/config/icons 下无需图标省略显示服务名首字母 selfh.st/icons 有常用开源服务图标库直接引用 CDN 即可。7.3 Docker 状态集成docker.yaml 里配置实例后任何服务只要在 services.yaml 里写server: 实例名container: 容器名就自动显示状态。支持多 Docker 实例# docker.yaml 本地Docker: socket: /var/run/docker.sock 远程服务器: host: tcp://192.168.1.10:2375 # 远程 Docker API7.4 Widgets小组件默认已显示 CPU/内存/磁盘。settings.yaml 可加更多# settings.yaml 示例 providers: openweathermap: your-api-key # 天气组件常用 widgets系统资源、天气预报、搜索结果、日期时间。7.5 搜索框页面顶部内置搜索框settings.yaml 可选搜索引擎# settings.yaml search: provider: baidu # google / baidu / duckduckgo / bing 等八、数据持久化与备份Homepage 的数据就是配置文件全部在config/目录# 备份其实就是复制配置文件 tar czf homepage-config-backup.tar.gz config/ # 迁移到新机器 # 1. 新机器建 config 目录并解压备份 tar xzf homepage-config-backup.tar.gz # 2. 重新 docker run挂载同一目录 # 3. 页面配置全部还原 相比其他服务数据库在卷里Homepage 备份异常简单——配置即全部改坏了改回来也容易。九、常见问题Q1: 页面空白 / 服务卡片不显示检查 services.yaml 格式顶层必须是- 组名:带连字符看容器日志docker logs homepage | grep error确认 config 目录挂载正确docker exec homepage ls /app/configQ2: 状态徽标不显示没有 RUNNING/HEALTHY确认 docker.yaml 存在且格式正确socket:不是host:确认 services.yaml 里服务写了server: my-dockercontainer: 容器名容器名要完全一致docker ps看 NamesQ3: 配置改了没生效先试热加载等 10 秒刷新页面不行就docker restart homepage还不行查日志有无 YAML 解析错误Q4: 服务图标显示不出来破图CDN 图标库可能被墙 → 换 selfh.st 其他 CDN 或本地图标国内网络建议下载图标到/app/config/icons/后用本地路径Q5: 如何加一个不在 Docker 里的服务如外部网站services.yaml 里不写 server/container即可只保留 href/description- 外部服务: - 百度: href: https://www.baidu.com description: 搜索引擎Q6: 端口冲突3000 被占改映射端口- 8080:3000访问http://IP:8080。注意 services.yaml 里的 href 也要同步改。十、总结与速查卡回到总Homepage 把分散的服务入口收拢成一个带实时状态的可视化门户——配一次天天用。配合本系列Portainer 管容器、Uptime Kuma 盯故障、Homepage 做门户三件套齐活你的 HomeLab 体验直接上一个大台阶。速查卡项值镜像gethomepage/homepage:latest端口3000Web UI配置目录/app/config挂载本地 ./config核心文件config.yaml / services.yaml / docker.yaml关键挂载/var/run/docker.sock状态检测访问地址http://服务器IP:3000版本本文实测 v2.2.0一键部署mkdir -p homepage/config cd homepage docker run -d --name homepage --restartalways \ -p 3000:3000 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $(pwd)/config:/app/config \ gethomepage/homepage:latest三步上手部署一条命令 → 写 services.yaml放服务 → 加 docker.yaml开状态本文为《Docker 可部署项目清单》系列第三篇。第一篇Portainer 可视化面板第二篇Uptime Kuma 监控后续Ollama Open WebUI 本地 AI 等欢迎关注。如果本文对你有帮助欢迎点赞收藏。评论区可以交流 Homepage 使用中遇到的问题。