Homer 应用导航仪表板搭建教程

Homer 是一款极简的静态应用导航仪表板，通过一个 YAML 配置文件即可管理所有的服务链接。与 Dashy 等功能丰富的仪表板不同，Homer 的设计理念是极致简洁和零依赖，它只是一个纯静态页面，不需要后端服务或数据库，资源消耗几乎为零。本文将介绍如何在搬瓦工 VPS 上使用 Docker 部署 Homer。部署前请确保已安装好 Docker 和 Docker Compose。

一、系统要求

操作系统：任何 Linux 发行版。
内存：Homer 几乎不占用内存，256MB 系统即可。
磁盘：不到 100MB。

二、Docker 快速部署

mkdir -p /opt/homer/assets
cd /opt/homer

cat > /opt/homer/docker-compose.yml <<'EOF'
version: '3.8'

services:
  homer:
    image: b4bz/homer:latest
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - /opt/homer/assets:/www/assets
    environment:
      - INIT_ASSETS=1
EOF

docker compose up -d

首次启动时，INIT_ASSETS=1 会自动在 assets 目录中生成默认配置文件和图标。

三、编写配置文件

编辑 /opt/homer/assets/config.yml，这是 Homer 的核心配置文件：

cat > /opt/homer/assets/config.yml <<'EOF'
title: "My HomeLab"
subtitle: "服务导航"
logo: "assets/logo.png"

header: true
footer: 'Powered by Homer'

columns: "3"
connectivityCheck: true

theme: default
colors:
  light:
    highlight-primary: "#3367d6"
    highlight-secondary: "#4285f4"
    highlight-hover: "#5a95f5"
    background: "#f5f5f5"
    card-background: "#ffffff"
    text: "#363636"
    text-header: "#ffffff"
    text-title: "#303030"
    text-subtitle: "#424242"
    card-shadow: rgba(0, 0, 0, 0.1)
    link: "#3273dc"
    link-hover: "#363636"
  dark:
    highlight-primary: "#3367d6"
    highlight-secondary: "#4285f4"
    highlight-hover: "#5a95f5"
    background: "#131313"
    card-background: "#2b2b2b"
    text: "#eaeaea"
    text-header: "#ffffff"
    text-title: "#fafafa"
    text-subtitle: "#f5f5f5"
    card-shadow: rgba(0, 0, 0, 0.4)
    link: "#3273dc"
    link-hover: "#ffdd57"

links:
  - name: "GitHub"
    icon: "fab fa-github"
    url: "https://github.com"
    target: "_blank"

services:
  - name: "基础设施"
    icon: "fas fa-server"
    items:
      - name: "VPS 管理面板"
        logo: "assets/tools/sample.png"
        subtitle: "搬瓦工 KiwiVM"
        url: "https://kiwivm.64clouds.com"
        target: "_blank"
      - name: "Portainer"
        logo: "assets/tools/sample2.png"
        subtitle: "Docker 管理"
        url: "https://portainer.yourdomain.com"
        target: "_blank"

  - name: "应用服务"
    icon: "fas fa-cloud"
    items:
      - name: "Nextcloud"
        subtitle: "私有云盘"
        url: "https://cloud.yourdomain.com"
        target: "_blank"
      - name: "Gitea"
        subtitle: "代码托管"
        url: "https://git.yourdomain.com"
        target: "_blank"
      - name: "Bitwarden"
        subtitle: "密码管理"
        url: "https://vault.yourdomain.com"
        target: "_blank"

  - name: "监控工具"
    icon: "fas fa-heartbeat"
    items:
      - name: "Uptime Kuma"
        subtitle: "服务监控"
        url: "https://uptime.yourdomain.com"
        target: "_blank"
      - name: "Umami"
        subtitle: "网站统计"
        url: "https://analytics.yourdomain.com"
        target: "_blank"
EOF

四、配置 Nginx 反向代理

cat > /etc/nginx/sites-available/homer <<'EOF'
server {
    listen 80;
    server_name home.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

ln -s /etc/nginx/sites-available/homer /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d home.yourdomain.com

五、自定义图标

Homer 支持多种图标来源：

Font Awesome：在 icon 字段使用 FA 图标类名，如 fas fa-server。
本地图标：将图标文件放入 /opt/homer/assets/icons/ 目录，然后使用 logo: "assets/icons/my-icon.png" 引用。
Dashboard Icons：使用社区维护的 Dashboard Icons 项目，提供大量自托管应用的图标。

# 下载常用应用图标
mkdir -p /opt/homer/assets/icons
cd /opt/homer/assets/icons
wget https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/nextcloud.png
wget https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/gitea.png
wget https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/bitwarden.png

六、深色模式

Homer 内置了深色模式支持。在配置文件中定义 colors.dark 后，页面右上角会出现深色/浅色模式切换按钮。Homer 也会自动跟随系统的深色模式设置。

七、多页面支持

Homer 支持通过 URL 参数加载不同的配置文件，实现多页面导航：

# 创建额外的配置文件
cp /opt/homer/assets/config.yml /opt/homer/assets/config-dev.yml

然后通过 https://home.yourdomain.com/?config=config-dev 访问不同页面。

八、使用 Nginx Basic Auth 保护

由于 Homer 本身没有认证功能，建议使用 Nginx Basic Auth 进行保护：

# 安装 htpasswd 工具
apt install apache2-utils -y

# 创建密码文件
htpasswd -c /etc/nginx/.htpasswd admin

在 Nginx 配置中添加认证：

location / {
    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:8080;
    # ... 其他 proxy 配置
}

九、常见问题

配置修改后不生效

Homer 是静态应用，修改配置文件后只需刷新浏览器页面即可，不需要重启容器。如果使用了浏览器缓存，请强制刷新（Ctrl+F5）。

YAML 格式错误

YAML 对缩进敏感，确保使用空格而非制表符，并保持一致的缩进层级。可以使用在线 YAML 验证工具检查配置文件格式。

总结

Homer 是最轻量的自托管应用导航仪表板，纯静态、零依赖、资源消耗几乎为零。如果你只需要一个简洁的服务导航页面，Homer 是最佳选择。如果需要更丰富的功能（如状态监控、小部件），可以考虑 Dashy 或 Homarr。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的循环折扣。