前言

使用 Homepage 汇总家庭服务入口，配置文件保存在 Docker LXC 的本地目录。本文从基本导航开始，再补充分组、图标、容器状态和域名访问。

一、准备环境

在 NAS 折腾日记（2）PVE 与 Docker 基础环境部署 的 Docker LXC 中部署，通过 NAS 折腾日记（3）Portainer 部署与容器管理 管理。示例主机为 192.168.20.30，导航服务使用端口 3000。

bash
1
2
3
mkdir -p /srv/appdata/homepage/config /srv/appdata/homepage/icons
chown -R 1000:1000 /srv/appdata/homepage
chmod -R u+rwX,g+rX,o-rwx /srv/appdata/homepage

配置文件可以直接在 LXC 中编辑，也可以使用 NAS 折腾日记（4）FileBrowser 部署与配置文件权限。服务地址都使用示例值，按自己的实际入口替换。

二、部署导航页面

先用 FileBrowser 在 homepage/config 目录创建 services.yaml：

yaml
1
2
3
4
5
6
7
8
9
10
- 管理工具:
    - PVE:
        href: https://192.168.20.10:8006
        description: 虚拟机与 LXC 管理
    - Portainer:
        href: https://192.168.20.30:9443
        description: Docker 容器管理
    - FileBrowser:
        href: http://192.168.20.30:8081
        description: 应用配置编辑

这是纯链接导航配置。Portainer 的 Add container 页面填写：

位置	参数
Name	homepage
Image	ghcr.io/gethomepage/homepage:latest
Port publishing	Host 3000 → Container 3000，TCP
Env	HOMEPAGE_ALLOWED_HOSTS=192.168.20.30:3000,home.example.com
Env	PUID=1000、PGID=1000
Restart policy	Unless stopped

保持 User 字段默认，由镜像通过 PUID/PGID 启动应用。这个身份与 FileBrowser 篇一致，避免 Homepage 新生成的文件又变成 root 属主。若在终端以 root 创建 YAML，保存后对新文件设置 1000:1000 属主；通过 FileBrowser 编辑时沿用它的运行身份。

添加 Bind：

Host	Container
/srv/appdata/homepage/config	/app/config
/srv/appdata/homepage/icons	/app/public/icons

部署后访问 http://192.168.20.30:3000，页面应显示三个管理入口。若日志出现 Host 校验错误，检查环境变量是否包含浏览器访问时的域名或 IP 与端口。当前官方镜像与变量说明见 Homepage Docker 部署文档。

后续修改 services.yaml 即可添加应用链接。容器页面的 Duplicate/Edit 可调整端口、环境变量和挂载，再重新部署；挂载目录中的配置随重建保留。

三、配置分组、书签与图标

services.yaml 按组列出应用。每个应用的 href 是点击后访问的地址，description 为说明。另建 settings.yaml：

yaml
1
2
3
4
5
6
title: 家庭服务导航
language: zh-CN
layout:
  管理工具:
    style: row
    columns: 3

在 bookmarks.yaml 保存常用外部链接：

yaml
1
2
3
4
- 文档:
    - Docker:
        - abbr: DK
          href: https://docs.docker.com/

自定义图标放入本地 icons 目录，例如 nas.png，对应的服务条目增加：

yaml
1
icon: /icons/nas.png

保存文件后刷新页面检查 YAML 缩进、分组和链接。具体字段见 Homepage 服务配置文档。

四、接入 Docker 容器状态

前面部署的 Portainer、FileBrowser 和 Homepage 都运行在同一个 Docker LXC。这里先增加容器状态，再接应用自己的指标。

直接挂载 Docker socket 即使带 :ro，也不能限制通过 socket 发出的管理请求。按照 Homepage 的 Docker 接入说明，增加一个只允许查询的 socket proxy，并让它与 Homepage 处于同一个 Docker 网络。在 Docker LXC 中执行：

bash
1
2
3
4
5
6
7
8
9
docker network create homepage-monitor
docker run -d \
  --name homepage-dockerproxy \
  --restart unless-stopped \
  --network homepage-monitor \
  -e CONTAINERS=1 \
  -e POST=0 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/tecnativa/docker-socket-proxy:latest

代理没有发布宿主端口。它能查询这个 Docker daemon 下的容器信息，因此该网络只接维护所需的容器。在 Portainer 对 Homepage 使用 Duplicate/Edit，将 Network 改为 homepage-monitor，保留原端口和目录后重新部署。Homepage 本身不挂载 Docker socket。普通 bridge 网络仍允许它访问局域网中的 PVE、QNAP 等 API。

在 /srv/appdata/homepage/config/docker.yaml 写入：

yaml
1
2
3
local-docker:
  host: homepage-dockerproxy
  port: 2375

修改原有 Portainer 条目，补上容器关联：

yaml
1
2
3
4
5
6
- 管理工具:
    - Portainer:
        href: https://192.168.20.30:9443
        server: local-docker
        container: portainer
        showStats: true

FileBrowser 的 container 填 filebrowser；若增加 Homepage 自身的卡片，填 homepage。这些名称可在 Portainer 容器列表核对。showStats 展示容器资源使用，不能说明应用数据库、NFS 或登录接口是否正常，下一节继续接应用 API。

五、接入前面各项服务

href 由浏览器打开，widget.url 和 siteMonitor 则由 Homepage 容器请求。这里让 API 直接走内网 IP，网页链接以后可以改成 Lucky 提供的域名；不要把 API 地址写成 Homepage 容器自己的 localhost。

5.1 保存接入凭据

在 Portainer 的 Homepage → Duplicate/Edit → Env 中添加以下各小节需要的变量。YAML 通过 Homepage 的 HOMEPAGE_VAR_ 替换功能引用它们，例如 "{{HOMEPAGE_VAR_PORTAINER_KEY}}"。变量值填真实凭据，不要把外层双引号也填进 Env；新增或修改环境变量后需要重新部署容器。

这种方式把凭据与服务列表分开，Docker 管理员仍能读取环境变量。备份运行参数时也要保存这些值，并按凭据保管。以下配置均合并到同一份 services.yaml，已有同名分组或卡片时修改原条目。

5.2 PVE 主机与 LXC

在 PVE 的 Datacenter → Permissions → Users 新建 homepage@pve，Realm 选择 PVE。随后创建权限分离的 API Token，Token ID 使用 monitor，记录仅显示一次的 Secret。

权限分离模式下，用户权限与 Token 权限取交集，需要在 Datacenter → Permissions 分别添加两项，Path 均为 /，Role 均为 PVEAuditor，勾选 Propagate：

ACL 类型	对象
User Permission	homepage@pve
API Token Permission	homepage@pve!monitor

给 Homepage 增加 HOMEPAGE_VAR_PVE_TOKEN_ID=homepage@pve!monitor 和 HOMEPAGE_VAR_PVE_TOKEN_SECRET。PVE 卡片配置如下：

yaml
1
2
3
4
5
6
7
8
9
10
- 管理工具:
    - PVE:
        href: https://192.168.20.10:8006
        widget:
          type: proxmox
          url: https://192.168.20.10:8006
          username: "{{HOMEPAGE_VAR_PVE_TOKEN_ID}}"
          password: "{{HOMEPAGE_VAR_PVE_TOKEN_SECRET}}"
          node: pve
          fields: ["vms", "lxc", "resources.cpu", "resources.mem"]

node: pve 改为 PVE 左侧树中实际的节点名。此组件查看虚拟机、LXC 数量和节点 CPU、内存使用；给其他服务显示所属 LXC 状态，还需要另建 proxmox.yaml：

yaml
1
2
3
4
pve:
  url: https://192.168.20.10:8006
  token: "{{HOMEPAGE_VAR_PVE_TOKEN_ID}}"
  secret: "{{HOMEPAGE_VAR_PVE_TOKEN_SECRET}}"

这里顶层的 pve 也必须是实际节点名。随后可以在“管理工具”组内加一个 Docker LXC 条目：

yaml
1
2
3
4
5
- Docker LXC:
    href: https://192.168.20.10:8006
    proxmoxNode: pve
    proxmoxVMID: 200
    proxmoxType: lxc

这段是组内条目，需要按原组的缩进加入。后面的 Lucky、AdGuard Home 篇分别关联 CT 201、202。API 组件与 LXC 状态使用同一只读 Token，配置格式见 PVE 应用组件 和 PVE 状态接入。

5.3 Portainer

在 Portainer 的 My account → Access tokens 创建 Token，保存到 Homepage 的 HOMEPAGE_VAR_PORTAINER_KEY。进入当前 Docker 环境，从浏览器 URL 中取得环境 ID，例如 #!/endpoints/1 对应 env: 1。这个数字按实际值填写。

将第四节的 Portainer 卡片扩展为：

yaml
1
2
3
4
5
6
7
8
9
10
11
12
- 管理工具:
    - Portainer:
        href: https://192.168.20.30:9443
        server: local-docker
        container: portainer
        showStats: true
        widget:
          type: portainer
          url: https://192.168.20.30:9443
          env: 1
          key: "{{HOMEPAGE_VAR_PORTAINER_KEY}}"
          fields: ["running", "stopped", "total"]

卡片上的容器资源对应 Portainer 自己，组件中的数量对应选定环境内的全部容器。API Token 继承创建者权限；使用管理员生成时就具有管理员访问范围，不能将它称为只读凭据。若只需要每个容器是否运行，第四节的 Docker 状态已经足够，可以不配置这一项 Token。

5.4 FileBrowser

在 FileBrowser 用户管理中新增 homepage-reader，Scope 限定为 /homepage，关闭管理员权限，以及创建、修改、删除、重命名、分享和执行命令等权限。Homepage 仅需登录后读取用量接口。在 Homepage Env 中保存 HOMEPAGE_VAR_FILEBROWSER_USER 和 HOMEPAGE_VAR_FILEBROWSER_PASSWORD：

yaml
1
2
3
4
5
6
7
8
9
10
11
12
- 管理工具:
    - FileBrowser:
        href: http://192.168.20.30:8081
        server: local-docker
        container: filebrowser
        showStats: true
        widget:
          type: filebrowser
          url: http://192.168.20.30:8081
          username: "{{HOMEPAGE_VAR_FILEBROWSER_USER}}"
          password: "{{HOMEPAGE_VAR_FILEBROWSER_PASSWORD}}"
          fields: ["available", "used", "total"]

用量来自 FileBrowser 所访问目录所在的文件系统。本系列挂载的是 Docker LXC 的 /srv/appdata，因此这里显示本地应用盘空间，QNAP 的存储空间用下一项查看。

5.5 QNAP

给 QNAP 建立专用监控账号，在 Homepage Env 中保存 HOMEPAGE_VAR_QNAP_USER 和 HOMEPAGE_VAR_QNAP_PASSWORD。确认 QTS 的 HTTPS 管理地址与端口，下例使用 https://192.168.20.20:443：

yaml
1
2
3
4
5
6
7
8
9
- 存储服务:
    - QNAP:
        href: https://192.168.20.20:443
        widget:
          type: qnap
          url: https://192.168.20.20:443
          username: "{{HOMEPAGE_VAR_QNAP_USER}}"
          password: "{{HOMEPAGE_VAR_QNAP_PASSWORD}}"
          fields: ["cpuUsage", "memUsage", "systemTempC", "poolUsage"]

该组件调用 QTS 管理 API，专用账号是否能读取这些指标取决于 QTS 版本和权限配置。先以受限账号接入，出现权限错误时核对 QTS 授权；若当前版本无法提供合适的只读权限，可以只保留导航链接，通过 QTS 查看资源。多个卷时按 QNAP 组件说明 在 widget 下设置 volume 为实际卷名，并把 fields 中的 poolUsage 改为 volumeUsage，明确卡片显示哪个卷。

5.6 已有 Nextcloud

如果沿用 NAS 系列前面部署的 Nextcloud，可以一并放进“存储服务”。在 Nextcloud 应用页面启用 Monitoring（serverinfo），到管理员设置的系统信息页取得监控用的 NC-Token，保存为 Homepage 的 HOMEPAGE_VAR_NEXTCLOUD_TOKEN。该组件支持用监控 Token 读取统计；界面没有创建入口时，也可以通过 occ 设置。沿用 NAS 折腾日记（1）容器化部署 nextcloud 中名为 nextcloud 的官方镜像容器，在 运行该容器的 QNAP Docker 主机执行：

bash
1
2
3
docker exec -u www-data nextcloud php /var/www/html/occ app:enable serverinfo
docker exec -u www-data nextcloud php /var/www/html/occ config:app:set serverinfo token \
  --value='REPLACE_WITH_A_LONG_RANDOM_TOKEN'

将占位符换成密码管理器生成的长随机值，并将同一个值填入 HOMEPAGE_VAR_NEXTCLOUD_TOKEN。这条命令会替换已有监控 Token；若已有其他监控使用它，应沿用原值或同步更新。serverinfo token 的设置方式也可见 Nextcloud 官方 AIO 启动配置。

yaml
1
2
3
4
5
6
7
8
9
- 存储服务:
    - Nextcloud:
        href: https://cloud.example.com
        siteMonitor: https://cloud.example.com/status.php
        widget:
          type: nextcloud
          url: https://cloud.example.com
          key: "{{HOMEPAGE_VAR_NEXTCLOUD_TOKEN}}"
          fields: ["numfiles", "numshares", "activeusers", "freespace"]

地址改成已有实例，确保 Homepage 容器可以解析并访问。文件数、共享数等统计由 Nextcloud 后台任务更新，不要求与一次网页操作立即同步。未部署 Nextcloud 时跳过这项，不必为了导航新增一个实例。认证方式与可显示指标见 Nextcloud 组件文档。

六、继续加入后续服务

后续三篇各自补充接入参数，沿用本篇的凭据替换、Docker 代理和 PVE Token：

服务	状态来源	应用检查
AdGuard Home	PVE LXC 202	DNS 查询、拦截量、响应时间
Lucky	PVE LXC 201	检查一个经反向代理访问的 HTTPS 地址
qBittorrent	Docker 容器	下载、做种任务数与上下行速度

Homepage 用来集中查看当前状态，历史趋势和主动告警需要另外的监控系统。HTTP 检查正常也不能代表 DNS 的 53 端口、NFS 的读写或证书自动续期均正常，具体服务仍保留各篇中的验证方式。

七、域名访问与维护

先使用 IP 和端口验证页面，再按 NAS 折腾日记（6）AdGuard Home 部署与内网 DNS 配置 DNS，按 NAS 折腾日记（7）Lucky 部署与反向代理 配置反代。HOMEPAGE_ALLOWED_HOSTS 中保留实际访问的 Host，包括使用非默认端口时的端口号。该变量用于 Host 校验，不能代替访问认证；本系列先放在管理内网使用。

bash
1
2
3
docker logs --tail 80 homepage
docker logs --tail 80 homepage-dockerproxy
curl -I http://192.168.20.30:3000

现象	检查位置
页面提示 Host 不允许	实际域名、端口与 HOMEPAGE_ALLOWED_HOSTS
Docker 状态不显示	两个容器是否同在 homepage-monitor，容器名是否一致
应用组件 401/403	凭据是否更新进容器、Token 权限与 API 地址
PVE 能显示主机指标，LXC 不显示	proxmox.yaml、实际节点名、CT ID 与 proxmoxType
浏览器能打开，组件或检查失败	Homepage 容器的 DNS、路由和 API 访问权限

备份 config、icons 和容器运行参数，特别是环境变量中的凭据。更新镜像时保留这些内容以及 Docker 网络，再复查链接、容器状态和应用指标。

参考

• Homepage Docker 部署文档
• Homepage 服务配置文档
• Portainer 组件
• FileBrowser 组件