Files
TinyImgUploader/README.md
T
terry 8ac51d3160 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
2026-11-05 17:33:44 +08:00

168 lines
9.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# TinyImgUploader 2.0.0 — 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 模板 | `![%alt%](%url%)` | 占位符 `%url%` / `%alt%` / `%name%`;想与极简上传页一致填 `![](%url%)` |
| 附加表单字段 / 附加请求头 | 空 | 每行 `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` 的联网部分需在博客服务器上运行。