Sun-Panel-Helper

Appearance

数据迁移教程 ​

本文档详细介绍如何在 Sun-Panel-Helper 版本升级过程中正确迁移数据，特别是针对 v2.0.5 及以上版本引入的新目录结构变更。

重要提示

v2.0.5 版本调整了数据存储目录结构。所有未映射 data 目录的用户，如果需要保存现有配置，都需要进行数据迁移！

v2.0.5 新增了备份功能，只有已经在 v2.0.5 版本中创建了备份，并且想要保留这些备份的用户，才需要迁移 backups 目录数据！

目录结构变更说明 ​

在 v2.0.5 版本中:

  1. data 目录: 用户数据存储在 /app/backend/data 目录，这是Helper自己的目录，需要您自己创建，用于数据持久化
  2. backups 目录: v2.0.5 新增的备份功能目录，这是Helper自己的目录，需要您自己创建，只有在 v2.0.5 中已创建备份并希望保留的用户才需要迁移此目录
  3. custom 目录: 必须指向Sun-Panel的custom目录，Helper通过它控制美化Sun-Panel

从 v2.0.4 及更早版本迁移 ​

步骤 1：准备工作 ​

创建必要的本地数据目录：

bash
# 创建Helper的数据存储目录（这些是Helper自己的目录，不是Sun-Panel的目录）
mkdir -p /your/helper/path/data
mkdir -p /your/helper/path/backups

关于 custom 目录

custom 目录必须指向 Sun-Panel 的 custom 目录，而不是创建新目录！

如果 Sun-Panel 的 custom 目录不存在，需要在 Sun-Panel 的 conf 目录下手动创建：

bash
mkdir -p /path/to/sunpanel/conf/custom

确保目录权限正确：

bash
chmod -R 755 /your/helper/path/data
chmod -R 755 /your/helper/path/backups
chmod -R 755 /path/to/sunpanel/conf/custom

步骤 2：导出现有数据 ​

首先，获取当前运行的容器名称或 ID：

bash
docker ps | grep sun-panel-helper

然后，将容器中的数据复制到本地目录：

bash
# 复制核心数据 (v2.0.4 及之前的版本，数据存储在容器内的 /app/backend/data 目录)
docker cp your-container-name:/app/backend/data/. /your/helper/path/data/

# 如果之前没有挂载 custom 目录，需要复制到 Sun-Panel 的 custom 目录
docker cp your-container-name:/app/backend/custom/. /path/to/sunpanel/conf/custom/

说明

v2.0.5 之前的版本没有备份功能，因此不需要导出 backups 目录。

步骤 3：停止并移除旧容器 ​

安全停止并删除旧版容器：

bash
docker stop your-container-name
docker rm your-container-name

步骤 4：部署新版本 ​

使用新的目录结构部署 v2.0.5 或更高版本：

bash
# Docker 部署
docker pull madrays/sun-panel-helper:latest
docker run -d \
  --name sun-panel-helper \
  -p 33002:80 \
  -e BACKEND_PORT=3001 \
  # Helper自己的数据目录
  -v /your/helper/path/data:/app/backend/data \
  # Helper自己的备份目录
  -v /your/helper/path/backups:/app/backend/backups \
  # 必须指向Sun-Panel的custom目录
  -v /path/to/sunpanel/conf/custom:/app/backend/custom \
  madrays/sun-panel-helper:latest

注意

上述命令中，/path/to/sunpanel/conf/custom 必须替换为您的 Sun-Panel 实际 custom 目录的绝对路径！

Docker Compose 部署：

yaml
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:
      # Helper自己的数据目录
      - /your/helper/path/data:/app/backend/data
      # Helper自己的备份目录
      - /your/helper/path/backups:/app/backend/backups
      # 必须指向Sun-Panel的custom目录
      - /path/to/sunpanel/conf/custom:/app/backend/custom
    restart: unless-stopped

步骤 5：验证数据迁移 ​

启动新容器后：

  1. 访问 Web 界面，确认所有设置和配置已正确加载
  2. 检查各组件是否正常工作
  3. 验证自定义组件是否显示正常
  4. 测试创建手动备份功能是否正常

如果界面无法正常加载或数据丢失，请参考数据恢复部分。

已经使用 v2.0.5 但未配置目录映射的用户 ​

未映射 data 目录的情况 ​

如果您使用 v2.0.5 但未映射 data 目录，需要导出数据并重新配置：

bash
# 获取当前容器名称或ID
docker ps | grep sun-panel-helper

# 导出核心数据到本地Helper目录
docker cp your-container-name:/app/backend/data/. /your/helper/path/data/

已创建备份但未映射 backups 目录的情况 ​

如果您在 v2.0.5 中已创建备份，并且希望保留这些备份，需要导出备份目录：

bash
# 获取当前容器名称或ID
docker ps | grep sun-panel-helper

# 导出备份数据到本地Helper目录
docker cp your-container-name:/app/backend/backups/. /your/helper/path/backups/

完成数据导出后，重新部署容器并正确映射目录：

bash
# 停止并移除当前容器
docker stop your-container-name
docker rm your-container-name

# 使用正确的挂载配置重新部署
docker run -d \
  --name sun-panel-helper \
  -p 33002:80 \
  -e BACKEND_PORT=3001 \
  -v /your/helper/path/data:/app/backend/data \
  -v /your/helper/path/backups:/app/backend/backups \
  -v /path/to/sunpanel/conf/custom:/app/backend/custom \
  madrays/sun-panel-helper:latest

从 v2.0.5 迁移到更高版本 ​

如果您已经正确配置了 v2.0.5 版本的所有挂载目录，迁移到更高版本非常简单：

bash
# 拉取最新镜像
docker pull madrays/sun-panel-helper:latest

# 停止并移除旧容器
docker stop sun-panel-helper
docker rm sun-panel-helper

# 使用相同的挂载目录创建新容器
docker run -d \
  --name sun-panel-helper \
  -p 33002:80 \
  -e BACKEND_PORT=3001 \
  -v /your/helper/path/data:/app/backend/data \
  -v /your/helper/path/backups:/app/backend/backups \
  -v /path/to/sunpanel/conf/custom:/app/backend/custom \
  madrays/sun-panel-helper:latest

使用 Docker Compose：

bash
# 进入 docker-compose.yml 所在目录
docker-compose pull
docker-compose up -d

数据恢复 ​

如果在迁移过程中遇到问题，或者不慎丢失数据，可以尝试以下恢复方法：

使用备份恢复（仅适用于 v2.0.5+ 版本） ​

如果您之前使用 v2.0.5 版本并创建了备份：

  1. 进入 Web 界面的"备份管理"页面
  2. 选择一个可用的备份文件
  3. 点击"恢复"按钮
  4. 按照界面提示完成恢复过程

手动恢复 ​

如果没有可用的备份，但之前导出了容器数据：

  1. 停止当前容器
  2. 清空挂载目录中的 data 目录
  3. 将之前备份的数据复制回 data 目录
  4. 重新启动容器
bash
docker stop sun-panel-helper
rm -rf /your/helper/path/data/*
cp -r /your/backup/path/* /your/helper/path/data/
docker start sun-panel-helper

常见问题 ​

Q: 升级后无法访问界面或显示空白页面 ​

可能的解决方法：

  • 检查容器日志 docker logs sun-panel-helper
  • 确认所有必要挂载目录都已正确配置
  • 尝试清除浏览器缓存或使用隐身模式访问

Q: Helper 设置的美化和组件在 Sun-Panel 中不生效 ​

可能的原因和解决方法：

  • custom 目录未正确挂载到 Sun-Panel 的 custom 目录
  • 确认 /app/backend/custom 已正确挂载到 Sun-Panel 的 custom 目录
  • 检查 Sun-Panel 的 custom 目录权限是否正确
  • 确认 Sun-Panel 和 Helper 都能正常访问该目录

Q: TR 组件域名前缀设置不生效 ​

v2.0.6 版本已修复此问题。如果您使用的是 v2.0.5 版本，请升级到 v2.0.6。

Q: 如何确认数据已正确迁移？ ​

查看容器日志，确认没有数据相关的错误信息，并检查 Web 界面上的设置是否与之前一致。

Q: 备份文件太多，如何管理？ ​

  • 自动备份：系统会自动清理，最多保留 100 个
  • 手动备份：永久保存，需要手动删除不需要的备份

基于 MIT 许可发布

Copyright © 2024-present Madrays