建站与协作

Homepage:用 Docker 搭建 NAS 导航页

  • 0 次阅读
  • 0 条评论
文章摘要

Homepage 是通过 YAML 配置服务卡片与信息组件的自托管主页。适合将 NAS、路由器、媒体库和管理页面整理为一个入口;没有 Docker 自动发现需求时,可以只挂载配置目录。 YAML 描述分组、链接和组件,页面据此展示服务。静态链接不需要容器引擎权限,组件数据再按需配置。 适合希望用文件管理导航的用户。先建立少量用途分类,再加入真正需要的信息组件。

项目介绍

Homepage 是通过 YAML 配置服务卡片与信息组件的自托管主页。适合将 NAS、路由器、媒体库和管理页面整理为一个入口;没有 Docker 自动发现需求时,可以只挂载配置目录。

YAML 描述分组、链接和组件,页面据此展示服务。静态链接不需要容器引擎权限,组件数据再按需配置。

适合希望用文件管理导航的用户。先建立少量用途分类,再加入真正需要的信息组件。

核心功能

功能 作用与使用方式
服务分组 组织常用入口
卡片链接 设置名称图标地址
信息组件 按支持接口读取状态
配置文件 便于版本管理
主机校验 限制允许的访问域名

界面展示

Homepage 官方页面

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

Homepage 官方界面示例
项目官方界面示例,展示上游演示数据。

项目信息

项目 说明
类型 Docker
分类 建站与协作
项目仓库 gethomepage/homepage
官方入口或文档 直接访问
整理日期 2026-11-14

安装或使用条件

准备支持 Docker Compose 的主机、空闲端口与持久化目录。群晖可使用 Container Manager 的项目功能;示例目录以 /volume1/docker 为基准,其他存储卷需要自行替换。

安装与使用步骤

  1. 创建 /volume1/docker/homepage/config 目录。下面示例使用宿主端口 3010,把 HOMEPAGE_ALLOWED_HOSTS 中的 NAS_IP 换成 NAS 的真实地址;通过域名访问时也要加入该域名和需要的端口。
  2. 在 Container Manager 新建项目并启动,打开 http://NAS_IP:3010。首次启动生成的配置位于挂载目录,编辑 services.yaml 添加服务分组和链接。
  3. 先添加一个能正常访问的服务,例如路由器页面,再按用途建立“存储”“媒体”“运维”等分组。只配置静态链接不需要 Docker Socket。
  4. 需要组件数据时参照对应 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 官方页面,保留原页面标识。