Sun-Panel-Helper
为 Sun-Panel 设计的可视化美化工具
让你的 Sun-Panel 锦上添花
主要特性
中转服务
连接 Sun-Panel 前端与 Helper 后端
自动同步配置文件
实时更新无需重启
支持多实例部署
可视化配置
所见即所得的编辑体验
实时预览修改效果
参数持久化存储
一键应用到面板
扩展支持
CSS 样式扩展
JS 功能增强
组件动态加载
配置自动同步
便捷部署
Docker 一键部署
自动挂载配置
支持反向代理
完整的部署文档
在线体验
我们提供了完整的演示环境，让你在部署前可以充分体验：
Sun-Panel-Helper Demo
http://demo.cocoyoo.cn
功能：
体验完整的样式编辑功能
预览各种美化效果
测试部署流程
Sun-Panel 演示站
http://home.cocoyoo.cn
特点：
展示实际应用效果
体验优化后的界面
感受流畅的交互体验
系统要求
硬件要求
CPU: 1 核心以上
内存: 512MB 以上
硬盘空间: 100MB 以上
软件要求
Docker 19.03 或更高版本
Sun-Panel 已安装并正常运行
支持的操作系统：
Linux (推荐)
Windows
macOS
前置条件
1. Docker 环境
确保 Docker 已正确安装并运行：
# 检查 Docker 版本 docker -v # 检查 Docker 服务状态 systemctl status docker # Linux docker info # Windows/macOS
2. Sun-Panel 配置
Sun-Panel 已正常运行
可以访问 Sun-Panel 的配置目录
确认 custom 目录位置：
# 常见位置示例 /path/to/sunpanel/conf/custom # 标准路径 /vol1/@appshare/sunpanel/conf/custom # 飞牛OS /var/apps/Sun-Panel/var/web/custom #飞牛OS应用商店版固定为此路径
3. 网络要求
确保以下端口可用：
33002: Helper 前端访问端口（可自定义）
3001: Helper 后端服务端口（可自定义）
如果使用反向代理，需要：
支持 WebSocket
正确配置 SSL（如果使用 HTTPS）
4. 权限要求
Docker 运行权限
Sun-Panel custom 目录的读写权限
端口绑定权限（如果不使用 root 用户）
配置检查清单
在开始部署前，请检查以下项目：
Docker 正常运行
Sun-Panel 可以正常访问
已确认 custom 目录位置
所需端口未被占用
具备必要的文件权限
网络连接正常
特殊场景准备
IPv6 环境
如果需要在 IPv6 环境下使用：
确保 Docker 支持 IPv6
准备使用 Host 网络模式
检查 IPv6 连接性
反向代理
如果计划使用反向代理：
准备好域名（可选）
配置好 SSL 证书（如果使用 HTTPS）
确认代理服务器支持 WebSocket
部署方式选择
Sun-Panel-Helper 支持两种 Docker 部署模式：
标准模式
最常用的部署方式
使用端口映射访问服务
适合大多数使用场景
Host 网络模式
直接使用主机网络
支持 IPv6 环境
适合特殊网络需求
标准模式部署
1. 拉取镜像
docker pull madrays/sun-panel-helper:latest
2. 创建容器
docker run -d \\ --name sun-panel-helper \\ -p 33002:80 \\ -e BACKEND_PORT=3001 \\ # 这是您自己创建的Helper数据目录，不是Sun-Panel的目录！ -v /your/helper/path/data:/app/backend/data \\ # 这是您自己创建的Helper备份目录，不是Sun-Panel的目录！ -v /your/helper/path/backups:/app/backend/backups \\ # 注意：这个目录必须指向Sun-Panel的custom目录，Helper通过它来控制美化Sun-Panel -v /path/to/sunpanel/conf/custom:/app/backend/custom \\ madrays/sun-panel-helper:latest
参数说明
--name sun-panel-helper: 容器名称
-p 33002:80: 前端端口映射
-e BACKEND_PORT=3001: 后端服务端口
-v /your/helper/path/data:/app/backend/data: Helper的数据目录，必须挂载，用于保存Helper的配置数据
-v /your/helper/path/backups:/app/backend/backups: Helper的备份目录，必须挂载，用于保存自动和手动备份
-v /path/to/sunpanel/conf/custom:/app/backend/custom: 必须挂载，必须指向 Sun-Panel 的 custom 目录
Host 网络模式部署
1. 拉取镜像
docker pull madrays/sun-panel-helper:latest
2. 创建容器
docker run -d \\ --name sun-panel-helper \\ --network host \\ -e BACKEND_PORT=3001 \\ -e FRONTEND_PORT=33002 \\ # 这是您自己创建的Helper数据目录，不是Sun-Panel的目录！ -v /your/helper/path/data:/app/backend/data \\ # 这是您自己创建的Helper备份目录，不是Sun-Panel的目录！ -v /your/helper/path/backups:/app/backend/backups \\ # 注意：这个目录必须指向Sun-Panel的custom目录，Helper通过它来控制美化Sun-Panel -v /path/to/sunpanel/conf/custom:/app/backend/custom \\ madrays/sun-panel-helper:latest
参数说明
--network host: 使用主机网络
-e FRONTEND_PORT=33002: 前端监听端口
-e BACKEND_PORT=3001: 后端服务端口
-v /your/helper/path/data:/app/backend/data: Helper的数据目录，必须挂载，用于保存Helper的配置数据
-v /your/helper/path/backups:/app/backend/backups: Helper的备份目录，必须挂载，用于保存自动和手动备份
-v /path/to/sunpanel/conf/custom:/app/backend/custom: 必须挂载，必须指向 Sun-Panel 的 custom 目录
端口配置
前端端口
标准模式：通过 -p 参数映射，如 -p 33002:80
Host 模式：通过环境变量设置，如 -e FRONTEND_PORT=33002
后端端口
通过环境变量设置：-e BACKEND_PORT=3001
默认值：3001
建议：除非端口冲突，否则保持默认值
目录挂载
必要目录
必须挂载
以下目录必须挂载，否则会导致数据丢失、备份功能无法使用或 Helper 功能无法生效！
# 数据目录 - 存储Helper的用户配置和设置（您需要在本地创建此目录） -v /your/helper/path/data:/app/backend/data # 备份目录 - 存储Helper的自动和手动备份（您需要在本地创建此目录） -v /your/helper/path/backups:/app/backend/backups # Sun-Panel 的 custom 目录 - Helper 功能生效的关键 -v /path/to/sunpanel/conf/custom:/app/backend/custom
custom 目录特别说明 /app/backend/custom 必须挂载到 Sun-Panel 的 custom 目录，这是 Helper 与 Sun-Panel 交互的关键。 如果此目录挂载错误，Helper 的所有修改都不会在 Sun-Panel 中生效！ 如果 Sun-Panel 的 custom 目录不存在，需要手动在 Sun-Panel 的 conf 目录下创建。
部署配置
标准模式配置
创建 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: - ./data:/app/backend/data # 必须挂载：Helper的数据目录 - ./backups:/app/backend/backups # 必须挂载：Helper的备份目录 - /path/to/sunpanel/conf/custom:/app/backend/custom # 必须挂载：Sun-Panel的custom目录 restart: unless-stopped
注意
上述配置中，/path/to/sunpanel/conf/custom 必须替换为您的 Sun-Panel 实际 custom 目录的绝对路径！ 而 ./data 和 ./backups 是相对路径，指向您为Helper创建的数据目录。
Host 网络模式配置
如果需要使用 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: - ./data:/app/backend/data # 必须挂载：Helper的数据目录 - ./backups:/app/backend/backups # 必须挂载：Helper的备份目录 - /path/to/sunpanel/conf/custom:/app/backend/custom # 必须挂载：Sun-Panel的custom目录 restart: unless-stopped
目录挂载说明
必须挂载的目录
必须挂载
以下目录必须挂载，否则会导致数据丢失、备份功能无法使用或 Helper 功能无法生效！
./data:/app/backend/data - Helper的数据目录，用于存储用户配置和设置
./backups:/app/backend/backups - Helper的备份目录，用于存储自动和手动备份
/path/to/sunpanel/conf/custom:/app/backend/custom - 必须指向 Sun-Panel 的 custom 目录
custom 目录特别说明
/app/backend/custom 必须挂载到 Sun-Panel 的 custom 目录，这是 Helper 与 Sun-Panel 交互的关键。 如果此目录挂载错误，Helper 的所有修改都不会在 Sun-Panel 中生效！
如果 Sun-Panel 的 custom 目录不存在，需要手动在 Sun-Panel 的 conf 目录下创建。
而 data 和 backups 目录是 Helper 自己的数据目录，需要您自己创建，不是 Sun-Panel 的目录。
部署命令
启动服务
# 在 docker-compose.yml 所在目录执行 docker-compose up -d
查看日志
# 查看所有日志 docker-compose logs # 查看实时日志 docker-compose logs -f # 查看最近 100 行日志 docker-compose logs --tail=100
停止服务
docker-compose down
重启服务
docker-compose restart
更新镜像
# 拉取最新镜像 docker-compose pull # 使用新镜像重新创建容器 docker-compose up -d
常见问题
1. 配置文件权限
确保 docker-compose.yml 的权限正确：
chmod 644 docker-compose.yml
2. 目录权限
确保挂载目录的权限正确：
# Helper自己的数据目录 chmod -R 755 data chmod -R 755 backups # Sun-Panel的custom目录 chmod -R 755 /path/to/sunpanel/conf/custom # 确保Sun-Panel的custom目录权限正确
3. 端口冲突
如果端口被占用，修改 docker-compose.yml 中的端口映射：
ports: - "33003:80" # 将 33002 改为其他可用端口
4. Helper 功能不生效
检查 custom 目录是否正确挂载到 Sun-Panel 的 custom 目录。确保：
custom 目录路径正确指向 Sun-Panel 的 conf/custom 目录
Sun-Panel 可以访问此目录（权限正确）
如果 Sun-Panel 的 custom 目录不存在，需要手动创建
目录结构说明
从 v2.0.5 版本开始，Sun-Panel-Helper 引入了新的目录结构，以提供更好的数据持久化和备份功能。本文将详细介绍新的目录结构和挂载要求。
必要挂载目录
/app/backend/data
必须挂载
这是Helper存储用户核心数据的目录，必须挂载，否则每次重启或升级容器会丢失配置！这个目录是Helper自己的目录，需要您自己创建，不是Sun-Panel的目录。
/app/backend/backups
必须挂载
这是Helper存储备份文件的目录，必须挂载，否则无法保留历史备份！这个目录是Helper自己的目录，需要您自己创建，不是Sun-Panel的目录。
用途：存储自动和手动备份文件
数据类型：ZIP 格式备份文件
重要性：必须挂载，确保数据安全
创建方式：需要用户自行创建此目录，它属于Helper，不是Sun-Panel的目录
/app/backend/custom
必须挂载
这是 Sun-Panel 的 custom 目录，必须正确挂载，否则 Helper 的所有修改都无法生效！这个目录必须指向Sun-Panel的custom目录，不是Helper自己的目录。
用途：与 Sun-Panel 交互的关键目录，所有自定义组件和美化功能都通过此目录实现
数据类型：自定义组件配置、JS、CSS 等
重要性：必须挂载，这是 Helper 功能生效的基础，必须指向 Sun-Panel 的 custom 目录
注意事项：必须指向 Sun-Panel 的 conf 目录下的 custom 文件夹，如：/path/to/sunpanel/conf/custom
数据说明
/app/backend/data 目录
此目录包含以下重要数据：
用户配置文件
应用程序设置
组件配置和布局信息
其他核心运行数据
提示
这是Helper自己的数据目录，需要用户自行创建。这不是Sun-Panel的目录。
/app/backend/backups 目录
此目录存储两类备份：
自动备份：系统每小时自动创建，最多保留 100 个
手动备份：用户手动创建，永久保存不会被自动清理
提示
这是Helper自己的备份目录，需要用户自行创建。这不是Sun-Panel的目录。
/app/backend/custom 目录
特别重要
这个目录必须指向 Sun-Panel 的 custom 目录！Helper 的所有功能都依赖于此目录与 Sun-Panel 的正确交互。这不是Helper自己的目录，而是必须指向Sun-Panel的目录。
此目录用于：
存储 Helper 生成的自定义组件代码
应用美化样式和功能
实现 Sun-Panel 与 Helper 的交互
部署所有自定义配置到 Sun-Panel
如果此目录指向错误，Helper 的所有修改都不会在 Sun-Panel 中生效。
容器内其他目录（不需要挂载）
容器内还有一些其他目录，这些目录通常不需要挂载：
/app/frontend：前端代码目录
/app/nginx：Nginx 配置目录
/etc/nginx：Nginx 系统配置
注意
不建议挂载非文档明确指定的目录，可能会导致容器运行异常。