喵pass

logo
喵pass
一只怕老鼠的猫

使用 Docker Compose 部署 Sun-Panel-Helper

2025/10/30
#docker
4
0

一款为 Sun-Panel 设计的可视化美化工具，让你的 Sun-Panel 锦上添花~

作者原址：madrays/sun-panel-helper: 为hslr-s/sun-panel开发的一个一键快捷美化的小项目~

🚀 快速部署

重要参数说明

  • 端口配置:

    • Sun-Panel端口: 3002:3002

      • 3002为访问端口,可自定义修改

      • 3002为容器内端口(勿改)

    • Helper前端端口:

      • 普通模式: 33002:80 (33002为访问端口,可自定义修改)

      • 自定义内部端口: FRONTEND_PORT=8080 (可选,默认80)

      • Host模式: FRONTEND_PORT=33002 (必须设置)

    • Helper后端端口: BACKEND_PORT=3001

      • 默认3001,可通过环境变量修改

      • 注意避免与其他服务冲突

  • 数据目录:

    • 必须挂载三个重要目录:

      • /app/backend/custom: Sun-Panel的custom目录(必需)

      • /app/backend/data: Helper的数据目录(必需)

      • /app/backend/backups: 备份文件存储目录(必需)

    • 确保目录权限正确(需要读写权限)

重要变更通知 (v2.0.5+)

⚠️ v2.0.5版本新增两个重要数据目录挂载，请务必添加以下挂载点：

  • /app/backend/data：用户数据目录，存储重要配置信息

  • /app/backend/backups：备份文件存储目录，保存系统备份

1. 命令行部署

Docker命令部署

# 标准模式
docker run -d \
  --name sun-panel-helper \
  -p 33002:80 \
  -e BACKEND_PORT=3001 \
  -v /path/to/sunpanel/conf/custom:/app/backend/custom \
  -v /path/to/helper/data:/app/backend/data \
  -v /path/to/helper/backups:/app/backend/backups \
  madrays/sun-panel-helper:latest

# Host网络模式 (解决IPv6问题)
docker run -d \
  --name sun-panel-helper \
  --network host \
  -e BACKEND_PORT=3001 \
  -e FRONTEND_PORT=33002 \
  -v /path/to/sunpanel/conf/custom:/app/backend/custom \
  -v /path/to/helper/data:/app/backend/data \
  -v /path/to/helper/backups:/app/backend/backups \
  madrays/sun-panel-helper:latest

Docker Compose部署

创建docker-compose.yml文件:

# 标准模式
version: '3'
services:
  sun-panel-helper:
    image: madrays/sun-panel-helper:latest
    container_name: sun-panel-helper
    environment:
      - BACKEND_PORT=3001  # 后端服务端口,可自定义修改避免冲突
    ports:
      - "33002:80"        # 前端页面访问端口,可自定义修改避免冲突
    volumes:
      - /path/to/sunpanel/conf/custom:/app/backend/custom
      - /path/to/helper/data:/app/backend/data
      - /path/to/helper/backups:/app/backend/backups
    restart: unless-stopped
# Host网络模式 (解决IPv6问题)
version: '3'
services:
  sun-panel-helper:
    image: madrays/sun-panel-helper:latest
    container_name: sun-panel-helper
    network_mode: host    # 使用Host网络模式
    environment:
      - BACKEND_PORT=3001     # 后端服务端口
      - FRONTEND_PORT=33002   # 前端页面访问端口(Host模式必须设置)
    volumes:
      - /path/to/sunpanel/conf/custom:/app/backend/custom
      - /path/to/helper/data:/app/backend/data
      - /path/to/helper/backups:/app/backend/backups
    restart: unless-stopped

运行命令:

docker-compose up -d

🔧 更新注意事项

  • 数据目录挂载：

    • 必须挂载三个目录：custom, data, backups

    • 如从旧版升级，请创建新的data和backups目录

    • 备份目录需要足够空间存储100份备份

  • 文件上传限制：

    • 已增大Nginx上传限制至60MB

    • 支持更大的字体和Logo文件上传

  • 备份功能：

    • 系统最多保留100份备份，自动清理旧备份

    • 建议定期手动清理不需要的备份释放空间

  • 镜像更新：

    • 请删除旧版容器后重新部署，不建议直接更新

    • 更新前请先备份重要数据

IPv6兼容性说明

如果您需要管理位于纯IPv6网络的TR/QB下载器，请使用Host网络模式部署Helper:

  1. 为什么需要Host模式?

    • Docker默认网络模式下容器无法直接访问IPv6网络

    • Host模式让容器直接使用宿主机网络，支持IPv6连接

    • 解决TR/QB组件无法连接IPv6下载器的问题

  2. 如何使用Host模式部署?

    • 设置network_mode: host

    • 必须设置FRONTEND_PORT指定前端监听端口

    • 确保指定的端口未被占用

  3. 注意事项

    • Host模式下端口映射(-p)参数无效

    • 使用环境变量FRONTEND_PORT指定前端访问端口

    • 多个容器端口不能冲突

2. 图形化界面部署

Portainer部署

标准模式

  1. 打开Portainer界面

  2. 进入"Containers" > "Add Container"

  3. 填写以下信息:

    • Name: sun-panel-helper

    • Image: madrays/sun-panel-helper:latest

    • Port mapping: 33002:80

    • Environment variables:

      • BACKEND_PORT=3001

    • Volumes:

      • host: /path/to/sunpanel/conf/custom

      • container: /app/backend/custom

      • host: /path/to/helper/data

      • container: /app/backend/data

      • host: /path/to/helper/backups

      • container: /app/backend/backups

  4. 点击"Deploy the container"完成部署

Host网络模式 (解决IPv6问题)

  1. 打开Portainer界面

  2. 进入"Containers" > "Add Container"

  3. 填写以下信息:

    • Name: sun-panel-helper

    • Image: madrays/sun-panel-helper:latest

    • Network: Host

    • 不需要设置端口映射

    • Environment variables:

      • BACKEND_PORT=3001

      • FRONTEND_PORT=33002

    • Volumes:

      • host: /path/to/sunpanel/conf/custom

      • container: /app/backend/custom

      • host: /path/to/helper/data

      • container: /app/backend/data

      • host: /path/to/helper/backups

      • container: /app/backend/backups

  4. 点击"Deploy the container"完成部署

群晖Docker部署

标准模式

  1. 打开Docker套件

  2. 下载镜像madrays/sun-panel-helper:latest

  3. 创建容器时配置:

    • 端口设置: 33002:80

    • 环境变量: BACKEND_PORT=3001

    • 卷: 选择Sun-Panel的custom目录映射到/app/backend/custom

    • 卷: 选择Helper的数据目录映射到/app/backend/data

    • 卷: 选择Helper的备份目录映射到/app/backend/backups

  4. 应用设置并启动容器

Host网络模式 (解决IPv6问题)

  1. 打开Docker套件

  2. 下载镜像madrays/sun-panel-helper:latest

  3. 创建容器时配置:

    • 高级设置 > 网络 > 使用与Docker Host相同的网络

    • 环境变量:

      • BACKEND_PORT=3001

      • FRONTEND_PORT=33002

    • 卷: 选择Sun-Panel的custom目录映射到/app/backend/custom

    • 卷: 选择Helper的数据目录映射到/app/backend/data

    • 卷: 选择Helper的备份目录映射到/app/backend/backups

  4. 应用设置并启动容器

Sun-Panel + Helper 一键部署（以飞牛OS为例）

标准模式

version: "3.2"
services:
  # Sun-Panel 服务
  sun-panel:
    image: "hslr/sun-panel:latest"
    container_name: sun-panel
    volumes:
      - /vol1/@appshare/sunpanel/conf:/app/conf
      - /var/run/docker.sock:/var/run/docker.sock # 挂载docker.sock
      - /vol1:/os # 硬盘挂载点（根据自己需求修改）
    ports:
      - 3002:3002
    restart: always

  # Sun-Panel-Helper 服务
  sun-panel-helper:
    image: madrays/sun-panel-helper:latest
    container_name: sun-panel-helper
    environment:
      - BACKEND_PORT=3001  # 后端服务端口,可自定义修改避免冲突
    ports:
      - "33002:80"        # 前端页面访问端口
    volumes:
      - /vol1/@appshare/sunpanel/conf/custom:/app/backend/custom  # Sun-Panel的custom目录
      - /vol1/@appshare/helper/data:/app/backend/data
      - /vol1/@appshare/helper/backups:/app/backend/backups
    restart: always

Host网络模式 (解决IPv6问题)

version: "3.2"
services:
  # Sun-Panel 服务
  sun-panel:
    image: "hslr/sun-panel:latest"
    container_name: sun-panel
    volumes:
      - /vol1/@appshare/sunpanel/conf:/app/conf
      - /var/run/docker.sock:/var/run/docker.sock # 挂载docker.sock
      - /vol1:/os # 硬盘挂载点（根据自己需求修改）
    ports:
      - 3002:3002
    restart: always

  # Sun-Panel-Helper 服务 (Host网络模式)
  sun-panel-helper:
    image: madrays/sun-panel-helper:latest
    container_name: sun-panel-helper
    network_mode: host
    environment:
      - BACKEND_PORT=3001  # 后端服务端口
      - FRONTEND_PORT=33002  # 前端页面访问端口
    volumes:
      - /vol1/@appshare/sunpanel/conf/custom:/app/backend/custom  # Sun-Panel的custom目录
      - /vol1/@appshare/helper/data:/app/backend/data
      - /vol1/@appshare/helper/backups:/app/backend/backups
    restart: always

启动命令：

docker-compose up -d

注意事项：

  • 端口说明:

    • Sun-Panel默认端口3002可修改

    • Helper前端默认端口33002:

      • 标准模式: 通过映射到容器内部80端口实现

      • Host模式: 通过FRONTEND_PORT环境变量设置

    • Helper后端默认端口3001可通过环境变量修改

    • 所有端口请避免冲突

  • IPv6支持:

    • 如需管理IPv6下载器，建议使用Host网络模式

    • Host模式需要明确设置FRONTEND_PORT环境变量

    • 使用Host模式后，不需要设置端口映射

  • 首次启动可能需要拉取镜像，请耐心等待

  • Helper的数据目录必须正确挂载到Sun-Panel的custom目录

  • 路径说明:

    • 飞牛OS默认路径: /vol1/@appshare/sunpanel/conf/custom

    • 其他环境请根据实际情况调整

  • 建议先启动Sun-Panel,确认运行正常后再部署Helper

  • 端口冲突解决方案:

    • Sun-Panel端口: 修改compose中的3002:3002

    • Helper前端端口: 修改compose中的33002:80或设置FRONTEND_PORT

    • Helper后端端口: 修改环境变量BACKEND_PORT

📝 初始登录信息

Sun-Panel 登录信息

账号：admin@sun.cc
密码：12345678

Sun-Panel-Helper 登录信息

账号：helper
密码：helper123

🔧注意事项：

  • 端口说明:

    • Sun-Panel默认端口3002可修改

    • Helper前端默认端口33002:

      • 标准模式: 通过映射到容器内部80端口实现

      • Host模式: 通过FRONTEND_PORT环境变量设置

    • Helper后端默认端口3001可通过环境变量修改

    • 所有端口请避免冲突

  • IPv6支持:

    • 如需管理IPv6下载器，建议使用Host网络模式

    • Host模式需要明确设置FRONTEND_PORT环境变量

    • 使用Host模式后，不需要设置端口映射

  • 首次启动可能需要拉取镜像，请耐心等待

  • Helper的数据目录必须正确挂载到Sun-Panel的custom目录

  • 路径说明:

    • 飞牛OS默认路径: /vol1/@appshare/sunpanel/conf/custom

    • 其他环境请根据实际情况调整

    • 如无custom目录,请自行创建

  • 建议先启动Sun-Panel,确认运行正常后再部署Helper

  • 端口冲突解决方案:

    • Sun-Panel端口: 修改compose中的3002:3002

    • Helper前端端口: 修改compose中的33002:80或设置FRONTEND_PORT

    • Helper后端端口: 修改环境变量BACKEND_PORT

🎨 效果展示

🏠 主页面

主界面

🎨 CSS 样式库

CSS 样式

⚡ JS 功能库

JS 功能

🛍️ 组件市场

组件市场

📌 固定组件

固定组件

🚀 自由组件

自由组件

🔧 实时预览与部署

实时预览调参部署

🔑 初始账号

  • 账号：helper

  • 密码：helper123

⚠️ 已知问题

1. 样式冲突

  • 部分组件样式存在冲突

  • 对于必然冲突的项目，已在详情页面中标注说明

  • 目前需要用户自行调整以达到最佳显示效果

2. 组件加载顺序

  • 已通过固定加载顺序解决组件间冲突问题

  • 如MaxKB浮窗和小鱼页脚等组件现可正常共存

  • 状态：已修复 ✅

3. Markdown编辑器配置

  • 配置保存和部署功能已优化

  • 现可正常保存并即时生效

  • 状态：已修复 ✅

4. 天气组件安全性 🔧

  • 组件功能已修复并可正常使用

  • API密钥泄露风险仍然存在

  • 建议：请谨慎在公网环境使用

  • 状态：安全性优化中

🎯 项目介绍

Sun Panel Helper 是一个专注于增强 Sun-Panel 功能的辅助工具。我们致力于为您的 Sun-Panel 带来更多精彩的功能和更好的使用体验。

作为一个热爱折腾的 AI 爱好者，我希望通过这个项目展示 AI 辅助开发的无限可能。本项目由 Sun-Panel 作者红烧猎人技术指导，全程使用 AI 辅助开发。如果你也对 AI 开发或 Sun-Panel 美化感兴趣，欢迎加入交流群一起探讨！

赞赏码.png