Docker 部署

本文详细介绍如何使用 Docker 部署 Sun-Panel-Helper。

重要提示 - v2.0.5+ 版本目录变更

从 v2.0.5 版本开始，Sun-Panel-Helper 引入了新的目录结构，必须挂载 /app/backend/data、/app/backend/backups 和 /app/backend/custom 目录。其中 data 和 backups 目录是 Helper 自己的数据目录，需要您自己创建；而 custom 目录必须指向 Sun-Panel 的 custom 目录。如果您是从旧版本升级，请参考数据迁移教程。

部署方式选择

Sun-Panel-Helper 支持两种 Docker 部署模式：

1. 标准模式

   • 最常用的部署方式
   • 使用端口映射访问服务
   • 适合大多数使用场景

2. 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 目录下创建。

常见路径

• 标准路径：/path/to/sunpanel/conf/（仅针对custom目录！）
• 飞牛OS：/vol1/@appshare/sunpanel/conf/（仅针对custom目录！）
• 飞牛OS商店版请使用固定路径：/var/apps/Sun-Panel/var/web/custom（仅针对custom目录！）
• Helper的data和backups目录建议放在易于管理的位置，例如：/docker/sunpanel-helper/data和/docker/sunpanel-helper/backups

权限要求

• 确保目录存在
• 具有读写权限
• 正确的所有者和权限设置

容器管理

查看容器状态

docker ps -a | grep sun-panel-helper

查看容器日志

docker logs sun-panel-helper

重启容器

docker restart sun-panel-helper

停止容器

docker stop sun-panel-helper

删除容器

docker rm sun-panel-helper

常见问题

1. 端口被占用

# 查看端口占用
netstat -tunlp | grep 33002
# 或
lsof -i :33002

# 更换端口
-p 33003:80  # 标准模式
-e FRONTEND_PORT=33003  # Host模式

2. 目录权限问题

# 修改目录权限（这里的目录路径应该是您实际创建的路径）
chmod -R 755 /your/helper/path/data
chmod -R 755 /your/helper/path/backups
chmod -R 755 /path/to/sunpanel/conf/custom

3. Helper 功能不生效

检查 custom 目录是否正确挂载到 Sun-Panel 的 custom 目录。确保：

• custom 目录路径正确指向 Sun-Panel 的 conf/custom 目录
• Sun-Panel 可以访问此目录（权限正确）
• 如果 Sun-Panel 的 custom 目录不存在，需要手动创建

4. 数据迁移问题

如果您是从 v2.0.4 或更早版本升级，请参考数据迁移教程。

下一步

• 参考常见问题
• 了解备份与恢复功能
• 查看目录结构说明