Dashy 4.9.0 配置参数详解（conf.yml）

逐项拆解 Dashy 4.9.0 的 conf.yml 配置体系：查看与修改渠道、全量参数分组详解、生产模板与校验器三态实测，枚举值取自应用内置 Schema（2026-10-25）。

DashyDashy仪表盘自托管2026/10/25

Dashy 4.9.0 配置参数详解（conf.yml）

目标：吃透 Dashy 4.9.0 的单文件配置体系——从「查看当前生效配置、修改配置的三种渠道」讲到「全量参数分组详解与生产可用模板」，并沉淀参数校验器三态输出、状态探测端点与认证配置的实测结论。本文全部命令与回显已在 Ubuntu 22.04 + Dashy 4.9.0（Node v24.22.1，监听 8080）环境实测通过；参数枚举与默认值以 Dashy 4.9.0 自带的 JSON Schema（应用内置 /schema.json 端点）为准，查询日期 2026-10-25。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • Dashy 版本：4.9.0（2026-10-25 实查 GitHub Releases/latest 稳定版，见《Dashy 4.9.0 介绍与选型指南》）
  • 运行时：Node.js v24.22.1（官方要求裸机 Node LTS 22.22+/24.15+/26+）
  • 服务监听：0.0.0.0:8080（部署形态默认端口，PORT 环境变量可覆盖）
  • 配置文件：user-data/conf.yml（相对部署目录；本文源码部署形态位于 /opt/dashy/user-data/conf.yml，Compose 部署时该目录挂载为 /app/user-data，路径口径一致）
  • 参数字典来源：应用内置 JSON Schema（/schema.json 端点直接下发，与官方仓库 src/utils/config/ConfigSchema.json 同源）
  • 实测覆盖：配置查看（/conf.yml、/schema.json）、校验器三种输出、HTTP 状态检查与 ICMP ping 探测端点、基本认证配置生效链路、配置修改后重启生效流程

二、前置条件

  1. Dashy 4.9.0 已在服务器上运行。验证方式与实测回显：
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/healthz

实测输出：

200

/healthz 是应用内置健康端点，返回 200 即服务正常，后续所有「改配置 → 验证」都以此作为基线。

  1. 修改配置前先备份当前配置（Dashy 无内建配置版本管理，UI 编辑器误操作可能直接写盘）：
cp /opt/dashy/user-data/conf.yml /opt/dashy/user-data/conf.yml.bak
  1. 确认部署目录下的 user-data/ 可被服务进程读写：UI 编辑器的「Save to Disk」与配置写回都落在这个目录；只读场景（权限收紧的生产形态）只能走「改文件 + 重启」渠道。

三、参数查看与修改方式

3.1 查看当前生效配置：/conf.yml

Dashy 的服务端会把部署目录下的 conf.yml 原样下发：

curl -s http://localhost:8080/conf.yml | head -12

实测输出（输出节选，实测首部）：

pageInfo:
  title: Ops Dashboard
  description: 自托管服务导航与状态一览
  navLinks:
    - title: Dashy 仓库
      path: https://github.com/Lissy93/dashy
appConfig:
  theme: one-dark
  language: zh-CN
  layout: horizontal
  iconSize: medium
  startingView: default

该接口读到的是服务进程当前下发的配置内容，可直接用来核对「文件里写的」与「页面正在用的」是否一致。

⚠️ 注意：实测发现开启认证后 GET /conf.yml 仍可匿名读取（详见第七章 Q4）。若配置中含内网地址等敏感信息，应在反向代理层对该路径做访问控制。

3.2 在线参数字典：/schema.json

应用内置的 JSON Schema 就是一个可随时访问的参数字典，与官方文档全量对应：

curl -s http://localhost:8080/schema.json | head -c 200

实测输出（输出节选，实测首部）：

{"$schema":"http://json-schema.org/draft-07/schema#","$id":"https://raw.githubusercontent.com/lissy93/dashy/master/src/utils/config/ConfigSchema.json","title":"Dashy Config","description":"Validates a

本文第四章、第五章的全部枚举值与默认值均取自该 Schema（4.9.0，查询日期 2026-10-25）。

3.3 修改配置的三种渠道

渠道操作路径生效方式适用场景
直接改文件编辑 user-data/conf.yml 后重启服务重启后生效批量调整、自动化运维、IaC 托管
UI 编辑器页面上右键任意分区/条目选「Edit」，或右上角铅笔图标进入编辑模式「Save to Disk」立即写回 conf.yml；「Save Locally」仅存浏览器临时微调、快速试样式
云备份恢复UI「Config」菜单导出/导入加密备份恢复后生效多实例同步、免文件初始化

其中「直接改文件」是生产环境主渠道，标准动作是三步：改文件 → 校验 → 重启 → 验证：

vi /opt/dashy/user-data/conf.yml
node /opt/dashy/services/utils/config-validator

实测输出（配置合法时）：


Checking config file against schema...
✔️ Config file is valid, no issues found

校验通过后重启服务使新配置加载（服务进程在启动时读取并校验配置，运行中不会热加载）：

systemctl restart dashy
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/healthz

实测输出：

200

💡 说明：config-validator 校验的是「当前部署目录下 user-data/conf.yml」；也可以把它接进发布流水线，作为配置变更的门禁。

四、参数总览

conf.yml 顶层只有 4 个键（来源：4.9.0 ConfigSchema 顶层 properties）：

顶层键类型作用是否必填
pageInfoobject页面元信息：标题、描述、Logo、页脚、导航栏链接否（但 pageInfo.title 若出现则必填）
appConfigobject全局行为开关，4.9.0 共 47 个参数否
sectionsarray仪表盘主体：分区（section）→ 条目（item）两级否（不写则展示默认示例页）
pagesarray多页面：为不同场景挂多份子配置文件否

appConfig 的 47 个参数按功能域分组如下（键名取自 Schema）：

功能域参数键
外观主题theme、cssThemes、customColors、dayTheme、nightTheme、customCss、externalStyleSheet、backgroundImg、colCount、contentMaxWidth、iconSize、layout
语言与区域language
视图与启动startingView、defaultOpeningMethod、workspaceLandingUrl、showSplashScreen、enableMultiTasking
搜索webSearch（子对象）
状态检查statusCheck、statusCheckInterval、statusCheckAccessibility、pingCheckEnabled、pingCheckInterval、pingCheckCount、pingCheckTimeout、pingCheckAccessibility
图标enableFontAwesome、enableMaterialDesignIcons、fontAwesomeKey、faviconApi、defaultIcon
认证与权限auth（子对象）、enableAuthProxyCompat
配置安全allowConfigEdit、preventLocalSave、preventWriteToDisk、disableConfiguration、disableConfigurationForNonAdmin、disableContextMenu
组件与其他hideComponents、widgetsAlwaysUseProxy、enableServiceWorker、enableErrorReporting、sentryDsn、disableUpdateChecks、disableSmartSort

常用枚举值速查（Schema enum 实查）：

参数合法取值
appConfig.startingViewhome / default / minimal / workspace
appConfig.layouthorizontal / vertical / auto / masonry / sidebar
appConfig.iconSizesmall / medium / large
appConfig.auth.users[].typeadmin / normal
条目 target（打开方式）sametab / newtab / newwindow / modal / workspace / clipboard / parent / top

💡 说明：startingView 的四种取值对应四种入口形态——default 主页、minimal 极简起始页、workspace 工作台、home 官方默认示例页；把 Dashy 当浏览器起始页用时通常配 minimal。

五、核心参数分类详解

5.1 pageInfo：页面元信息

参数类型说明
titlestring页面标题（浏览器标签页与页头主标题）
descriptionstring页面描述（元数据，便于检索）
logostringLogo 图标路径（相对 user-data 或 URL）
faviconstring站点 favicon 路径
navLinksarray页头导航链接，每项含 title 与 path
footerstring页脚文本（支持 HTML）
colorstring页面主色

示例（本文实测配置的 pageInfo 部分）：

pageInfo:
  title: Ops Dashboard
  description: 自托管服务导航与状态一览
  navLinks:
    - title: Dashy 仓库
      path: https://github.com/Lissy93/dashy

title 是该节唯一必填项；navLinks 适合放「回到管理台」「文档站」等常驻入口。

5.2 appConfig 外观类参数

最常用的外观参数及实测取值：

appConfig:
  theme: one-dark            # 内置主题名，UI 主题选择器里可预览全部内置主题
  language: zh-CN            # 界面语言，简体中文为 zh-CN（30+ 语言可选）
  layout: horizontal         # 分区排布：horizontal/vertical/auto/masonry/sidebar
  iconSize: medium           # 图标尺寸：small/medium/large
  customCss: ""              # 自定义 CSS，直接内联，可覆盖主题样式
  externalStyleSheet:        # 外部样式表 URL 数组
    - https://example.com/theme.css
  backgroundImg: /bg.jpg     # 全屏背景图，挂到 user-data 下的相对路径
  hideComponents:
    - navSearch              # 隐藏页头搜索框等组件（按组件名数组）

要点：theme 改名即换肤（内置主题清单见官方 Theming 文档）；layout 选 masonry 可获得瀑布流排布，适合分区数量多的场景；customCss 与 externalStyleSheet 是外观定制的兜底手段，主题覆盖不到的细节用它补。

5.3 appConfig 视图、启动与搜索

appConfig:
  startingView: default          # 启动进入的视图：home/default/minimal/workspace
  defaultOpeningMethod: newtab   # 条目默认打开方式，8 种枚举见第四章速查
  workspaceLandingUrl: ""        # 工作台视图的默认落地页
  showSplashScreen: false        # 是否显示启动闪屏
  enableMultiTasking: false      # 工作台视图允许多任务并排
  webSearch:
    searchEngine: duckduckgo     # 内置支持的搜索引擎名，或 customSearchEngine 自定义
    openingMethod: newtab        # 搜索结果打开方式
    searchBangs:                 # 搜索 Bangs：输入前缀直接跳转对应站点
      /g: github
    disableWebSearch: false      # 关闭 Web 搜索（只搜本地条目）
    openUrlsDirectly: false      # 输入疑似 URL 时不经搜索引擎直接打开

搜索是 Dashy 的核心交互：页面输入即过滤本地条目（按名称/域名/标签），回车走 webSearch 配置的搜索引擎；searchBangs 相当于自定义快捷前缀，上面实测配置的 /g 前缀会把搜索直接转给 GitHub。

5.4 appConfig 状态检查与探测端点

全局开关（条目级可覆盖，见 5.6）：

appConfig:
  statusCheck: true            # 全局开启条目 HTTP 状态检查
  statusCheckInterval: 60      # 轮询间隔（秒）；不配则仅在页面加载时检查一次
  pingCheckEnabled: true       # 全局开启主机 ICMP ping 检查
  pingCheckInterval: 30
  pingCheckCount: 3            # 每次 ping 的回包数
  pingCheckTimeout: 2000       # 单次 ping 超时（毫秒）

服务端配套两个探测端点，可独立于页面验证探测能力。HTTP 状态检查（url 参数为探测目标）：

curl -s "http://localhost:8080/status-check?url=http%3A%2F%2Flocalhost%3A8080%2Fhealthz"

实测输出：

{"statusCode":200,"statusText":"OK","successStatus":true,"timeTaken":2,"message":"✅ Server responded with 200 - OK. \n⏱️Took 2 ms"}

ICMP ping 检查（注意参数名是 host，count 最小为 2）：

curl -s "http://localhost:8080/ping-check?host=127.0.0.1&count=2"

实测输出：

{"successStatus":true,"message":"127.0.0.1  is UP (0.825 ms)","timeTaken":1.62}

探测失败与参数错误的真实回显（用于对照判断）：

{"successStatus":false,"message":"192.0.2.55  is DOWN"}
{"successStatus":false,"message":"Invalid host given for ping check."}

⚠️ 注意：/ping-check 首次实测用 hostname=127.0.0.1 得到 Invalid host given for ping check.——该端点的参数名是 host 而非 hostname（排障过程详见第七章 Q6）。

5.5 appConfig.auth：认证与权限

💡 技术拓展：Web 应用的「认证」常见三种落地位置——应用内基本认证（应用自管用户与哈希）、OIDC/SSO（对接外部身份源）、反向代理侧认证（网关层收口，应用信任代理头）。Dashy 三种全支持，本节实测第一种；已有 Keycloak/Authentik 的团队优先看 enableOidc/enableKeycloak，已有认证网关的看 enableHeaderAuth/enableAuthProxyCompat。

auth 子对象的全部键（Schema 实查）：users、enableGuestAccess、enableOidc、oidc、enableKeycloak、keycloak、enableHeaderAuth、headerAuth、logoutRedirectUrl。

基本认证最小配置（本文实测通过）：

appConfig:
  auth:
    users:
      - user: admin
        hash: 13A5C202E320D0BF9BB2C6E2C7CF380A6F7DE5D392509FEE260B809C893FF2F9  # 口令 q1w2e3r4 的 SHA-256 大写十六进制
        type: admin
      - user: guest
        hash: 13A5C202E320D0BF9BB2C6E2C7CF380A6F7DE5D392509FEE260B809C893FF2F9
        type: normal

参数要点：

  • hash：SHA-256 摘要，Schema 校验模式为 ^[a-fA-F0-9]{64}$（64 位十六进制，大小写均可）。生成方式：
echo -n 'q1w2e3r4' | sha256sum

实测输出：

13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9  -
  • type：仅允许 admin（可编辑配置）与 normal（普通访问）。实测填 guest 会触发校验警告（回显见第七章 Q2），是 4.9.0 实查中最容易踩的枚举坑。
  • users[].password：Schema 还支持以环境变量注入明文密码（变量名必须以 VITE_APP_ 开头），避免哈希直接出现在配置里。
  • 配置生效后，浏览器访问仪表盘先出现登录页，以 admin / q1w2e3r4 登录获得管理员权限（可进 UI 编辑器），guest 账号为普通权限。
  • 服务端 /get-user 端点在未登录时返回空对象（实测 curl -s http://localhost:8080/get-user 输出 {}），可用于脚本判断会话状态。

5.6 sections：分区与条目

分区结构（sections[] 每项可用键）：name（必填）、icon、items（条目数组）、widgets（信息组件数组）、displayData（分区级展示控制，21 个键）。

displayData 高频键速查：

键作用
cols / rows分区网格占用列/行数
itemSize条目尺寸覆盖
sortBy条目排序方式
collapsed是否默认折叠
hideForUsers / showForUsers按用户名隐藏/显示该分区
hideForGuests访客不可见（配合 enableGuestAccess）
itemCountX / itemCountY固定每行列数
sectionLayout分区内部布局形态

条目（items[] 每项）共 28 个键，按用途分组：

分组键
基础title、description、icon、url、target、hotkey、tags、id、provider、rel
状态检查（HTTP）statusCheck、statusCheckUrl、statusCheckHeaders、statusCheckAcceptCodes、statusCheckAllowInsecure、statusCheckMaxRedirects、statusCheckInterval
主机存活（ICMP）pingCheckEnabled、pingCheckHost、pingCheckInterval、pingCheckCount、pingCheckTimeout
内外网双地址localUrl、localUrlCheckInterval、localUrlTimeout、localUrlCheckInterval
外观与层级backgroundColor、color、displayData、subItems（子条目下拉）、alias（路径别名）

本文实测配置中的两个条目覆盖了高频写法——普通导航条目（热键 + 标签）与状态探测条目（自定探测地址）：

sections:
  - name: 导航收藏
    icon: favicon
    items:
      - title: Dashy 仓库
        icon: favicon
        description: 本仪表盘的上游项目
        url: https://github.com/Lissy93/dashy
        target: newtab
        hotkey: 1
        tags: [dev, nav]
      - title: 本机健康检查
        icon: fas fa-heartbeat
        description: 指向本机 /healthz 的状态探测条目
        url: http://localhost:8080/
        statusCheck: true
        statusCheckUrl: http://localhost:8080/healthz

要点：icon: favicon 让 Dashy 自动抓取目标站点的图标，是省事的首选写法；statusCheckUrl 允许探测地址与跳转地址分离（跳转走内网域名、探测走健康端点是常见组合）；hotkey 取 0-9 数字键，按下即直达。

5.7 pages：多页面

当一张仪表盘装不下多类服务时，用 pages 拆分多页，每页一份独立 YAML（可在 user-data 本地，也可以是任意可访问的远程地址）：

pages:
  - name: 网络服务
    path: networking.yml
  - name: 工作相关
    path: work.yml

子页面配置文件结构与主配置完全一致（可含自己的 pageInfo/sections/appConfig），页面切换在 UI 顶部完成。path 支持远程 URL，因此可以把多张页面的配置分散托管。

六、生产配置模板

以下模板适用于「个人/小团队 homelab 统一门户」场景：2 核 4GB 内存单机（Dashy 自身约 256MB 内存、250MB 磁盘足矣，官方口径），开启基本认证、全局状态检查与中文界面，可直接作为起点：

pageInfo:
  title: Ops Dashboard
  description: 自托管服务导航与状态一览
  footer: "<a href='https://github.com/Lissy93/dashy'>Powered by Dashy</a>"
  navLinks:
    - title: Dashy 仓库
      path: https://github.com/Lissy93/dashy
appConfig:
  theme: one-dark                  # 主题按团队审美换，UI 内可实时预览
  language: zh-CN                  # 中文界面
  layout: horizontal               # 分区横向排布；分区多可改 masonry
  iconSize: medium
  startingView: default            # 作浏览器起始页可改 minimal
  defaultOpeningMethod: newtab
  statusCheck: true                # 全局状态灯
  statusCheckInterval: 60          # 每分钟轮询，探测压力可控
  webSearch:
    searchEngine: duckduckgo
    openingMethod: newtab
    searchBangs:
      /g: github
  allowConfigEdit: true            # 允许 UI 编辑器写盘；纯展示门户改 false
  auth:
    users:
      - user: admin
        hash: 13A5C202E320D0BF9BB2C6E2C7CF380A6F7DE5D392509FEE260B809C893FF2F9  # q1w2e3r4
        type: admin
      - user: guest
        hash: 13A5C202E320D0BF9BB2C6E2C7CF380A6F7DE5D392509FEE260B809C893FF2F9  # q1w2e3r4
        type: normal
sections:
  - name: 导航收藏
    icon: favicon
    displayData:
      sortBy: default
      cols: 1
    items:
      - title: Dashy 仓库
        icon: favicon
        description: 本仪表盘的上游项目
        url: https://github.com/Lissy93/dashy
        target: newtab
        hotkey: 1
        tags: [dev, nav]
      - title: 本机健康检查
        icon: fas fa-heartbeat
        description: 指向本机 /healthz 的状态探测条目
        url: http://localhost:8080/
        statusCheck: true
        statusCheckUrl: http://localhost:8080/healthz

模板要点：管理账号与访客账号分离（admin 可编辑、normal 只读浏览）；allowConfigEdit 是「UI 改配置」的总开关，对外展示型门户建议关闭以防误触写盘；statusCheckInterval 不要低于 30 秒，避免对低配设备形成无谓探测压力。

七、常见问题

Q1：改完 conf.yml 页面没变化？

服务进程在启动时读取配置，运行中不热加载。标准流程是「改文件 → config-validator 校验 → 重启服务 → curl /conf.yml 核对」，任一步骤跳过都会出现「改了没生效」。

Q2：校验器报 must be equal to one of the allowed values？

实测复现：把 appConfig.auth.users[].type 写成 guest（想当然的取值）。真实回显（输出节选）：


Checking config file against schema...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Warning: 1 issue found in config file
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. /appConfig/auth/users/1/type must be equal to one of the allowed values

4.9.0 中 type 的合法值只有 admin 与 normal（Schema enum 实查），改为 normal 后校验恢复 ✔️ Config file is valid, no issues found。注意这是警告级输出，进程仍能以退出码 0 通过，容易被忽略——生产变更应把「零 warning」当门槛。

Q3：校验器报 YAML 缩进错误？

实测复现：把 auth 块追加到了文件末尾（sections: 之后），缩进层级错误。真实回显（完整）：


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Error, unable to validate 'conf.yml'
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️ Error on line 37, column 2: bad indentation of a mapping entry

 35 |         url: http://localhost:8080/
 36 |         statusCheck: true
 37 |         statusCheckUrl: http://lo ...
 38 |   auth:
--------^
 39 |     users:
 40 |       - user: admin
 ℹ️ You might find it helpful to use a YAML validator, like: https://yamlchecker.com/

定位方法就在回显里：错误行号、列号与上下文片段会直接给出，appConfig 的子键必须挂在 appConfig: 之下（2 空格缩进），不能落在顶层键之后。

Q4：开启认证后 /conf.yml 仍可匿名访问？

实测确认：配置 auth.users 并重启后，未携带凭据与携带错误凭据的 curl -o /dev/null -w '%{http_code}' http://localhost:8080/conf.yml 均返回 200。即 4.9.0 的基本认证主要作用于前端登录与写配置接口，配置文件本身的读取没有强制认证。若 conf.yml 含内网拓扑等敏感信息，建议在反向代理层对 /conf.yml、/schema.json 做访问控制，或干脆只暴露页面路径。

Q5：校验器报 Config file could not be found？

实测复现：user-data 目录下没有 conf.yml 时直接跑校验器，真实回显：


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Error, unable to validate 'conf.yml'
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️ Config file could not be found at /app/user-data/conf.yml

Dashy 4.9.0 允许空配置启动（显示默认示例页），但一旦要自定义就必须补上这个文件；Compose 部署时确认挂载源目录在宿主机侧已创建且包含 conf.yml。

Q6：/ping-check 一直报 Invalid host？

实测复现与定位：先用 hostname=127.0.0.1 调用，返回 {"successStatus":false,"message":"Invalid host given for ping check."}；阅读 4.9.0 源码 services/endpoints/ping-check.js 确认参数名为 host（count 最小 2、timeout 毫秒），改用 host=127.0.0.1&count=2 后正常返回 UP (0.825 ms)。结论：参数名以源码/Schema 为准，不要凭直觉拼。

八、参考链接

  1. 官方配置文档 Configuring：https://github.com/Lissy93/dashy/blob/master/docs/configuring.md（conf.yml 全量参数权威说明）
  2. 应用内置参数字典：http://localhost:8080/schema.json（本文枚举与默认值来源，4.9.0，查询日期 2026-10-25）
  3. 状态检查官方文档：https://github.com/Lissy93/dashy/blob/master/docs/status-indicators.md
  4. 认证官方文档：https://github.com/Lissy93/dashy/blob/master/docs/authentication.md
  5. 多页面官方文档：https://github.com/Lissy93/dashy/blob/master/docs/pages-and-sections.md
  6. 本站关联篇目：《Dashy 4.9.0 介绍与选型指南》