b4bz/homer

Homer Docker镜像文档

一、镜像概述

Homer 是一个极简的静态服务器主页工具，旨在通过简单的 YAML 配置文件，帮助用户集中管理和快速访问服务器上的各类服务。它生成纯静态的 HTML/JS 页面，无需后端依赖，可直接部署在 HTTP 服务器上，适合作为个人或团队的服务导航门户。

二、核心功能与特性

• YAML 配置驱动：通过单一 config.yml 文件定义服务、分组和页面样式，配置简单直观。
• PWA 支持：支持作为渐进式 Web 应用安装，提升访问体验。
• 搜索功能：内置服务搜索，支持快速定位目标服务。
• 服务分组：可按类别（如工具、监控、文档等）对服务进行分组管理。
• 主题定制：支持自定义页面主题样式，满足个性化需求。
• 离线健康检查：可配置服务离线状态检测，直观显示服务可用性。
• 键盘快捷键：
  • /：激活搜索框；
  • Escape：退出搜索；
  • Enter：打开首个匹配结果（遵循服务配置的 _target 属性）；
  • Alt/Option + Enter：在新标签页打开首个匹配结果。

三、使用场景与适用范围

• 个人服务器管理：集中展示和快速访问个人服务器上的各类服务（如 NAS、数据库、媒体服务等）。
• 家庭网络导航：作为家庭网络的服务入口，方便家庭成员访问智能家居、文件共享等服务。
• 小型团队内部门户：为团队提供统一的内部服务导航（如项目管理工具、文档系统、CI/CD 平台等）。
• 实验室/工作室服务聚合：整合实验环境中的各类工具和服务，提升工作效率。

四、部署与使用方法

4.1 Docker 快速部署

通过 docker run 命令直接启动容器，映射本地目录存储配置和资源文件：

sh
docker run -d \
  -p 8080:8080 \  # 端口映射（主机端口:容器端口）
  -v /your/local/assets:/www/assets \  # 挂载本地assets目录（存放配置和静态资源）
  -e INIT_ASSETS=1 \  # 可选：是否安装示例配置和资源（默认1，首次使用建议保留）
  -e SUBFOLDER=null \  # 可选：若部署在子路径（如http://domain/homer），设置为子路径（如/homer）
  --restart=always \  # 容器退出后自动重启
  b4bz/homer:latest

说明：

• 首次启动时，INIT_ASSETS=1 会自动在挂载的 /your/local/assets 目录下生成示例配置文件（config.yml.dist）和静态资源（如图标），需手动将 config.yml.dist 重命名为 config.yml 并修改配置。
• 容器内 HTTP 服务默认监听 8080 端口，可通过 -p 参数调整主机映射端口。

4.2 Docker Compose 部署

创建 docker-compose.yml 文件，自定义端口和卷挂载配置：

yaml
version: '3'
services:
  homer:
    image: b4bz/homer:latest
    container_name: homer
    restart: always
    ports:
      - "8080:8080"  # 主机端口:容器端口
    volumes:
      - /your/local/assets:/www/assets  # 本地assets目录挂载
    environment:
      - INIT_ASSETS=1  # 安装示例配置和资源
      - SUBFOLDER=null  # 子路径配置（如无需子路径保持null）

启动容器：

sh
cd /path/to/docker-compose.yml
docker-compose up -d

4.3 其他部署方式（简要说明）

预构建 Tarball（适合无Docker环境）

下载官方预构建包，解压后直接部署到 HTTP 服务器（如 Nginx、Apache）：

sh
wget https://github.com/bastienwirtz/homer/releases/latest/download/homer.zip
unzip homer.zip
cd homer
cp assets/config.yml.dist assets/config.yml  # 复制示例配置
# 部署/dist目录到HTTP服务器

手动构建（适合开发或定制需求）

从源码构建：

sh
# 使用yarn（推荐）
yarn install
yarn build

# 或使用npm
npm install
npm run build
# 构建产物位于/dist目录，部署到HTTP服务器

五、配置说明

5.1 环境变量

5.2 配置文件（config.yml）

配置文件位于挂载的 assets 目录下（/your/local/assets/config.yml），基于 YAML 格式，用于定义服务、分组、页面标题、主题等。首次使用需将 config.yml.dist 重命名为 config.yml 并修改内容。

基本结构示例：

yaml
title: "我的服务门户"
subtitle: "服务器服务导航"
logo: "assets/logo.png"  # 页面logo路径（相对于assets目录）

services:
  - name: "工具类"  # 分组名称
    icon: "fas fa-wrench"  # 分组图标（使用Font Awesome图标）
    items:
      - name: "WebSSH"  # 服务名称
        logo: "assets/tools/webssh.png"  # 服务图标
        url: "http://192.168.1.100:2222"  # 服务URL
        description: "网页终端工具"  # 服务描述

详细配置项可参考 https://github.com/bastienwirtz/homer/blob/main/docs/configuration.md%E3%80%82

六、注意事项

• HTTP 服务依赖：Homer 是静态页面，必须通过 HTTP 服务器（如容器内置的 Nginx、外部 Apache/Nginx）访问，不可直接通过 file:// 协议打开 dist/index.html。
• 配置文件权限：挂载本地 assets 目录时，需确保容器对该目录有读写权限，避免配置文件无法修改或保存。
• 图标资源：可使用 Font Awesome 图标（配置中直接指定图标类名，如 fas fa-server）或自定义图片（放置在 assets 目录下并指定路径）。