@gilhrpenner/convex-files-control

中文文档
0.6.0发布于 2026/11/09Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 5.4万

Convex 的一个对流文件控制组件.

中文使用文档
文档目录21 节
  1. 特征
  2. 开发和演示
  3. 安装
  4. 快开始
  5. (1) 增加该部分
  6. 2) 在您的应用程序中创建包装功能
  7. 3) 可选的HTTP路线
  8. 上传文件
  9. 指定 URL 流量
  10. 反应钩
  11. 下载文件
  12. 创建赠款+构建 URL
  13. 可共享链接
  14. 密码保护赠款
  15. 访问控制查询( C)
  16. 清理
  17. 服务器侧助手( Files Control)
  18. R2配置
  19. 供应商之间的转让
  20. 测试助手
  21. 示例应用程序

Convex 文件控制

用于安全文件上传、访问控制、下载授权和 寿命周期清理。 与Convex仓库和Cloudflare R2公司合作,以及使用 一个可选的HTTP上传/下载路由器外加反应上载钩.

生活节日

特征

  • 双步上传(已指定 URL) 有访问密钥和可选过期 .
  • 可选的HTTP上传/下载路由并带有认证钩.
  • 下载最大用途、过期、可选密码和可共享的赠款 链接.
  • 基于访问钥匙的授权(用户身份证、租户身份证等).
  • 为过期的上传,赠款,和文件建立内部清理.
  • Convex和R2之间传输文件.
  • 预签名或HTTP上传的反应钩子.

开发和演示

见 捐款额 用于可复制的检查, 实例/README.md 用于当地设置,以及 实例/就业 用于部署。 现场演示是共享的 有演示用户假冒的沙盒;仅上传可支配测试数据.

安装

要求Convex 1.46+和节点 22.12+(建议第24个节点)。 反应 18和19 继续支持.

npm install @gilhrpenner/convex-files-control

快开始

(1) 增加该部分

// convex.config.ts
import { defineApp } from "convex/server";
import convexFilesControl from "@gilhrpenner/convex-files-control/convex.config";

const app = defineApp();
app.use(convexFilesControl);

export default app;

2) 在您的应用程序中创建包装功能

构成部分储存出入控制和下载赠款。 您的应用程序应该存储 其自己的文件元数据(名称,所有者等)并强制执行 auth. 下面的包装 镜像示例应用程序 example/convex/files.ts。 。 。 .

// convex/files.ts
import { ConvexError, v } from "convex/values";
import { mutation } from "./_generated/server";
import { components } from "./_generated/api";

export const generateUploadUrl = mutation({
  args: {
    provider: v.union(v.literal("convex"), v.literal("r2")),
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new ConvexError("Unauthorized");

    return await ctx.runMutation(
      components.convexFilesControl.upload.generateUploadUrl,
      {
        provider: args.provider,
        // r2Config: { accountId, accessKeyId, secretAccessKey, bucketName },
      },
    );
  },
});

export const finalizeUpload = mutation({
  args: {
    uploadToken: v.string(),
    storageId: v.string(),
    fileName: v.string(),
    expiresAt: v.optional(v.union(v.null(), v.number())),
    metadata: v.optional(
      v.object({
        size: v.number(),
        sha256: v.string(),
        contentType: v.union(v.string(), v.null()),
      }),
    ),
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new ConvexError("Unauthorized");

    const { fileName, ...componentArgs } = args;
    const result = await ctx.runMutation(
      components.convexFilesControl.upload.finalizeUpload,
      {
        ...componentArgs,
        accessKeys: [identity.subject],
      },
    );

    // Store your own file record (name, owner, etc.) here.
    // await ctx.db.insert("files", { ... });

    return result;
  },
});

3) 可选的HTTP路线

如果你想的话 /files/upload 财务报告和审定财务报表 /files/download,将路由器注册到 convex/http.ts。访问密钥由您的钩(而不是通过窗体)提供.

// convex/http.ts
import { httpRouter } from "convex/server";
import { registerRoutes } from "@gilhrpenner/convex-files-control";
import { components } from "./_generated/api";

const http = httpRouter();

registerRoutes(http, components.convexFilesControl, {
  pathPrefix: "files",
  enableUploadRoute: true,

  // Required when enableUploadRoute is true
  checkUploadRequest: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) {
      return new Response(JSON.stringify({ error: "Unauthorized" }), {
        status: 401,
        headers: { "Content-Type": "application/json" },
      });
    }

    return { accessKeys: [identity.subject] };
  },

  // Optional: persist file metadata after a successful HTTP upload
  onUploadComplete: async (ctx, { result, file, formData }) => {
    const fileNameFromForm = formData.get("fileName");
    const fileName =
      typeof fileNameFromForm === "string"
        ? fileNameFromForm
        : ((file as File).name ?? "untitled");
    // await ctx.runMutation(api.files.recordUpload, { ...result, fileName });
  },

  // Optional: provide accessKey for downloads
  checkDownloadRequest: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (identity) return { accessKey: identity.subject };
  },
});

export default http;

HTTP 上传要求 multipart/form-data 有字段的字段 :

  • file (必须)
  • provider (可选,"convex" q"r2")
  • expiresAt (可选、时间戳或 null(中文(简体) )

访问密钥不能通过窗体接受;它们必须来自 checkUploadRequest。其他表格字段可在 onUploadComplete 通过 formData。 。 。 .

有用的路由选项 :

  • pathPrefix (默认 : /files(中文(简体) )
  • defaultUploadProvider (单位:千美元)\"convex\" 或者说 \"r2\"(中文(简体) )
  • enableDownloadRoute (默认 : true(中文(简体) )
  • requireAccessKey (人数) checkDownloadRequest 以返回访问密钥)
  • passwordHeader 编号 : passwordQueryParam (覆盖或禁用密码输入)
  • cors (精确浏览器来源和允许的标题;其他浏览器来源) 实收 403(中文(简体) )
registerRoutes(http, components.convexFilesControl, {
  cors: {
    allowedOrigins: ["https://app.example.com"],
    allowedHeaders: ["Authorization", "Content-Type"],
    allowCredentials: false,
  },
});

请求无 Origin 标题继续工作。 若为 cors 删除 现有允许的CORS行为保持不变.

上传文件

指定 URL 流量

// Client-side
const { uploadUrl, uploadToken } = await generateUploadUrl({
  provider: "convex",
});

const uploadResponse = await fetch(uploadUrl, {
  method: "POST",
  body: file,
  headers: { "Content-Type": file.type || "application/octet-stream" },
});

const { storageId } = await uploadResponse.json();

const result = await finalizeUpload({
  uploadToken,
  storageId,
  fileName: file.name,
  expiresAt: Date.now() + 60 * 60 * 1000,
});

反应钩

import { useUploadFile } from "@gilhrpenner/convex-files-control/react";
import { api } from "../convex/_generated/api";

const convexSiteUrl = import.meta.env.VITE_CONVEX_URL.replace(
  ".cloud",
  ".site",
);

const { uploadFile } = useUploadFile(api.files, {
  method: "presigned",
  http: { baseUrl: convexSiteUrl },
});

// Presigned
await uploadFile({ file, provider: "convex" });

// HTTP route
await uploadFile({
  file,
  method: "http",
  provider: "convex",
  http: {
    baseUrl: convexSiteUrl,
    // authToken: useAuthToken() from @convex-dev/auth/react
  },
});

uploadFile 接受:

  • file (必须)
  • provider ("convex"" ""r2")
  • expiresAt (时间戳或 null(中文(简体) )
  • method ("签名""http")

下载文件

创建赠款+构建 URL

import { buildDownloadUrl } from "@gilhrpenner/convex-files-control";

const grant = await ctx.runMutation(
  components.convexFilesControl.download.createDownloadGrant,
  {
    storageId,
    maxUses: 1,
    expiresAt: Date.now() + 10 * 60 * 1000,
    shareableLink: false,
  },
);

const url = buildDownloadUrl({
  baseUrl: "https://<your-convex-site>",
  downloadToken: grant.downloadToken,
  filename: "report.pdf",
  // pathPrefix: "/files", // Optional if you changed the HTTP route prefix
});

访问密钥不放在 URL 中 。 对于私人赠款,通过下列渠道提供: checkDownloadRequest (HTTP路线)或通过 accessKey 调用时 consumeDownloadGrantForUrl。 。 。 .

设定 shareableLink: true 以允许未经认证的下载(无访问密钥) a. 组织事项 例应用就是这样产生公共链接的. 如果您启用 requireAccessKey 在 HTTP 路由中,仍需要共享链接 checkDownloadRequest 以返回访问密钥.

密码保护赠款

const grant = await ctx.runMutation(
  components.convexFilesControl.download.createDownloadGrant,
  { storageId, password: "secret-passphrase" },
);

要使用密码保护的赠款, 请通过 password 改为 consumeDownloadGrantForUrl,或通过 x-download-password 标题(首选)或 password 查询参数。 查询 params可以被泄露到日志中,因此头或POST流比较安全.

访问控制查询( C)

访问密钥是常态化的( trimmed) , 必须包含至少一个非空 数值.

  • accessControl.addAccessKey(storageId, accessKey)
  • accessControl.removeAccessKey(storageId, accessKey)
  • accessControl.updateFileExpiration(storageId, expiresAt)
  • queries.hasAccessKey(storageId, accessKey)
  • queries.listAccessKeysPage(storageId, paginationOpts)
  • queries.listFilesPage(paginationOpts)
  • queries.listFilesByAccessKeyPage(accessKey, paginationOpts)
  • queries.listDownloadGrantsPage(paginationOpts)
  • queries.getFile({ storageId })

增殖用途 { numItems: number, cursor: string | null }。 。 。 .

清理

使用 cleanUp.cleanupExpired 删除已过期的上传、赠款和文件。 这个 例应用将它包裹在突变中,运行在克龙任务中.

// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

const crons = cronJobs();
crons.hourly(
  "cleanup-expired-files",
  { minuteUTC: 0 },
  internal.files.cleanupExpiredFiles,
  {},
);
export default crons;

服务器侧助手( Files Control)

如果您喜欢围绕组件调用进行类包装, 请使用 FilesControl数字 :

import { FilesControl } from "@gilhrpenner/convex-files-control";
import { components } from "./_generated/api";

const files = new FilesControl(components.convexFilesControl, {
  // r2: { accountId, accessKeyId, secretAccessKey, bucketName, jurisdiction },
});

await files.generateUploadUrl(ctx, { provider: "convex" });

FilesControl.clientApi() 还返回一个准备导出 API 表面 如果您想要组件生成您的 Convex 变异和 询问您.

R2配置

使用 R2 进行上传、下载、删除或删除时提供 R2 证书 转让。 你可以通过 r2Config 给组件调用或提供env vars hTTP 路线 :

  • R2_ACCOUNT_ID
  • R2_ACCESS_KEY_ID
  • R2_SECRET_ACCESS_KEY
  • R2_BUCKET_NAME
  • R2_JURISDICTION (例如可选) eu 或者说 fedramp(中文(简体) )

设定 R2_JURISDICTION 只有用 Cloudflare R2 创建了您的桶 管辖权。 见"云花" 数据位置 用于支持的管辖权值和S3端点格式.

供应商之间的转让

const result = await ctx.runAction(
  components.convexFilesControl.transfer.transferFile,
  { storageId, targetProvider: "r2", r2Config },
);

转移保存访问密钥和下载授权,更新文件记录, 并删除原始存储对象.

测试助手

import { convexTest } from "convex-test";
import { register } from "@gilhrpenner/convex-files-control/test";

const t = convexTest(schema, modules);
register(t, "convexFilesControl");

示例应用程序

生活节日

一个完整的 Convex + React + Convex Auth 执行位于 example/。 显示:

  • 预签名和 HTTP 上传
  • 认证下载和共享链接
  • 访问密钥管理
  • convex 和 R2 之间的转移
  • 预定清理

版本与发布记录

@gilhrpenner/convex-files-control 共发布 16 个版本,首次发布于 2025/12/29;过去 12 个月发布了 16 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.6.0latest2026/11/097 天前
0.5.92026/09/241 个月前
0.5.82026/08/262 个月前
0.5.72026/08/033 个月前
0.5.62026/06/125 个月前
0.5.52026/06/035 个月前

关于 @gilhrpenner/convex-files-control 的常见问题

@gilhrpenner/convex-files-control 是什么?

Convex 的一个对流文件控制组件.

如何安装 @gilhrpenner/convex-files-control?

在项目目录运行 npm install @gilhrpenner/convex-files-control,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^18.3.1 || ^19.0.0)、convex(^1.46.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gilhrpenner/convex-files-control 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gilhrpenner/convex-files-control 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gilhrpenner/convex-files-control 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.12.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gilhrpenner/convex-files-control 可以商用吗?

@gilhrpenner/convex-files-control 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@gilhrpenner/convex-files-control 的下载量有多少?

根据 npm 官方下载统计,@gilhrpenner/convex-files-control 在 2026/10/17 – 2026/11/15 这 30 天内被下载 54,049 次,日均约 1,802 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gilhrpenner/convex-files-control 还在维护吗?

最新版本 0.6.0 发布于 2026/11/09(7 天前);至今共发布 16 个版本,其中过去 12 个月发布了 16 个;首次发布于 2025/12/29。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。