RSS 阅读器、云笔记、数据库后台各占一个域名，收藏夹里又混着预览环境和旧地址。Homepage 把这些入口按用途放进同一页，也能为支持的服务显示状态，方便从目录进入相应工具。
它适合给自己或小团队做服务目录。每个工具仍然负责自己的账号、权限和数据，Homepage 不会替它们统一登录，也不会把一个失效的应用变成可用服务。把数据库管理器放进导航以后，数据库管理器的认证仍要保留。
当前版本为 Homepage 2.4.0，发布于 2026 年 9 月 17 日。这个版本可以通过 Docker 部署，配置主要保存在 YAML 文件中。与一些旧教程不同，2.x 已经提供可选的密码或 OIDC 登录；公开使用时仍需要受控的入口，不能只设置一个域名白名单就让整页向外开放。
图中是项目提供的示例布局。刚装好时不需要添加这么多内容，先把自己每天使用的几个服务放上去，目录就已经有用。
先决定这页给谁看
如果只给自己用，可以先只监听服务器本机端口，通过 SSH 隧道打开。不必为了一个导航页先配置公网域名，也不用为了查看它而把其他应用的管理端口全部开放。
需要在手机和不同地点访问时，再增加 HTTPS 域名和访问控制。团队场景则要决定谁能进入这页、哪些服务可以显示，以及是否需要按角色建立不同入口。Homepage 的内置登录是一个简单的准入门槛，不应当作完整的多角色权限系统。
导航链接里可能出现内部域名、预览地址、管理后台名称。接入组件以后，还可能显示文档数量、媒体库统计或其他运行数据。因此，私人导航与公开导航最好分开配置。公开页面只放准备公开的服务，不要依赖访客“不知道地址”来保护后台信息。
如果已有能运行 Docker 的 VPS，可以先利用现有机器。重新购买时核对剩余内存、磁盘、网络和软件要求，不需要为了这个目录单独承诺某种固定配置必定够用。雨云优惠码为 KuZhuJi；是否适用以及当前折扣，以账号资格和订单显示为准。服务器的位置也不需要与所有被导航的工具一致，关键是使用者能打开入口、组件能连接到需要读取的服务。
用 Docker 起一个只监听本机的实例
下面以支持 Docker Engine 和 Compose 插件的 Linux 服务器为前提，使用普通用户管理部署目录。该用户需要有使用 Docker 的权限。镜像固定为 2.4.0，避免下次更新时无意换到不同版本。
mkdir -p ~/homepage/config
cd ~/homepage
printf 'APP_UID=%s\nAPP_GID=%s\n' "$(id -u)" "$(id -g)" > .env
chmod 600 .env
.env 中记录容器的用户和组 ID。官方 Docker 文档提供了 PUID、PGID 用法，挂载目录必须让对应用户有读写权限。这里使用当前部署用户的 ID，不假定所有机器都是 1000。
创建 compose.yaml：
services:
homepage:
image: ghcr.io/gethomepage/homepage:v2.4.0
restart: unless-stopped
ports:
- "127.0.0.1:3100:3000"
volumes:
- ./config:/app/config
env_file:
- homepage.env
environment:
PUID: "${APP_UID}"
PGID: "${APP_GID}"
3000 是容器里的服务端口，3100 是宿主机本机端口。选择 3100 是为了便于避开已有的 3000 服务；端口仍可能被其他程序占用，需要按自己的服务器调整。默认没有挂载 Docker socket，普通链接和文件配置不需要它。
内置登录采用独立的强密码与会话密钥，下面用 Python 生成并写入 homepage.env，不把密码直接嵌进 Compose：
python3 - <<'PY'
import os
import secrets
from pathlib import Path
os.umask(0o077)
settings = [
'HOMEPAGE_ALLOWED_HOSTS=localhost:3000,127.0.0.1:3000',
'HOMEPAGE_AUTH_ENABLED=true',
'HOMEPAGE_EXTERNAL_URL=http://localhost:3000',
'HOMEPAGE_AUTH_SECRET=' + secrets.token_urlsafe(48),
'HOMEPAGE_AUTH_PASSWORD=' + secrets.token_urlsafe(24),
]
Path('homepage.env').write_text('\n'.join(settings) + '\n')
PY
chmod 600 homepage.env
chmod 700 config
这一步仅用于首次创建配置，不要每次重启都运行，否则会改变密码与会话密钥。登录密码保存在自己的受限文件里，按自己的密码管理方式取用；不要把这个文件加入公开仓库，也不要在求助截图中展示它。
先检查 Compose，再启动：
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100 homepage
配置检查能发现部分结构和变量问题。容器启动后，还要在浏览器里确认入口与组件是否正常。查看日志时注意不要把含凭据的信息直接转发给别人。
从自己的电脑打开，不需要放行 3100
在本机终端建立 SSH 转发，替换用户与地址：
ssh -N -L 127.0.0.1:3000:127.0.0.1:3100 \
deploy@203.0.113.10
203.0.113.10 是文档示例地址，实际使用时替换为服务器地址。SSH 端口和密钥按自己的配置安排。本机浏览器访问 http://localhost:3000，请求通过 SSH 到达服务器的本机 3100 端口，不需要在服务器防火墙里放行 3100。
前面的 HOMEPAGE_EXTERNAL_URL 对应这个本机入口，所以先保留为 http://localhost:3000。这是一种经 SSH 转发的个人访问方式，不应照搬为公网 HTTP 部署。终端断开以后隧道停止；本机 3000 已被占用时，应同时调整转发端口、允许的 Host 和外部入口 URL。
HOMEPAGE_ALLOWED_HOSTS 用来检查请求中的 Host，不用来核验访问者身份。允许值是主机名以及必要的端口，不带 http:// 或路径，多个值用没有空格的逗号分隔。出现 Host 校验错误时，查看日志里实际收到的名称，再核对配置，不要为了解决一次错误直接写成 *。
把真正使用的服务写进 services.yaml
先在 config/services.yaml 中放几个入口。下面的域名都是示例，替换成自己已有的地址；这些服务不由 Homepage 部署：
- 阅读与资料:
- RSS 阅读器:
href: https://rss.example.com
description: 日常订阅与未读文章
- 云笔记:
href: https://notes.example.com
description: 项目说明与维护记录
- 站点管理:
- 博客后台:
href: https://blog.example.com/admin
description: 文章与媒体管理
- 数据库工作台:
href: https://db.example.com
description: 仅供授权账号使用
顶层是分组，每个组下面是服务列表，href 是点卡片后浏览器要打开的地址。缩进使用空格，不要混入制表符。复制示例以后，保留列表前的短横线与层级；YAML 写错时，问题经常出在结构而不是服务器性能。
分组名称最好反映自己的使用习惯。按“阅读、站点、运维”整理，比按软件发布年代排列容易查找；如果有正式环境和预览环境，把名称直接写清楚，避免两个外观一样的后台点错。
服务配置支持服务描述、组件等选项。起步阶段只配 href 和说明即可，确认地址正确以后再加图标与状态。很少使用的工具可以先不添加，留下自己经常找的入口。
常用文档和代码仓库可以写进 config/bookmarks.yaml：
- 文档与代码:
- Docker 文档:
- abbr: DK
href: https://docs.docker.com
- Homepage 文档:
- abbr: HP
href: https://gethomepage.dev
这里使用文字缩写，不依赖外部图标。书签与服务的配置层级不完全相同，按各自文档填写，不要把一个文件的结构直接复制进另一个文件。
页面布局只调整有必要的部分
在 config/settings.yaml 中可以设置标题、主题和分组布局：
title: 我的服务入口
theme: dark
color: slate
layout:
阅读与资料:
style: row
columns: 2
站点管理:
style: row
columns: 2
布局中的组名要与 services.yaml 相同。开始时两列已经方便浏览，不必为了利用桌面宽度给每组堆很多列。手机上还需要看卡片名称是否容易辨认、描述是否过长，界面能缩放不等于所有文字都适合小屏。
修改配置以后刷新页面，按界面提供的配置刷新方式重新读取；没有反映时再查看日志与挂载目录。改变环境变量则需要重新创建容器：
docker compose up -d --force-recreate
文件布局与容器环境是两种配置来源。把域名改写在环境文件中以后，只刷新浏览器并不能让旧容器自动获得新值。
状态组件的 url，不一定与 href 相同
href 供浏览器使用，组件的 url 则是 Homepage 后端需要请求的服务地址。电脑能打开一个域名，不能证明服务器里的 Homepage 容器也能访问它；容器里的 localhost 也不是宿主机，更不是自己电脑。
例如已经部署 Uptime Kuma，并创建状态页 /status/services，可以为它添加组件：
- 运维:
- 服务状态:
href: https://status.example.com/status/services
description: 已公开状态页的监测摘要
widget:
type: uptimekuma
url: https://status.example.com
slug: services
这里的 slug 来自状态页地址最后的名称，不包含 /status/。这个组件读取一个状态页的数据，不代表自动获得 Uptime Kuma 后台的所有监测任务。状态页需要按自己的使用范围配置，其访问控制也要允许组件采用的请求方式。
Uptime Kuma 组件文档列出可显示字段。状态摘要可以帮助进入对应工具，报警通知和监控历史仍由实际监控系统负责。不要看到一个绿色状态就推断所有数据库、登录与上传操作都正常。
其他服务可能需要 API 密钥。Homepage 的组件请求通过后端代理完成，但能打开导航页的人仍可能看到代理返回的数据。密钥没有直接出现在浏览器里，不等于服务信息可以放心公开。
组件凭据可以通过以 HOMEPAGE_VAR_ 或 HOMEPAGE_FILE_ 开头的环境变量注入。比如环境里存在 HOMEPAGE_VAR_TOOL_KEY，配置中可用对应占位形式：
key: "{{HOMEPAGE_VAR_TOOL_KEY}}"
具体组件是否使用 key、支持什么认证形式，依照该组件文档填写；这个片段只说明变量替换方式，不是适用于所有产品的 API 配置。变量管理能把配置与凭据分开，环境文件本身仍需要保护。权限允许时，使用独立、最小权限的凭据，减少一个导航组件拥有的能力。
Docker 状态先不接，确实需要时再加
把 Docker socket 挂进容器，Homepage 就有机会读取 Docker 信息，但这也让原本只提供导航的程序接触宿主机管理接口。socket 的 :ro 挂载不能被简单理解为 Docker API 的所有操作都已变成只读。
官方文档不推荐直接连接 Docker socket，提供了 socket proxy 的安排。需要容器发现与状态时，可以按 Docker 集成文档配置代理，只开放实际需要的 API，并把代理留在受控的内部网络。代理端口不应直接对公网开放。
如果只是几十个固定链接，手动维护服务文件通常已经够用。为了自动发现而增加一个管理接口和网络组件，会多出一份需要维护的配置；它带来的便利要与自己的使用频率相符。
需要域名时，让受控入口转发到本机端口
准备改为 https://home.example.com 后，先配置域名、有效证书与入口访问控制，再修改 homepage.env 中这两项：
HOMEPAGE_ALLOWED_HOSTS=home.example.com
HOMEPAGE_EXTERNAL_URL=https://home.example.com
内置登录保持启用，使用 HTTPS 外部 URL，让认证 Cookie 按安全入口处理。重新创建容器后，宿主机上的 Caddy 可以代理到 127.0.0.1:3100。以下站点块使用入口密码验证，密码哈希必须替换为自己生成的值：
home.example.com {
basic_auth {
operator <PASSWORD_HASH>
}
reverse_proxy 127.0.0.1:3100
}
通过 caddy hash-password 交互生成哈希，按 Caddy basic_auth 文档写入配置。<PASSWORD_HASH> 是占位符，不能原样投入使用。Caddy 运行在宿主机是这个本机转发例子的前提；若也用容器运行，需要改成两个容器可达的连接地址。
这个安排同时有入口验证和 Homepage 自身登录。团队已经有统一的访问控制服务，可以按自己的方案接入，不必沿用这里的入口密码。无论选哪一种，先限制能进入导航的人，再允许它请求内部服务。
2.x 的密码登录没有应用层尝试频率限制。直接对不受信任网络暴露时，要按照官方要求在入口层安排限速，或通过受控网络限制访问；简单部署不想增加这项维护，可以继续使用 SSH 或 VPN 入口。OIDC 模式也需要在身份提供方设置允许使用此客户端的人员，Homepage 不会再自动替你按组过滤。
配置备份与版本更新，放在日常维护里
Homepage 的主要维护材料是 compose.yaml、非敏感的 YAML 配置、环境文件以及自定义资源。配置可以记录版本，凭据要单独保存在受限位置。备份有了配置却没有认证密钥或组件凭据，恢复时仍需要重新安排这些连接。
更新前先阅读目标版本的说明，保留当前镜像版本和配置副本，再修改版本标签、拉取并重建。不要使用删除持久化目录的方式解决一次启动错误；先看配置、权限、挂载和日志。
常见问题可以按实际发生的位置排查：页面访问失败，看本机监听、隧道或反向代理；Host 错误，看入口名与允许列表；登录循环，看外部 URL、HTTPS 和入口转发；只有某个组件失败，看容器到服务的连接与该组件凭据。区分浏览器到入口、入口到应用、应用到组件这几段连接，再排查发生错误的位置。
目录开始使用以后，迁移服务时顺手更新链接，停用工具时删除卡片，定期检查仍在使用的组件凭据。服务地址变化以后，目录也要同步更新。