40 分钟实战：用 Dashy 搭建个人 Homelab 仪表盘

40 分钟实战：用 Dashy 搭建个人 Homelab 仪表盘

当你手中的微服务、API 接口、数据库越来越多时，迟早会面临一个管理难题：服务入口分散在各个角落，哪个在运行、哪个挂了一目了然吗？

传统的做法是丢进浏览器书签栏。但这无法提供运行状态，也无法集中管理。搭建一个专属的仪表盘（Dashboard）是更优解。Dashy 是一个轻量、高度可定制的开源仪表盘，通过单个 YAML 文件即可驱动整个界面。

本教程将带你通过 Docker 快速部署 Dashy，完成从服务聚合、状态监控到信息面板展示的完整搭建流程。

前置准备

• 环境：Linux、macOS 或 Windows（含 WSL2/Docker Desktop）。
• 依赖：已安装 Docker 且可正常拉取镜像。
• 技能：基本终端操作与 YAML 编辑能力。

选择 Docker 部署是因为 Dashy 采用配置即代码模式，单容器运行极其轻量。无需本地安装 Node.js 环境，容器内已包含所有依赖，更新与迁移只需搬运配置文件。

第一步：启动容器

打开终端执行以下命令，即可拉起一个 Dashy 实例：

docker run -d \
  -p 4000:8080 \
  -v $HOME/dashy-config:/app/user-data \
  --name dashy \
  --restart=always \
  lissy93/dashy:latest

核心参数解析：

• -p 4000:8080：将容器内部 8080 端口映射到宿主机的 4000。这意味着你可以通过 http://localhost:4000 访问界面。若 4000 端口被占用，可改为其他空闲端口。
• -v $HOME/dashy-config:/app/user-data：配置持久化。将容器内的 /app/user-data 挂载到宿主机的本地目录。这是仪表盘配置保存的地方，务必执行，否则容器销毁后所有配置丢失。
• --restart=always：守护策略。当宿主机重启或 Docker 守护进程重启时，仪表盘会自动启动，保障 Homelab 的高可用性。

启动成功后，浏览器访问本地地址，即可看到默认演示页面。

第二步：编写核心配置文件

Dashy 的灵魂在于配置文件 conf.yml。该文件应位于挂载目录 $HOME/dashy-config/ 下。

若目录为空，手动创建 conf.yml 并填入基础结构：

appConfig:
  theme: dark
  language: zh-CN
  statusCheck: true
  statusCheckInterval: 60

defaults:
  icon: favicon

sections:
  - name: 开发服务
    items:
      - title: Jenkins
        description: CI/CD 持续集成
        url: http://192.168.1.10:8080
        icon: https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@main/png/jenkins.png
      - title: SonarQube
        description: 代码质量扫描
        url: http://192.168.1.10:9000
        icon: https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@main/png/sonarqube.png

结构说明：

• appConfig：全局控制中心。theme 控制视觉风格；statusCheck: true 开启服务存活检测，这是运维最关心的功能；statusCheckInterval 设定轮询周期。
• defaults.icon：默认图标策略。设为 favicon 可自动抓取链接对应网站的 Favicon，大幅减少手动找图的工作量。
• sections & items：页面主体。每个 section 是一个视觉区块，包含多个 items（服务链接）。

保存文件后，刷新浏览器。你会看到服务卡片出现，且在线的服务旁边显示绿点，离线的显示红点。配置已即时生效。

第三步：添加 Widgets 信息聚合

除了服务入口，优秀的仪表盘还应展示环境与基础设施状态。Dashy 内置了丰富的 Widgets。

我们需要引入多页面概念。在主项目录下创建 monitoring.yml，并在主 conf.yml 中定义页面路由。

修改 conf.yml，追加 pages：

pages:
  - name: 主页
    path: config.yml
  - name: 监控面板
    path: monitoring.yml

然后在同级目录创建 monitoring.yml，编写监控面板内容：

appConfig:
  theme: cyberpunk

sections:
  - name: 系统状态
    displayData:
      type: widgets
    widgets:
      - type: clock
        options:
          timezone: Asia/Shanghai
      - type: weather
        options:
          apiKey: "YOUR_OPENWEATHER_API_KEY"
          city: "Beijing"
      - type: glances
        options:
          hostname: http://192.168.1.10:61208

defaults:
  icon: favicon

亮点功能：

• displayData.type: widgets：将此区块渲染为组件模式而非链接模式。
• Clock Widget：显示实时时间，支持 IANA 时区格式配置。
• Weather Widget：集成天气信息，需前往 OpenWeatherMap 申请免费 API Key 后填入。
• Glances Widget：强烈推荐。搭配 Glances 工具（pip install glances），可将宿主机的 CPU、内存、磁盘 IO 等核心指标以图表形式直观展示在仪表盘上，实现轻量级运维监控。

第四步：主题定制与图标优化

Dashy 提供多种内置主题，如 one-dark、dracula、nord、light 等。只需修改 appConfig.theme 并刷新即可切换，无需修改 CSS。

图标管理是仪表盘的颜值关键。除了自动抓取 Favicon，还支持：

• Font Awesome：例如 fab fa-docker。
• Simple Icons：例如 si-github。
• Emoji：直接在 iconContent 填写 Emoji。
• 本地静态文件：将图片放入挂载目录的 public/icons/ 下，通过 icon: icons/my-service.png 引用。

推荐方案是使用 dashboard-icons 项目的 CDN 链接，图标覆盖全且加载速度快。

实战完整案例：Homelab 控制台总览

结合以上步骤，一个生产级的仪表盘配置结构如下：

$HOME/dashy-config/
├── conf.yml          # 主页配置（含页面定义）
└── monitoring.yml    # 监控页配置

完整 conf.yml 示例：

appConfig:
  theme: one-dark
  language: zh-CN
  statusCheck: true
  statusCheckInterval: 30
  startingView: default

defaults:
  icon: favicon

sections:
  - name: 基础设施
    items:
      - title: Proxmox
        description: 虚拟机管理平台
        url: https://192.168.1.100:8006
        icon: https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@main/png/proxmox.png
      - title: Router
        url: http://192.168.1.1
        icon: emoji
        iconContent: 🌐

  - name: 开发工具
    items:
      - title: Gogs
        description: 私有 Git 服务
        url: http://192.168.1.10:3000
        tags: [git, code]
      - title: Nexus
        description: Maven 私有仓库
        url: http://192.168.1.10:8081

  - name: 快捷搜索
    displayData:
      type: search

常见问题与避坑指南

Q1：状态监控一直加载中或不显示？
A：确保 statusCheck: true。若服务在容器内网，容器需能访问目标 IP。若目标服务有鉴权，可使用 statusCheckUrl 指向一个无需鉴权的健康检查端点（如 /ping）。

Q2：修改 YAML 后页面不变化？
A：配置文件修改通常实时生效。若未变，尝试硬刷新浏览器（Ctrl+F5）。检查 YAML 缩进是否使用空格（禁止使用 Tab），运行 docker logs dashy 查看是否有 YAML 语法解析错误。

Q3：如何安全地暴露在公网？
A：务必开启认证。在 appConfig 中添加：

auth:
  users:
    - user: admin
      hash: "bcrypt_hash_string"

或者结合 Nginx 反向代理配置 Basic Auth。

Q4：Docker Compose 如何使用？
A：将部署命令改写为 docker-compose.yml 便于多服务编排：

version: '3'
services:
  dashy:
    image: lissy93/dashy:latest
    container_name: dashy
    ports:
      - "4000:8080"
    volumes:
      - $HOME/dashy-config:/app/user-data
    restart: always

总结

通过 40 分钟的实践，我们已经完成了：

1. 利用 Docker 快速部署 Dashy 容器环境。
2. 编写 YAML 配置实现服务聚合与自动状态巡检。
3. 搭建多页面架构，集成时钟、天气、系统监控等 Widgets。
4. 掌握主题切换与图标个性化定制。

Dashy 的价值在于极简的维护成本。新增服务只需在 YAML 中追加几行，更新版本仅需重新拉取镜像。对于 Homelab 玩家和运维工程师而言，这是一个高性价比的数字工作台解决方案。