Contribuv/ Typecho-fnos-oss

Typecho的轻对象存储,服务端运行在飞牛nas,服务端项目在 fnos-oss

PHP 100.0%

项目文档

文档更新于 5 小时前

fnos-oss — Typecho 对象存储插件

Release Downloads Stars Typecho PHP

把 Typecho 的附件复制到部署在飞牛 fnOS 上的轻量对象存储 fnos-oss,同时保留本地副本。 支持公开直链与私有桶预签名两种访问方式,停用插件后自动回到本地地址。

  • 插件仓库:https://github.com/Contribuv/Typecho-fnos-oss
  • 作者:豪子 · https://www.infowe.site/projects/11
  • 适用版本:Typecho 1.3.x
  • 运行环境:PHP 7.4+,需要 curl 扩展
  • 当前版本:1.1.0

特性

  • 上传附件时先落本地 usr/uploads,再复制一份到对象存储,本地永远有回退副本
  • 历史附件一键迁移:只复制,不删除本地文件,不修改任何内容数据库
  • 停用插件后钩子失效,Typecho 自动使用本地 URL,不会裂图
  • 直链 / 预签名 / 代理三种访问方式,可随时切换
  • 删除、替换附件;已迁移的文件会同步更新对象
  • 支持大于 64 MB 的分段上传
  • 自动创建存储桶
  • 配置页内置「测试连接」与迁移进度
  • 不依赖 Composer 或 AWS SDK,纯 PHP 实现 SigV4

目录结构

usr/plugins/FnosOss/
├── Plugin.php      插件元数据、激活、配置表单、上传钩子
├── S3Client.php    SigV4、path-style、PUT/GET/HEAD/DELETE、预签名、分段上传
├── Settings.php    配置读取与校验
├── Store.php       上传 / 迁移 / 替换 / 删除 / URL
├── Map.php         本地路径 ↔ 对象键映射(migrated.json)
├── About.php       配置页顶部的插件信息卡片
├── probe.php       连通性自检入口
├── migrate.php     历史附件迁移入口
├── proxy.php       私有桶附件代理(支持 Range)
├── logo.png        插件图标
└── README.md

运行后会生成 migrated.json(迁移映射)与可选的 debug.log,这两个文件不随插件包发布。

安装

从 Release 下载(推荐)

  1. 打开 Releases 页面。
  2. 下载最新版本的 FnosOss-1.1.0.zip。
  3. 解压后得到 FnosOss 目录,把整个目录放入 Typecho 的 usr/plugins/。
  4. 登录 Typecho 后台,进入「控制台 → 插件」,启用「fnos-oss」。
  5. 点击「设置」,填写 Endpoint、存储桶、Access Key、Secret Key 并保存。
  6. 点击「保存设置」旁边的「测试连接」,全部 ✓ 后即可上传附件。

从源码安装

  1. 克隆仓库或下载源码压缩包。
  2. 把文件放入 usr/plugins/FnosOss/,目录名必须是 FnosOss。
  3. 后续步骤同上。

fnos-oss 侧准备

  1. 在飞牛应用中心安装「轻量对象存储」,记下安装时设置的 S3 TCP 端口(默认 9100)。
  2. 打开 fnos-oss 管理端,在「访问密钥」页面创建或查看密钥,得到 Access Key 与 Secret Key。
  3. 新建一个存储桶,例如 typecho。
  4. 如果使用直链模式,在桶的设置里把策略改为 public-read。

fnos-oss 默认监听 0.0.0.0:9100,插件在服务器端通过内网地址访问即可。 Endpoint 填 http://内网IP:9100,不要带 /app/fnos-oss 路径。

配置说明

配置项 说明
Endpoint S3 地址,例如 http://192.168.1.10:9100
公网 Endpoint 可选。直链与预签名使用的浏览器访问地址,例如 https://s3.example.com;留空则使用 Endpoint
存储桶 对象写入的桶名
Region 默认 us-east-1,需与 fnos-oss 的 oss.json 一致
Access Key / Secret Key 在 fnos-oss 管理端创建
对象前缀 默认 typecho,对象键形如 typecho/uploads/2026/11/xxxxxxxx.png
访问方式 直链 / 预签名 / 代理,见下文
预签名有效期 仅预签名模式生效,60–604800 秒(7 天),默认 86400
请求超时 单个 S3 请求的超时,默认 300 秒
自动创建存储桶 上传前检查桶是否存在,不存在则创建
HTTPS 证书校验 使用自签证书的反向代理时选「不校验」
调试日志 写入插件目录的 debug.log,排查问题时开启

本地副本始终保留,没有关闭选项;这是「停用插件后 URL 仍然正确」的前提。

三种访问方式

直链(推荐)

附件 URL 为 公网 Endpoint/桶名/对象键,例如:

https://s3.example.com/typecho/typecho/uploads/2026/11/1a2b3c4d.png
  • 需要把桶策略设为 public-read
  • URL 永久有效,适合图片站,不消耗 PHP 流量
  • 含私密附件的站点不建议使用

预签名

附件 URL 带 X-Amz-Signature 等参数,在有效期内可访问,适合私有桶。

  • 不需要公开桶
  • 链接会在有效期后失效,适合短期分享,不适合长期引用的正文图片

代理

附件 URL 指向本站的 usr/plugins/FnosOss/proxy.php,由插件从私有桶读取并转发。

  • 链接稳定,建议长期使用私有桶时选择
  • 支持 Range,视频拖动、大图分段加载正常
  • 附件流量会经过 PHP,附件多、流量大时注意服务器负载

切换访问方式后,新生成的 URL 会立即变化;URL 是按附件路径实时计算的,不需要回写数据库。

迁移历史附件

配置页顶部的「历史附件迁移」面板会把 usr/uploads 里的文件逐个复制到对象存储:

  1. 先保存配置并完成「测试连接」。
  2. 展开「历史附件迁移」,点击「开始迁移」。
  3. 迁移按每批 10 个文件进行,本地文件不动,失败的可以修复后重试。
  4. 已存在的对象会跳过,重复点击不会重复上传。

迁移只做两件事:上传对象、写入 migrated.json 映射。不会修改文章、附件或任何内容表。

迁移完成后,前台附件 URL 会自动指向对象存储;停用插件后映射不再读取,URL 回到本地路径。

迁移前不要修改「对象前缀」。对象键由 前缀 + /uploads/ + 本地相对路径 组成,前缀变化会让已有映射指向错误的对象。

使用与回退

  • 附件记录里的路径始终是站内相对路径,例如 /usr/uploads/2026/11/a.png。
  • 已迁移的路径在 attachmentHandle 渲染时转换为 OSS URL;未迁移的继续用本地 URL。
  • 停用插件后钩子移除,Typecho 默认拼接本地 URL,本地文件仍在,页面不会裂图。
  • 删除附件会同时删除本地文件与已迁移的对象,并移除映射。
  • 替换附件会覆盖本地文件;已迁移的会同时覆盖同键对象。
  • 从 1.0.0 升级上来的 oss:// 旧记录仍然兼容,但它们没有本地副本,停用插件后无法回退。
  • 迁移不会删除本地文件;确认不再需要回退后,可以手动清理 usr/uploads 释放空间。

常见问题

测试连接提示 403

  • 检查 Access Key / Secret Key 是否复制完整
  • fnos-oss 会校验 X-Amz-Date,请确认服务器时间准确(误差不超过 15 分钟)
  • 如果密钥被限制到指定桶,需要换一个无限制的密钥

直链返回 403

桶策略不是 public-read。在 fnos-oss 管理端修改桶策略,或改用预签名 / 代理模式。

图片能上传但前台不显示

  • 检查「公网 Endpoint」是否是浏览器能访问的地址
  • 内网地址只适合内网访问;外网访问需要端口映射或反向代理
  • 使用反向代理时,代理必须保留原始 Host,否则预签名 URL 会签名不匹配
  • 预签名模式下链接过期也会导致图片失效

上传大文件失败

  • 确认 PHP 的 upload_max_filesize、post_max_size 足够大
  • 确认「请求超时」不低于文件上传所需时间
  • 超过 64 MB 的文件会自动分段上传,单段 16 MB

迁移中断或失败

  • 已上传的文件已经写入映射,重新点击「开始迁移」会跳过它们
  • 失败文件会在面板底部列出,修复权限或网络后重试即可
  • 迁移过程中不要修改对象前缀或切换存储桶

停用插件后附件会怎样

不会裂图。插件只负责把本地路径转换成 OSS URL,停用后 Typecho 回到默认的本地地址,文件仍在 usr/uploads。

卸载会不会删除对象

不会。卸载插件不会清理桶里的数据;需要删除时请在 fnos-oss 管理端操作。

数据与安全

  • Secret Key 按 Typecho 插件惯例保存在 options 表中,数据库备份会包含它
  • migrated.json 只记录站内路径与对象键,不包含密钥
  • 调试日志只记录请求方法、URL 与状态码,不记录密钥和签名
  • 建议为 Typecho 单独创建密钥,只授予需要的桶
  • 公开桶意味着任何知道 URL 的人都能读取对象,请勿存放敏感附件
  • 备份 fnos-oss 数据时请先停止服务,再整体复制数据目录

开发说明

插件通过 Typecho 的 Widget\Upload 钩子接管附件存储:

钩子 实现
uploadHandle 保存本地并复制到 OSS,返回本地路径
modifyHandle 覆盖本地文件,已迁移的同步覆盖对象
deleteHandle 删除本地文件与对象,移除映射
attachmentHandle 已迁移的生成 OSS URL,其余返回本地 URL
attachmentDataHandle 本地优先读取,必要时回源 OSS

S3Client 仅实现插件需要的子集:path-style 寻址、SigV4 头签名、预签名 URL、 单文件 PUT、分段上传、GET / HEAD / DELETE、建桶,方便审计和二次开发。

更新日志

1.1.0(最新)

  • 新增历史附件迁移:只复制,不删除本地文件,不修改内容数据库
  • 上传改为「本地 + OSS」双写,附件记录始终保存站内路径
  • 停用插件后自动回到本地 URL,不会再出现 oss:// 死链
  • 配置页新增迁移面板:进度条、失败列表、已迁移统计
  • 删除 / 替换附件时同步处理对象与映射
  • 对象键统一为 前缀/uploads/年/月/文件名,与本地路径一一对应
  • 移除「失败回退本地」开关,本地副本改为始终保留
历史版本

1.0.0

  • 首个版本:附件上传、直链 / 预签名 / 代理、删除与替换、失败回退本地、 自动建桶、连通性自检、调试日志

许可

插件代码可自由修改与分发;fnos-oss 本体遵循其仓库的许可协议。

评论 0

还没有评论,来抢沙发吧~

写下你的想法… 写评论 收起评论框
0 / 2000