飞牛NAS部署Homepage：打造NAS导航门户

为什么你需要一个导航门户

如果你和我一样，NAS 上跑着十几个 Docker 容器——Jellyfin、qBittorrent、Nextcloud、Vaultwarden……每次要访问某个服务，都得在浏览器里敲 IP 加端口，或者翻书签。时间久了，不仅效率低下，还容易记混端口号。Homepage 就是来解决这个痛点的。

Homepage 是一个轻量级的应用仪表盘，它能把你的所有服务整合到一个漂亮的网页上，支持服务状态检测、Docker 集成、自定义分组和快捷搜索。部署在飞牛 NAS 上，几分钟就能搞定，而且界面颜值极高，支持暗色主题，放在客厅电视上展示也毫不违和。

准备工作

在开始之前，请确认你的飞牛 NAS 已经安装好 Docker 环境（fnOS 自带 Docker 管理界面，也可以用命令行）。另外，建议提前规划好端口，Homepage 默认使用 3000 端口，如果被占用，可以自行修改映射。

部署步骤

第一步：创建配置目录

SSH 登录到你的飞牛 NAS（或者直接使用文件管理创建目录），执行以下命令：

sudo mkdir -p /vol1/docker/homepage/config

请根据你的实际存储路径调整 /vol1/docker 部分，飞牛 NAS 的挂载点通常是 /vol1 或 /vol2。

第二步：运行容器

这里推荐使用 Docker Compose 方式部署，方便后期维护。新建一个 docker-compose.yml 文件：

version: "3.3"
services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      - PUID=1000
      - PGID=1000
    ports:
      - 3000:3000
    volumes:
      - /vol1/docker/homepage/config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

注意，挂载 Docker socket 是为了让 Homepage 能自动检测和展示 Docker 容器状态。如果你对安全性有顾虑，也可以不挂载，改用 API 方式集成。

在 docker-compose.yml 所在目录执行：

sudo docker compose up -d

等待镜像拉取完成，容器启动后，访问 http://你的NASIP:3000，就能看到 Homepage 的默认界面了。如果看到 “Configuration required” 提示，说明配置文件还没有生成，稍等片刻刷新即可。

第三步：编写基础配置

Homepage 的配置分为两个核心文件：settings.yaml（全局设置）和 services.yaml（服务分组）。我们先创建 settings.yaml：

# 标题和布局
title: "我的 NAS 导航"
theme: dark
language: zh-CN

# 显示天气（可选）
weather:
  provider: openweathermap
  location: 北京
  apiKey: your_api_key_here

# 布局设置
layout:
  Home:
    style: row
    columns: 4

然后创建 services.yaml，这里是最核心的内容，定义你的服务分组。示例：

- 媒体服务:
    - Jellyfin:
        href: http://192.168.1.100:8096
        description: 影视中心
        icon: jellyfin
        widget:
          type: jellyfin
          url: http://192.168.1.100:8096
          username: admin
          password: yourpassword

    - qBittorrent:
        href: http://192.168.1.100:8080
        description: 下载管理
        icon: qbittorrent
        widget:
          type: qbittorrent
          url: http://192.168.1.100:8080
          username: admin
          password: yourpassword

- 工具服务:
    - Nextcloud:
        href: https://cloud.example.com
        description: 私有云盘
        icon: nextcloud

    - Vaultwarden:
        href: http://192.168.1.100:8088
        description: 密码管理器
        icon: vaultwarden

把 <你的NASIP> 替换成实际的 IP 地址，保存文件后重启容器：

sudo docker restart homepage

第四步：启用 Docker 集成（可选但推荐）

如果你挂载了 docker.sock，Homepage 会自动检测所有运行中的容器。你可以直接在 services.yaml 中这样引用：

- Docker 容器:
    - 容器状态:
        type: docker
        container: jellyfin
        href: http://192.168.1.100:8096

这样当容器停止时，Homepage 上会显示红色状态灯，一目了然。

进阶美化与技巧

自定义图标

Homepage 支持 icon 字段，可以填内置图标名（如 jellyfin、qbittorrent），也可以直接用外部图片链接：

icon: https://你的图标地址/icon.png

添加快捷搜索

在 settings.yaml 中配置搜索栏：

quicklinks:
  - name: Google
    url: https://google.com
  - name: Bing
    url: https://bing.com

分组排序

通过修改 services.yaml 的组顺序，可以控制显示顺序。组内的服务按列表顺序排列，想置顶就放最前面。

常见问题排查

如果页面显示异常，先检查配置文件格式。YAML 对缩进极其敏感，建议使用 VS Code 或在线 YAML 校验工具检查。

如果服务状态一直显示离线，确认服务地址是否可访问，以及 widget 配置的用户名密码是否正确。有些服务（如 Jellyfin）需要在设置中开启 API 访问。

端口冲突时，修改 docker-compose.yml 中的端口映射，例如改为 3001:3000，然后重新 up -d。

总结

通过以上步骤，你的飞牛 NAS 就拥有一个美观实用的导航门户了。Homepage 的价值在于它把零散的服务入口统一管理起来，配合 Docker 集成，你甚至不用记住任何端口号。后续新增容器时，只需在配置文件中加几行 YAML，重启即可生效。对于家庭用户来说，把 Homepage 设为浏览器主页，整个 NAS 的使用体验会顺畅很多。如果你还想折腾更多功能，比如接入 Home Assistant、添加自定义 API 小组件，官方文档写得非常详细，值得深入研究。