十两东日的随想

⑥ Homer 导航页：从零配置到内置图标与轻度美化（Docker + 反代 + YAML 实战）

目标：用 Docker Compose 快速部署 Homer 作为“起始页/服务导航”，通过 Nginx 反代 + HTTPS 对外发布；以 Font Awesome 内置图标 替代本地图像；补充一份可直接复制的 config.yml 与 custom.css；并沉淀常见坑与修复办法。

说明：文中已脱敏，示例域名以 home.example.com 表示；请按你的实际情况替换。默认以 admin 账号、家目录 /home/admin 操作。

【实操教学】

一、目录准备与（可选）UID/GID 确认

mkdir -p /home/admin/homer/assets        # mkdir：创建目录；-p 不存在就一并创建
id -u admin                               # id -u：查看 admin 的 UID（给容器用）
id -g admin                               # id -g：查看 admin 的 GID

为什么要 UID/GID？

指定容器以内哪个系统用户身份写文件（避免生成 root 属主导致权限问题）。如果你已知数值，比如都是 1003，可直接写死。

二、写

docker-compose.yml

（V2 写法，无

version:

顶级字段）

cd /home/admin/homer                      # cd：切换到项目目录（change directory）
nano docker-compose.yml                   # nano：打开编辑器

粘贴（仅需把 UID/GID 改成你的数值即可）：

services:
  homer:
    image: b4bz/homer:latest                 # Homer 官方镜像
    container_name: homer
    restart: unless-stopped                  # 异常退出后自动重启
    environment:
      - TZ=Asia/Shanghai                     # 时区
      - INIT_ASSETS=1                        # 首次启动时把示例资源写入 /www/assets
      - UID=1003                             # 用 admin 的 UID（示例）
      - GID=1003                             # 用 admin 的 GID（示例）
    volumes:
      - /home/admin/homer/assets:/www/assets # 挂载配置与图标目录
    ports:
      - "127.0.0.1:3002:8080"                # 仅本机回环开放；外网走 Nginx/443

保存（Ctrl+O 回车）→ 退出（Ctrl+X）→ 启动：

docker compose up -d                        # up -d：按编排启动并后台运行
docker compose ps                           # ps：查看状态与端口（应见 127.0.0.1:3002->8080）
curl -I http://127.0.0.1:3002               # -I：只取响应头；200/302 说明后端已正常

三、Nginx/面板反向代理 + HTTPS（公网只开 443）

  • 在面板添加站点：home.example.com，类型选 静态。

  • 反向代理目标：http://127.0.0.1:3002/。

  • SSL：申请 Let’s Encrypt 并强制 HTTPS。

  • 反代段务必加入“六行黄金请求头”（避免样式/JS 混合内容问题）：

proxy_set_header Host              $host;          # 保持原始 Host
proxy_set_header X-Real-IP         $remote_addr;   # 传递客户端 IP
proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;        # 告诉后端当前是 https/http
proxy_set_header X-Forwarded-Host  $host;
proxy_set_header X-Forwarded-Port  $server_port;

现在从外网访问 https://home.example.com 应该能打开 Homer 默认首页。

四、配置导航——

用内置图标，而不是图片

关键区别：

  • icon: → 使用 Font Awesome 内置图标（推荐，永不卡图）

  • logo: → 使用图片文件/URL（若图不存在就会显示“断图”）

打开配置：

nano /home/admin/homer/assets/config.yml

将下列 可用即贴 的示例覆盖粘贴（已全部换用内置图标）：

# === Homer 配置（内置图标版） ===
title: "Start"
subtitle: "Self-Hosted Services"
# logo: "logo.png"            # 若有自定义图片可启用；没有就注释掉

theme: default                # 可切换：default / dracula / …
columns: 3                    # 主区域列数（2~4 之间调整）

# 顶部快捷链接
links:
  - name: "Blog"
    icon: "fa-brands fa-wordpress"
    url: "https://blog.example.com"
  - name: "FreshRSS"
    icon: "fa-solid fa-square-rss"
    url: "https://rss.example.com"
  - name: "Vaultwarden"
    icon: "fa-solid fa-key"
    url: "https://vault.example.com"
  - name: "Syncthing"
    icon: "fa-solid fa-arrows-rotate"
    url: "https://sync.example.com"
  - name: "Status"
    icon: "fa-solid fa-heart-pulse"
    url: "https://status.example.com"

# 主区域卡片（关键：每个 item 用 icon 字段）
services:
  - name: "Daily"
    icon: "fa-solid fa-star"
    items:
      - name: "Blog"
        subtitle: "WordPress"
        icon: "fa-brands fa-wordpress"
        url: "https://blog.example.com"
        target: "_blank"
      - name: "FreshRSS"
        subtitle: "Feeds Hub"
        icon: "fa-solid fa-square-rss"
        url: "https://rss.example.com"

  - name: "Personal"
    icon: "fa-solid fa-user-shield"
    items:
      - name: "Vaultwarden"
        subtitle: "Password Vault"
        icon: "fa-solid fa-key"
        url: "https://vault.example.com"
      - name: "Syncthing"
        subtitle: "File Sync"
        icon: "fa-solid fa-arrows-rotate"
        url: "https://sync.example.com"

  - name: "Ops"
    icon: "fa-solid fa-screwdriver-wrench"
    items:
      - name: "Status"
        subtitle: "Uptime Kuma"
        icon: "fa-solid fa-heart-pulse"
        url: "https://status.example.com"

# 顶部消息（可删）
message:
  style: "is-info"
  title: "Welcome"
  content: |
    This is my self-hosted start page. Quick links above, grouped cards below.

# 关闭底部版权（可选）
footer: false

# 自定义样式（下一节会新建）
stylesheet:
  - "assets/custom.css"

保存退出，刷新页面即可生效；若浏览器缓存未更新，可轻重启：

docker compose restart homer     # restart：重启容器读取新配置

五、轻度美化（可选）：

custom.css

背景 + 卡片阴影

nano /home/admin/homer/assets/custom.css

粘贴：

/* 背景柔和渐变 */
body {
  background: radial-gradient(1000px 600px at 20% 0%, #eef4ff 0%, #ffffff 60%, #ffffff 100%);
}

/* 卡片圆角 + 轻阴影 */
.card {
  box-shadow: 0 4px 14px rgba(0,0,0,.06);
  border-radius: 14px;
}

/* 顶部横幅轻渐变（根据主题自行调色） */
.navbar, .hero {
  background-image: linear-gradient(90deg, #3b82f6, #2563eb);
}

保存 → 刷新或 docker compose restart homer。

如果你更喜欢暗色，把 theme: dracula，并在 CSS 把背景色调暗即可。

六、把首页纳入监控（避免“空白页 200”）

在 Uptime Kuma 新建 home.example.com 的 HTTP(s) – 关键字 监控，关键字填页面标题的一段，如 Self-Hosted Services。这样即使反代返回了一个 200 的默认页，也能识别内容异常。

七、升级与备份

cd /home/admin/homer
docker compose pull && docker compose up -d   # 拉新镜像并平滑更新
docker compose logs -f                        # 观察启动日志（Ctrl+C 退出）

备份：保存 /home/admin/homer/assets/ 整个目录（配置与样式都在这里）。

常见坑与解决

  1. “小方块图标显示断图”

    • 原因：在 logo: 填了 fa-… 类名（Homer 会当“图片路径”加载，当然失败）。

    • 解法：改用 icon: 字段写 fa-…；仅当你使用图片文件时才用 logo:。

  2. “修改配置不生效”

    • 原因：浏览器缓存或容器未重新读取配置。

    • 解法：强刷页面；若仍旧，用 docker compose restart homer。

  3. “YAML 报错/页面空白”

    • 原因：缩进不规范（YAML 必须用空格）、冒号后缺空格、Tab 混入。

    • 解法：统一用 2 空格缩进；在线 YAML 校验工具检查语法。

  4. “反代后页面没样式/JS 被拦截”

    • 原因：反向代理未正确传 X-Forwarded-Proto/Host。

    • 解法：在站点反代里加“六行黄金请求头”，重载 Nginx。

  5. “想用自己的图标文件”

    • 做法：把 png/svg 放在 /home/admin/homer/assets/，在配置里用

icon: "/assets/my-icon.svg"

    • 或继续使用 logo: 字段（用于卡片左侧大图/页头 Logo）。

【深度解析与知识扩展】

  • 为什么端口只绑定回环（127.0.0.1）？

    让后端只对本机开放，外网统一走 443/Nginx。好处：减少暴露面、统一证书/访问策略、日志集中化，故障点清晰。

  • “内置图标”优于“图片”的场景

    图标字体加载自带缓存，不依赖本地图片文件；没有路径/权限/缓存穿透问题。图片更个性但维护成本高。

  • Homer 与 Heimdall 的取舍

    Homer 为静态站 + YAML 配置，超轻、版本化友好；Heimdall 基于 PHP 框架、有后台界面但运行时更重，反代头不完整时容易出“样式消失”。

  • 配置的可迁移性

    只要把 assets/ 目录打包，换服务器/换域名基本即插即用；Compose 文件也几乎不动，属于“可复制基础设施”。

交付核对清单（Checklist）

  • https://home.example.com 正常打开（反代 + 强制 HTTPS）

  • docker compose ps 显示 127.0.0.1:3002->8080（未对公网直曝）

  • assets/config.yml 使用 icon:（Font Awesome），无断图

  • assets/custom.css 已生效（背景/阴影）

  • Uptime Kuma 已对首页做 HTTP(s)–关键字 监控

  • 升级命令、备份路径清晰（/home/admin/homer/assets/）

Previous Article
Next Article

发表回复

Your email address will not be published. Required fields are marked *.

*
*

Copyright © 2025 十两东日的随想. All Rights Reserved.

鄂ICP备2025140583号-1 | 鄂公网安备42011102005804号

近期文章

近期评论

您尚未收到任何评论。

归档

分类