Docker 部署 Docker-Panel：把容器变成可点击的服务导航

NAS 上的容器越来越多之后，最容易变乱的往往不是容器本身，而是访问入口：新服务要抄端口、拼地址、找图标，再手工塞进导航页。Docker-Panel 会读取本机 Docker 信息，为新容器生成导航卡片，同时把容器、Compose 项目、镜像和远程 Agent 节点收进同一个中文工作台。

这种便利来自很高的宿主机权限。Docker-Panel 需要读写 Docker Socket；启用 Compose 在线编辑时，还会读写主机上的项目目录。适合的边界是个人 NAS、家庭实验室或受信任内网，不应把 9527 管理端口直接暴露到公网。

部署结论

项目	本文采用的值
项目地址	Docker-Panel 官方 Wiki
官方镜像	mouyanbin/docker-panel:latest
项目版本	v2.0.9；镜像只提供官方 latest 部署入口，版本无法一一对应
正式部署	Docker Compose，单容器
适用范围	NAS、Linux Docker 主机、可信局域网中的个人或小规模运维
主机架构	官方安装文档提供 AMD64 与 ARM64 配置；本次未能从 Registry 读取 manifest
最低资源	官方未给出 CPU、内存和磁盘下限；磁盘需额外容纳 SQLite、图标、背景和备份
对外端口	9527/tcp，仅向可信局域网、VPN 或反向代理开放
持久化位置	宿主机 ./data -> 容器 /app/data
依赖服务	无外部数据库；使用 /app/data/panel.db 中的 SQLite
高权限接口	/var/run/docker.sock 必须可写；Compose 项目目录按功能选择只读或可写
验证范围	官方文档与固定提交静态核对；Compose 静态校验；未拉取或运行第三方镜像
部署日期	2026-09-13

官方 Wiki 当前记录的功能版本为 v2.0.9，部署示例却使用滚动更新的 latest。这意味着本文可以给出当前官方路径，却不能承诺日后重建仍得到同一应用版本。对版本可复现性有要求时，应先从 Docker Registry 取得对应架构的 digest，再将 image 固定为 mouyanbin/docker-panel@sha256:...；无法取得 digest 的环境需要接受镜像可能随下次拉取变化的风险。

运行结构与权限边界

浏览器访问 Docker-Panel 的 9527 端口。面板通过 Docker Socket 管理容器，并在配置的根目录中扫描 Compose 文件；SQLite、导航卡片、Agent 信息、上传图标和背景都落在 /app/data。

Mermaid 流程图

正在准备渲染...

查看源码

flowchart LR
  Browser[浏览器] -->|可信内网 / VPN / HTTPS| Panel[Docker-Panel :9527]
  Panel --> Data[(data/panel.db 与上传资源)]
  Panel --> Socket[/Docker Socket/]
  Socket --> Engine[宿主机 Docker Engine]
  Panel --> Compose[Compose 项目目录]
  Agent[远程 Agent 节点] -->|主动连接| Panel

Docker Socket 的写权限接近宿主机 root 权限：取得面板管理员权限的人，可以启动特权容器、挂载宿主机目录或修改其他服务。Compose 项目目录使用 rw 时，面板还能改写 YAML 并重建项目。只需要查看项目时改为 ro，但在线编辑、删除项目文件和面板内重建会随之不可用。

部署前准备

主机需要 Docker Engine、Docker Compose v2 和 OpenSSL。以下命令只读取版本与架构：

docker --version
docker compose version
docker info | sed -n 's/^ Architecture: //p'
openssl version

准备两个目录。/opt/docker-panel 保存本次部署；/opt/compose-projects 是示例 Compose 项目根目录，需要替换为主机上的真实位置。飞牛 NAS 常见路径是 /vol1/1000/docker，群晖常见路径可能是 /volume1/docker。

sudo install -d -m 0750 /opt/docker-panel/data /opt/compose-projects
sudo chown -R "$(id -u):$(id -g)" /opt/docker-panel
cd /opt/docker-panel

如果主机已经有 Compose 项目，不要迁移目录来迎合示例。后文同时修改 DOCKER_COMPOSE_ROOTS 和卷映射的宿主机路径，二者必须指向同一位置。

Docker Compose 正式部署

生成会话密钥

在 /opt/docker-panel 中创建权限受限的 .env。随机值不会出现在 Compose 文件或命令历史中：

cd /opt/docker-panel
umask 077
printf 'SESSION_SECRET=%s\n' "$(openssl rand -hex 32)" > .env
printf 'PANEL_BIND_IP=127.0.0.1\n' >> .env
chmod 600 .env

SESSION_SECRET 用于保护会话，至少 32 位，并且升级时保持不变。.env 和数据目录应一同纳入备份，但不要把真实值放进截图、Git 仓库或聊天记录。

保存 Compose 文件

将下面内容保存为 /opt/docker-panel/compose.yaml：

services:
  panel:
    image: mouyanbin/docker-panel:latest
    container_name: docker-panel
    restart: unless-stopped
    ports:
      - "${PANEL_BIND_IP:-127.0.0.1}:9527:9527"
    environment:
      NODE_ENV: production
      PORT: "9527"
      DATABASE_URL: "file:/app/data/panel.db"
      SESSION_SECRET: "${SESSION_SECRET:?SESSION_SECRET must be set}"
      DOCKER_SOCKET: "/var/run/docker.sock"
      DOCKER_COMPOSE_ROOTS: "/opt/compose-projects"
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock
      - /opt/compose-projects:/opt/compose-projects:ro

这里先把管理端口绑定到 127.0.0.1，适合由同机 HTTPS 反向代理转发；也先把 Compose 项目目录设为只读。局域网直连时，把 .env 中的 PANEL_BIND_IP 改为 NAS 的局域网 IP，并在防火墙中只允许可信网段访问 TCP 9527。确认确实需要在面板中修改 YAML、删除项目文件或重建项目后，再把最后的 :ro 改成 :rw。这些限制不会降低 Docker Socket 本身的权限，因此访问控制仍然是必需条件。

ARM64 主机可以在 panel 服务中增加：

    platform: linux/arm64

AMD64 主机无需增加 platform，也可以显式写成 linux/amd64。官方安装页声明支持两种配置；由于本次无法读取 Docker Hub manifest，启动前仍应先确认拉取结果与主机架构匹配。

静态检查并启动

仍在 /opt/docker-panel 目录执行：

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps

config --quiet 没有输出并返回 0，表示变量替换和 YAML 结构通过检查。docker compose ps 中 docker-panel 应为 Up；如果拉取出现 no matching manifest，先核对 docker info 输出中的 Architecture 和 Compose 的 platform，不要在未知架构上强行运行。

验证部署结果

容器与日志

cd /opt/docker-panel
docker compose ps
docker compose logs --tail=120 panel

日志不应出现 SQLite、Docker Socket、端口占用或权限错误。出现 pnpm: not found 时，官方故障文档将原因归为旧镜像缓存或 Compose 覆盖了启动命令：确认文件中没有 command、entrypoint，再重新拉取并强制重建。

HTTP 与登录

保持默认 PANEL_BIND_IP=127.0.0.1 时，在 Docker 主机上检查 HTTP 响应：

curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9527/

若已经把 PANEL_BIND_IP 改为 NAS 的局域网 IP，则把下面的 NAS-IP 换成 .env 中的实际地址：

curl -fsS -o /dev/null -w '%{http_code}\n' http://NAS-IP:9527/

命令应输出 200 或页面正常跳转时的 301、302。非零退出或 5xx 时，先查看 docker compose logs --tail=120 panel，不要继续配置代理。收到有效 HTTP 响应后，经同机反向代理访问配置的 HTTPS 域名。局域网直连模式还需用防火墙限制来源，再在同一可信局域网的浏览器打开：

http://NAS-IP:9527

默认管理员账户是 admin，默认密码是 password。第一次登录后立即在系统设置中修改管理员密码；在完成密码修改、访问限制和备份之前，不要把服务转发到公网。

核心功能

部署成功不止是页面能打开。登录后创建或启动一个已经映射宿主机端口的测试容器，确认 Docker-Panel 能读取名称、镜像、状态和端口，并自动生成可点击的导航卡片。卡片地址不正确时，检查容器是否真的发布了宿主机端口；Host 网络、非根路径和反向代理域名通常需要手工修正或使用 Docker Labels。

持久化

完成密码修改或新建一张导航卡片后，重建面板容器：

cd /opt/docker-panel
docker compose up -d --force-recreate

重新登录并确认账户设置、卡片和分组仍存在，同时检查宿主机已有数据库文件：

test -s /opt/docker-panel/data/panel.db && echo 'panel.db exists'

看见 panel.db exists 只证明文件存在；重新登录并核对卡片，才完成业务层的持久化验收。

首次配置

导航页真正省事的前提，是先把地址规则设对。进入后台后按以下顺序处理：

1. 修改默认管理员密码，并确认退出后能用新密码重新登录。
2. 设置本机内网地址；需要外网访问时，填写已经由 HTTPS 反向代理提供的域名。
3. 设置本机与 Agent 新容器的默认分组。
4. 用一个非关键测试容器验证自动建卡、端口识别、图标匹配和点击访问。
5. 只有确实需要在线维护 Compose 时，才把项目目录改为 rw。

自动、内网、外网三种访问模式解决的是“同一张卡片在不同网络里该打开哪个地址”，并不自动建立公网入口，也不替代 DNS、TLS、反向代理或 VPN。

日常运维

查看状态和日志

cd /opt/docker-panel
docker compose ps
docker compose logs --tail=200 panel
docker stats docker-panel --no-stream

Docker-Panel v2.0.9 的后台任务日志默认保留 30 天或最多 5 万条。容器日志仍应通过 Compose 查看并纳入宿主机的日志轮转策略。

数据与恢复边界

/opt/docker-panel/data 是主要恢复单元，包含 SQLite、导航配置、Agent 节点信息、图标和背景；.env 保存必须保持稳定的会话密钥，compose.yaml 记录运行契约。备份前停止容器，避免复制到正在写入的 SQLite 文件：

cd /opt/docker-panel
docker compose stop panel
# 按你的备份系统复制 data/、.env 和 compose.yaml
docker compose start panel

通用的绑定目录备份、校验和恢复步骤见Docker 镜像与数据备份恢复指南。恢复时使用与备份兼容的镜像，放回这三个对象后启动容器，再以登录、卡片、分组、Agent 状态和上传资源作为业务验收。

Docker-Panel 后台还提供导航配置与 Agent 信息导出。官方文档说明，恢复到同一面板地址后 Agent 可自动重连，但导入不会覆盖管理员账号和密码。界面导出适合迁移业务配置，不能代替 /app/data、.env 和 Compose 文件的整套灾难恢复备份。

升级与回滚

先给当前镜像添加不会随 latest 移动的本地回滚标签，再停止写入并完成备份：

cd /opt/docker-panel
docker images --no-trunc --quiet mouyanbin/docker-panel:latest
docker tag mouyanbin/docker-panel:latest docker-panel:rollback-20260913
docker compose stop panel
# 完成 data/、.env 和 compose.yaml 的备份后再继续
docker compose start panel

然后拉取并重建：

docker compose pull
docker compose up -d --force-recreate
docker compose ps
docker compose logs --tail=120 panel

升级后重复 HTTP、登录、自动建卡和持久化检查。官方只给出 latest。要回滚，在 Compose 中临时改用升级前创建的本地标签，并禁止 Compose 尝试远程拉取：

    image: docker-panel:rollback-20260913
    pull_policy: never

停止新容器、恢复升级前的数据目录和 .env，再运行 docker compose up -d --force-recreate。确认旧版本恢复后，保留回滚标签直到观察期结束。若旧镜像已经被清理，Docker Hub 的 latest 无法保证重新取得旧版本，回滚将依赖自己的 Registry 或离线镜像归档。

docker compose down 默认删除容器和项目网络，不删除 /opt/docker-panel/data；手工删除该目录会丢失数据库与上传资源。面板中删除其他 Compose 项目，本质上会执行对应项目的 docker compose down；是否再删除项目文件取决于目录权限和操作选择，执行前先核对目标项目。

生产环境安全

• 9527 是带宿主机控制能力的管理入口，只向可信局域网或 VPN 开放。需要域名访问时，通过 HTTPS 反向代理暴露，并把源站端口限制在代理可达范围。
• 首次登录立即更换公开默认密码；保留随机 SESSION_SECRET，不要通过 Compose、截图或日志泄露。
• Docker Socket 无法按容器细分权限。把面板视为宿主机管理员入口，不与不可信用户共享。
• Compose 项目目录默认使用 ro。切换 rw 之前，确认面板管理员可以改写和删除哪些项目。
• SSH、Telegram、企业微信和代理功能可能保存主机凭据、Token 或代理认证信息。这些配置进入数据备份后，备份文件也必须按敏感数据保护。
• Agent 不需要把远程 Docker Socket 暴露到公网；公网接入应使用 HTTPS，并保持 Agent 的 HTTPS 要求开启。

反向代理应只转发到绑定在本机的 9527 端口，启用有效 TLS 证书，并验证登录、退出和长时间会话；宿主机还应限制 Docker 管理权限、设置容器日志轮转，并在更新镜像前核对来源。Docker-Panel 没有可核验的公开应用源码或许可证，官方 Wiki 仓库只包含文档站；在安全审计、软件许可或供应链透明度有硬性要求的环境中，应先完成额外评估。

常见问题

页面打不开

症状是浏览器连接失败。先运行 docker compose ps 和 docker compose logs --tail=120 panel，再确认端口绑定与 .env 中的 PANEL_BIND_IP 一致、NAS 防火墙允许可信网段访问，以及反向代理指向正确主机。修复后先用上一节与绑定地址匹配的 curl 命令复验，再从客户端访问。

能登录，但看不到容器

检查 /var/run/docker.sock:/var/run/docker.sock 是否存在且没有 :ro。官方要求可写 Socket 才能完成发现、启动、停止和更新；如果组织安全策略不允许这种权限，Docker-Panel 的本机管理模式不适合该环境。

Compose 项目能看，不能保存

确认 DOCKER_COMPOSE_ROOTS 与卷映射中的容器路径完全一致。目录使用 :ro 时只能读取；确实需要在线编辑后改成 :rw，执行 docker compose up -d 让挂载生效，再用一个非关键测试项目验证保存与重建。

新容器没有自动生成卡片

确认容器正在运行并映射了可访问的宿主机端口，同时排除隐藏容器、分组筛选和隐藏 Label。修复后触发容器同步，检查导航页是否出现卡片；没有端口的后台任务通常没有可自动生成的访问地址。

镜像拉取失败

保留 Compose 中的官方镜像地址，先检查 Docker Hub 连通性。Docker-Panel v2.0.8 起提供“DP 兜底拉取”，只在 Docker 原生拉取失败后按配置的镜像源尝试；公共镜像源的归属、可用性和内容一致性会变化，使用前逐个测试，并把第三方代理视为新的供应链信任路径。需要宿主机级镜像加速时，不要覆盖现有 /etc/docker/daemon.json，应合并配置并在重启 Docker 前校验 JSON。

部署完成后

先用一个非关键容器跑通“上线、自动建卡、地址可访问”这条路径，再决定是否开启自动升级、容器自动恢复和定时重启。数据库、认证和反向代理服务不适合仅因资源曲线波动就自动重启；自动化规则应有明确阈值、冷却时间和失败通知。

管理多台服务器时，下一步是在 HTTPS 可达的面板上生成 Agent 接入信息，让远程节点主动连接。不要开放远程主机的 Docker TCP Socket；节点离线、时间偏差和旧接入信息失效时，按官方故障自检逐项排查。

总结

Docker-Panel 最有价值的结果，是新容器上线后直接出现在导航页，并能从同一个工作台查看状态和维护 Compose。相应代价是面板掌握 Docker Socket、项目文件和多类运维凭据。把服务留在可信网络、立即修改默认密码、保持 /app/data 与会话密钥的完整备份，并在每次滚动升级前保留旧镜像，才能把便利控制在可恢复的边界内。

参考资料

• Docker-Panel 官方 Wiki
• Docker-Panel 安装教程
• Docker-Panel 使用教程
• Docker-Panel 配置说明
• Docker-Panel 备份与升级
• Docker-Panel 故障自检
• Docker-Panel 版本日志
• Docker-Panel Wiki 固定提交
• Docker Hub：mouyanbin/docker-panel
• 遇见好软件：容器上线即成导航卡片！Docker-Panel