@homurajs/storage 26.10.13 → 26.10.14

package/README.md

@@ -2,10 +2,18 @@
 
 对象存储/图床：三后端（local-fs / s3 兼容 / supabase）+ `/files/<key>` 代理路由。
 
+> ⚠ **qw-pages 上三个后端都不可用**（2026-10-13 实测）：
+>
+> - `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'
 
 const storage = createLocalStorage({ rootDir: './data/files' })
 
@@ -23,4 +31,17 @@ import { createFileProxyRoutes } from '@homurajs/storage/proxy'
 app.route('/', createFileProxyRoutes(storage))
 ```
 
-使用示范见模板 `src/server/routes/files.ts`。
+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/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.14",
   "type": "module",
   "description": "homura 对象存储/图床适配：supabase-storage / s3 兼容(minio/oss) / local-fs 三后端 + 代理路由",
   "engines": {
@@ -36,7 +36,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@homurajs/core": "26.10.13"
+    "@homurajs/core": "26.10.14"
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": ">=3.0.0",