目录结构说明

从 v2.0.5 版本开始，Sun-Panel-Helper 引入了新的目录结构，以提供更好的数据持久化和备份功能。本文将详细介绍新的目录结构和挂载要求。

必要挂载目录

/app/backend/data

必须挂载

这是Helper存储用户核心数据的目录，必须挂载，否则每次重启或升级容器会丢失配置！这个目录是Helper自己的目录，需要您自己创建，不是Sun-Panel的目录。

• 用途：存储用户配置、偏好设置等基本数据
• 数据类型：JSON 配置文件，用户设置等
• 重要性：必须挂载，核心数据存储位置
• 创建方式：需要用户自行创建此目录，它属于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

目录结构变更图示

以下是 v2.0.5 版本前后的目录结构对比：

【v2.0.4及之前版本】             【v2.0.5及之后版本】
/app/backend/                   /app/backend/
  └── custom/ (必须挂载)           ├── data/ (必须挂载) ⭐新增⭐
                                 ├── backups/ (必须挂载) ⭐新增⭐
                                 └── custom/ (必须挂载)

重要说明

• /app/backend/data - 新增目录，是Helper自己的目录，需要您自己创建
• /app/backend/backups - 新增目录，是Helper自己的目录，需要您自己创建
• /app/backend/custom - 必须指向Sun-Panel的custom目录，不是Helper自己的目录

数据说明

/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 系统配置

注意

不建议挂载非文档明确指定的目录，可能会导致容器运行异常。