Dashy 4.9.0 Docker Compose 部署指南

目标：用 Docker Compose 在单台 Ubuntu 22.04 服务器上部署 Dashy 4.9.0 自托管仪表盘，完成配置目录持久化、内置健康检查与配置修改后的生效验证，实现「启动即健康、配置即生效、重建不丢数据」的 0→1 部署。本文全部命令与回显已在 Docker Engine 29.9.2（Compose v5.6.1）环境实测通过；conf.yml 参数的逐项释义见《Dashy 4.9.0 配置参数详解（conf.yml）》，产品定位与选型背景见《Dashy 4.9.0 介绍与选型指南》。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Docker Engine：29.9.2，Docker Compose 插件 v5.6.1
• Dashy 版本：4.9.0（2026-10-25 实查 GitHub Releases/latest 与 Docker Hub 标签清单；镜像内 Node.js v24.22.1）
• 镜像体积：547MB（lissy93/dashy:4.9.0 实查）
• 端口规划：宿主端口 8135 → 应用端口 8080（8080 为 Dashy 部署形态默认端口，PORT 环境变量可覆盖；生产环境可改用 80 或由反向代理直接占用 80/443）
• 编排目录：/opt/dashy/（示例路径，含 docker-compose.yml 与 user-data/ 配置子目录）
• 独立网络：dashy-net（bridge，网段 10.89.62.0/24，由 Compose 在 up 时创建）
• 应用内置健康检查：node services/healthcheck.js 探测 /healthz 端点，间隔 300 秒、超时 10 秒、启动宽限期 20 秒、重试 3 次（镜像 HEALTHCHECK 实查）

二、镜像选型说明

Dashy 官方同时发布到 Docker Hub（lissy93/dashy）与 GHCR（ghcr.io/lissy93/dashy），两边内容一致，选型要点集中在仓库地址与标签策略两点。以下标签清单于 2026-10-25 通过 Docker Hub Registry API（/v2/repositories/lissy93/dashy/tags）实查：

💡 说明：实查的标签全部为 multi-arch（amd64 + arm64），官方明确不支持 32 位 ARM；4.x/4.9 这类浮动标签在 2026-10-25 实查时均指向 4.9.0。本文全部使用 4.9.0 精确标签，搭配显式 name: 项目名与固定网段，保证编排可复现、可回滚。

镜像内部要点（docker compose ps 与 docker inspect 实查）：入口为 /sbin/tini -- node server（tini 作为 PID 1 负责回收僵尸进程）；进程以非 root 用户 node（uid=1000）运行；内置健康检查如第一章所列，因此 docker compose ps 能直接看到 healthy 状态。

三、前置条件

1. 服务器已安装 Docker Engine 与 Compose 插件，验证：

docker version --format 'Engine {{.Server.Version}} ({{.Server.Os}}/{{.Server.Arch}})'

实测输出：

Engine 29.9.2 (linux/amd64)

docker compose version --short

实测输出：

5.6.1

2. 端口 8135 未被占用，验证（无输出即空闲）：

ss -ltn | grep ':8135 '

实测输出：

（无输出，端口空闲）

3. 编排与配置目录就绪（挂载源目录必须先创建，否则编排启动时会把同名路径当作目录挂载出来、且属主错乱）：

mkdir -p /opt/dashy/user-data

4. 准备最小配置 conf.yml（Dashy 4.x 允许空配置启动，但推荐首次部署就落一份可读的起点配置；完整参数体系见《Dashy 4.9.0 配置参数详解（conf.yml）》）：

cat > /opt/dashy/user-data/conf.yml << 'EOF'
pageInfo:
  title: Ops Dashboard
  description: 自托管服务导航与状态一览
sections:
  - name: 导航收藏
    icon: favicon
    items:
      - title: Dashy 仓库
        icon: favicon
        url: https://github.com/Lissy93/dashy
        target: newtab
EOF

四、部署步骤

本章按「编写编排文件 → 启动 → 验证」完成 0→1 部署。预期结果：编排状态 healthy、健康端点返回 200、日志出现欢迎横幅与版本检查结论。

4.1 编写编排文件

在 /opt/dashy/ 下创建 docker-compose.yml，全文如下（显式 name: 避免多套栈互相干扰；网段显式指定避免与其他业务冲突）：

name: dashy-4.9.0-stack

services:
  dashy:
    image: lissy93/dashy:4.9.0
    container_name: dashy-4.9.0-compose
    ports:
      - "8135:8080"
    volumes:
      - ./user-data:/app/user-data
    restart: unless-stopped
    networks:
      - dashy-net

networks:
  dashy-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.62.0/24

逐项说明：

4.2 启动编排

cd /opt/dashy
docker compose up -d

实测输出：

 Container dashy-4.9.0-compose Creating
 Container dashy-4.9.0-compose Created
 Container dashy-4.9.0-compose Starting
 Container dashy-4.9.0-compose Started

4.3 验证部署

等健康检查完成（启动宽限期 20 秒内），查看编排状态：

docker compose ps

实测输出：

NAME                  IMAGE                 COMMAND                  SERVICE   CREATED          STATUS                    PORTS
dashy-4.9.0-compose   lissy93/dashy:4.9.0   "/sbin/tini -- node …"   dashy     12 seconds ago   Up 12 seconds (healthy)   0.0.0.0:8135->8080/tcp, [::]:8135->8080/tcp

STATUS 出现 (healthy) 即镜像内置健康检查通过。再从应用层确认健康端点与页面：

curl -s -o /dev/null -w 'healthz %{http_code}\n' http://localhost:8135/healthz
curl -s -o /dev/null -w 'index  %{http_code}\n' http://localhost:8135/

实测输出：

healthz 200
index  200

最后看一眼启动日志，确认版本与更新检查结论：

docker compose logs dashy | tail -14

实测输出（输出节选，ASCII 横幅以实际为准）：

dashy-4.9.0-compose  | [34m*******************************************************************************************
dashy-4.9.0-compose  | [0m[36mWelcome to Dashy! 🚀[0m
dashy-4.9.0-compose  | [32mYour new dashboard is now up and running in container ID 0.0.0.0
dashy-4.9.0-compose  | [34m*******************************************************************************************
dashy-4.9.0-compose  | [0m
dashy-4.9.0-compose  |
dashy-4.9.0-compose  | Using Dashy V-4.9.0. Update Check Complete
dashy-4.9.0-compose  | [1m[32m✅ Dashy is Up-to-Date[0m

日志中另有 SSL Not Enabled: Public key not present 一行，属正常提示（默认 HTTP，HTTPS 证书通过 SSL_* 环境变量注入，见第六章）。

浏览器打开 http://<服务器IP>:8135 即见仪表盘首页（标题为 conf.yml 中的 Ops Dashboard）。

五、数据持久化说明

Dashy 的全部状态都在 user-data/ 目录（配置文件、子页面配置、自定义图标/字体/CSS），没有数据库。持久化三要点：

1. 挂载即持久：./user-data:/app/user-data 是唯一必须持久化的挂载。实测验证——往配置追加内容并重启后接口即读出新值；down 删除编排再 up -d 重建，配置仍在：

cat >> /opt/dashy/user-data/conf.yml << 'EOF'
appConfig:
  language: zh-CN
EOF
docker compose restart
curl -s http://localhost:8135/conf.yml | tail -4

实测输出：

        url: https://github.com/Lissy93/dashy
        target: newtab
appConfig:
  language: zh-CN

docker compose down && docker compose up -d
curl -s http://localhost:8135/conf.yml | grep -c 'language: zh-CN'

实测输出（重建后配置仍为 1 处命中，未丢失）：

1

2. 配置修改后需重启才生效：服务进程在启动时读取配置，改完 conf.yml 要 docker compose restart（实测输出：Container dashy-4.9.0-compose Restarting / Started）。UI 编辑器「Save to Disk」例外——它走服务端写盘接口，保存即写回文件。
3. 备份就是拷目录：定期备份 /opt/dashy/user-data/ 即可整体兜底；UI「Config」菜单也能导出配置（另有可选的官方云备份功能，属端到端加密的可选项）。

⚠️ 注意：如果不挂载 user-data，配置写在编排内部存储层，docker compose down 后配置随可写层一并丢弃——这是「升级后配置丢失」的最常见原因。

六、环境变量表

以下环境变量整理自 4.9.0 源码 server.js 与 services/（process.env 引用全集实查），编排文件中按需注入：

💡 说明：与 homepage 等同类不同，Dashy 的业务配置（认证用户、主题、条目）全部在 conf.yml 而非环境变量，环境变量只负责「进程运行形态」。密码哈希的生成与认证配置见《Dashy 4.9.0 配置参数详解（conf.yml）》第 5.5 节。

七、配置参数说明

部署侧只涉及三组参数：

1. 端口与网络：ports 宿主端口任意；网段经 ipam 显式固定，变更时同步修改编排文件；
2. 运行形态：PORT/SSL_*/REDIRECT_HTTPS 等环境变量（第六章），决定「HTTP 还是 HTTPS、监听在哪」；
3. 页面行为：全部在 conf.yml（认证、主题、状态检查、条目……），逐项释义见《Dashy 4.9.0 配置参数详解（conf.yml）》。

其中与部署强耦合的一个参数是 appConfig.allowConfigEdit：UI 编辑器「Save to Disk」要写挂载目录，目录权限不足或该开关关闭时只能走「改文件 + 重启」渠道（排障见第十一章 Q1）。

八、配置文件挂载

挂载后的 user-data/ 目录布局（宿主机视角 /opt/dashy/user-data/，编排内为 /app/user-data）：

user-data/
├── conf.yml          # 主配置（必需）
├── networking.yml    # 子页面配置（pages 引用时才需要）
├── icons/            # 本地图标（条目 icon 用相对路径引用）
├── fonts/            # 自定义字体
└── custom.css        # 自定义样式（externalStyleSheet 可引用）

• 目录内除 conf.yml 外均为可选，按需创建即可；
• 子页面配置（pages[].path）支持相对路径（落在此目录）或远程 URL；
• 进程以 node 用户（uid=1000）运行，UI 写盘要求该目录对其可写，属主核对方法见第十一章 Q1。

九、等价 docker run

不使用 Compose 时，等价的启动命令（先 mkdir -p /opt/dashy/user-data 并放好 conf.yml）：

docker run -d \
  --name dashy-4.9.0 \
  --restart unless-stopped \
  -p 8135:8080 \
  -v /opt/dashy/user-data:/app/user-data \
  lissy93/dashy:4.9.0

验证方式与 4.3 相同（docker compose ps 换成 docker ps，/healthz 返回 200 即健康）。生产环境建议仍用 Compose：项目名隔离、升级回滚操作面更小。

十、常用运维命令

# 查看服务状态（healthy 即正常）
docker compose ps

实测输出（见 4.3，状态列 Up ... (healthy)）。

# 跟踪运行日志（启动横幅、版本检查、SSL 提示都在这里）
docker compose logs -f dashy

实测输出（输出节选）：启动横幅、Using Dashy V-4.9.0. Update Check Complete、✅ Dashy is Up-to-Date（版本检查可经 conf.yml 的 appConfig.disableUpdateChecks 关闭）。

# 应用层健康检查（免认证探活端点）
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8135/healthz

实测输出：

200

# 修改配置后重启生效
docker compose restart

实测输出：

 Container dashy-4.9.0-compose Restarting
 Container dashy-4.9.0-compose Started

# 停止 / 清理编排（挂载目录与数据不受影响）
docker compose down

实测输出：

 Container dashy-4.9.0-compose Stopping
 Container dashy-4.9.0-compose Stopped
 Container dashy-4.9.0-compose Removing
 Container dashy-4.9.0-compose Removed
 Network dashy-490-stack_dashy-net Removing
 Network dashy-490-stack_dashy-net Removed

升级流程（以升到未来 4.9.1 为例）：改编排文件 image: lissy93/dashy:4.9.1 → docker compose pull 拉新版本 → docker compose up -d 原地重建 → curl /healthz 验证。回滚就是把标签改回 4.9.0 重复一遍，user-data 挂载不受影响。

十一、常见问题

Q1：UI 编辑器保存失败 / 配置写盘报权限错误？

镜像内进程以 node（uid=1000）运行（docker exec dashy-4.9.0-compose id 实测输出 uid=1000(node) gid=1000(node) groups=1000(node)）。挂载源目录若由 root 创建且未放权，UI「Save to Disk」与写盘类接口都会失败。处理方法二选一：把宿主机目录属主改成 1000（chown -R 1000:1000 /opt/dashy/user-data），或干脆只读使用——改配置走「改文件 + docker compose restart」渠道。

Q2：状态显示 healthy，但浏览器打不开页面？

先分清三层：docker compose ps healthy 只代表编排内健康检查（/healthz 200）通过；再确认 curl -s -o /dev/null -w '%{http_code}' http://localhost:8135/ 返回 200；最后排查宿主端口占用与防火墙（ss -ltn | grep 8135、云服务器安全组）。/healthz 通而页面不通的情况极少见，通常是挂载了空的 user-data 且路径写错导致前端资源加载异常，按第五章确认挂载路径。

Q3：启动日志一直报 Up-to-Date / Update Check？

这是 4.9.0 启动时自带的版本更新检查（实测日志：Using Dashy V-4.9.0. Update Check Complete、✅ Dashy is Up-to-Date）。离线或不想外联的部署，在 conf.yml 加 appConfig.disableUpdateChecks: true 即可关闭。

Q4：down 之后配置丢了？

docker compose down 只删编排与网络，不动挂载目录；「丢配置」一定是没用第五章的挂载方式（配置写在了编排内部存储层）。重新挂载 ./user-data:/app/user-data 并把 conf.yml 放回去即可。

Q5：同一台机器跑了别的栈，up 时网段冲突？

本文显式指定 10.89.62.0/24；若该网段已被占用（docker network inspect <网络名> --format '{{(index .IPAM.Config 0).Subnet}}' 逐个核对），换一个空闲 /24 并同步修改编排文件即可，Dashy 对网段无特殊要求。

十二、参考链接

1. 官方部署文档 Deployment：https://github.com/Lissy93/dashy/blob/master/docs/deployment.md（Compose/裸机/一键云部署全口径）
2. 官方样例编排文件：https://github.com/Lissy93/dashy/blob/master/docker-compose.yml
3. Docker Hub 镜像页：https://hub.docker.com/r/lissy93/dashy/tags（标签清单实查日期 2026-10-25）
4. GitHub Releases：https://github.com/Lissy93/dashy/releases（latest 于 2026-10-25 指向 4.9.0）
5. 本站关联篇目：《Dashy 4.9.0 介绍与选型指南》、《Dashy 4.9.0 配置参数详解（conf.yml）》