Bubble Emby Admin

Appearance

首页模板 ​

首页模板用于替换访客访问网站根路径 / 时看到的默认页面。管理员可以上传符合系统规范的 ZIP 模板包，在不修改后台和用户中心的情况下自定义公开首页。

后台入口：配置中心 -> 外观 -> 首页模板

启用模板后：

  • / 显示当前启用的首页模板
  • /login 继续作为用户登录入口
  • /admin/login 继续作为管理员登录入口
  • 用户中心、管理员后台和现有 API 路由不受模板影响

获取官方案例模板 ​

Bubble Emby System Template 是官方提供的 React、TypeScript 与 Vite 首页模板开发案例。可以直接从该仓库的 Releases 下载已经构建好的 ZIP，也可以按仓库 README 自行修改和重新构建。

在系统后台上传的是 Release 中的模板 ZIP，不是 GitHub 自动生成的 Source code 压缩包，也不是包含 src、node_modules 或构建脚本的源码目录。

安装模板 ​

  1. 点击 选择 ZIP 模板包 并上传文件。
  2. 系统先检查模板清单、目录结构、文件类型、资源引用和体积限制，不会立即安装。
  3. 检查通过后，核对模板名称、版本、作者、说明、文件数量和解压大小。
  4. 确认来源可信后点击 安装模板。
  5. 安装完成的模板会进入模板库，但不会立即替换当前首页。

待安装文件会在关闭确认窗口时删除；未继续操作的待安装文件也会在 30 分钟后自动失效。

预览、启用与恢复默认首页 ​

模板库中的每个模板都可以单独操作：

  • 预览：打开带时效签名的预览地址，不影响当前公开首页
  • 启用：把该模板设为当前首页；同一时间只能启用一个模板
  • 恢复默认首页：停用当前模板并恢复系统内置首页
  • 删除：永久删除模板记录和解压文件；当前正在使用的模板必须先停用才能删除

安装与启用是两个独立步骤。安装模板不会自动替换访客首页，必须在核对预览结果后手动点击 启用。

安全提示 ​

首页模板包含可以在访客浏览器中执行的 HTML、CSS 和 JavaScript。系统会检查路径穿越、隐藏文件、符号链接、文件类型、危险资源引用和体积限制，并通过浏览器隔离策略限制外部脚本、接口请求、表单和内嵌页面。

这些检查不能判断模板中的文字、图片、链接或交互是否具有误导性。第三方模板仍可能伪装成登录页或诱导用户访问外部地址，因此：

  • 只安装来源明确且可以审查源码的模板
  • 上传前确认模板作者和下载地址可信
  • 第三方模板建议先使用页面中的 复制 AI 审查提示词 做只读安全审查
  • 不要在模板源码或模板包中保存密码、Token、API Key 或其他后台凭据

模板包基本要求 ​

ZIP 根目录必须直接包含：

text
index.html
bubble-template.json

不要在 ZIP 外再包一层项目文件夹。主要限制包括：

  • ZIP 最大 50 MB
  • 解压后最大 200 MB
  • ZIP 中的文件与目录合计最多 2,000 项
  • 单个普通文件最大 50 MB
  • 单个 HTML 文件最大 3 MB
  • bubble-template.json 最大 16 KiB
  • 禁止隐藏文件、符号链接、服务端脚本、可执行文件、数据库、密钥文件、Source Map 和嵌套压缩包

bubble-template.json 示例：

json
{
  "formatVersion": 1,
  "name": "My Homepage",
  "version": "1.0.0",
  "author": {
    "name": "Template Author",
    "url": "https://example.com"
  },
  "description": "自定义首页模板"
}

本地 CSS、JavaScript、图片、字体和视频需要使用模板包内的相对资源。外部图片和字体可以使用无账号信息的 HTTPS 地址；不要加载外部 JavaScript、外部样式表或远程 CSS @import。

自定义开发 ​

模板页面可以使用 React、Vue、原生 HTML 或其他前端技术开发，只要最终 ZIP 符合系统规则即可。使用 Vite 等构建工具时，需要正确保留系统静态资源占位符：

text
{{BUBBLE_ASSET_BASE}}

系统在预览和正式访问时会把该占位符替换成当前模板真实的资源基础地址。不要把构建产物硬编码为 /assets/... 根路径，否则模板安装后可能无法加载资源。

完整开发、打包和禁止文件规范请参考官方案例仓库的 README。

存储、反向代理与备份 ​

模板文件存放在容器内的 /app/data/uploads/homepage。Docker Compose 默认将宿主机的 ./docker-data/data 挂载到 /app/data；升级和迁移时必须同时备份数据库与该目录。

上传模板需要反向代理允许略高于 50 MB 的请求体。Nginx 配置示例、多实例限制和存储说明请查看 安装指南的首页模板章节，升级备份步骤请查看 升级指南。

Bubble Emby Admin