宝贝回家（Baobei）插件使用文档

作者：kuakeba.cn · 版本：1.0.0 · 适用：Zsens Admin 3.0（PHP 8.2+ / ThinkPHP 8）

一、插件简介

「宝贝回家」是一款纯公益向插件。启用后，插件将接管站点的默认 404 页面，并接入宝贝回家公益寻亲数据接口，在 404 页面随机展示走失儿童的寻亲信息（姓名、性别、照片、出生日期、走失时间、走失地点、体貌特征）。

每一个走错门的访客，都会多看一眼正在等待回家的孩子。让站点的每一次 404 都成为一次公益曝光，帮助走失儿童早日回家。

核心特性：

• 启用即接管默认 404 页面，无需修改任何模板或核心代码（基于路由 Route::miss 机制，仅在全部路由未命中时触发，不影响正常路由与后台功能）
• 接入宝贝回家公益寻亲数据接口，随机推送走失儿童寻亲信息
• 本地信息池缓存：随机轮换展示、减轻接口压力，且每次 404 刷新内容不同
• 接口异常 / 未配置时自动降级为普通 404 提示页，不影响站点可用性
• 后台提供一键连通性测试，快速验证接口与 Token 配置
• 精心设计的暖色公益风格页面，响应式布局，移动端自适应；照片加载失败自动显示占位剪影
• 页面输出 noindex 并保留 HTTP 404 状态码，不影响站点 SEO

二、安装与卸载

1. 进入后台「应用中心 → 插件」，找到「宝贝回家」点击安装；
2. 安装完成后在插件列表点击「配置」进行设置（见下文）；
3. 开启「启用插件」开关后，站点 404 页面即刻生效，可访问任意不存在的路径（如 https://你的域名/not-exist）查看效果；
4. 卸载插件后自动恢复站点默认 404 行为，无任何残留数据（本插件不建表）。

三、配置项说明

四、免费 Token 获取步骤（默认接口）

1. 访问起零数据开放平台：https://api.istero.com，注册开发者账号；
2. 进入「开发者中心」创建应用，获取应用 Token；
3. 将 Token 填入本插件「接口 Token」配置项并保存；
4. 点击「测试连接」，提示「连通性测试通过」即配置成功。

「宝贝回家公益服务」为免费公益接口，无限次调用，不消耗平台每日额度包次数。

五、工作原理与降级策略

• 接管机制：插件启用后通过框架路由 Route::miss 注册兜底路由，所有未命中站点路由的请求（即原本返回默认 404 的请求）改由本插件渲染；HTTP 状态码仍为 404，不影响搜索引擎对站点死链的识别。
• 数据获取：本地维护一个最多 24 条的寻亲信息池（带缓存过期时间）。渲染 404 时从池中随机抽取展示；池内数量不足时实时向接口补抓（单次页面渲染最多尝试 4 次请求，超时 5 秒）。
• 降级策略：接口故障、未配置或返回异常时，页面自动降级为普通 404 提示（保留返回首页与宝贝回家官网入口），保证站点可用性不受影响。
• 隐私与合规：页面信息全部来源于宝贝回家官方公益接口，页面显著标注信息来源与官方渠道链接，方便热心人士通过官方渠道提供线索。

六、常见问题

Q：启用后访问不存在的路径仍显示默认 404？

A：请确认插件已「启用插件」开关开启；若刚安装，刷新页面或清空框架缓存后重试。

Q：404 页面显示「寻亲信息加载失败或暂无可展示数据」？

A：多为接口 Token 未填写或网络受限所致，可在后台「连通性测试」排查；即使数据不可用，页面仍会正常降级展示。

Q：照片显示不出来？

A：照片直链来自宝贝回家官网，个别服务器或浏览器策略下可能被防盗链拦截，此时自动显示占位剪影，不影响其他信息展示。

Q：可以自定义展示样式吗？

A：404 页为自包含 HTML（无外部 CSS 依赖），可在 plugins/Baobei/controller/NotFound.php 中按需调整样式；升级插件时请注意备份修改。

七、更新日志

1.0.0（2026-10-20）

• 首个版本：404 页面接管、宝贝回家公益寻亲数据随机展示、信息池缓存、接口异常降级、后台连通性测试。

由 kuakeba.cn 为 Zsens Admin 开发 · 数据来源：宝贝回家寻子网（宝贝回家志愿者协会）