Files
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

9.2 KiB
Raw Permalink Blame History

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. 验证命令

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」模式时才需要:

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 的联网部分需在博客服务器上运行。