Skip to content

🚀 使用 Docker Compose 部署 Sun Panel 导航面板

🚀 使用 Docker Compose 部署 Sun-Panel 导航面板

Sun-Panel 是一款开源、简洁高效的个人导航面板，特别适合用于管理服务器、NAS设备以及常用网站书签。它提供了可视化操作界面和丰富的自定义功能，让用户能够零代码搭建个性化的浏览器首页。

下面将详细介绍如何使用 Docker Compose 部署 Sun-Panel。

📦 项目简介

Sun-Panel 的核心特点可以概括为下表：

特点类别 具体说明
界面与操作 界面简洁，功能强大，资源占用少；上手简单，可视化操作，可0代码使用；支持网页内置小窗口打开（部分三方网站屏蔽此功能）。
部署与集成 支持 Docker 部署（支持 Arm 系统）；简单的 Docker 管理器，支持查看容器状态；简单使用可以无需连接外部数据库。
个性化与账户 支持多账号隔离使用；丰富图标风格自由搭配，支持 iconify 图标库；支持自定义 Js、Css。
网络功能 一键切换内、外网模式链接。

使用场景 * NAS 导航面板：在家庭或企业网络中，作为 NAS 设备的导航面板，方便访问和管理家庭网络存储设备上的文件和媒体资源。 * 统一工作台：集中管理各类内部系统（如 OA、企业邮箱、项目看板）的入口，提升工作效率。 * 个人浏览器首页：设置为浏览器首页，快速访问常用网站和资源。

📋 部署前准备

1.环境要求 确保你的服务器已安装 Docker 和 Docker Compose。你可以通过在终端执行 docker -v 和 docker compose version 来验证。对于 Linux 系统，可参考以下步骤安装：

    # 以 CentOS 为例，更新系统并安装依赖
    sudo yum update -y
    sudo yum install -y yum-utils device-mapper-persistent-data lvm2

    # 添加 Docker 官方仓库并安装
    sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
    sudo yum install -y docker-ce docker-ce-cli containerd.io

    # 启动 Docker 并设置开机自启
    sudo systemctl start docker
    sudo systemctl enable docker

    # 安装 Docker Compose (版本号可更新至最新稳定版)
    sudo curl -SL https://github.com/docker/compose/releases/download/v2.27.1/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
    sudo chmod +x /usr/local/bin/docker-compose

2.资源检查 * 端口：确认 3002 端口未被其他程序占用。 * 磁盘空间：确保部署目录有足够的空间。 * 权限：确保当前用户对部署目录有读写权限。

⚙️ 配置 Docker Compose

1.创建项目目录 创建一个目录（如 sun-panel）用于存放所有相关文件，并进入该目录。

    mkdir -p /path/to/your/sun-panel && cd /path/to/your/sun-panel

2.创建 docker-compose.yml 文件 将以下配置内容保存到新创建的 docker-compose.yml 文件中。

#version: "3.2"

services:
  sun-panel:
    image: "hslr/sun-panel:latest"  # 官方最新镜像
    container_name: sun-panel  # 容器名称，便于管理
    volumes:
      - ./conf:/app/conf  # 配置文件持久化：本地 ./conf → 容器 /app/conf（保存面板设置）
      - /var/run/docker.sock:/var/run/docker.sock   # 关键：挂载docker.sock＆Docker控制文件，使面板能管理本地容器
      # - ./runtime:/app/runtime   # 可选：挂载日志目录（需取消注释并创建 ./runtime 目录）
      # - /mnt/sata1-1:/os  # 可选：挂载硬盘分区（替换为你的硬盘路径，用于监控该分区）
    ports:
      - 3002:3002  # 端口映射：主机 3002 → 容器 3002（面板 Web 访问端口）
    restart: always  # 容器退出后自动重启，保障服务稳定

3.关键配置说明 * 镜像：hslr/sun-panel:latest 是 Sun-Panel 的官方 Docker 镜像。如果拉取镜像困难，可以考虑使用第三方镜像，如 registry.cn-hangzhou.aliyuncs.com/weiyigeek/sun-panel:1.4.0。 * 数据持久化：volumes 部分将容器内的目录挂载到宿主机，防止容器重启后数据丢失。请确保 conf, uploads, database 这些目录在宿主机存在，或者 Docker Compose 会自动创建它们。 * Docker 管理功能：挂载 /var/run/docker.sock 使得 Sun-Panel 容器能够与宿主的 Docker 守护进程通信，从而实现容器管理功能（如查看容器状态）。请注意，这具有一定安全风险，因为它赋予了 Sun-Panel 容器很大的权限，请确保在可信环境中使用。 * 端口映射："3002:3002" 表示将宿主机的 3002 端口映射到 Sun-Panel 容器的 3002 端口。你可以按需修改宿主机的端口，例如 "8080:3002"。

🚀 启动与验证

1.启动服务 在 docker-compose.yml 文件所在目录下，执行以下命令来后台启动服务：

    docker-compose up -d

2.检查服务状态 使用以下命令查看容器是否正常运行：

    docker-compose ps

如果状态（State）栏显示为 Up，则表明容器已成功启动。

3.查看日志 如果容器启动异常，可以通过日志来排查问题：

    docker-compose logs sun-panel

成功启动的日志通常会包含 "Sun-Panel is Started" 类似信息。

4.访问服务 在浏览器中输入 http://你的服务器IP:3002。如果看到 Sun-Panel 的登录界面，说明服务已成功部署。

（2）访问 Sun Panel 管理界面

  1. 打开浏览器，输入 http://服务器IP:3002（如内网 http://192.168.1.100:3002）；
  2. 首次登录：默认用户名 admin，默认密码 admin123（必须立即修改）；
  3. 登录成功后进入主界面，显示服务器 CPU、内存、网络等实时数据，说明服务正常。

🔧 基础配置与使用

  1. 初始登录

    • 在浏览器中访问 http://你的服务器IP:3002。
    • 使用默认账号 admin@sun.cc 和密码 12345678 进行登录。

  2. 安全配置（重要）

    • 登录后，强烈建议立即修改默认管理员密码或创建新的管理员账户。
    • 操作路径：点击页面右下角的设置图标 -> "账号管理"。
    • 你可以选择直接修改 admin@sun.cc 的密码，或者新建一个管理员账号，然后退出登录并使用新账号，再删除默认的 admin@sun.cc 账户。

  3. 添加导航项与分组

    • 点击首页的 "添加" 按钮。
    • 在弹出页面中，填写项目标题、选择图标（支持文字、上传图片或从丰富的在线图标库中选择）、设置背景颜色、输入网址等。
    • 建议先创建分组对导航项进行分类管理（如"常用网站"、"NAS服务"等），使得首页更加整洁。

  4. 个性化设置

    • 在"风格设置"中，可以上传自定义 Logo 和背景壁纸，调整壁纸模糊度等，打造个性化的导航页面。
    • 利用"分组管理"功能，可以添加和调整首页的组件布局。

🔧 基础配置与使用2

Sun Panel 的核心使用场景是 “监控服务器状态→管理 Docker 容器→查看存储信息”，新手可按以下步骤操作：

1. 步骤 1：修改默认密码（安全必备）

  1. 登录后点击右上角 “用户头像”→“个人设置”；
  2. 在 “密码修改” 栏输入原密码 admin123，设置新密码（建议含字母 + 数字 + 符号）；
  3. 点击 “保存”，下次登录需使用新密码。

2. 步骤 2：监控 Docker 容器

  1. 左侧菜单点击 “Docker 容器”，面板会列出所有本地 Docker 容器（因挂载了 docker.sock）；
  2. 对容器进行操作：
    • 启动 / 停止 / 重启：点击容器右侧对应按钮；
    • 查看日志：点击 “日志” 可实时查看容器输出；
    • 资源监控：容器列表显示 CPU、内存占用率，点击容器名可查看历史趋势。

3. 步骤 3：添加硬盘监控（可选）

若需监控除系统盘外的其他硬盘（如挂载的 NAS 或外接硬盘）：

1.编辑 docker-compose.yml，取消注释并修改硬盘挂载项：

    volumes:
      - /mnt/my-disk:/os  # 替换 /mnt/my-disk 为你的硬盘实际挂载路径

2.重启容器：docker compose restart； 3.登录面板，左侧菜单点击 “存储”，即可看到新增硬盘的容量、使用率等信息。

4. 步骤 4：设置资源告警（进阶）

  1. 左侧菜单点击 “告警设置”；
  2. 配置阈值（如 CPU 使用率超过 80%、内存使用率超过 90% 时告警）；
  3. 选择告警方式（如邮件、Webhook，需提前配置对应服务），避免服务器资源耗尽。

🔄 维护与管理

1.更新服务 当有新版本发布时，可以按以下步骤更新：

    # 进入 docker-compose.yml 所在目录
    cd /path/to/your/sun-panel
    # 拉取最新的 Sun-Panel 镜像
    docker-compose pull
    # 重新创建并启动容器
    docker-compose up -d
    # 清理无用的旧镜像
    docker image prune

2.数据备份 * Sun-Panel 的所有配置、上传文件和数据库都保存在宿主机挂载的 conf, uploads, database 目录中。 * 定期备份整个项目目录（例如打包压缩）即可备份所有数据。

3.服务卸载 如需卸载 Sun-Panel，在项目目录下执行：

    docker-compose down

如果希望彻底删除所有数据（包括配置和数据库），在上述命令后移除整个项目目录即可。

🐛 常见问题排查

问题现象 可能原因与解决方案
容器启动失败 1. 检查 docker-compose.yml 文件语法是否正确，例如缩进、引号等。
2. 执行 docker-compose logs sun-panel 查看具体错误日志。
无法访问网页 1. 确认服务器防火墙是否开放了 3002（或你自定义的）端口。
2. 检查 docker-compose ps 确认容器是否在运行状态。
登录后提示密码错误 1. 确认输入的默认账号为 admin@sun.cc，密码为 12345678。
2. 如果已修改密码但遗忘，可以尝试通过命令重置：
docker exec -it sun-panel ./sun-panel -password-reset。此命令会将首个管理员账户（通常是 admin@sun.cc）的密码重置为 12345678。
图标加载失败或缓慢 1. 网络问题导致在线图标库加载慢，可尝试更换网络环境，或推荐使用本地上传图标的方式。
Docker 状态查看不显示 1. 检查 docker-compose.yml 中是否已挂载 /var/run/docker.sock。
2. 确认宿主机 Docker 服务正常运行。

希望这篇教程能帮助你顺利搭建属于自己的 Sun-Panel 导航页，享受高效、美观的导航体验！如果在部署和使用过程中遇到更多问题，Sun-Panel 的 GitHub 项目页面是寻求解决方案的好去处。

🐛 常见问题排查2

1. 面板无法显示 Docker 容器

  • 原因 1：docker.sock 挂载错误或权限不足。解决：

    1. 确认配置中包含 - /var/run/docker.sock:/var/run/docker.sock；
    2. 检查权限：执行 ls -la /var/run/docker.sock，确保当前用户属于 docker 组（输出含 docker 组）；
    3. 重启容器：docker compose restart。
    4. 原因 2：Docker 服务未启动。解决：启动 Docker 服务：sudo systemctl start docker。

2. 登录失败（提示 “用户名或密码错误”）

  • 原因 1：密码修改后遗忘，或首次登录未修改默认密码。解决：重置密码（需删除配置文件重建）：
    # 停止容器
    docker compose down
    # 删除配置目录（会丢失所有设置，谨慎操作）
    rm -rf conf/*
    # 重启容器，恢复默认账号密码
    docker compose up -d
  • 原因 2：配置文件损坏。解决：按上述步骤重置配置目录，重新配置面板。

3. 硬盘监控不显示新增分区

  • 原因：硬盘挂载路径错误或未重启容器。

    解决： 1. 确认 volumes 中硬盘路径正确（如 /mnt/my-disk 确实存在且已挂载）； 2. 重启容器使配置生效：docker compose restart。

4. 面板访问缓慢或卡顿

  • 原因 1：服务器资源不足（CPU / 内存占用过高）。解决：通过面板 “系统监控” 查看资源占用，关闭不必要的进程或容器。

  • 原因 2：浏览器缓存问题。解决：清除浏览器缓存（Ctrl+Shift+Delete），或使用隐私模式访问。

通过以上步骤，新手可快速部署 Sun Panel 并实现服务器与 Docker 容器的可视化管理。Sun Panel 适合个人用户简化服务器运维，后续可探索其插件扩展或自定义监控指标，具体参考 Sun Panel 官方文档（若有）。