CMS后端前端插件系统【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址https://gitcode.com/gh_mirrors/emdas/emdash点击查看免费下载导读EmDash 是构建在 Astro 之上的全栈 TypeScript CMSWordPress 的精神继承者其沙箱化插件系统为插件提供了三套插件级数据 API可查询的记录集合ctx.storage、用户可配置的设置ctx.settings含加密密钥以及键值状态存储ctx.kv。本文以仓库内插件开发技能参考文档 storage.md 为骨架结合packages/core、packages/plugin-types、packages/cloudflare、packages/workerd中的真实实现系统讲解集合声明、CRUD 与批量写入、基于修订号的 CAS 并发控制、谓词守卫原子更新、索引查询以及密钥轮换读完即可在沙箱插件中安全、正确地持久化数据。三套存储 API 概览沙箱插件Sandboxed plugin拥有三套插件作用域的数据 API全部落在宿主数据库中按运行时插件 ID 隔离且都不需要声明任何 capabilityAPI用途ctx.storage.collection在emdash-plugin.jsonc中声明的可查询记录集合ctx.settings用户可配置的设置支持声明为secret的加密密钥ctx.kv游标、缓存值以及其他键值状态这套接口类型定义在 packages/plugin-types/src/index.ts清单侧与 packages/core/src/plugins/types.ts运行时侧中。从源码结构看三套 API 共享同一套宿主存储后端集合走_plugin_storage数据表、设置走options仓库隔离边界由plugin:pluginId:settings:等命名前缀与运行时插件 ID 共同实现。声明存储集合每个集合及其查询索引都必须在清单中显式声明{ storage: { submissions: { indexes: [formId, status, createdAt, [formId, createdAt]], uniqueIndexes: [externalId], }, }, }indexes中的每条目既可以是单个字段名单列索引也可以是字段名数组复合索引uniqueIndexes携带 UNIQUE 约束字段形状与indexes相同uniqueIndexes中的字段本身已可查询不要再重复放进indexes未声明的集合会被沙箱桥sandbox bridge拒绝。对应的清单类型定义StorageCollectionConfig/PluginStorageConfig见 packages/plugin-types/src/index.ts清单是 bundler写入方与运行时读取方共同遵守的线格式wire contract。集合操作完整可移植 API每个已声明集合在原生、Cloudflare 沙箱、Node/workerd 沙箱三种执行环境中都暴露同一套可移植 API接口签名见 packages/core/src/plugins/types.tsinterface StorageCollectionT unknown { get(id: string): PromiseT | null; put(id: string, data: T): Promisevoid; delete(id: string): Promiseboolean; exists(id: string): Promiseboolean; getVersioned(id: string): Promise{ value: T; revision: string } | null; compareAndSet( id: string, expectedRevision: string | null, data: T, ): Promise{ applied: true; revision: string } | { applied: false }; compareAndDelete(id: string, expectedRevision: string): Promise{ applied: boolean }; updateIf(id: string, args: UpdateIfArgsT): PromiseUpdateIfResultT; getMany(ids: string[]): PromiseMapstring, T; putMany(items: Array{ id: string; data: T }): Promisevoid; deleteMany(ids: string[]): Promisenumber; query(options?: QueryOptions): Promise{ items: Array{ id: string; data: T }; cursor?: string; hasMore: boolean; }; count(where?: WhereClause): Promisenumber; }注意Node/workerd 包装器还包含内容批量方法content batch methods但它们不属于StorageCollection上表中存储批量方法在两个运行时之间都是可移植的。基本写入与批量写入const submissions ctx.storage.submissions as StorageCollectionSubmission; await submissions.put(sub_123, { formId: contact, status: pending, createdAt: new Date().toISOString(), }); const item await submissions.get(sub_123); const exists await submissions.exists(sub_123); const items await submissions.getMany([sub_123, sub_456]); await submissions.putMany([ { id: sub_456, data: { formId: contact, status: pending } }, { id: sub_789, data: { formId: sales, status: pending } }, ]); const deleted await submissions.deleteMany([sub_456, sub_789]);getMany()返回Map跨越任一条沙箱桥后仍保持该语义因此可以放心地以Map.get(id)方式读取批量结果。基于修订号的比较并交换CAS当并发请求可能替换同一个完整值时使用getVersioned()、compareAndSet()与compareAndDelete()const current await submissions.getVersioned(sub_123); if (!current) throw new Error(Submission not found); const result await submissions.compareAndSet(sub_123, current.revision, { ...current.value, status: processing, }); if (!result.applied) { // 另一个请求已修改或删除该值先重新读取再重试。 }各操作的前置条件操作行为getVersioned(key)返回{ value, revision }仅当键不存在时返回nullcompareAndSet(key, null, value)仅在键不存在时创建compareAndSet(key, revision, value)仅当当前修订号匹配时替换compareAndDelete(key, revision)仅当当前修订号匹配时删除几点关键语义存储的 JSONnull仍会返回版本化信封即getVersioned返回{ value: null, revision }而非null只有“行不存在”才返回null这一点在 packages/core/src/plugins/types.ts 有明确注释每次成功写入都会改变修订号包括写入相同值的put()/set()修订号是不透明的、按键隔离的值原样回传即可冲突返回applied: false非法输入、权限失败、唯一索引冲突、数据库故障则以 reject 形式抛出冲突后请重新读取、重新计算并保持重试次数有界丢失的响应可能使写入结果未知因此CAS 不是外部副作用的恰好一次exactly-once机制。版本化方法同样适用于ctx.kvconst current await ctx.kv.getVersionednumber(state:completed); const next (current?.value ?? 0) 1; const result await ctx.kv.compareAndSet(state:completed, current?.revision ?? null, next);谓词守卫更新 updateIfupdateIf()在存储数据匹配守卫时修改既有文档的字段。守卫、字段替换与整数增量对该记录原子执行是不超卖no-oversell的原语守卫与算术在同一个UPDATE … RETURNING语句中完成N 个并发守卫递减会被正确串行化见 packages/core/src/plugins/types.ts 的注释。const result await submissions.updateIf(sub_123, { where: { status: pending, attempts: { lt: 3 } }, set: { status: processing, lastAttemptAt: new Date().toISOString() }, delta: { attempts: { inc: 1 } }, }); if (result.applied) { ctx.log.info(Claimed submission, { submission: result.data }); }updateIf()在以下情况返回{ applied: false }行不存在、守卫失败、存储文档不是对象、整数运算不安全。它从不插入。规则where必填显式{}表示匹配任意既有行set替换提供的顶层字段其余字段保持不变delta每个字段恰好包含一个安全整数inc或dec缺失或为null的计数器从零开始同一字段不能同时出现在set与delta中set或delta中至少要保留一个已定义字段需要保证值非负时请将dec: n与gte: n守卫配对使用。参数校验逻辑在 packages/core/src/plugins/storage-update.ts守卫操作数必须是字符串或有限数值delta必须是恰好一个inc/dec的安全整数字段名经过 JSON 字段名校验。格式错误的参数会在不写入的情况下 reject。串行化失败与死锁在原生 PostgreSQL 执行中串行化失败与死锁会抛出StorageSerializationError其code为STORAGE_SERIALIZATION_FAILURE、retryable为true定义见 packages/core/src/plugins/storage-query.ts。两种触发场景40001serialization_failure仅在高于 READ COMMITTED 的隔离级别出现失败方无法基于更新的快照重读40P01deadlock_detected任意隔离级别下事务按相反顺序获取行锁时出现。沙箱传输层会保留安全字段但不保证instanceof关系因此跨沙箱时请检查code与retryable字段。重试整个显式事务前请先重启该事务。无论哪种情况失败的写入者永远不会应用其更新——要么得到{ applied: false }要么抛出该错误这是不超卖安全不变量的保证。索引查询只有已声明的索引字段才能被过滤或排序const result await submissions.query({ where: { formId: contact, status: { in: [pending, processing] }, createdAt: { gte: 2026-01-01 }, }, orderBy: { createdAt: desc }, limit: 100, cursor, });支持的过滤器类型精确值、{ in: [...] }、{ startsWith: ... }、范围对象使用gt、gte、lt或lte。范围过滤器至少需要一个已定义的边界。query()默认返回 50 条每页最多 100 条当hasMore为 true 时沿cursor继续翻页count(where)接受同样的索引过滤器复合索引顺序决定可用的查询形态[formId, createdAt]支持按formId过滤并按createdAt排序但不能替代省略formId时所需的独立createdAt索引。查询校验与 SQL 构建在 packages/core/src/plugins/storage-query.ts 中实现对非索引字段执行过滤或排序会抛出StorageQueryError其suggestion会直接提示你将该字段加入清单的storage.collection.indexes。startsWith会先对%与_等 LIKE 元字符做转义escapeLikePattern见 storage-query.ts避免前缀被当作通配符数值比较在 PostgreSQL 上通过类型守卫的::numeric强制转换避免词法排序9 10为真的陷阱SQLite 则天然返回类型化数值。范围过滤器若无任何已定义边界会被直接拒绝storage-query.ts避免在条件写操作中意外剥掉守卫。KV 操作KV 支持无条件、版本化、删除与前缀列举操作interface KVAccess { getT(key: string): PromiseT | null; set(key: string, value: unknown): Promisevoid; delete(key: string): Promiseboolean; list(prefix?: string): PromiseArray{ key: string; value: unknown }; getVersionedT(key: string): Promise{ value: T; revision: string } | null; compareAndSet( key: string, expectedRevision: string | null, value: unknown, ): Promise{ applied: true; revision: string } | { applied: false }; compareAndDelete(key: string, expectedRevision: string): Promise{ applied: boolean }; }运行时类型KVAccess定义见 packages/core/src/plugins/types.ts。约定state:*存放内部插件状态不展示给用户cache:*存放可复用的计算结果或远端数据。用稳定的前缀让内部 KV 键可被发现await ctx.settings.set(webhookUrl, url); await ctx.kv.set(state:lastRun, new Date().toISOString()); await ctx.kv.set(cache:summary, summary); const settings await ctx.settings.list();设置Settings与加密密钥插件 CLI 会序列化admin.settingsSchema两条沙箱桥都将ctx.settings路由到与生成的 admin 表单相同的 options 记录上因此表单中保存的值可以通过ctx.settings.get(key)读到。完整的设置 API 支持set、delete、list、getVersioned、compareAndSet、compareAndDelete运行时实现见 packages/core/src/plugins/settings.ts键前缀为plugin:pluginId:settings:。secret 字段的 AES-GCM 信封声明为secret的字段使用带版本的 AES-GCM 信封加密**插件 ID 与设置键作为认证数据additional data**参与运算packages/core/src/plugins/settings.ts因此密文无法被复制到其他插件或键名下解密。信封结构为{ $emdash: plugin-setting, v: 1, kid, iv, ciphertext }settings.ts。EMDASH_ENCRYPTION_KEY可包含逗号分隔的轮换列表第一个键加密新值信封中的kid选择读取时使用的键缺失、错误或被篡改的密钥一律失败关闭fail closed不泄露明文既有明文密钥仍可读取再次保存时会被加密。kid是解码后的密钥字节的 SHA-256 前 8 个字符packages/core/src/config/secrets.ts解析逻辑要求每个条目形如emdash_...前缀加固定长度 base64url 主体并可用emdash secrets generate生成。密钥轮换、校验、去重与启动时验证也都集中在该文件中。运维提醒请将完整密钥列表随操作备份一起保留。如果数据库恢复到不包含其加密设置所引用的全部密钥这些值将无法读取。此外ctx.kv.get(settings:key)在整个 EmDash 0.x 中仍是兼容别名新插件应改用ctx.settingspackages/core/src/plugins/types.ts 亦注明该约定。总结集合ctx.storage清单声明 索引约束驱动提供 CRUD、批量、CAS、updateIf原子守卫与索引分页查询跨原生 / Cloudflare / workerd 三种执行环境可移植设置ctx.settings与 admin 表单同源的 options 存储secret字段走 AES-GCM 信封加密支持密钥轮换与 fail-closedKVctx.kv轻量键值状态建议用state:/cache:前缀组织同样支持版本化并发原语。三者共用宿主数据库、按插件 ID 隔离且无需 capability。在并发场景下优先使用compareAndSet/updateIf而非读-改-写三步操作并始终把重试次数控制得有界——这是从本仓库的存储实现中提炼出的最重要的一条工程经验。赞分享CMS后端前端插件系统【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址https://gitcode.com/gh_mirrors/emdas/emdash点击查看免费下载相关推荐EmDash 插件存储指南Storage、Settings 与 KV 的声明、读写与并发控制EmDash 插件存储指南Storage、Settings 与 KV 的声明、读写与并发控制 EmDash 为沙箱化插件提供了三套插件级数据 API可查询的CMS后端前端插件系统EmDash 插件存储指南基于 Sandboxed 插件的 Collection、Settings 与 KV 数据 API 实战EmDash 插件存储指南基于 Sandboxed 插件的 Collection、Settings 与 KV 数据 API 实战 导读 本文是 EmDashCMS后端前端插件系统EmDash 插件存储与 KV 完全指南ctx.storage、ctx.settings 与 ctx.kv 的声明、并发控制与加密实践EmDash 插件存储与 KV 完全指南ctx.storage、ctx.settings 与 ctx.kv 的声明、并发控制与加密实践 沙盒化插件SandbCMS后端前端插件系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考