xnx_maintenance 站点维护

功能

• 品牌化站点维护页面，维护期间返回 503 状态码 + Retry-After 头，利于搜索引擎

• 维护生效条件：插件开关 enabled=1，或系统 runlevel=0（两者任一即生效）

• 白名单放行：gid=1,2 管理员永远放行；自定义用户组白名单（gid_whitelist）；IP 精确匹配白名单（ip_whitelist）

• 恢复时间倒计时（recover_at，前台 JS 实时倒计时）

• 主题模式（dark/light）、主题色、自定义 CSS、联系邮箱

• API 拦截开关（block_api，开启后接口请求也返回维护页面）

• 双拦截入口：model_check_runlevel_start.php（最早，系统 runlevel 检查时）+ index_inc_route_before.php（路由分发前）

• 模板降级输出：模板文件缺失时输出最小化 HTML，避免白屏

文件结构

plugin/xnx_maintenance/
├── conf.json
├── install.php / uninstall.php
├── setting.php + setting.htm
├── model/MaintenanceService.php
├── hook/
│   ├── model_inc_file.php
│   ├── model_check_runlevel_start.php
│   ├── index_inc_route_before.php
│   └── lang_zh_cn_bbs.php
├── view/htm/maintenance.htm
├── static/
│   ├── css/maintenance.css
│   └── js/maintenance.js
└── lang/
    ├── zh-cn.php
    ├── zh-tw.php
    └── en-us.php

配置流程

1. 后台启用插件

2. 进入「插件设置」→ 填写维护标题/描述/原因、设置恢复时间、配置 IP/用户组白名单、选择主题模式与主题色

3. 按需开启「拦截 API」

4. 测试：开启维护开关 → 普通用户访问前台看到维护页（503）→ 白名单内用户/IP 正常访问后台与前台 → 关闭开关恢复