Docker Compose 部署

本文介绍如何使用 Docker Compose 部署 Sun-Panel-Helper。Docker Compose 提供了更便捷的部署和管理方式，特别适合需要管理多个容器的场景。

重要提示 - 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 目录。如果您是从旧版本升级，请参考数据迁移教程。

准备工作

1. 安装 Docker Compose

如果尚未安装 Docker Compose，请先安装：

# Linux
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# 验证安装
docker-compose --version

Windows 和 macOS 的 Docker Desktop 已经包含了 Docker Compose。

2. 创建部署目录

mkdir -p ~/docker/sun-panel-helper
cd ~/docker/sun-panel-helper
# 创建Helper所需的数据目录（这些是Helper自己的目录，不是Sun-Panel的目录）
mkdir -p data backups

重要

custom 目录必须指向 Sun-Panel 的 custom 目录，而不是创建新目录！ 上面的示例仅创建了Helper自己需要的data和backups目录。

部署配置

标准模式配置

创建 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

数据迁移

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

常见问题

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 目录不存在，需要手动创建

5. 备份管理

查看备份与恢复了解如何管理备份和恢复数据。

下一步

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