@homurajs/storage 26.10.13 → 26.10.15

package/README.md

@@ -1,11 +1,24 @@
 # @homurajs/storage
 
-对象存储/图床：三后端（local-fs / s3 兼容 / supabase）+ `/files/<key>` 代理路由。
+对象存储/图床：四后端（local-fs / s3 兼容 / supabase / **db**）+ `/files/<key>` 代理路由。
+
+> **qw-pages 上只有 `db` 后端可用**（其余三个 2026-10-13 实测均不可用，db 后端 2026-10-14 实测可用）：
+>
+> - `db`：✅ **Pages 唯一可用的 storage 后端**——二进制**分块** base64 存进 `homura_files`（清单）+
+>   `homura_file_chunks`（数据），走 PostgREST（Pages 唯一可用的数据路径）。分块绕开网关 body 上限，
+>   支持大文件（受可配总上限约束，缺省 50MB）；2026-10-14 实测 3MB 分 8 块上传 + 流式下载逐字节一致。
+>   ⚠ 大文件正解仍是 s3 预签名直传（见下），db 分块是无对象存储时的兜底
+> - `supabase`：❌ 桶建不出来——anon 建桶被 RLS 拒（400 内含 403），平台受控迁移角色对 `storage` schema 也无权（`42501`）
+> - `local`：❌ 默认 `./data/files` 在 Pages 不可写（应用根只读），且 `mkdir` 发生在**每次上传时**而非构造期 → 启动正常、`/_healthz` 报 ok、首次上传才 EACCES；改指 `QWENWORK_WRITABLE_DIR` 也只能当临时缓冲（跨发布清空）
+> - `s3`：⚠️ 理论可行（凭据可经 `homura.config.env` 投递），但需 App 自行安装 optional peer，且 S3 端点出网未验证
+>
+> 详见 `docs/specs/module-qw-pages.md` 与 AGENTS.md 的支持矩阵。
 
 ```ts
-import { createLocalStorage } from '@homurajs/storage/local'   // 独立形态
-// import { createS3Storage } from '@homurajs/storage/s3'      // minio/oss（AWS SDK 动态加载）
-// import { createSupabaseStorage } from '@homurajs/storage/supabase' // qw-pages（手写 REST）
+import { createLocalStorage } from '@homurajs/storage/local' // 独立形态
+// import { createS3Storage } from '@homurajs/storage/s3'      // minio/oss（AWS SDK 动态加载，需自装 peer）
+// import { createSupabaseStorage, loadSupabaseStorageEnv } from '@homurajs/storage/supabase'
+// import { createDrizzleFileStore, createRestFileStore } from '@homurajs/storage/db'  // DB-backed
 
 const storage = createLocalStorage({ rootDir: './data/files' })
 
@@ -23,4 +36,142 @@ import { createFileProxyRoutes } from '@homurajs/storage/proxy'
 app.route('/', createFileProxyRoutes(storage))
 ```
 
-使用示范见模板 `src/server/routes/files.ts`。
+## db 后端（DB-backed 分块存储，qw-pages 唯一可用）
+
+把二进制**分块**写进数据库——qw-pages 上的兜底后端。三后端在 Pages 全倒，而 `rest`（PostgREST）
+是 Pages 唯一可用的数据路径，故 db 后端是**第一个能在 Pages 上跑的 storage**。强制分块以绕开两道
+平台限制：网关 body 上限（实测 ≥1MB 413）+ PostgREST 单值 ~1MB。
+
+```ts
+import { createDrizzleFileStore, createRestFileStore } from '@homurajs/storage/db'
+
+// SQL 方言（sqlite / pg）：构造时 CREATE TABLE IF NOT EXISTS，与 drizzle 迁移幂等共存
+const storage = createDrizzleFileStore(db, { chunkSize: 384 * 1024, maxTotalBytes: 50 * 1024 * 1024 })
+
+// REST 方言（qw-pages）：不建表（无 DDL 权限），两张表须由部署期受控迁移预建
+const storage = createRestFileStore(rest, { chunkSize: 384 * 1024, maxTotalBytes: 50 * 1024 * 1024 })
+```
+
+两张表（`@homurajs/storage/tables` 的 `pgStorageTables` / `sqliteStorageTables`），App spread 进
+自己的 schema 参与迁移（照 `@homurajs/license/tables` 先例）：
+
+- `homura_files`：清单（object_key PK / content_type / total_size / chunk_size / chunk_count / status / created_at / updated_at）
+- `homura_file_chunks`：数据分块（object_key + chunk_index 复合主键 / data）
+
+```ts
+// schema/pg.ts
+import { pgStorageTables } from '@homurajs/storage/tables'
+export const homuraFiles = pgStorageTables.homuraFiles
+export const homuraFileChunks = pgStorageTables.homuraFileChunks
+export const pgSchema = { todos, /* ... */, homuraFiles, homuraFileChunks }
+```
+
+**整文件 API 仍可用**（`uploadFile`/`downloadFile`，内部分块/重组，服务端一次性场景）；
+**大文件走分块协议**（前端切片，避免整文件进内存、避免撞网关限）：
+
+```ts
+// 前端（浏览器）：import { uploadChunked } from '@homurajs/storage/chunk-client'
+const r = await uploadChunked(file, { chunkSize: 384 * 1024, onProgress: (loaded, total) => ... })
+// r.url 即 /files/<objectKey> 代理下载地址（服务端流式重组）
+```
+
+对应服务端路由（模板 `routes/files.ts` 已示范）：`POST /api/files/init` → `PUT /api/files/chunk?key=&index=`
+（原始字节 body）→ `POST /api/files/complete`。
+
+**关键设计**：
+
+- `data` 列是 **base64 文本**（不是 bytea/blob）。PostgREST 对 bytea 的 JSON 编解码不可靠
+  （2026-10-14 Pages 实测：308B 进去、618B mojibake 出来），文本列三方言一致、编解码由 `db.ts`
+  显式控制（toBase64/fromBase64）。代价 +33% 体积——对兜底后端可接受
+- **分块绕网关**：每块 base64 后 ≤512KB（raw 缺省 384KB），避开网关 body 限与 PostgREST 单值限。
+  客户端每块发**原始字节**（不 base64），请求体 = raw 块大小，最大化余量
+- **可配总上限**（`maxTotalBytes`，缺省 50MB）：DB 存 blob 是反模式（撑大库、无 CDN、慢、贵），
+  "无限大"是陷阱，故设上限并在超限时提示改用 s3 预签名直传。⚠ **Pages 上网关先拦**：实测 512KB 稳、
+  768KB 撞 PostgREST 值上限报 500、≥1MB 被 openresty 413——故单块必须小，大文件靠分块累积
+- **流式下载**：`downloadStream` 逐块 yield（Hono `ReadableStream`），避免整文件进内存；代理路由
+  `/files/<key>` 优先用它（带 `content-length`，浏览器可显示进度）
+- **残块 GC**：`status=uploading` 超 `staleUploadMs`（缺省 24h）的清单在 initUpload 时顺带清扫
+  （概率 `sweepProbability`，缺省 0.05；await 而非 fire-and-forget，兼容 Pages/serverless 进程冻结）
+- `listFiles` 只返 `status=complete` 的清单、只选元数据列（不拉 data）
+- presign 下载无意义（DB 无直连 URL），降级为代理路径 `/files/<key>`
+- 依赖方向：storage → `@homurajs/db` schema-helpers（照 auth/license 先例，见 AGENTS.md 白名单）；
+  `drizzle-orm` 是 optional peer，`./db` 子路径动态 import
+
+## 大文件正解：预签名直传对象存储
+
+DB 分块是兜底；**大文件的正解是浏览器预签名直传 OSS/S3**——字节不过 App、不过网关，既绕开 body
+上限又不膨胀 DB。s3 后端提供 `getSignedUploadUrl`（预签名 PUT）：
+
+```ts
+// 服务端：签发直传 URL（模板经 POST /api/files/presign 暴露）
+const uploadUrl = await s3Storage.getSignedUploadUrl(objectKey, contentType, 900)
+
+// 前端：import { uploadViaPresign } from '@homurajs/storage/chunk-client'
+await uploadViaPresign(file, uploadUrl)   // 浏览器直接 PUT 到 OSS，流式发送 Blob
+// 下载仍走 /files/<objectKey> 代理（服务端从 OSS 取），或另签 GET 预签名
+```
+
+⚠ 前置：对象存储侧配好 **CORS**（允许 Pages 域名的 `PUT` + `Content-Type` 头）；`uploadViaPresign`
+的 content-type 必须与签发时一致（签名覆盖了它）。OSS 从浏览器侧的可达性需自行确认。
+
+## s3 后端接阿里云 OSS（配置 recipe）
+
+s3 后端用 AWS SDK 的 S3 兼容模式接 OSS——OSS 提供 S3 兼容端点，**无需 OSS 专用 SDK**：
+
+```ts
+import { createS3Storage } from '@homurajs/storage/s3'
+
+const storage = createS3Storage({
+  // OSS 的 S3 兼容端点：https://oss-<region>.aliyuncs.com（如 oss-cn-hangzhou.aliyuncs.com）
+  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
+  region: 'oss-cn-hangzhou', // OSS 的 region 名（带 oss- 前缀）
+  bucket: 'my-bucket',
+  accessKeyId: process.env.S3_ACCESS_KEY!,     // OSS AccessKey ID
+  secretAccessKey: process.env.S3_SECRET_KEY!, // OSS AccessKey Secret
+  forcePathStyle: false, // ⚠ OSS 必须 false（virtual-hosted）；path-style 会报 SecondLevelDomainForbidden
+  autoCreateBucket: false, // ⚠ OSS 桶须在控制台预建；S3 的 CreateBucket 对 OSS 不一定生效，关掉更稳
+  presignDirect: false,    // 走 /files 代理下载（不暴露 OSS 直连 URL）；要直连下载再开
+})
+```
+
+模板里对应 env（`config/homura.config.env` 或真实环境变量）：
+
+```
+STORAGE_BACKEND=s3
+S3_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
+S3_REGION=oss-cn-hangzhou
+S3_BUCKET=my-bucket
+S3_ACCESS_KEY=<OSS AccessKey ID>
+S3_SECRET_KEY=<OSS AccessKey Secret>
+S3_FORCE_PATH_STYLE=false
+```
+
+**OSS 注意点**：
+
+- ⚠ **必须 `forcePathStyle: false`（virtual-hosted：`bucket.endpoint/key`）**。OSS 对对象操作强制
+  virtual-hosted，path-style（`endpoint/bucket/key`，minio 缺省）会报
+  `403 SecondLevelDomainForbidden: Please use virtual hosted style`——2026-10-14 真 OSS 实测确认。
+  预签名 URL 的寻址风格也随此开关，故直传前必须配对（模板经 `S3_FORCE_PATH_STYLE=false` 投递）
+- `region` 用 OSS 的写法（`oss-cn-hangzhou`），不是 AWS 的 `cn-hangzhou`
+- 桶必须**预先在 OSS 控制台创建**并配好读写权限；`autoCreateBucket` 对 OSS 不保证生效，建议关
+- 需 App 自行安装两个 optional peer：`@aws-sdk/client-s3` + `@aws-sdk/s3-request-presigner`
+- ✅ **预签名直传已对真 OSS 实测通过**（2026-10-14）：建桶 → `getSignedUploadUrl` → PUT 3MB → 200 →
+  `downloadFile` 回读逐字节一致 → 预签名 GET 200。浏览器直传是客户端 → OSS，不经 Pages 网关，
+  故网关 body 上限不适用；服务端 `downloadFile`/代理下载走 Pages→OSS 443 出网，实测可达
+- ⚠ 浏览器直传仍需 OSS 桶配 **CORS**（允许 Pages 域名的 `PUT` + `Content-Type` 头）；curl/node 直传
+  不受 CORS 约束（故上述实测用 node fetch 模拟），但真实浏览器流程必须配 CORS
+
+supabase 后端的 env 解析用**本包**的 loader，不要用 `@homurajs/db/pg` 的那个：
+
+```ts
+import { createSupabaseStorage, loadSupabaseStorageEnv } from '@homurajs/storage/supabase'
+
+// 只需 SUPABASE_URL + SUPABASE_ANON_KEY（qw-pages 会自动注入这两项）
+const { platformUrl, apiKey } = loadSupabaseStorageEnv(process.env)
+const storage = createSupabaseStorage({ platformUrl, apiKey, bucket: 'files' })
+// ⚠ bucket 必须预先存在：本包与平台迁移都建不出桶（见上方警告）
+```
+
+`@homurajs/db/pg` 的 `loadSupabaseEnv` 要 `SUPABASE_PROJECT_REF` + `SUPABASE_DB_PASSWORD`（PG 直连用，仅自托管 supabase 有），拿它来配对象存储会因为缺 PG 凭据而抛错——这个连带依赖已经拆掉。
+
+使用示范见模板 `src/server/routes/files.ts` 与 `app.ts`（buildStorage）。

package/dist/index.d.ts

@@ -29,14 +29,82 @@ export interface FileStorage {
   }>;
   /** 弱后端降级为代理路径 */
   getPresignedUrl(objectKey: string, expirySeconds: number): Promise<string>;
+  /**
+   * 预签名**上传** URL（浏览器直传对象存储用，绕开 App 网关的 body 上限）。
+   * 可选能力：只有 s3 兼容后端实现；DB/local/supabase 不支持（返回 undefined 或抛错）。
+   * 见 Phase B「预签名直传 OSS」。
+   */
+  getSignedUploadUrl?(objectKey: string, contentType: string, expirySeconds: number): Promise<string>;
+  /**
+   * 流式下载（可选）：逐块 yield，避免整文件进内存。代理路由优先用它，缺失时退回 downloadFile。
+   * 分块后端（ChunkedFileStorage）必须实现。
+   */
+  downloadStream?(objectKey: string): Promise<{
+    stream: ReadableStream<Uint8Array>;
+    contentType: string;
+    size: number;
+  }>;
   deleteFile(objectKey: string): Promise<void>;
   /** 强制 ns 前缀，无法越权列举 */
   listFiles(ns: string, prefix: string, limit: number): Promise<FileInfo[]>;
 }
+/** 清单状态：uploading（分块上传中）| complete（块齐、可下载） */
+export type FileStatus = 'uploading' | 'complete';
+/** 分块文件的清单（manifest）——不含数据本身 */
+export interface FileManifest {
+  objectKey: string;
+  contentType: string;
+  /** 原始总字节数 */
+  totalSize: number;
+  /** 每块原始字节数（最后一块可能更小） */
+  chunkSize: number;
+  chunkCount: number;
+  status: FileStatus;
+  createdAt: Date;
+}
+/**
+ * 分块文件存储：在 FileStorage 之上加分块上传协议（init/putChunk/complete）。
+ *
+ * 为什么需要：qw-pages 网关对单请求 body 有上限（实测 ≥1MB 413），PostgREST 单值也 ~1MB。
+ * 把文件切成 ≤chunkSize 的块、每块一个小请求，即可绕开限制支持大文件。前端用
+ * `@homurajs/storage/chunk-client` 切片上传；下载由 `downloadStream` 逐块流式重组。
+ *
+ * 整文件 API（uploadFile/downloadFile）仍可用：内部自动分块/重组（服务端一次性场景）。
+ */
+export interface ChunkedFileStorage extends FileStorage {
+  /** 初始化分块上传：建清单（status=uploading），返回实际块数与块大小 */
+  initUpload(input: {
+    objectKey: string;
+    contentType: string;
+    totalSize: number;
+    chunkSize?: number;
+  }): Promise<{
+    objectKey: string;
+    chunkCount: number;
+    chunkSize: number;
+  }>;
+  /** 写入单块（幂等 upsert，可重试/并行）；data 为该块原始字节 */
+  putChunk(objectKey: string, index: number, data: Uint8Array): Promise<void>;
+  /** 完成上传：校验块齐 → status=complete；缺块抛错（残块由 GC 清） */
+  completeUpload(objectKey: string): Promise<FileManifest>;
+  /** 读清单（不存在返回 null） */
+  getManifest(objectKey: string): Promise<FileManifest | null>;
+  /** 流式下载（分块后端必须实现） */
+  downloadStream(objectKey: string): Promise<{
+    stream: ReadableStream<Uint8Array>;
+    contentType: string;
+    size: number;
+  }>;
+}
 /** 上传载荷（Node 侧 Uint8Array；浏览器 File/Blob 由调用方先转） */
 export type FilePayload = Uint8Array | ReadableStream<Uint8Array>;
 /** object key 校验：禁止路径穿越 */
 export declare function assertSafeObjectKey(key: string): void;
 /** 统一代理路径 */
 export declare function proxyUrl(objectKey: string): string;
+/**
+ * 生成业务 objectKey：`<ns>/files/<unixMs>_<safeName>`。
+ * 服务端用它在分块上传 init 时定 key（强制 ns 前缀、清洗文件名），与整文件 uploadFile 同格式。
+ */
+export declare function generateObjectKey(ns: string, fileName: string, now: number): string;
 //#endregion

package/dist/index.js

@@ -7,5 +7,13 @@ function assertSafeObjectKey(key) {
 function proxyUrl(objectKey) {
 	return `/files/${objectKey}`;
 }
+/**
+* 生成业务 objectKey：`<ns>/files/<unixMs>_<safeName>`。
+* 服务端用它在分块上传 init 时定 key（强制 ns 前缀、清洗文件名），与整文件 uploadFile 同格式。
+*/
+function generateObjectKey(ns, fileName, now) {
+	assertSafeObjectKey(ns);
+	return `${ns}/files/${now}_${fileName.replace(/[/\\]/g, "_")}`;
+}
 //#endregion
-export { assertSafeObjectKey, proxyUrl };
+export { assertSafeObjectKey, generateObjectKey, proxyUrl };

package/dist/local.js

@@ -1,7 +1,7 @@
 import { assertSafeObjectKey, proxyUrl } from "./index.js";
 import { createReadStream, existsSync } from "node:fs";
 import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 //#region src/local.ts
 /**
 * local-fs 后端：独立单机形态的缺省实现。
@@ -13,7 +13,7 @@ async function* walk(dir, base = dir) {
 	for (const entry of await readdir(dir, { withFileTypes: true })) {
 		const full = join(dir, entry.name);
 		if (entry.isDirectory()) yield* walk(full, base);
-		else if (!entry.name.endsWith(".meta.json")) yield full.slice(base.length + 1);
+		else if (!entry.name.endsWith(".meta.json")) yield full.slice(base.length + 1).split(sep).join("/");
 	}
 }
 function createLocalStorage(options) {

package/dist/proxy.js

@@ -10,6 +10,14 @@ function createFileProxyRoutes(storage, options) {
 	app.get(`${mount}/:key{.+}`, async (c) => {
 		const key = c.req.param("key");
 		try {
+			if (storage.downloadStream) {
+				const { stream, contentType, size } = await storage.downloadStream(key);
+				return new Response(stream, { headers: {
+					"content-type": contentType ?? "application/octet-stream",
+					"content-length": String(size),
+					"cache-control": "public, max-age=31536000, immutable"
+				} });
+			}
 			const { data, contentType } = await storage.downloadFile(key);
 			return new Response(data, { headers: {
 				"content-type": contentType ?? "application/octet-stream",

package/dist/s3.d.ts

@@ -10,6 +10,13 @@ export interface S3StorageOptions {
   autoCreateBucket?: boolean;
   /** 预签名走直连 URL（默认 false：走代理路径降级，避免暴露 endpoint） */
   presignDirect?: boolean;
+  /**
+   * 寻址风格：true = path-style（`endpoint/bucket/key`），false = virtual-hosted（`bucket.endpoint/key`）。
+   * 缺省 true（minio 需要）。⚠ **阿里云 OSS 必须 false**：OSS 对对象操作强制 virtual-hosted，
+   * path-style 会报 `403 SecondLevelDomainForbidden: Please use virtual hosted style`
+   * （2026-10-14 真 OSS 实测）。预签名 URL 的寻址风格也随此开关，故直传前必须配对。
+   */
+  forcePathStyle?: boolean;
 }
 export declare function createS3Storage(options: S3StorageOptions): FileStorage;
 //#endregion

package/dist/s3.js

@@ -17,7 +17,7 @@ function createS3Storage(options) {
 		const client = new deps.S3Client({
 			endpoint: options.endpoint,
 			region: options.region,
-			forcePathStyle: true,
+			forcePathStyle: options.forcePathStyle ?? true,
 			credentials: {
 				accessKeyId: options.accessKeyId,
 				secretAccessKey: options.secretAccessKey
@@ -85,6 +85,21 @@ function createS3Storage(options) {
 				Key: objectKey
 			}), { expiresIn: expirySeconds });
 		},
+		/**
+		* 预签名**上传** URL（PUT）：浏览器拿到后直传对象存储，字节不过 App。
+		* 这是大文件的正解——绕开 App 网关的 body 上限（qw-pages 实测 ≥1MB 413），
+		* 也避免 DB-backed 分块的开销。前端用 @homurajs/storage/chunk-client 的 uploadViaPresign 对接。
+		* ⚠ 纯本地 SigV4 计算，不联网；但浏览器直传需对象存储侧配好 CORS（允许 Pages 域名的 PUT）。
+		*/
+		async getSignedUploadUrl(objectKey, contentType, expirySeconds) {
+			assertSafeObjectKey(objectKey);
+			const { client, deps } = await ensure();
+			return deps.getSignedUrl(client, new deps.PutObjectCommand({
+				Bucket: options.bucket,
+				Key: objectKey,
+				ContentType: contentType
+			}), { expiresIn: expirySeconds });
+		},
 		async deleteFile(objectKey) {
 			const { client, deps } = await ensure();
 			await client.send(new deps.DeleteObjectCommand({

package/dist/supabase.d.ts

@@ -8,4 +8,25 @@ export interface SupabaseStorageOptions {
   fetchImpl?: typeof fetch;
 }
 export declare function createSupabaseStorage(options: SupabaseStorageOptions): FileStorage;
+export interface SupabaseStorageEnv {
+  /** 平台 URL（已去尾斜杠），如 https://supabase.<平台域> */
+  platformUrl: string;
+  /** anon key（public bucket 足够；private bucket 需 service role key，而平台不下发） */
+  apiKey: string;
+}
+/**
+ * 从 env 解析 supabase storage 所需的最小集：平台 URL + anon key。
+ *
+ * 与 @homurajs/db/pg 的 loadSupabaseEnv（PG 直连，需 PROJECT_REF + DB_PASSWORD）**刻意分离**：
+ * 2026-10-13 实测 qw-pages 只注入 SUPABASE_URL / SUPABASE_ANON_KEY / SUPABASE_INSTANCE_ID，
+ * 既无 project ref 也无 DB 密码，且平台没有自定义 env 注入口 → PG 直连在 Pages 上不可用。
+ * 旧实现让 storage 复用 PG 的 loader，导致「只想要对象存储」也被 PG 凭据缺失一起拖死。
+ *
+ * ⚠ Pages 上的硬限制（均为实测）：
+ * - anon 无建桶权：POST /storage/v1/bucket → 400（内层 403 "new row violates row-level security policy"）
+ * - 受控迁移角色对 storage schema 也无权：INSERT INTO storage.buckets → 42501 permission denied
+ * → **bucket 必须预先存在**，否则 upload/download 一律 "Bucket not found"。
+ * - GET /storage/v1/bucket 可达（200，实测返回空数组），说明端点与鉴权本身没问题。
+ */
+export declare function loadSupabaseStorageEnv(env: NodeJS.ProcessEnv): SupabaseStorageEnv;
 //#endregion

package/dist/supabase.js

@@ -105,5 +105,29 @@ function toBytes(data) {
 	if (data instanceof Uint8Array) return data;
 	throw new Error("supabase 后端不支持流式载荷：请先聚合为 Uint8Array");
 }
+/**
+* 从 env 解析 supabase storage 所需的最小集：平台 URL + anon key。
+*
+* 与 @homurajs/db/pg 的 loadSupabaseEnv（PG 直连，需 PROJECT_REF + DB_PASSWORD）**刻意分离**：
+* 2026-10-13 实测 qw-pages 只注入 SUPABASE_URL / SUPABASE_ANON_KEY / SUPABASE_INSTANCE_ID，
+* 既无 project ref 也无 DB 密码，且平台没有自定义 env 注入口 → PG 直连在 Pages 上不可用。
+* 旧实现让 storage 复用 PG 的 loader，导致「只想要对象存储」也被 PG 凭据缺失一起拖死。
+*
+* ⚠ Pages 上的硬限制（均为实测）：
+* - anon 无建桶权：POST /storage/v1/bucket → 400（内层 403 "new row violates row-level security policy"）
+* - 受控迁移角色对 storage schema 也无权：INSERT INTO storage.buckets → 42501 permission denied
+* → **bucket 必须预先存在**，否则 upload/download 一律 "Bucket not found"。
+* - GET /storage/v1/bucket 可达（200，实测返回空数组），说明端点与鉴权本身没问题。
+*/
+function loadSupabaseStorageEnv(env) {
+	const platformUrl = (env["SUPABASE_URL"] ?? env["SUPABASE_PLATFORM_URL"] ?? "").replace(/\/$/, "");
+	const apiKey = env["SUPABASE_ANON_KEY"] ?? "";
+	const missing = [!platformUrl ? "SUPABASE_URL" : null, !apiKey ? "SUPABASE_ANON_KEY" : null].filter((x) => x !== null);
+	if (missing.length > 0) throw new Error(`supabase storage 环境不完整：缺少 ${missing.join(" 与 ")}。（qw-pages 会自动注入这两项；独立部署需自行设置。SUPABASE_PROJECT_REF / SUPABASE_DB_PASSWORD 是 PG 直连用的，Pages 不下发，storage 也不需要）`);
+	return {
+		platformUrl,
+		apiKey
+	};
+}
 //#endregion
-export { createSupabaseStorage };
+export { createSupabaseStorage, loadSupabaseStorageEnv };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homurajs/storage",
-  "version": "26.10.13",
+  "version": "26.10.15",
   "type": "module",
   "description": "homura 对象存储/图床适配：supabase-storage / s3 兼容(minio/oss) / local-fs 三后端 + 代理路由",
   "engines": {
@@ -26,6 +26,18 @@
       "types": "./dist/supabase.d.ts",
       "import": "./dist/supabase.js"
     },
+    "./db": {
+      "types": "./dist/db.d.ts",
+      "import": "./dist/db.js"
+    },
+    "./tables": {
+      "types": "./dist/tables.d.ts",
+      "import": "./dist/tables.js"
+    },
+    "./chunk-client": {
+      "types": "./dist/chunk-client.d.ts",
+      "import": "./dist/chunk-client.js"
+    },
     "./proxy": {
       "types": "./dist/proxy.d.ts",
       "import": "./dist/proxy.js"
@@ -36,11 +48,13 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@homurajs/core": "26.10.13"
+    "@homurajs/core": "26.10.15",
+    "@homurajs/db": "26.10.15"
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": ">=3.0.0",
     "@aws-sdk/s3-request-presigner": ">=3.0.0",
+    "drizzle-orm": "1.0.0-rc.4",
     "hono": ">=4.0.0"
   },
   "peerDependenciesMeta": {
@@ -50,6 +64,9 @@
     "@aws-sdk/s3-request-presigner": {
       "optional": true
     },
+    "drizzle-orm": {
+      "optional": true
+    },
     "hono": {
       "optional": true
     }
@@ -57,6 +74,7 @@
   "devDependencies": {
     "@aws-sdk/client-s3": "^3.700.0",
     "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "drizzle-orm": "1.0.0-rc.4",
     "hono": "^4.10.0",
     "tsdown": "^0.23.1"
   },