使用 Docker 部署 Dashy 个人仪表盘：镜像架构、容器配置与生产实践指南

使用 Docker 部署 Dashy 个人仪表盘镜像架构、容器配置与生产实践指南【免费下载链接】dashy A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!项目地址: https://gitcode.com/GitHub_Trending/da/dashy导读Dashy 是一个可自托管的个人仪表盘应用而 Docker 是官方推荐的首选部署方式。本文将以 docs/deployment/docker.md 为核心骨架结合仓库内的 Dockerfile、docker-compose.yml、server.js 以及 CI 发布流水线 .github/workflows/docker.yml 等源码证据系统讲解镜像拉取、docker run与docker compose两种启动方式、Podman 兼容使用、健康检查机制以及权限、更新、备份、环境变量等生产运维要点。读完本文你将能够在一台 amd64 或 arm64 主机上独立完成 Dashy 容器的部署、配置挂载、健康监控与日常维护。为什么推荐用 Docker 运行 DashyDashy 的官方镜像被发布到两个容器仓库DockerHub 的lissy93/dashy与 GHCR 的ghcr.io/lissy93/dashy。镜像具备以下特点多架构支持同一标签同时适用于 amd64 与 arm64arm64v8Docker 会自动为你的宿主机选择正确的架构变体。这一点可以从发布流水线 .github/workflows/docker.yml 中看到——构建任务在linux/amd64ubuntu-latest与linux/arm64ubuntu-24.04-arm两条原生 runner 上并行执行最后通过docker buildx imagetools create合并为多架构 manifest。完整 semver 标签发布标签包括latest、精确版本如4.6.5以及滚动的小版本/大版本标签如4.6、4.x。在 .github/workflows/docker.yml 的Generate tags步骤中可以看到typesemver,pattern{{version}}、{{major}}.{{minor}}、{{major}}.x三种模式共同生成了这套标签体系。轻量基础镜像镜像基于node:24-alpine构建最终运行镜像只包含生产依赖与构建产物。容器内部约定容器对外提供两个核心约定理解它们就能掌握 Dashy 的全部部署逻辑端口容器在8080端口提供服务可通过环境变量PORT覆盖。这一点在 server.js 中体现const port process.env.PORT || (isDocker ? 8080 : 4000);即容器环境下默认 8080裸机环境下默认 4000监听地址默认0.0.0.0。数据目录你的配置文件conf.yml以及所有其他资源图标、样式、主题、字体、脚本等都存放在容器内的/app/user-data目录。仓库自带的示例配置 user-data/conf.yml 展示了配置文件的典型结构pageInfo、appConfig、sections。镜像构建与安全基线从 Dockerfile 可以进一步确认镜像的内部细节多阶段构建第一阶段build安装全部依赖并执行yarn build产出dist/第二阶段deps只安装生产依赖最终阶段从前两阶段拷贝产物保证运行镜像尽量精简。以非 root 用户运行USER node即容器内以 uid 1000 的node用户运行。PID 1 使用 tiniENTRYPOINT [/sbin/tini, --]由 tini 作为 init 进程托管node server.js保证信号正确处理、避免僵尸进程。ping 能力通过setcap cap_net_rawep为系统ping授予原始套接字能力使容器内的状态检测功能可用。OCI 元数据标签镜像携带org.opencontainers.image.*系列标签title、description、source、licenses、version 等方便供应链追溯。CI 安全扫描.github/workflows/docker.yml 在发布前用 Trivy 对每个架构的镜像做 CRITICAL 级别漏洞扫描并生成 SBOMSPDX 格式与构建 provenance 证明attest 到 GHCR。方式一docker run 快速启动在安装好 Docker 之后用下面的命令即可启动 Dashydocker run -d \ -p 8080:8080 \ -v /path/to/your/user-data:/app/user-data \ --name dashy \ --restartalways \ lissy93/dashy:latest各参数说明参数含义-d以 detached 模式运行容器在终端后台运行不占用前台-p端口映射格式为[宿主机端口]:[容器端口]。容器端口请保持为8080宿主端口可自由修改如4000:8080-v将宿主机上包含conf.yml的目录挂载到容器内/app/user-data--name为容器指定一个可读的名称便于后续docker exec、docker logs引用--restartalways设置重启策略Docker daemon 启动时自动拉起容器容器异常退出后自动重启lissy93/dashy:latest要运行的镜像。如需固定版本可将:latest替换为具体版本号如:4.6.5挂载目录的要求挂载的user-data目录必须包含conf.yml。目录里还可以放置子配置文件*.yml/*.yaml用于 Dashy 的多页面支持本地图标如item-icons/foo.png配置中通过icon: ./item-icons/foo.png引用自定义 favicon、manifest、robots.txt、字体、CSS 等任何希望从 Web 根目录提供的资源。这些文件在浏览器中都会以/文件名的形式被访问。从 services/app.js 可以看到服务端依次将user-data目录、dist/构建产物与public/目录作为静态资源根目录挂载其中user-data优先级最高可覆盖同名内置文件。其他镜像源与标签通过 GHCR 拉取docker pull ghcr.io/lissy93/dashy:latest运行时同样把镜像名替换为ghcr.io/lissy93/dashy:latest即可。镜像为多架构同一个标签在 amd64 和 arm64 上均可直接使用Docker 自动选择匹配宿主机的架构变体。发布标签包括latest、精确版本如4.6.5以及滚动标签4.6、4.x可按需锁定版本。更多docker run的完整选项请参阅 Docker 官方文档的docker container run参考。关于容器内用户与权限的注意事项容器以node用户uid 1000运行。如果你挂载的user-data目录归属的用户不是 1000可能会遇到权限错误例如 UI 中保存配置失败。两种解决办法调整目录属主sudo chown -R 1000:1000 /path/to/your/user-data以当前用户身份运行容器在docker run中追加--user $(id -u):$(id -g)更详细的说明见下文“文件所有权与权限”一节以及 docs/management.md。方式二docker compose 声明式部署Docker Compose 适合将完整的启动参数保存为文件、避免每次敲长命令也便于团队协作与多容器编排其格式与 Docker Swarm 的 stack 文件非常接近。将下面的内容保存为docker-compose.yml仓库根目录已提供一份可直接参考的 docker-compose.yml然后执行docker compose up -d启动如果文件不在当前目录用-f指定路径例如docker compose -f /path/to/docker-compose.yml up -d。-d表示后台运行。services: dashy: # 要拉取的镜像及版本。也可使用 ghcr.io/lissy93/dashy image: lissy93/dashy:latest # 或者改为从源码构建将 image: 替换为 build: . # build: . # 可选容器名称 container_name: dashy # 对外服务端口保持第二个即容器端口为 8080 ports: - 8080:8080 # 挂载包含 conf.yml 及其他资源的目录 volumes: - ./user-data:/app/user-data # 如需要在此添加服务端环境变量 environment: - NODE_ENVproduction # 若挂载文件出现权限错误可改用你自己的 uid/gid用 id -u / id -g 查看 # user: 1000:1000 # 开机自动启动 restart: unless-stopped # 可选健康检查覆盖镜像自带内置健康检查默认每 5 分钟执行一次 healthcheck: test: [CMD, node, /app/services/healthcheck.js] interval: 1m30s timeout: 10s retries: 3 start_period: 30s要点说明镜像源切换如需从 GHCR 拉取将image改为ghcr.io/lissy93/dashy:latest。从源码构建将image:行替换为build: .即可基于当前目录源码构建镜像适合自行修改代码或离线构建的场景。健康检查镜像自带内置健康检查每 5 分钟执行一次上面的示例覆盖为更频繁的检查间隔 1m30s满足对可用性更敏感的场景。健康检查脚本位于 services/healthcheck.js其实现细节见下文。方式三Podman 无守护进程运行Podman 是 Docker 的替代品无需守护进程、运行容器不强制要求 root。在 Fedora、RHEL 等发行版上或偏好 daemonless 容器时Podman 可以直接使用与 Docker 相同的镜像CLI 也基本一致podman run -d \ -p 8080:8080 \ -v /path/to/your/user-data:/app/user-data:Z \ --name dashy \ --restartalways \ docker.io/lissy93/dashy:latest注意两点差异镜像名使用docker.io/lissy93/dashy:latest显式指定 registry挂载参数末尾的:Z后缀用于 SELinux 重打标签在 Fedora/RHEL 上必不可少如果未启用 SELinux可以去掉。Podman 同样支持podman-compose或podman compose需要 compose 插件并且可以直接使用上文展示的同一个docker-compose.yml文件。健康检查机制与 /healthz 探活端点内置健康检查脚本镜像自带的健康检查脚本 services/healthcheck.js 会向http://0.0.0.0:port/healthz发起 GET 请求收到200即退出码 0健康否则退出码 1不健康。脚本细节端口自动推断容器环境下默认8080可用PORT覆盖若检测到/etc/ssl/certs/dashy-priv.key与dashy-pub.pem存在即启用了内置 SSL则改用SSL_PORT容器默认 443。允许自签名证书请求 agent 设置了rejectUnauthorized: false保证 SSL 场景下探活不被证书问题阻断。超时 2 秒并打印请求耗时与状态码方便排查。对应的 HTTP 探活端点在 services/app.js 中定义GET /healthz返回{ status: ok, uptime, version }响应头带Cache-Control: no-store且该端点不经过认证与 SSL 重定向保证在任意鉴权配置下探活始终可用。运维中的健康检查命令查看容器健康状态docker inspect --format {{json .State.Health }} [container-id]docker ps中也会显示健康状态摘要。手动触发一次检查docker exec -it [container-id] node services/healthcheck.js或使用 package.json 中定义的yarn health-check脚本。禁用健康检查在docker run中追加--no-healthcheck。自动重启不健康容器可借助 autoheal 等第三方镜像监听 unhealthy 容器并自动重启注意需要在容器上打 label 并挂载 Docker socket。反向代理 / Kubernetes 场景可直接将/healthz作为 HTTP 探针例如 KuberneteslivenessProbe配置httpGet: { path: /healthz, port: 8080 }详见 docs/management.md。生产运维进阶更新、备份、权限与环境变量文件所有权与权限容器内 Dashy 以 uid/gid 1000 的node用户运行见 Dockerfile。大多数 Linux/macOS 主机的第一个用户恰好也是 uid 1000因此 bind mount 的user-data目录通常可直接读写但在 NAS 或多用户服务器上宿主机 uid 可能不同导致 UI 保存配置时报权限错误。两种解法以你自己的用户运行容器推荐不改动宿主机属主docker run -d -p 8080:8080 \ --user $(id -u):$(id -g) \ -v /path/to/user-data:/app/user-data \ lissy93/dashy:latestCompose 中则取消user: 1000:1000一行的注释并按id -u/id -g的实际输出修改。把目录属主交给 uid 1000sudo chown -R 1000:1000 /path/to/user-data不建议以 root--user 0:0运行容器——功能虽正常但会失去非 root 容器的安全收益。完整讨论见 docs/management.md。更新镜像Dashy 的更新流程与一般容器应用一致拉取新镜像docker pull lissy93/dashy:latest或指定新版本标签重建容器docker compose pull docker compose up -dCompose 方式更新前建议先备份配置若怀疑更新后行为异常可用docker logs查看容器日志并在 docs/troubleshooting.md 中查找“App Not Starting After Update”等已知问题的解决方案。备份策略Dashy 的全部状态都在user-data目录中因此备份 备份该目录。只需定期将conf.yml、子配置文件与自定义资源复制/同步到安全位置即可也可借助 docs/backup-restore.md 中描述的云端备份/恢复功能。注意不要试图备份整个容器容器本身是无状态的随时可由镜像重建。常用环境变量服务端默认不需要任何环境变量即可运行但以下变量在生产中常用完整清单见 docs/management.mdNODE_ENV生产环境设为productionPORT覆盖监听端口容器默认 8080由 server.js 读取HOST监听地址默认0.0.0.0USER_DATA_DIR自定义配置目录默认user-dataservices/app.js 中多处通过该变量解析配置路径SSL_PORT/SSL_PRIV_KEY_PATH/SSL_PUB_KEY_PATH内置 SSL 相关配置ENABLE_HTTP_AUTH、BASIC_AUTH_USERNAME、BASIC_AUTH_PASSWORD启用 HTTP Basic 认证配合conf.yml中的appConfig.auth详见 services/app.js 中的认证中间件实现DISABLE_PROXY_ENDPOINTStrue一键关闭所有发起出站请求的端点状态检查、CORS 代理等ENABLE_APItrue启用可选的 REST API。在docker run中用-e KEYVALUE传入在 Compose 中用environment:列表传入。在容器内执行命令对运行中的容器执行命令需要借助docker exec先用docker ps找到容器 ID再执行如docker exec -it [container-id] node services/healthcheck.js也可以进入容器 shelldocker exec -it [container-id] /bin/ashAlpine 基础镜像使用 ash。项目可用脚本见 package.json 的scripts字段如validate-config、health-check、build等。镜像发布流水线从源码到多架构镜像理解镜像从何而来有助于评估其可信度与供应链安全。仓库的 .github/workflows/docker.yml 描述了完整的发布流程触发时机推送 semver 格式的 git tag*.*.*、手动触发可指定 tag 或重建latest、以及每周一次的 cron 重建同步上游补丁。并行构建amd64 与 arm64 在各自的原生 runner 上并行构建并 push-by-digest最后合并成多架构 manifest再统一打上latest、X.Y.Z、X.Y、X.x标签。安全扫描每个架构镜像发布前都经过 Trivy CRITICAL 级别漏洞扫描cron 构建若发现 CRITICAL CVE 会直接失败。供应链证明为镜像生成 SBOMSPDX JSON与 build provenance并 attest 到 GHCR。这套流水线与 Dockerfile 中的 OCI 标签共同构成了可审计的镜像供应链。对镜像完整性要求较高的用户可参考 docs/management.md 的发布校验说明。常见问题速查配置未加载 / 看到默认仪表盘确认挂载目录中存在conf.yml且文件名与位置正确修改宿主机文件后需要重启容器或刷新缓存详见 docs/troubleshooting.md。保存配置报 Permission denied / EACCES / EROFS通常是 uid 不匹配或挂载目录只读按上文“文件所有权与权限”处理SELinux/AppArmor 场景需检查:Z标签详见 docs/troubleshooting.md。armv732 位 ARM无法拉取镜像仅提供 amd64 与 arm64arm64v832 位 ARM如树莓派 2不在支持范围内参见 docs/troubleshooting.md。健康检查失败先手动执行docker exec -it [container-id] node services/healthcheck.js观察输出确认端口与PORT环境变量是否匹配参见 docs/troubleshooting.md。DockerHub 拉取限流toomanyrequests可切换至 GHCR 镜像源ghcr.io/lissy93/dashy。更多问题与解决方案请参阅 docs/troubleshooting.md。继续阅读故障排查指南常见问题与解决方案全集应用管理文档覆盖更新、备份、健康检查、文件所有权与权限、环境变量、开机自启、发布校验与容器安全等全部运维主题配置指南理解conf.yml的完整语法与appConfig选项备份与恢复配置数据的备份/恢复方案部署总览裸机、云平台、自托管系统等其他部署方式【免费下载链接】dashy A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!项目地址: https://gitcode.com/GitHub_Trending/da/dashy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考