本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：WWW/docs/缤纷云存储插件开发计划_2026-09-21.md。

缤纷云存储插件开发计划（bitiful_storage）

依据：《FlintHub 插件开发规范》（docs/插件开发规范.md，2026-09-20 版）

接入对象：缤纷云 Bitiful S4（S3 兼容对象存储）　计划日期：2026-09-21

目标形态：本地落盘不变 + 云端镜像 + 前台 URL 改写，公开桶读取免签名

一、结论先行

二、缤纷云接入事实（已核实）

⚠️ 「不支持服务端加密」+「公开桶」= 桶内所有对象可被任何人按 URL 读取。

因此绝不能把私密附件（私信附件、待审核内容、回收站帖子附件）推上公开桶 —— 这是本插件的第一条设计红线（见 §七.1）。

三、FlintHub 侧现状（决定方案的硬约束）

这些是已经核实过的事实，方案的每一步都被它们约束：

四、架构选型（核心决策）

4.1 先说冲突：规范说「插件禁止改核心」，但这个功能绕不过去

规范 §二 原文：「修改核心文件（app/、assets/css/admin.css 等）—— 插件样式/JS 必须收敛到插件自己的 assets/」。

但由 §三 第 7、8、10 条可知：核心既没有上传钩子，也没有 URL 生成钩子，Plugin::http() 还不能发 PUT。三条路都堵死，插件没有任何合法的接入点。

所以要先把这件事讲清楚，二选一：

• 选项 ①（推荐）：把这次改动定性为「核心扩展点演进」，不是「插件改核心」。

即：核心新增 4 个通用扩展点（上传事件 + URL 过滤 + HTTP 方法支持），插件只是第一个使用者。

这 4 个扩展点对后续任何存储/同步/水印类插件都有用，属于平台能力补齐，应当随核心发布。

• 选项 ②：坚持「零核心改动」，改用 §4.3 的方案 B（纯插件），接受它的 3 项代价。

4.2 三个候选架构

4.3 方案 C 的 4 处核心改动（逐处说明必要性）

全部是只加不改语义的最小侵入；每处都给出「不做会怎样」。

改动 1 — Upload::file() 末尾加 upload_after 钩子（约 6 行）

位置：app/Helpers/Upload.php 成功分支 return [...] 之前（:511 前）。

// ★ 新增：上传成功后事件（供云存储/水印/审核类插件挂载）
//   此时文件已落盘、缩略图已生成；参数与返回结构一一对应，插件无需再查库
\app\Helpers\Plugin::hook('upload_after', [
    'rel'      => $rel,                    // '2026-09/ab12cd.png'（相对 uploads 的路径）
    'filename' => $rel,
    'original' => $file['name'] ?? '',
    'size'     => (int)$file['size'],
    'type'     => $mime ?? '',
    'thumb'    => $thumbPrefix,            // 'thumb_' / 'md_' / ''（头像不生成）
    'context'  => (string)($opts['context'] ?? ''),  // 调用方标注：avatar/attachment/cover...
]);

不做会怎样：插件只能在 thread_create_after 等业务钩子里正则解析正文反推附件路径 —— 封面图、种子头像、无正文引用的附件、孤儿文件全部漏网，且要等正文保存完才入队。

改动 2 — Upload::url() 末尾加 upload_url 过滤钩子（约 5 行）

位置：app/Helpers/Upload.php:58 返回前。

$url = \rtrim(UPLOAD_URL, '/') . '/' . \ltrim(\str_replace('\\', '/', $rel), '/');

// ★ 新增：URL 过滤（引用传参，插件可改写为 CDN 地址；不改则行为与改造前完全一致）
$params = ['rel' => $rel, 'url' => $url];
\app\Helpers\Plugin::hook('upload_url', $params);
return (string)$params['url'];

不做会怎样：只能用整页 ob_start 改写（方案 B），每请求多一次全页缓冲 + 字符串替换，且必须逐路由判断 Content-Type 以免污染附件下载流与 htmx 片段。

改动 3 — Upload::thumbUrl() 末尾加 upload_thumb_url 过滤钩子（约 6 行）

位置：app/Helpers/Upload.php:343 返回前。参数带 prefix，插件据此映射档位。

$thumbRel = self::thumbPath($rel, $prefix);
$url = $thumbRel !== null ? self::url($thumbRel) : self::url($rel);

// ★ 新增：缩略图 URL 过滤（带档位 prefix，供云端图片处理参数改写）
$params = ['rel' => $rel, 'thumb_rel' => $thumbRel, 'prefix' => $prefix, 'url' => $url];
\app\Helpers\Plugin::hook('upload_thumb_url', $params);
return (string)$params['url'];

不做会怎样：upload_url 收到的只是最终 URL，丢失了「这是 400×300 还是 800×600」的语义 → 无法把 thumb_ 映射成 CoreIX 的 ?w=400&h=300，只能老实地把三档都推到云端（多 2 倍对象数与流量）。

改动 4 — Plugin::http() 支持任意 HTTP 方法 + 返回状态码（约 28 行）

位置：app/Helpers/Plugin.php:215-272。

• file_get_contents 分支：content 不再限定 $method === 'POST'，改为有 body 就发；
• curl 分支：POST 之外支持 PUT/DELETE/PATCH/HEAD（CURLOPT_CUSTOMREQUEST + CURLOPT_POSTFIELDS）；
• 用 $http_response_header / curl_getinfo(CURLINFO_RESPONSE_CODE) 取状态码；
• 返回值增加 'status' => int（向后兼容：新增键，不改 ok/body/error 语义）。

不做会怎样：S3 上传必须 PUT。要么改核心（本项），要么插件内裸写 curl_init() —— 那就同时绕过了 net:fetch 权限门和 SSRF 防线，规范 §十三 明确要求「插件应通过本方法发起外部 HTTP(S) 请求，替代裸 file_get_contents / curl_init」，审计必然标记。

⚠️ 本项是通用能力补齐，与「存储插件」无关的插件也受益（任何需要 PUT/DELETE 外部 API 的插件）。

4.4 若你选方案 B（零核心改动），代价清单

五、推荐方案详细设计（方案 C）

5.1 数据流

用户上传
   │
   ▼
Upload::file()  ── 白名单/MIME/大小校验（核心，不动）
   │  ① 原图落盘 assets/uploads/2026-09/ab12cd.png
   │  ② 生成 thumb_（400×300）／ md_（800×600）
   │
   ├─► ★ upload_after 钩子
   │        └─► 插件：写队列 bs_objects(status=pending)
   │
   ▼
请求末尾（★ route_after_dispatch —— 响应已产出，index.php:321，无参数、单触发）
   │
   └─► 插件：排空队列（**单请求最多 1 条**，超时 5s）
            └─► S3Client::putObject()  ── SigV4 签名 ──► PUT https://.s3.bitiful.net/
                     │  成功 → status=done，记 etag/size/sha256
                     └─ 失败 → status=failed，attempts++，指数退避

用户浏览
   │
   ▼
Upload::url() / thumbUrl()
   │
   └─► ★ upload_url / upload_thumb_url 钩子
            ├─ 文件已在云端（内存白名单命中）→ 返回 https://.s3.bitiful.net/
            └─ 未同步 / 插件停用 / 白名单未命中 → **返回本地 URL（零裂图）**

核心设计原则：URL 改写是「按文件粒度」的，且默认回退本地。 任何一步失败都不会让页面裂图，最坏情况只是没走 CDN。

5.2 插件目录结构

plugins/bitiful_storage/
├── plugin.json                 # hooks 清单 + permissions
├── Plugin.php                  # 主类：db()/ddl()/activate()/deactivate()/uninstall() + 业务方法
├── S3Client.php                # SigV4 签名 + putObject/getObject/headObject/deleteObject
├── SyncQueue.php               # 队列：入队/取批/成功/失败退避/统计
├── UrlRewriter.php             # URL 改写：白名单查询 + 内存缓存 + 档位映射
├── AdminController.php         # 后台控制器（Tab 配置页 + 队列面板 + 全量补齐）
├── hook/
│   ├── init_after.php          # 惰性建表兜底（戳文件门控，避免每请求跑 DDL）
│   ├── route_after_dispatch.php # ★ 排空队列（响应已产出，单触发）
│   ├── upload_after.php        # ★ 上传成功 → 入队（只入队，不推送）
│   ├── upload_url.php          # ★ 原图 URL 改写
│   ├── upload_thumb_url.php    # ★ 缩略图 URL 改写（带档位）
│   ├── admin_route_register.php
│   ├── layout_head_end.php     # 仅插件后台页加载 assets/
│   └── controller_view_before.php  # 后台页数据注入
├── views/
│   ├── admin.php               # Tab1 连接配置 / Tab2 同步策略 / Tab3 队列与补齐
│   └── _queue_table.php        # 队列表格片段
├── assets/
│   ├── style.css               # 后台样式（复用 .admin-tabs；--mn-* 仅用于非后台页）
│   └── script.js               # Tab 切换 + 测试连接 + 手动补齐（零内联）
├── lang/
│   ├── zh.php / en.php / zh_tw.php   # 三语同步，键序一致
└── data/                       # Plugin::db() 自动创建
    └── bitiful_storage.sqlite

5.3 插件独立库表（Plugin::ensureSchema()，幂等）

-- 对象台账：一个「相对 uploads 路径 + 档位」一行
CREATE TABLE IF NOT EXISTS bs_objects (
    id          INTEGER PRIMARY KEY,
    rel         TEXT NOT NULL,              -- '2026-09/ab12cd.png'（原图相对路径）
    variant     TEXT NOT NULL DEFAULT 'orig', -- orig | thumb_ | md_
    object_key  TEXT NOT NULL,              -- 云端 key，如 'uploads/2026-09/ab12cd.png'
    size        INTEGER NOT NULL DEFAULT 0,
    etag        TEXT NOT NULL DEFAULT '',
    sha256      TEXT NOT NULL DEFAULT '',   -- 用于「内容变了才重推」
    status      TEXT NOT NULL DEFAULT 'pending', -- pending|done|failed
    attempts    INTEGER NOT NULL DEFAULT 0,
    last_error  TEXT NOT NULL DEFAULT '',
    next_try_at TEXT NOT NULL DEFAULT '',
    created_at  TEXT NOT NULL,
    synced_at   TEXT NOT NULL DEFAULT ''
);
CREATE UNIQUE INDEX IF NOT EXISTS idx_bs_rel_variant ON bs_objects(rel, variant);
CREATE INDEX IF NOT EXISTS idx_bs_status_next ON bs_objects(status, next_try_at);

-- 操作日志（后台可见，便于排障；保留最近 N 条）
CREATE TABLE IF NOT EXISTS bs_logs (
    id         INTEGER PRIMARY KEY,
    level      TEXT NOT NULL DEFAULT 'info',
    action     TEXT NOT NULL DEFAULT '',
    message    TEXT NOT NULL DEFAULT '',
    created_at TEXT NOT NULL
);

⚠️ 索引 DDL 必须写在 CREATE TABLE 之后（规范 §10.3）；activate() 里 ensureSchema() 成功才 return true；init_after 再做一次惰性兜底。

5.4 队列与执行模型（应对「没有 cron」）

「全量补齐」走后台按钮 + 分批（每批 50 条、AJAX 循环调用），不做 一次性同步 —— 避免 max_execution_time 与浏览器超时。

5.5 URL 改写策略（关键：永不裂图）

改写判定顺序（UrlRewriter::rewrite()）：

1. 插件未启用 / 未配好 AK-SK / 未绑定桶 → 直接返回原 URL（零开销）
2. 传入值已是外链（http(s)://）→ 原样返回（不碰外链，与 Upload::url() 既有语义一致）
3. 查内存白名单（进程内静态数组，status='done' 的 rel 集合，单请求最多 1 次 DB 查询）

• 命中 → 拼 https://<bucket>.s3.bitiful.net/<key_prefix><key>
• 未命中 → 返回本地 URL

1. 可选「缩略图走 CoreIX」：thumb_ 档命中时，改写为原图 key + 处理参数（?w=400&h=300&fm=webp&q=80），省一次对象存储

⚠️ PageCache 交互：缓存里存的是改写前的 HTML（本地 URL），改写发生在缓存输出之后 —— 这正是想要的（缓存不绑域名，换 CDN 域名不用清缓存）。验证时必须覆盖「缓存命中」路径。

5.6 配置项（Settings key 清单，全部带 bitiful_storage_ 前缀）

5.7 后台页面（3 个 Tab，复用核心 .admin-tabs）

plugin.json 的 admin_url 指向 /admin/bitiful-storage。

5.8 i18n 键（三语同步，键序一致）

命名遵循规范 §八 plugin.{插件名}.{语义}，全部为 plugin.bitiful_storage.*：

• 后台：title tab_conn tab_policy tab_queue fld_endpoint fld_region fld_bucket fld_prefix fld_ak fld_sk fld_public_base btn_test btn_save btn_drain btn_scan btn_clear test_ok test_fail stat_pending stat_done stat_failed col_rel col_variant col_status col_attempts col_error col_synced empty err_bucket_invalid err_ak_required err_key_missing err_net err_perm act_queued act_synced act_scanned act_cleared
• 后台文案约定：无后缀 err_ = 后台表单校验；_act = 操作结果提示（规范 §十三 附加约定）

5.9 权限声明（plugin.json）

"permissions": ["route:admin", "system:settings", "net:fetch"]

• route:admin — 注册后台路由
• system:settings — activate() 写默认设置
• net:fetch — 调 Plugin::http() 访问 S3

5.10 plugin.json 草案

{
    "name": "缤纷云存储",
    "version": "1.0.0",
    "author": "FlintHub",
    "description": "缤纷云 Bitiful S4 对象存储：附件本地落盘后镜像到公开桶，前台 URL 自动改写为 CDN 地址，未同步文件自动回退本地",
    "activated": false,
    "category": "system",
    "icon": "cloud",
    "admin_url": "/admin/bitiful-storage",
    "hooks": {
        "init_after": "hook/init_after.php",
        "route_after_dispatch": "hook/route_after_dispatch.php",
        "upload_after": "hook/upload_after.php",
        "upload_url": "hook/upload_url.php",
        "upload_thumb_url": "hook/upload_thumb_url.php",
        "admin_route_register": "hook/admin_route_register.php",
        "layout_head_end": "hook/layout_head_end.php",
        "controller_view_before": "hook/controller_view_before.php"
    },
    "permissions": ["route:admin", "system:settings", "net:fetch"]
}

⚠️ 三个 upload_* 钩子是本计划新增的核心钩子；hook/upload_url.php 等文件绝不可声明顶层函数/类（否则被降级为 include_once，见规范 §9.0）。

⚠️ 排空挂在 route_after_dispatch 而非 init_after：init_after 在请求早期，做网络推送会直接拖慢首字节；route_after_dispatch 时响应已产出，耗时与失败都不进页面（计划书原稿写的是 init_after，P2 实装时按「不拖慢页面」硬约束改掉）。

⚠️ 改动 hooks 清单后必须 Plugin::refresh() 重建 plugins/plugins_cache.json。

⚠️ 不注册 nav_plugin_links（存储插件无前台入口）；不注册 nav_pc_user_links（死钩子）。

六、分阶段实施计划

P0 — 核心扩展点 + 插件骨架（约 0.5 人日）

P1 — S3 链路打通（约 1 人日）

P2 — 自动同步队列（约 1 人日）

P3 — URL 改写 + 全量补齐（约 1 人日）

P4 — 验证与发布（约 0.5 人日）

见 §七。产出 update/29/（含 4 处核心改动文件：app/Helpers/Upload.php、app/Helpers/Plugin.php）+ 插件目录 + 重建的 plugins/plugins_cache.json。

七、验证清单（对齐规范 §十二）

7.1 安全红线自查（逐条给证据）

7.2 自动化验证

7.3 必须人工走查的场景

1. 发帖带图（原图 > 800×600）→ 列表摘要、正文图、附件卡三处 URL 都正确
2. 头像上传（不生成 thumb_）→ 改写正确、无 404
3. 上传后立刻刷新（还没同步）→ 走本地 URL，不裂图
4. 停用插件 → 全站立刻回本地
5. 断网 → 队列退避 → 恢复后自动补推
6. 双主题（默认浅色 + 暗夜星辰）后台页可读性

八、需要你裁决的事项

九、风险登记

十、交付物清单

本计划基于 2026-09-21 对 app/Helpers/Upload.php、app/Helpers/Plugin.php、app/Helpers/PageCache.php、app/Core/TemplateCompiler.php、index.php、cron_trigger.php 的逐行核实，以及缤纷云官方文档（docs.bitiful.com）的接口事实。