Contribuv/ Typecho-fnos-oss
Typecho的轻对象存储,服务端运行在飞牛nas,服务端项目在 fnos-oss
项目文档
文档更新于 5 小时前fnos-oss — Typecho 对象存储插件
把 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 下载(推荐)
- 打开 Releases 页面。
- 下载最新版本的
FnosOss-1.1.0.zip。 - 解压后得到
FnosOss目录,把整个目录放入 Typecho 的usr/plugins/。 - 登录 Typecho 后台,进入「控制台 → 插件」,启用「fnos-oss」。
- 点击「设置」,填写 Endpoint、存储桶、Access Key、Secret Key 并保存。
- 点击「保存设置」旁边的「测试连接」,全部 ✓ 后即可上传附件。
从源码安装
- 克隆仓库或下载源码压缩包。
- 把文件放入
usr/plugins/FnosOss/,目录名必须是FnosOss。 - 后续步骤同上。
fnos-oss 侧准备
- 在飞牛应用中心安装「轻量对象存储」,记下安装时设置的 S3 TCP 端口(默认
9100)。 - 打开 fnos-oss 管理端,在「访问密钥」页面创建或查看密钥,得到 Access Key 与 Secret Key。
- 新建一个存储桶,例如
typecho。 - 如果使用直链模式,在桶的设置里把策略改为
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 里的文件逐个复制到对象存储:
- 先保存配置并完成「测试连接」。
- 展开「历史附件迁移」,点击「开始迁移」。
- 迁移按每批 10 个文件进行,本地文件不动,失败的可以修复后重试。
- 已存在的对象会跳过,重复点击不会重复上传。
迁移只做两件事:上传对象、写入 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
还没有评论,来抢沙发吧~
验证码将发送到