高度可定制的仪表盘，Dashy 本地 Docker 部署记录

msedge_zmCPyHTU5L.png
前言

在拥有多台服务器或使用多个自托管服务的场景下，如何高效、集中地访问这些服务成为一个值得关注的问题。为每个服务记住 IP 地址和端口号既不方便也容易混淆。仪表盘（Dashboard）应用应运而生，旨在解决这一痛点。Dashy 是其中一款开源的、功能丰富的仪表盘应用，它以高度可定制化和现代化的界面著称。本文将以中立客观的视角，详细记录使用 Docker 在本地环境中部署 Dashy 的全过程，并汇总其核心功能、适用场景及常见问题。

1. Dashy 核心功能概览

Dashy 通过一个 conf.yml 配置文件来驱动整个仪表盘的展现。其主要功能点包括：

  • 高度可定制化：用户可以通过 YAML 文件对页面布局、项目、图标、主题和自定义 CSS 进行全面配置。
  • 实时状态监控：可为每个链接或服务开启状态指示器，实时显示其在线状态（Up/Down）和响应延迟。
  • 丰富的小组件 (Widgets)：支持集成各类服务的小组件，用于在仪表盘上直接显示动态内容或系统信息。
  • 多页面支持：允许创建多个独立的页面，以更好地对不同类型的服务进行分类管理。
  • 多种图标库：支持 Font-Awesome、本地图标、URL 图标以及自动抓取网站 Favicon 等多种图标来源。
  • 搜索与快捷键：内置即时搜索功能，可通过名称、标签或域名快速查找应用，并支持自定义快捷键。
  • 身份验证：支持简单的本地用户认证和基于 Keycloak 的 SSO 单点登录。
  • 多种视图：除了默认的卡片视图，还提供适合用作浏览器主页的 minimal (极简) 视图和用于多应用同屏操作的 workspace (工作区) 视图。

2. 适用场景

Dashy 的灵活性使其适用于多种场景：

  • Homelab (家庭实验室) 管理：集中管理和访问路由器、NAS、软路由及其他自托管服务。
  • 个人浏览器起始页：通过其极简视图，可作为功能强大的浏览器新标签页。
  • 开发与测试：为开发人员提供一个统一的入口，以访问本地开发环境、数据库管理工具和项目文档。
  • 团队内部资源导航：为团队成员提供一个共享的、包含所有常用工具和内部系统链接的导航门户。

3. 本地 Docker 部署步骤

使用 Docker Compose 是部署 Dashy 最推荐的方式，它能清晰地管理配置、端口和数据卷。

第一步：创建部署目录与文件

在本地磁盘任意位置创建一个文件夹，例如 dashy-deployment，用于存放部署所需的文件。

第二步：创建 docker-compose.yml 文件

在该文件夹内创建 docker-compose.yml 文件，并填入以下内容。此配置定义了 Dashy 容器的运行参数。

version: "3.8"
services:
  dashy:
    # 容器名称
    container_name: Dashy

    # 使用官方的 latest 镜像，它会拉取最新的稳定版本
    image: lissy93/dashy:latest

    # 数据卷映射：这是最关键的一步
    # 将本地的 my-conf.yml 文件映射到容器内部的配置文件路径
    volumes:
      - ./my-conf.yml:/app/user-data/conf.yml
      # 如果需要使用本地图标，可以取消下面这行的注释
      # - ./item-icons:/app/user-data/item-icons/

    # 端口映射: [宿主机端口]:[容器端口]
    # 部署成功后，可通过 http://localhost:4000 访问
    ports:
      - 4000:8080

    # 环境变量
    environment:
      - NODE_ENV=production

    # 重启策略：除非手动停止，否则容器在退出后会自动重启
    restart: unless-stopped

    # 健康检查：用于判断容器是否正常运行
    healthcheck:
      test: ['CMD', 'node', '/app/services/healthcheck']
      interval: 1m30s
      timeout: 10s
      retries: 3
      start_period: 40s

第三步：创建 my-conf.yml 配置文件

在同一文件夹内创建 my-conf.yml 文件。这是 Dashy 的核心，定义了仪表盘上显示的所有内容。以下是一个基础的配置模板：

pageInfo:
  title: 我的仪表盘
sections:
  - name: 常用网站
    icon: fas fa-star
    items:
      - title: Google
        description: 搜索引擎
        icon: fab fa-google
        url: https://google.com
      - title: GitHub
        description: 代码托管平台
        icon: fab fa-github
        url: https://github.com

  - name: 本地服务
    icon: fas fa-server
    items:
      - title: 路由器
        description: 网络管理
        url: http://192.168.1.1
        icon: fas fa-network-wired

第四步：启动容器

打开终端（如 PowerShell 或 CMD），使用 cd 命令进入 dashy-deployment 文件夹，然后执行以下命令：

docker compose up -d

Docker 将开始从 Docker Hub 拉取 lissy93/dashy 镜像并以后台模式启动容器。首次执行会因下载镜像而耗时较长。

第五步：访问仪表盘

启动成功后，在浏览器中访问 http://localhost:4000 即可看到基于 my-conf.yml 渲染的仪表盘界面。

4. 日常使用与定制

部署只是第一步，将 Dashy 当作一个日常应用来使用，主要涉及对其进行持续的定制和优化。

A. 修改配置与应用

所有对仪表盘的修改都通过编辑本地的 my-conf.yml 文件完成。修改保存后，需要重启容器才能使配置生效。重启命令为：

# 在 dashy-deployment 目录下执行
docker compose down && docker compose up -d

B. 寻找灵感与配置模板

如果对默认样式不满意，可以参考社区分享的配置。

  • 官方 Showcase：Dashy Showcase 1 页面收集了大量用户分享的仪表盘截图，是获取设计灵感的最佳来源。
  • 官方演示配置：Dashy 的 Live Demo 2 提供了一个功能全面的演示，其配置文件 (conf.yml) 3 是一个极佳的学习和模仿范本。
  • 社区 Gists：在 GitHub Gist 4 上搜索 dashy conf.yml 也能找到许多用户分享的实用配置。

C. 应用主题

Dashy 内置了多种主题。要应用一个主题，只需在 my-conf.yml 中添加 appConfig 部分即可。

pageInfo:
  title: 我的仪表盘
appConfig:
  theme: material-dark # 可替换为 'nord', 'minimal', 'dashy-dark' 等
sections:
  # ...

所有内置主题可在 官方文档 5 中预览。

5. 常见问题与注意事项

  1. 配置未生效：最常见的问题。原因通常是 docker-compose.yml 中的 volumes 路径不正确，或修改 my-conf.yml 后忘记重启容器。
  2. YAML 格式错误：conf.yml 对格式（尤其是缩进）要求严格。任何一个缩进错误都可能导致解析失败，使页面显示不全或白屏。建议使用支持 YAML 语法高亮的编辑器（如 VS Code）进行编辑。
  3. 容器无法启动：如果容器启动失败，可以使用 docker logs Dashy 命令查看容器的输出日志，日志中通常会包含详细的错误信息。
  4. 图标不显示：部分图标（如 Font-Awesome）需要正确的名称。如果图标不显示，应检查 icon 字段的值是否拼写正确，并符合其所属图标库的命名规范。

结论

Dashy 提供了一个强大且视觉效果现代化的仪表盘解决方案。通过 Docker 进行本地部署，整个过程清晰可控。其核心在于理解并熟练运用 conf.yml 配置文件。无论是个人使用还是团队协作，Dashy 都能通过简单的文本配置，构建出一个高度定制化、满足特定需求的导航中心。