alvesd/homelab

HomeLab

一个自托管的现代化仪表板，用于组织和监控您的常用链接。基于 React、Express 和 Tailwind CSS 构建。

概览

HomeLab 结合了现代化的链接管理仪表板与强大的服务器管理工具，提供一站式的家庭实验室管理解决方案。通过直观的界面，用户可以组织链接、监控服务健康状态、管理网络设备及远程访问服务器，同时支持多用户协作和高可用部署。

核心功能与特性

链接管理

• 链接管理 — 添加、编辑、删除链接，并支持拖放排序
• 链接分组 — 将链接组织到命名的彩色编码组中，支持跨组拖放和组内排序
• 智能排序 — 按使用频率（默认）、字母顺序或自定义拖放顺序排序
• 健康监控 — 后台 HTTP 健康检查，每个卡片显示火花线图表
• 链接健康配置 — 按链接切换健康检查，设置自定义健康检查 URL 和 SLA 目标
• 正常运行时间仪表板 — 专用页面提供 24h/7d/30d SLA 视图：总体正常运行时间百分比、平均/p95 响应时间、每小时可用性时间线、前 10 慢响应时间图表，以及带 SLA 徽章的可排序链接表

服务器与网络管理

• Wake-On-LAN — 管理 WOL 目标并一键唤醒。手动添加 MAC 地址，或从 UniFi 控制器客户端列表一键导入。支持通过无状态 WOL 代理实现跨子网唤醒
• Web 终端与 SSH/VNC — 内置浏览器终端，支持访问容器 shell、建立 SSH 连接或打开 VNC 图形桌面。支持凭据、代理转发、密钥及移动友好的屏幕键盘控制
• Proxmox 管理 — 从仪表板管理一个或多个 Proxmox VE 集群：状态监控、VM/LXC 清单、浏览器内 noVNC 控制台、虚拟机电源操作、节点重启/关闭
• UniFi 网络 — 连接 Site Manager API 密钥，显示站点元数据、客户端列表、设备清单及单设备重启功能
• Synology 日志 — 连接 Synology NAS DSM 凭据，获取日志、执行 AI 驱动的日志摘要及自由形式问答
• Cloudflare 集成 — DNS CRUD 管理、零信任隧道状态监控与重启、实时 GraphQL 分析及可搜索防火墙事件威胁日志

高级功能

• Active/Active 高可用集群 — 在负载均衡器后运行多个节点，支持自动写入所有者选举、近实时快照复制和点对点 WebSocket 票据
• 应用内手册与 Q&A — 通过汉堡菜单访问全面用户指南，支持离线 PDF 导出和 Gemini 驱动的问答助手
• 自定义页面 — 每个用户可切换和重新排序左上角汉堡菜单中显示的页面
• Google OAuth — 支持 Google 登录及用户名/密码认证
• AI 集成 — Gemini 驱动的智能链接建议、后台生成和链接组织
• 自定义图标 — 上传自定义图标或从预设中选择，所有用户共享
• 天气小部件 — 基于地理位置的当前状况和天气预报
• 自定义背景 — 从预设图像、颜色中选择或上传自己的背景
• 多用户支持 — 管理员用户管理，支持基于角色的访问控制
• 导入/导出 — 从文本或浏览器书签 HTML 文件批量导入链接
• 网格与列表视图 — 在网格和列表布局之间切换
• 拖放功能 — 在编辑模式下通过拖放重新排序链接
• Docker 就绪 — 提供 Docker 镜像（amd64 架构）

使用场景与适用范围

HomeLab 适用于以下场景：

• 家庭实验室管理者需要集中管理各类服务链接和设备状态
• 系统管理员需要远程监控和管理多台服务器及网络设备
• 团队需要共享常用服务链接并协作管理基础设施
• 需要高可用性部署的关键服务监控环境
• 希望通过单一界面整合多种第三方服务（Proxmox、UniFi、Cloudflare 等）管理的用户

详细使用方法与配置说明

快速启动

Docker（推荐）

bash
docker run -d \
  -p 80:3000 \
  -v $(pwd)/data:/app/data \
  -e APP_URL=http://localhost:80 \
  -e SESSION_SECRET=your-random-secret \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=changeme \
  docker.xuanyuan.run/alvesd/homelab:latest

关于主机网络的说明： Wake-On-LAN 现在依赖手动条目或 UniFi 控制器进行发现，不需要 arp-scan。默认的 -p 80:3000 端口映射已足够。仅当您希望 WOL 魔法包直接在主机的 LAN 上广播而非通过 Docker 的 NAT 桥接时，主机网络才有用。

然后打开 http://localhost:80%E3%80%82

Docker Compose

在项目目录中创建 docker-compose.yml 文件：

yaml
version: '3.8'

services:
  homelab:
    image: docker.xuanyuan.run/alvesd/homelab:latest

    ports:
      - "80:3000"

    environment:
      NODE_ENV: production
      APP_URL: http://localhost:80
      SESSION_SECRET: your-random-secret-here-change-in-production
      ADMIN_USERNAME: admin
      ADMIN_PASSWORD: admin
      # 可选：
      # GOOGLE_CLIENT_ID: your-client-id
      # GOOGLE_CLIENT_SECRET: your-client-secret
      # GEMINI_API_KEY: your-key
    volumes:
      - ./data:/app/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

然后运行：

bash
docker-compose up -d

环境变量

Google OAuth 设置

要启用 Google 登录：

1. 在 https://console.cloud.google.com/apis/credentials 中创建 OAuth 客户端（Web 应用类型）
2. 将您的 APP_URL 添加到已授权的 JavaScript 来源
3. 将 {APP_URL}/auth/google/identity/callback 添加到已授权的重定向 URI
4. 在环境中设置 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET

管理员必须预先创建具有匹配 Google 电子邮件的用户，然后用户才能使用 Google 登录。在设置 > 用户中为用户关联 Google 电子邮件。

健康监控

服务器以可配置的间隔对所有链接执行后台 HTTP 健康检查。

全局设置（管理员）

在设置 > 全局中配置：

• 启用/禁用 — 为整个实例打开或关闭健康监控
• 检查间隔 — 设置链接检查频率（1–60 分钟，默认：15）

链接级设置

添加或编辑链接时配置：

• 健康检查切换 — 为单个链接启用或禁用健康检查
• 自定义健康检查 URL — 可选使用不同的 URL 进行健康检查（例如 https://api.example.com/health 而非主页面 URL）
• SLA 目标 — 每链接正常运行时间目标（0–100%，默认 99.9）。驱动正常运行时间仪表板上的绿/红徽章

工作原理

• 服务器向每个链接发送 HTTP HEAD 请求（如果 HEAD 失败则回退到 GET）
• 任何 HTTP 响应（包括 4xx）都视为可达 — 只有 5xx 响应和网络/超时故障视为停机，因此受身份验证保护的端点（例如 403 登录重定向）不会影响 SLA
• 原始结果保留30 天，并驱动卡片火花线和正常运行时间仪表板
• 绿色区域显示响应时间；红色点表示停机
• 悬停在火花线上可查看确切时间戳和响应时间
• 禁用健康检查的链接将被跳过，其历史记录从正常运行时间仪表板中删除

正常运行时间仪表板

从左上角的汉堡菜单打开正常运行时间页面，查看所有受监控链接的完整 SLA 视图：

• 时间范围选择器 — 24h / 7d / 30d 分段控制
• 摘要卡片 — 总体正常运行时间百分比、符合 SLA 的数量、平均响应时间、p95 响应时间、事件计数
• 响应时间图表 — 每小时绘制的前 10 个最慢链接
• 可用性时间线 — 每小时上下检查的堆叠条形图
• 每链接表 — 可按名称、正常运行时间百分比、平均响应时间、p95 或事件计数排序。当正常运行时间达到链接的 SLA 目标时，每行显示绿色徽章，否则显示红色徽章

Wake-On-LAN

从左上角的汉堡菜单发现并唤醒 LAN 上的机器。

工作原理

• WOL 目标可以手动添加（管理员点击"添加服务器"并输入 MAC）或通过从 UniFi 导入（"从 UniFi 添加"选择器列出当前连接的控制器客户端，一键添加到 WOL 列表）
• 服务器全局存储在 data/db.json 中，对所有用户可见
• 点击主机名旁边的铅笔图标可重命名服务器
• 唤醒按钮通过 https://www.npmjs.com/package/wake-on-lan 包广播魔法包 — 如果目标位于远程子网，则通过注册的 WOL 代理路由，否则通过本地广播
• 多选择唤醒：勾选多个服务器旁边的复选框，点击唤醒所选以并行向所有服务器发送魔法包
• 确认弹窗：每次唤醒都会打开一个模态框，显示每台服务器的成功/失败细分，让您始终知道哪些包实际发送出去

要求

• 魔法包需要到达 LAN 的广播域 — 默认的 -p 80:3000 映射适用于大多数设置，因为唤醒调用会遍历主机的网络堆栈。仅当 Docker NAT 吞噬广播流量时才使用 --network host
• 目标机器必须在 BIOS/UEFI 和 OS 网络适配器设置中启用 WOL

多子网 WOL 代理

要唤醒其他子网（独立 VLAN、远程站点）上的机器，在该子网内的主机上以无状态 WOL 代理模式运行相同镜像。代理自动向中央 homelab 注册并转发 /wake 魔法包调用。

bash
docker run -d \
  -e WOL_AGENT_MODE=true \
  -e WOL_AGENT_TOKEN=long-random-string \
  -e HOMEPAGE_URL=http://homelab.lan:80 \
  docker.xuanyuan.run/alvesd/homelab:latest

或在 docker-compose.yml 中（参见 repo 中 compose 文件的注释 wol-agent 块）：

yaml
wol-agent:
  image: docker.xuanyuan.run/alvesd/homelab:latest
  environment:
    WOL_AGENT_MODE: "true"
    WOL_AGENT_TOKEN: "long-random-string"
    HOMEPAGE_URL: "http://homelab.lan:80"
    # 可选：
    # WOL_AGENT_PORT: "9999"
    # WOL_AGENT_NAME: "garage-rack"
  restart: unless-stopped

必需的环境变量：

• WOL_AGENT_MODE=true — 将镜像切换到无头代理模式
• WOL_AGENT_TOKEN=… — homelab 用于调用代理的 Bearer 令牌
• HOMEPAGE_URL=… — 自注册地址（例如 http://192.168.1.10:80）

可选的环境变量：

• WOL_AGENT_PORT — 默认为 9999
• WOL_AGENT_NAME — UI 中显示的标签；默认为 OS 主机名

代理在启动时将其名称、IP、端口、令牌、子网和注册的 homelab URL 打印到容器日志。它每 5 分钟发送一次心跳；UI 在约 12 分钟未收到心跳后将代理显示为离线。代理是无状态的 — 不需要卷。

Web 终端与 SSH / VNC

从汉堡菜单访问内置浏览器终端。

功能

• 本地 Shell：直接进入容器的 shell (/bin/bash)
• SSH 客户端：使用用户名/密码、SSH 密钥或代理转发连接到任意主机
• VNC 客户端：在浏览器中打开图形桌面（由 noVNC 提供支持），可连接到任何 RFB 服务器 — x11vnc、TigerVNC、macOS 屏幕共享、Windows UltraVNC、Proxmox/ESXi 控制台等。与 SSH 共享相同的保存连接列表、组侧边栏和图标预设。端口默认为 5901，可自由编辑
  • 触摸和移动键盘支持：在移动设备上，点击 VNC 视口右中部的浮动键盘按钮 (⌨) 以调出系统软键盘和扩展工具栏。工具栏提供对修饰键（Ctrl、Alt、Shift、Super）、特殊键（Esc、Tab、箭头、F1–F12）和 Ctrl+Alt+Delete 序列的快速访问。修饰键可锁定，因此您可以点击一次 Ctrl，然后点击另一个键发送 Ctrl+键。非常适合从平板或手机管理无头服务器、VM 或图形桌面
• 代理转发：与 Wake-On-LAN 和 SSH 一样，VNC 会话可以通过远程 WOL 代理无缝转发，以访问隔离网络上的机器 — 代理在目标 LAN 上打开 TCP 连接，并通过 WebSocket 将原始 RFB 字节传回
• 连接组：保存和组织您经常访问的服务器

认证

如果目标服务器需要 SSH 密钥，您可以通过映射卷将它们挂载到 Docker 容器中：

bash
-v ~/.ssh/id_ed25519:/root/.ssh/id_ed25519:ro

或者，如果主机网络上启用了 SSH Agent 转发，您也可以使用该功能。

VNC 密码与 SSH 密码一起以 AES-256-GCM 加密存储在 db.json 中。明文密码仅在 RFB 握手前通过一次性、带票据的 WebSocket 传递给浏览器 — 绝不会出现在 URL 查询字符串中。

Proxmox 管理

从汉堡菜单的 Proxmox 页面管理一个或多个 Proxmox VE 集群。

功能

• 集群快照 — 每节点状态（在线/离线、正常运行时间、CPU、内存、rootfs）、VM 和 LXC 清单（带状态徽章），标签可见时每 5 秒轮询一次
• 客户机操作 — 启动、停止、重启、关闭、挂起、恢复、迁移、克隆、删除（可选清除）— 所有操作返回 Proxmox 任务 UPID，UI 轮询直到成功或出错
• 浏览器内控制台 — 一键访问任何客户机的 noVNC 控制台，通过 homelab 的 WebSocket 隧道 — 浏览器中无需