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_IDR2_ACCESS_KEY_IDR2_SECRET_ACCESS_KEYR2_BUCKET_NAMER2_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 之间的转移
- 预定清理