Dashy 4.9.0 CLI 命令详解

目标：讲清 Dashy 4.9.0 自带的 CLI 命令体系——入口命令（yarn start/node server）、运维命令（健康检查、配置校验）、构建命令（Vite build/dev/preview）与进程守护（PM2）的真实行为、适用边界与典型报错。本文全部命令均在 Dashy 4.9.0 官方镜像（Node.js v24.22.1、yarn 1.22.22）内实测，回显逐行为真实采集（2026-10-25）；部署侧的编排与参数见《Dashy 4.9.0 Docker Compose 部署指南》，conf.yml 配置体系见《Dashy 4.9.0 配置参数详解（conf.yml）》。

一、环境信息

• Dashy 版本：4.9.0（2026-10-25 实查 GitHub Releases/latest 稳定版）
• 运行时：官方镜像内 Node.js v24.22.1、yarn 1.22.22；应用目录 /app（源码部署形态按官方默认路径 /opt/dashy 同构）
• 现役服务：镜像内主进程 /sbin/tini -- node server（8080 端口常驻，供健康检查实测对照）
• 官方镜像内可用工具实测结论：yarn、node、vite（node_modules/.bin）可用；npm/npx 未随镜像发布；eslint/vitest/vue-tsc/pm2 等开发工具不在镜像内；dist/ 为预构建产物
• 命令注册方式：全部 CLI 都是 package.json 的 scripts 条目，经 yarn <name> 触发（或对 Node 脚本直接 node <script> 直跑）；Dashy 没有独立安装到 PATH 的自定义二进制

二、命令速查总览

以下为 4.9.0 package.json scripts 全表（实查），并标注官方镜像内的可用性（镜像内实测）：

💡 说明：所有「源码工作流」命令（构建、lint、测试、审计）都要求在 GitHub 源码检出目录（git clone 后 yarn install 完成）里运行；官方镜像只含运行所需的最小集合。这是 Dashy CLI 最重要的适用边界，踩坑实录见第七章。

三、服务运行命令：yarn start 与 node server

服务入口是 package.json 的 start 脚本（node server），也可直接执行 node server.js。端口与地址只认环境变量（4.9.0 server.js 源码实查，无任何命令行参数解析）：PORT（部署形态默认 8080，裸机形态 4000）与 HOST（默认 0.0.0.0）。

实测：指定 PORT=4321 启动，观察完整启动序列（timeout 截断，不长期占用）：

cd /app && timeout 8 env PORT=4321 yarn start

实测输出（完整序列）：

yarn run v1.22.22
$ node server

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

SSL Not Enabled: Public key not present

 ██████╗  █████╗ ███████╗██╗  ██╗██╗   ██╗
 ██╔══██╗██╔══██╗██╔════╝██║  ██║╚██╗ ██╔╝
 ██║  ██║███████║███████╗███████║ ╚████╔╝
 ██║  ██║██╔══██║██╔════╝██████║  ╚██╔╝
 ██║  ██║██╔══██╗██╔════╝██║  ██║  ╚██╔╝
 ██║  ██║███████║██╔════╝██║  ██║  ╚██╔╝
 ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝   ╚═╝
*******************************************************************************************
Welcome to Dashy! 🚀
Your new dashboard is now up and running in container ID 0.0.0.0
*******************************************************************************************

Using Dashy V-4.9.0. Update Check Complete
✅ Dashy is Up-to-Date

💡 说明：ASCII 横幅按终端宽度渲染，以上为实测采集（颜色码已按原文呈现）。启动序列的信息量很高：先校验配置 → SSL 证书探测 → 版本更新检查 → 欢迎横幅，任何一步的异常（配置告警、证书缺失提示、更新检查结果）都会在这段日志里出现，排障时先看它。

要点：

1. node server 前台运行；生产部署交给编排重启策略或 PM2/systemd 守护，不靠命令自身 daemon 化（Dashy 无 -d 类参数）；
2. 配置校验在启动早期执行，告警级问题（如枚举值不合法）不会中断启动，但会打进日志——上线检查脚本应结合第四章的 validate-config 做硬门槛；
3. SSL Not Enabled: Public key not present 属正常提示，注入 SSL_PRIV_KEY_PATH/SSL_PUB_KEY_PATH 两个证书后自动切 HTTPS（变量表见第九章）。

四、健康检查命令：yarn health-check

package.json 的 health-check 脚本执行 node services/healthcheck，逻辑是请求应用自身的 /healthz 端点并以退出码表达结果——这正是官方镜像 HEALTHCHECK 内置的探测命令（间隔 300 秒、重试 3 次），也可以拿来做发布流水线里的探活。

成功态实测（应用运行中，8080 正常）：

cd /app && yarn health-check

实测输出：

yarn run v1.22.22
$ node services/healthcheck
[Sun Oct 25 2026 03:31:32 GMT+0000 (Coordinated Universal Time)] Running health check...
Status: 200
Request took 0.013 seconds
---
Done in 0.08s.

退出码 0。失败态实测（PORT=9999 指向未监听端口）：

cd /app && PORT=9999 yarn health-check

实测输出：

yarn run v1.22.22
$ node services/healthcheck
[Sun Oct 25 2026 03:31:33 GMT+0000 (Coordinated Universal Time)] Running health check...
Healthceck Failed, Error: ECONNREFUSED
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

退出码 1。两个要点：

1. 探测目标由 PORT/HOST 环境变量决定（与服务器进程同参才会探到正确地址），失败回显为 ECONNREFUSED；
2. 输出中的 Healthceck 拼写为上游源码原文，非本文笔误——失败信息按前缀匹配时注意。

不经过 yarn 也可直跑脚本（退出码语义不变）：

node /app/services/healthcheck.js

实测输出：

[Sun Oct 25 2026 03:32:30 GMT+0000 (Coordinated Universal Time)] Running health check...
Status: 200
Request took 0.012 seconds
---

五、配置校验命令：yarn validate-config

validate-config 执行 node services/utils/config-validator，按应用内置 JSON Schema 校验当前配置（校验的是部署目录下 user-data/conf.yml）。合法配置实测：

cd /app && yarn validate-config

实测输出：

yarn run v1.22.22
$ node services/utils/config-validator

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

Done in 0.21s.

退出码 0。配置不合法时的三种真实回显（枚举值错误、YAML 缩进错误、配置文件缺失）已在本专栏《Dashy 4.9.0 配置参数详解（conf.yml）》第七章逐条实录，此处只给结论：

1. 枚举值错误输出警告但退出码仍为 0（如 type: guest），生产变更应把「零 warning」当门槛；
2. YAML 语法错误直接报 Error, unable to validate 'conf.yml' 并给出行号/列号与上下文；
3. 文件缺失报 Config file could not be found at /app/user-data/conf.yml。

⚠️ 注意：yarn start 启动时也会跑同一套校验，但只把结果打进日志不阻断进程；「改配置 → validate-config → 重启」才是安全的变更链路。

六、构建与预览命令（Vite）

4.9.0 的前端构建已迁移到 Vite（vite v8.3.4，实测横幅），三个命令的定位：build 生产构建、dev 开发热更新、preview 预览构建产物。

6.1 yarn preview：预览构建产物

官方镜像自带预构建的 dist/，因此 preview 可直接运行：

cd /app && timeout 10 yarn preview

实测输出：

yarn run v1.22.22
$ vite preview
  ➜  Local:   http://localhost:4173/
  ➜  Network: use --host to expose

默认监听 4173（--port 或 PORT 可改）。注意它只是「预览产物」的本地调试入口，不能替代 node server（没有配置下发、认证、状态检查等服务端能力）。

6.2 yarn dev：开发服务器

实测（官方镜像内）：

cd /app && timeout 12 yarn dev

实测输出（完整回显）：

yarn run v1.22.22
$ vite

  VITE v8.3.4  ready in 203 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
Error: EACCES: permission denied, mkdir '/app/node_modules/.vite/deps_temp_6d57c667'
    at Object.mkdirSync (node:fs:1410:26)
    at runOptimizeDeps (file:///app/node_modules/vite/dist/node/chunks/node.js:28550:5)
    ...
3:31:57 AM [vite] (client) error while updating dependencies:
Error: EACCES: permission denied, mkdir '/app/node_modules/.vite/deps_temp_d7de1001'

Vite 服务本体 203ms 就绪（监听 5173），但随后依赖预优化阶段报 EACCES：官方镜像内 node_modules 由 root 属主烘焙、进程以 node（uid=1000）运行，.vite 缓存目录不可写。结论：dev 是源码部署工作流命令——在源码检出目录用自己的 node_modules 跑，不要在官方镜像内跑（排障详见第十一章 Q3）。

6.3 yarn build：生产构建

在官方镜像内实测失败（完整回显）：

cd /app && yarn build

实测输出：

yarn run v1.22.22
$ vite build
vite v8.3.4 building client environment for production...
transforming...
✓ 1 modules transformed.
✗ Build failed in 16ms
error during build:
Build failed with 1 error:

[UNRESOLVED_ENTRY] Cannot resolve entry module index.html.

    at aggregateBindingErrorsIntoJsError (file:///app/node_modules/rolldown/dist/shared/error-CBG33oNV.mjs:49:18)
    ...
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

原因实查：官方镜像为运行做了精简，/app 下没有 Vite 构建入口 index.html（ls /app 实测只有 dist node_modules package.json public server.js services src user-data，且 src/main.js 亦不在），构建自然无从谈起。正确姿势：源码检出目录里构建——

git clone https://github.com/Lissy93/dashy.git
cd dashy
yarn install          # 安装全部依赖（含 devDependencies）
yarn build            # 产物输出到 dist/

这也是 server.js 头部注释的官方口径：「The app must first be built (yarn build) before this script is run」——源码部署形态必须先 build 再 start；官方镜像已内置产物，跳过构建直接 node server 即可。

七、进程守护命令（PM2）

package.json 提供 pm2-start（npx pm2 start server.js）用于裸机守护启动。官方镜像内实测：

cd /app && yarn pm2-start

实测输出：

yarn run v1.22.22
$ npx pm2 start server.js
/bin/sh: npx: not found
error Command failed with exit code 127.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

官方镜像未内置 npx（which npx 无结果），该命令在镜像内必然失败。两种正确用法：

1. 编排形态：不需要 PM2——编排重启策略已覆盖守护语义（restart: unless-stopped）；
2. 裸机形态：全局安装后使用——

npm install -g pm2
pm2 start server.js --name dashy
pm2 logs dashy

💡 说明：Dashy 仓库内另附 services/utils/pm2-v2-wrapper.sh 包装脚本，属源码侧工具；核心结论不变——镜像内做守护交给编排，裸机守护用自行安装的 PM2 或 systemd。

八、环境变量与端口对照

CLI 家族的全部行为开关都走环境变量（4.9.0 server.js 与 services/ 源码实查），按「谁在用」分组：

端口总览（实测口径）：8080（生产服务，PORT 可改）、4000（裸机形态默认）、5173（Vite dev）、4173（Vite preview）、443（HTTPS 启用时）。Vite dev/preview 仅源码工作流使用。

九、命令组合最佳实践

按角色给出三条惯用链路（命令均在本文实测过）：

1. 部署验证链路（发布后 30 秒体检）：

docker compose ps               # 期望 healthy
yarn validate-config            # 期望 ✔️ valid 且零 warning
yarn health-check               # 期望 Status: 200

2. 配置变更链路（改配置三步走）：

vi user-data/conf.yml
yarn validate-config            # 硬门槛：退出码 0 且无警告
docker compose restart          # 重启加载新配置

3. 源码定制链路（改主题/加组件后自建产物）：

git clone https://github.com/Lissy93/dashy.git && cd dashy
yarn install && yarn build      # 构建到 dist/
node server                     # 启动服务托管产物

十、常见问题

Q1：yarn build 报 Cannot resolve entry module index.html？

官方镜像不含源码入口（实测 /app/index.html 不存在），构建命令只在 GitHub 源码检出目录有效（第六章 6.3 完整实录）。镜像内想换前端产物没有捷径——要么源码构建，要么继续用镜像自带 dist/。

Q2：yarn pm2-start 报 /bin/sh: npx: not found？

官方镜像精简掉了 npm/npx（退出码 127，第七章实录）。编排形态用重启策略做守护；裸机形态自行 npm install -g pm2 后使用。

Q3：yarn dev 起来了却刷 EACCES: permission denied, mkdir '/app/node_modules/.vite/...'？

Vite 依赖预优化要在 node_modules/.vite 写缓存，官方镜像内该目录属 root 而进程是 uid=1000（第六章 6.2 完整实录）。在源码检出目录用自己的工作区跑 dev，不要在官方镜像内跑。

Q4：yarn health-check 探测的到底是哪个地址？

services/healthcheck.js 读取 PORT/HOST 环境变量构造 /healthz 请求，与服务器进程「同参」才会探到正确目标——用 PORT=9999 实测得到 Healthceck Failed, Error: ECONNREFUSED（第四章）。与主进程不同端口跑探活脚本时，先对齐环境变量。

十一、参考链接

1. 官方开发文档 Developing：https://github.com/Lissy93/dashy/blob/master/docs/developing.md（源码工作流与构建口径）
2. 4.9.0 package.json（scripts 全表）：https://github.com/Lissy93/dashy/blob/master/package.json
3. server.js 入口源码：https://github.com/Lissy93/dashy/blob/master/server.js（端口/主机/SSL 环境变量逻辑）
4. 本站关联篇目：《Dashy 4.9.0 Docker Compose 部署指南》、《Dashy 4.9.0 配置参数详解（conf.yml）》、《Dashy 4.9.0 介绍与选型指南》