项目介绍
Homepage 是通过 YAML 配置服务卡片与信息组件的自托管主页。适合将 NAS、路由器、媒体库和管理页面整理为一个入口;没有 Docker 自动发现需求时,可以只挂载配置目录。
YAML 描述分组、链接和组件,页面据此展示服务。静态链接不需要容器引擎权限,组件数据再按需配置。
适合希望用文件管理导航的用户。先建立少量用途分类,再加入真正需要的信息组件。
核心功能
| 功能 | 作用与使用方式 |
|---|---|
| 服务分组 | 组织常用入口 |
| 卡片链接 | 设置名称图标地址 |
| 信息组件 | 按支持接口读取状态 |
| 配置文件 | 便于版本管理 |
| 主机校验 | 限制允许的访问域名 |
界面展示

图 1:官方公开页面截图,用于说明项目入口与功能;不是本机部署画面。

项目信息
| 项目 | 说明 |
|---|---|
| 类型 | Docker |
| 分类 | 建站与协作 |
| 项目仓库 | gethomepage/homepage |
| 官方入口或文档 | 直接访问 |
| 整理日期 | 2026-11-14 |
安装或使用条件
准备支持 Docker Compose 的主机、空闲端口与持久化目录。群晖可使用 Container Manager 的项目功能;示例目录以 /volume1/docker 为基准,其他存储卷需要自行替换。
安装与使用步骤
- 创建
/volume1/docker/homepage/config目录。下面示例使用宿主端口3010,把HOMEPAGE_ALLOWED_HOSTS中的NAS_IP换成 NAS 的真实地址;通过域名访问时也要加入该域名和需要的端口。 - 在 Container Manager 新建项目并启动,打开
http://NAS_IP:3010。首次启动生成的配置位于挂载目录,编辑services.yaml添加服务分组和链接。 - 先添加一个能正常访问的服务,例如路由器页面,再按用途建立“存储”“媒体”“运维”等分组。只配置静态链接不需要 Docker Socket。
- 需要组件数据时参照对应 Widget 文档填入 API 地址与只读凭据;检查前端卡片和服务日志,不把管理令牌写进公开仓库。
首次使用与操作检查
先配置一个路由器入口,再增加媒体和运维分组。不同设备访问检查 URL。
出现主机校验错误核对允许域名与端口。API 凭据保持私密,导航备份包含配置与自定义图标。
Docker Compose
依据官方 README 的端口、环境变量和配置目录整理。示例只启用导航功能,不挂载 Docker Socket;下方准备命令会生成 NAS 地址;从域名访问时将该域名加入 HOMEPAGE_ALLOWED_HOSTS。
群晖目录准备
在群晖 SSH 终端执行下面这一段,再将下方配置保存为 /volume1/docker/homepage/compose.yaml。也可在 Container Manager 中新建项目,选择该目录并粘贴配置。
sudo sh <<'HALO_PREPARE'
set -eu
mkdir -p /volume1/docker/homepage /volume1/docker/homepage/config
cd /volume1/docker/homepage
umask 077
touch .env
NAS_ADDR=$(ip -4 route get 1.1.1.1 | sed -n "s/.* src \([^ ]*\).*/\1/p" | head -n 1)
test -n "$NAS_ADDR"
if ! grep -q "^HOMEPAGE_ALLOWED_HOSTS=." .env; then printf 'HOMEPAGE_ALLOWED_HOSTS=%s:3010\n' "$NAS_ADDR" >> .env; fi
chmod 600 .env
HALO_PREPARE
cd /volume1/docker/homepage
services:
homepage:
image: ghcr.io/gethomepage/homepage:latest
restart: unless-stopped
ports:
- "3010:3000"
environment:
HOMEPAGE_ALLOWED_HOSTS: "${HOMEPAGE_ALLOWED_HOSTS}"
volumes:
- /volume1/docker/homepage/config:/app/config
在项目目录保存为 compose.yaml 后,先检查配置,再启动:
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100
配置与常见问题
- 出现 Host 校验错误时修正允许的主机列表,不要为了省事直接开放所有 Host。
- 不要修改 docker.sock 的全局读写权限。Docker 自动发现属于可选功能,可以后续单独配置。
- 页面无法打开:先用
docker compose ps检查状态,再核对宿主机端口、NAS 防火墙与应用日志。不要把容器端口随意改成另一个数字。 - 文件无法保存:核对宿主目录是否存在、挂载方向及运行用户的读写权限。不要直接给整个存储卷开放所有权限。
更新与备份
整个 /app/config 对应目录是主要备份对象;配置中的 API 密钥另做保护。
更新前保留原配置和数据备份,阅读所用版本的升级说明;确认兼容后再执行 docker compose pull 和 docker compose up -d。只回退镜像不一定能回退已经迁移过的数据库。
参考资料
页面截图来源:Homepage 官方页面,保留原页面标识。