TinyImgUploader 2.0.0:Typecho 1.3 图片上传插件(对接 TinyImg 图床)
在撰写文章 / 页面的右侧栏增加图片上传窗口,选图后上传到自建 TinyImg
图床,并把 Markdown 链接插入编辑器光标处。
主要功能
1. 侧栏卡片 + 弹窗上传
- 挂在 admin/write-post.php 与 write-page.php 的 option 钩子
- 支持点选、拖入、Ctrl+V 粘贴,上传前可预览
- 用 getSelection / replaceSelection 插入光标处并触发 input 事件,
草稿自动保存与实时预览都能同步
2. 三种图床鉴权方式
- token(默认):X-TinyImg-Token 请求头,未配置则明确拒绝
- admin:模拟图床后台登录 Cookie(无需改图床,但凭证等价于后台密码)
- guest:游客上传,图片进 temp/ 并受每日配额限制
- token / admin 两种模式强制服务端代理,凭证绝不下发浏览器
3. 「测试连接」按钮
- 读取输入框当前值,无需先保存
- 经博客同源 Action(带 CSRF)调用图床 functions/upload.php?ping=1
- 返回图床版本、鉴权方式与管理员目录,并比对是否落在 upload/
4. 为什么必须走服务端代理
- 实测图床 upload.php 不返回 Access-Control-Allow-Origin,
浏览器从博客后台直接 POST 会被同源策略拦截
5. 服务端校验
- 登录态 + 用户组(可选「仅管理员」) + CSRF 令牌
- 上传大小上限、getimagesize 真实图片头校验(拦 SVG / 伪装脚本)
- 未认出管理员身份时返回 warn,前端不自动关闭弹窗
6. 附带工具与测试
- tools/probe.php:命令行连通性自检(只读探测 / 真实上传 / 目录判定)
- tools/cookie.php:本地计算图床管理员 Cookie 值,不联网
- tests/:六组共 207 项,含故意错误实现的反证
版本:2.0.0
This commit is contained in:
@@ -1,3 +1,167 @@
|
||||
# TinyImgUploader
|
||||
# TinyImgUploader 2.0.0 — Typecho 1.3 图床上传插件
|
||||
|
||||
TinyImgUploader typecho 1.3
|
||||
在 Typecho 撰写文章 / 页面右侧「选项」栏增加一个图片上传窗口:点击按钮 → 弹窗选图并预览 → 确认上传 → 图片上传到自建 **TinyImg 2.0** 图床 → Markdown 自动插入编辑框光标处。
|
||||
插件设置页里可以填 API Token,并有 **「测试连接」按钮** 一键验证图床是否认这个 Token。
|
||||
|
||||
---
|
||||
|
||||
## 1. 本次变更
|
||||
|
||||
| # | 变更 |
|
||||
|---|---|
|
||||
| 1 | 插件目录、命名空间、Action 名统一改为 `TinyImgUploader` / `tinyimg-uploader` |
|
||||
| 2 | 请求头改为 `X-TinyImg-Token`,配合图床 2.0 的后台 Token 设置页 |
|
||||
| 3 | 设置页 Token 字段新增「测试连接」按钮,读取输入框当前值(**无需先保存**),返回图床版本与管理员目录 |
|
||||
| 4 | 图床 `?ping=1` 自检端点由插件的服务端 Action 调用,不受跨域限制、不把凭证下发给浏览器 |
|
||||
| 5 | 默认值改为占位地址 `https://img.example.com/functions/upload.php`,侧栏会在未修改时给出红色提示 |
|
||||
| 6 | 去掉旧的图床补丁包(`patch/` 目录):Token 现在是图床原生功能 |
|
||||
| 7 | 管理员 Cookie 回退方案的盐同步改为 `tinyimg`;新增 `tests/host_test.php`、`tests/setting_test.php` 等六组测试 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 从 v1.2 升级(需要重装一次,请先看这节)
|
||||
|
||||
插件目录名变了,Typecho 靠目录名识别插件,**不能只覆盖文件**。
|
||||
|
||||
> ⚠️ **禁用插件会清空它的设置**。请先把旧设置页里的接口地址、插入模板等抄下来。
|
||||
|
||||
1. 打开 Typecho 后台 → 控制台 → 插件 → **禁用 v1.2 旧插件**(记录现有设置)。
|
||||
2. 删除服务器上 `usr/plugins/` 里 v1.2 的旧插件目录(就是之前上传的那个目录)。
|
||||
3. 把 `TinyImgUploader.zip` 解压到 `usr/plugins/`,确认 `usr/plugins/TinyImgUploader/Plugin.php` 存在。
|
||||
4. 后台启用 **TinyImgUploader**,进入「设置」。
|
||||
5. 填写「图床上传接口地址」与「图床 API Token」(Token 在图床后台「Token 设置」页生成)。
|
||||
6. 点 **「测试连接」**,看到 `✓ 连接成功,Token 有效 · TinyImg v2.0.0(20261104) · 管理员目录 upload` 即完成。
|
||||
7. 保存设置,打开撰写文章页试传一张小图。
|
||||
|
||||
如果图床还没升级到 2.0,本插件无法直接使用:请先按 `../TinyImg/README.md` 部署图床。
|
||||
|
||||
---
|
||||
|
||||
## 3. 全新安装
|
||||
|
||||
1. 解压 `TinyImgUploader.zip` 到 `usr/plugins/`。
|
||||
2. 后台 → 控制台 → 插件 → 启用 **TinyImgUploader**。
|
||||
3. 设置里填接口地址 + Token,点「测试连接」验证,保存。
|
||||
|
||||
环境要求:Typecho 1.3、PHP ≥ 7.0;服务端代理模式需要 `curl` 扩展(没有时自动退回 `file_get_contents` 手工 multipart),并确认 `upload_max_filesize` / `post_max_size` ≥ 2M。
|
||||
|
||||
---
|
||||
|
||||
## 4. 配置项
|
||||
|
||||
| 配置项 | 默认值 | 说明 |
|
||||
|---|---|---|
|
||||
| **图床上传接口地址** | `https://img.example.com/functions/upload.php` | **占位值,必须改成你的实际地址**。`TinyImg 2.0` 是 `/functions/upload.php` |
|
||||
| **上传到图床的鉴权方式** | `API Token` | 可选 `API Token` / `管理员 Cookie`(回退)/ `游客上传` |
|
||||
| **图床 API Token** | 空 | 与图床后台「Token 设置」页一致;下方有 **「测试连接」按钮** |
|
||||
| 图床管理员账号 | 空 | 仅 Cookie 模式使用,对应图床 `config.php` 的 `user` |
|
||||
| 图床管理员密码 / 登录 Cookie 值 | 空 | 仅 Cookie 模式使用;推荐填 `tools/cookie.php` 生成的 32 位值 |
|
||||
| 管理员上传目录名 | `upload` | 上传后据此判断身份是否真的生效;留空跳过判断 |
|
||||
| 允许使用该插件的博客用户组 | 贡献者及以上 | 也可设为「仅博客管理员可用」 |
|
||||
| 文件表单字段名 | `file` | TinyImg 2.0 用 `file` |
|
||||
| 上传方式 | 服务端代理 | 图床未返回 CORS 头,默认必须走代理;Token / Cookie 模式**强制**代理 |
|
||||
| 单张图片上限(MB) | `2` | 图床源码硬编码 2 MB |
|
||||
| 插入 Markdown 模板 | `` | 占位符 `%url%` / `%alt%` / `%name%`;想与极简上传页一致填 `` |
|
||||
| 附加表单字段 / 附加请求头 | 空 | 每行 `key=value` / `Key: Value` |
|
||||
|
||||
---
|
||||
|
||||
## 5. 「测试连接」按钮怎么工作
|
||||
|
||||
按钮在 **插件设置页** 的 Token 输入框下方,不在撰写页。
|
||||
|
||||
```
|
||||
设置页点击「测试连接」
|
||||
│ 读取 input[name=token] 当前值(不必先保存设置)
|
||||
▼
|
||||
POST 博客同源 /action/tinyimg-uploader?do=test&_=<CSRF>
|
||||
│ 服务端校验:登录 + 用户组 + Typecho 安全令牌
|
||||
▼
|
||||
PHP curl 转发 POST 到 图床 /functions/upload.php?ping=1
|
||||
│ 请求头 X-TinyImg-Token: <Token>
|
||||
▼
|
||||
图床只校验 Token,不接收文件、不写库
|
||||
│ 返回 {code:1, name, version, admin_dir}
|
||||
▼
|
||||
博客 Action 比对管理员目录、附加 warn,返回 JSON
|
||||
▼
|
||||
按钮旁显示 ✓/✗、图床版本、管理员目录
|
||||
```
|
||||
|
||||
要点:
|
||||
|
||||
- Token 只出现在「设置页输入框 → 博客服务端 → 图床请求头」这条链路里,**撰写文章页源码里没有任何图床地址或 Token**。
|
||||
- 测试不上传图片、不产生数据;可以直接测试刚粘贴但还没保存的新 Token。
|
||||
- 若图床返回的 `admin_dir` 与插件设置不一致,或当前鉴权方式不是 `token`,会给出橙色警告。
|
||||
- 图床侧未升级到 2.0(不支持 `?ping=1`)时会明确提示「请确认已升级到 TinyImg 2.0」。
|
||||
|
||||
---
|
||||
|
||||
## 6. 使用流程
|
||||
|
||||
1. 撰写文章 / 页面 → 右侧「选项」栏出现「图床上传」卡片,点「选择图片上传」。
|
||||
2. 弹窗里点选、拖入,或 Ctrl+V 粘贴图片 → 预览 → 点「确认上传」。
|
||||
3. 上传成功后自动把 Markdown 插入 `#text` 光标处,并触发 `input` / `change` 让草稿自动保存与预览刷新;弹窗自动关闭。
|
||||
4. 若身份没生效(例如 Token 被停用但仍以游客身份成功),弹窗**不会关闭**并显示橙色警告。
|
||||
|
||||
---
|
||||
|
||||
## 7. 排错
|
||||
|
||||
| 现象 | 原因 | 处理 |
|
||||
|---|---|---|
|
||||
| 侧栏红字「接口地址仍是占位值」 | 没改 `apiUrl` | 设置里填实际 `https://你的域名/functions/upload.php` |
|
||||
| 测试连接返回「请先在上方填入 API Token」 | Token 输入框为空且未保存过 | 从图床后台「Token 设置」复制 Token 粘进来 |
|
||||
| 测试连接返回「API Token 无效!」 | 两处 Token 不一致 / 图床已停用 | 图床后台确认状态,重新生成并同步 |
|
||||
| 测试连接返回「图床返回的不是 JSON」 | 图床不是 2.0 / 地址填错 / CSRF 过期 | 确认地址指向 `functions/upload.php`;刷新设置页重试 |
|
||||
| 测试连接返回「安全校验失败」 | Typecho 安全令牌过期 | 刷新插件设置页再点 |
|
||||
| 上传成功但提示「没按 Token 识别身份」 | 返回 URL 不含 `/upload/` | 检查「管理员上传目录名」是否与图床 `admindir` 一致 |
|
||||
| 真实上传报错「API Token 未配置」 | 图床还没生成 / 启用 Token | 到图床后台「Token 设置」生成 |
|
||||
| 升级后后台登录被踢出 | 图床 Cookie 盐改为 `tinyimg` | 到 `admin/login.php` 重新登录一次 |
|
||||
| v1.2 插件突然不能上传 | 请求头已改名 | 按第 2 节升级插件 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 验证命令
|
||||
|
||||
```bash
|
||||
cd TinyImgUploader
|
||||
|
||||
# 纯逻辑测试,不需要 Typecho、不需要联网
|
||||
php tests/util_test.php # 响应解析 + ?ping=1 地址推导
|
||||
php tests/auth_test.php # Cookie 回退方案契约
|
||||
php tests/token_test.php # 图床 Token 纯函数 + 上传端点契约 + 错误实现反证
|
||||
php tests/render_test.php # 侧栏、弹窗、测试按钮渲染与凭证隔离
|
||||
php tests/host_test.php # 图床更名 / 版本 / SM.MS 下线 / 设置页
|
||||
php tests/setting_test.php # 图床 Token 设置页渲染:完整 Token 不得出现在 HTML、reveal 必须校验 CSRF
|
||||
|
||||
# 命令行连通性自检(需要 PHP 的 curl 或 openssl 扩展)
|
||||
php tools/probe.php --url=https://你的域名/functions/upload.php --token=你的Token --ping
|
||||
php tools/probe.php --url=https://你的域名/functions/upload.php --token=你的Token --file=./test.png
|
||||
```
|
||||
|
||||
`tools/cookie.php` 仅在回退到「管理员 Cookie」模式时才需要:
|
||||
|
||||
```bash
|
||||
php tools/cookie.php 管理员账号 '明文密码'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 安全说明
|
||||
|
||||
1. Token 只被图床上传端点与自检端点识别,泄露也只能上传图片,**不能进图床后台**。
|
||||
2. 插件侧校验登录态、用户组与 Typecho CSRF 令牌;Token / Cookie 模式下强制服务端代理。
|
||||
3. 上传前用 `getimagesize()` 校验真实图片头,挡住 SVG / 伪装脚本;大小与类型双重限制。
|
||||
4. 图床比较用 `hash_equals`,空配置 / 停用 / 空请求一律 fail closed。
|
||||
5. 请全程使用 HTTPS;Token 不要提交到公开仓库、不要放进 URL。
|
||||
6. 轮换 Token 后,图床后台与插件设置都要更新,并用「测试连接」复核。
|
||||
|
||||
---
|
||||
|
||||
## 10. 已知限制
|
||||
|
||||
- 图床硬限 2 MB;本插件默认上限也是 2 MB。
|
||||
- 直接改 `textarea` 的 `value` 不会被 PageDown 的撤销栈记录(插入后 Ctrl+Z 可能不还原)。
|
||||
- 若博客与图床证书 / 协议不匹配(HTTPS 页面请求 HTTP 图床),服务端代理不受浏览器混合内容限制,但仍建议全 HTTPS。
|
||||
- 本机 PHP 若缺 `curl` / `openssl`,`tools/probe.php` 的联网部分需在博客服务器上运行。
|
||||
|
||||
Reference in New Issue
Block a user