YuImg 是我为 WordPress 开发的一套综合性个人资源管理主题。它不是简单的图库插件，而是一个集图片管理、独立文件库、文章发布与资源分享于一体的完整解决方案。

项目缘起

在日常工作中，我经常需要在不同场景下管理各类数字资源：摄影照片需要按项目分组归档，设计文档和电子书需要安全存储，技术分享又需要将图片、文件和文字组织成完整的文章。WordPress 原生媒体库对这些场景的支持非常有限——它把所有文件混在一起，没有独立的分组体系，也没有对外分享的权限控制；因此设计了此项目。

核心能力

1. 图片库 — 树形分组与 WebP 自动优化

YuImg 使用独立的数据库表管理图片分组，支持无限层级树形结构。每张图片上传后自动生成 thumb（320px）、small（640px）、medium（1280px）、large（1920px）和 origin（2560px）五级 WebP 规格，在保证画质的同时大幅减小文件体积。

图片支持公开/私有和过期时间控制。公开图片通过 /img/{id}/{size}/ 路由访问，私有图片需要 access_key 授权——原图直链不会出现在任何页面源码中。

2. 独立文件库 — 安全的非公开存储

文件库与图片库完全解耦，使用独立的数据库分组表。文件默认存储在站点公开根目录之外，通过扩展名与 Fileinfo MIME 双重白名单验证后写入私有目录。Office 文档和 EPUB 还会进行 ZIP 容器结构校验，防止改扩展名绕过检查。

访问时通过 /file/{id}/ 流式输出，支持 Range 断点续传和下载统计，CSS/JS 等文本文件以不可执行的方式响应，从协议层面杜绝了上传脚本文件的风险。

3. 主题分享 — 富文本 + 图片画廊 + 视频 + 交互地图

分享是 YuImg 最复杂的模块。它基于自定义文章类型 yuimg_share 构建，在 /shares/edit/ 提供四栏编辑器：

• 左侧：分类筛选
• 中间偏左：已有文章列表
• 中间偏右：富文本正文编辑器
• 右侧：页面设置（slug、分类、访问范围、过期时间、地图轨迹）

编辑器支持插入单图、2–9 张组图和轮播图，视频链接覆盖 YouTube、Bilibili、腾讯视频和优酷（白名单校验，拒绝任意 iframe 注入）。

地图轨迹是分享的亮点功能：导入 GPX/KML/GeoJSON 文件或在浏览器中手工绘制路径，添加最多 50 个带文字和图片的位置标注，服务端规范化为 WGS84 GeoJSON（最多保留 3,000 个轨迹点）。公开页使用本地 Leaflet 渲染交互地图，按需加载，无地图的页面零开销。

公开分享访问 /share/{id|slug}/，私有分享需 6–64 位密码验证，成功后签发 12 小时签名 Cookie。

4. 自动目录系统

文章和分享详情页会自动提取正文中的标题（文章为 H2–H5，分享为 H2/H3），生成稳定去重锚点。至少存在两个标题时，桌面端在正文左侧显示 sticky 吸附目录，当前章节随滚动高亮；移动端切换为正文上方折叠目录。这一切都是服务端渲染，无需前端框架。

5. 统一公开目录 /public/

所有主动公开的图库、文章和分享集中在 /public/ 页面，支持 ?type=galleries|articles|shares 分类筛选和独立分页。这是面向访客的统一入口——无需登录即可浏览所有公开内容。

6. 外部站点资源服务

YuImg 可以作为中心资源服务器，为其他 WordPress 站点提供图片和文件服务。每个接入站点分配独立的客户端 ID 和 AES-256-GCM 密钥，通过 HMAC 签名和时间戳防重放。资源签名覆盖 ID、规格、下载模式和过期时间，修改资源后旧 URL 自动失效。

7. 安全防护体系

分级请求保护覆盖所有敏感路径：登录凭据、邮件验证码、邀请码、私有分享密码按操作独立计数，敏感失败默认 5 次/30 分钟触发 72 小时封禁。高置信度探测（.env 扫描、SQL 注入、目录穿越等）立即阻断。可信代理 IP 白名单确保 X-Forwarded-For 不会被访客伪造。

8. 用户注册与两步登录

YuImg 从前台到后台都绕开了 WordPress 原生界面，构建了独立且完整的认证流程：

前台注册（/register/）支持两种模式——开放注册和邀请码注册，由管理员在 /settings/ 中切换。邀请码可以批量生成，每个码设置独立的使用上限和 UTC 有效期，适合小范围邀请或团队使用。注册流程强制邮箱验证：填写邮箱 → 收取验证码 → 设置密码，全程无需进入 WordPress 原生页面。

两步登录（前台弹窗）方案：

• 第一步：账号 + 密码 + 图形验证码（按需触发）
• 第二步：邮件验证码 + 重发倒计时
• 信任设备：勾选”记住此设备”后，服务端签发随机 Cookie 令牌并记录哈希，当天免二次验证；双重校验杜绝 Cookie 伪造

如果站点尚未配置 SMTP（MAIL_* 常量），登录弹窗自动降级为账号密码 + 图形验证码，不会把管理员锁在门外。SMTP 配置齐全后，邮件二次验证自动启用。

WP-Admin 访问控制：非管理员用户统一重定向到首页，仅精确放行 admin-ajax.php（前台 AJAX 交互必需）。WordPress Admin Bar 仅管理员访问 /wp-admin/ 时才展示，普通用户和前台页面完全不加载。

安全计数：登录凭据、邮件验证码、邀请码和私有分享密码按操作独立计数，并额外共用凭据攻击累计阈值。普通图形验证码错误只记录和限流，不会像敏感操作那样直接触发 72 小时封禁。

技术架构

命名空间职责：