模板开发文档
本项目支持 前台模板 与 后台模板 两套独立系统，可在后台「模板管理」或「站点设置 → 模板」中分别切换。
前台模板不仅可以修改首页，还可以覆盖 所有面向访客的公开页面（登录、注册、找回密码、重置密码、邮箱验证）以及 用户中心的外壳。
后台模板控制后台整体布局（侧栏、顶栏、菜单），两套模板互不影响。
一、目录结构
BLOCK0
- 目录名只能包含
[a-zA-Z0-9_-] - 所有文件均为可选：哪个缺失，就回退到
default的对应文件；default也缺，则使用内置渲染
二、前台模板
2.1 template.json
BLOCK1
| 字段 | 必需 | 说明 |
|---|---|---|
name |
否 | 后台展示名，缺省为目录名 |
author |
否 | 作者名 |
version |
否 | 版本号 |
description |
否 | 简介 |
preview |
否 | 预览图，相对模板根目录 |
pages |
否 | 支持的页面，缺省 ["index"] |
2.2 支持的页面与变量
| 页面 | 文件 | 变量 |
|---|---|---|
| 首页 | index.php |
$siteName $homeHtml $stats $user $csrf $announcements $baseUrl $favicon |
| 登录 | login.php |
$siteName $user $csrf $baseUrl $favicon $pageTitle |
| 注册 | register.php |
$siteName $user $csrf $baseUrl $favicon $defaultPoints $registerEnabled $inviteEnabled $inviteFromUrl $pageTitle |
| 找回密码 | forgot.php |
$siteName $user $csrf $baseUrl $favicon $pageTitle |
| 重置密码 | reset.php |
$siteName $user $csrf $baseUrl $favicon $token $pageTitle |
| 邮箱验证 | verify.php |
$siteName $user $csrf $baseUrl $favicon $result $pageTitle |
| 用户中心外壳 | layouts/user.php |
见下方说明 |
变量说明：
| 变量 | 类型 | 说明 | |
|---|---|---|---|
$siteName |
string | 站点名称 | |
$homeHtml |
string | 首页自定义内容（含 HTML，可安全输出） | |
$stats |
array | users / subdomains / domains / verified |
|
$user |
array\ | null | 当前登录用户 |
$csrf |
string | CSRF Token | |
$announcements |
array | 公告列表（content 含 HTML，可安全输出） |
|
$baseUrl |
string | 站点根 URL，如 https://example.com |
|
$favicon |
string | 后台配置的 Favicon URL，可能为空 | |
$pageTitle |
string | 页面标题（可选） | |
$defaultPoints |
int | 注册赠送积分 | |
$registerEnabled |
bool | 是否允许注册 | |
$inviteEnabled |
bool | 是否开启邀请码 | |
$inviteFromUrl |
string | URL 参数 ?invite= 的值 | |
$token |
string | 重置密码链接的 token | |
$result |
array | ['ok' => bool, 'msg' => string]，邮箱验证结果 |
2.3 用户中心外壳
layouts/user.php 需要定义两个函数，供 user/includes/layout.php 调用：
BLOCK2
$active 是当前页的 key，可能的值：
| key | 说明 | 显示条件 |
|---|---|---|
dashboard |
概览 | 总是 |
apply |
申请解析 | 总是 |
my_subdomains |
我的解析 | 总是 |
checkin |
每日签到 | 后台开启签到 |
redeem |
兑换码 | 后台开启兑换码 |
invite |
邀请好友 | 后台开启邀请码 |
point_logs |
积分流水 | 总是 |
api |
API Token | 后台开启「用户 API 申请」 |
profile |
个人资料 | 总是 |
菜单项显示逻辑示例：
BLOCK3
2.4 必做的三件事
1. 引入公共资源
BLOCK4
common.css提供深/浅色主题、按钮、表格、弹窗等基础样式common.js提供window.$app工具集与toast()弹窗提示
2. 渲染公告与统计
公告的 content 字段已含 HTML，可直接输出。统计数字需给元素加 id stat-users / stat-subdomains / stat-domains / stat-verified 并引入 assets/js/home.js 才会自动刷新。
3. 在页面底部调用访客弹窗
BLOCK5
2.5 用户 API 申请
用户 API 页面由项目内置（user/pages/api.php），模板不需要实现，只需在 layouts/user.php 的侧栏中按条件显示菜单项即可（见 2.3 节）。
用户申请流程：
- 管理员在后台「站点设置 → API 与开放」中开启「允许用户自助申请 API Token」
- 可选开启「需要管理员审核」
- 用户在「用户中心 → API Token」中看到申请按钮
- 若需审核，申请进入后台「用户 → API 申请」列表，管理员批准或拒绝
- 批准后用户可看到 Token，支持复制与重新生成
模板只需要在侧栏渲染菜单：
BLOCK6
2.6 调用后台接口
BLOCK7
api()自动附加_csrf- 返回结构固定为
{ code, msg, data } toast()会弹出居中的模态提示
2.7 回退规则
| 场景 | 行为 |
|---|---|
| 模板目录缺失 | 回退 default |
template.json 损坏 |
该模板不显示在后台 |
| 该模板没有某页面文件 | 回退 default 的同名文件 |
default 也缺失 |
使用内置渲染（仅首页） |
layouts/user.php 缺失 |
使用 user/includes/layout.php 内置布局 |
| 所有页面都缺失 | 内置首页渲染 + 其他页面 500 |
三、后台模板
后台模板只需一个 layout.php，里面定义两个函数：
BLOCK8
3.1 template.json
BLOCK9
3.2 可用全局变量
admin_layout_header() 内部可用：
| 变量 | 说明 |
|---|---|
$siteName |
站点名称 |
$user |
当前管理员 |
$csrf |
CSRF Token |
$active |
当前激活的 page 名 |
Auth::isSuperAdmin() |
是否超管 |
Auth::hasAdminPerm($key) |
是否有某功能权限 |
3.3 菜单权限过滤
后台菜单默认会自动按当前用户权限过滤，模板作者可以使用：
BLOCK10
3.4 默认值注入
后台模板需要在 <head> 中注入以下全局变量，供页面脚本读取：
BLOCK11
window.__CSRF__—— 所有 API 请求需要window.__DEFAULT_LOG_REMARK—— 删除/封禁等操作时，弹窗会自动填入的默认理由
3.5 页面菜单 key
后台所有页面 key：
| key | 名称 | 所需权限 |
|---|---|---|
dashboard |
概览 | 总是显示 |
users |
用户管理 | users |
user_groups |
用户组 | user_groups |
api_requests |
API 申请 | users |
dns_interfaces |
DNS 接口 | dns_interfaces |
domains |
域名管理 | domains |
subdomains |
解析记录 | subdomains |
reserved_words |
保留词 | reserved_words |
redeem_codes |
兑换码 | redeem_codes |
announcements |
公告 | announcements |
home_editor |
首页编辑 | home_editor |
point_logs |
积分流水 | point_logs |
admin_logs |
操作日志 | admin_logs |
settings |
站点设置 | settings |
templates |
模板管理 | templates |
四、模板专用资源
模板自有 css / js / 图片放在 assets/ 子目录，通过 Template::asset() 引用：
BLOCK12
Template::asset() 会自动使用当前启用模板的目录名，回退时自动指向 default。
五、安全与规范
- 永远用
e()转义用户输入：e()函数已全局可用，等价htmlspecialchars(..., ENT_QUOTES, 'UTF-8')。 $homeHtml/$announcements[i]['content']已由后台过滤，可安全直接输出；其他字段必须转义。- 不要在模板里直接连数据库，通过
window.$app.api()或已有的DB::getInstance()走服务层。 - 不要输出敏感字段：
$user里包含password/api_token等，禁止直接print_r/var_dump。 - 文件命名：模板目录名只能是
[a-zA-Z0-9_-]+，不能包含斜杠或点。 - 不要修改 core：模板只依赖
Template::/Popup::/e()/Setting::/DB::等公开接口。 - 后台模板不要注入未经转义的 HTML，尤其是
$user['username']等来自数据库的字段。
六、示例最小模板
templates/minimal/template.json：
BLOCK13
templates/minimal/index.php：
BLOCK14
七、问题排查
- 模板没出现在后台列表：检查
template.json是否为合法 JSON。 - 首页样式错乱：确认已引入
assets/css/common.css，且顺序正确。 - 数字不刷新：确认元素 id 为
stat-users等，并引入了assets/js/home.js。 - 弹窗不显示：确认后台已开启弹窗、内容不为空，且模板调用了
Popup::render()。 - 用户中心布局错乱：检查
layouts/user.php是否正确闭合标签。 - 后台布局错乱：检查后台模板的
layout.php是否正确闭合标签。 - 用户 API 菜单不显示：确认后台「站点设置 → API 与开放」中已开启「允许用户自助申请 API Token」。
- 后台按钮点击无反应：确认后台模板注入了
window.__CSRF__和window.__DEFAULT_LOG_REMARK。