Activepieces 架构决策记录ADR体系编号永不复用、以原因为中心的决策日志【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepiecesActivepieces 仓库在 brain/knowledge/decisions 目录维护了一份架构决策记录Architecture Decision Record, ADR日志每条记录对应一个难以逆转的技术决策以及产生该决策的完整推理。本篇文章围绕这份决策日志的组织约定展开并结合仓库内已落地的 11 条决策记录说明如何通过编号永不复用 原因优先的机制让一段架构演进史保持可追溯、可引用、可学习。一、决策日志是什么一条记录 一个难以逆转的决策打开 decisions/index.md第一句话就给出了整个目录的定位One hard-to-reverse call per record, with the reasoning that produced it. 每条记录对应一个难以逆转的决策以及产生该决策的推理。也就是说这个目录不是变更日志changelog不记录我们做了什么改动它记录的是**我们为什么做了这个决定**——尤其是那些一旦做出就难以回头的架构选择。例如000001-worker-is-the-sandbox-one-job-per-worker-scale-by-replicas.md 决定Worker 即沙箱一个 worker 一次只轮询一个任务concurrency 1在进程内用 node child isolated-vm 运行引擎不再有独立的沙箱容器、不再有/execute远程跳转、不再有 Docker socket、不再有资源池。这是一个牵一发动全身的执行架构决策一旦 worker 镜像承载了完整执行工具链就很难再退回去。000010-async-webhook-ack-is-redis-durable-not-postgres-durable.md 决定异步 Webhook 的 ACK 依赖 Redis 持久化AOFeverysec而非先写 Postgres 行——这是对Webhook 吞吐上限与最多 1 秒丢失窗口之间权衡的一次不可逆取舍。每条记录都遵循这一范式先说决策再说背景再说为什么是它胜出最后说它把你承诺到了什么地步。二、编号约定一次分配、永不复用index.md 给出了目录最核心的治理规则——编号语义Each file in this folder is numbered, and the number is assigned once and never reused, so a link to a decision stays good and the sequence tells you what came after what.编号一次分配、永不复用即使某条决策后来被修订甚至推翻例如 000001 被 000002 修订原编号依然保留不会回收给新决策使用。这保证了任何外部链接一旦指向某条记录就永远有效。顺序即历史编号的先后就是决策产生的先后。阅读整个目录的文件列表从000001到000034就能还原出 Activepieces 执行架构、文件分发、计费限额等主题的演进时间线。链接永不失效由于编号不复用文档里引用决策 000009是稳定的锚点不会因为后续新增决策而漂移。一个很好的实例是 000001 与 000002 的承接关系000002 的标题是Transitional multi-box concurrency (honor AP_WORKER_CONCURRENCY)其正文开篇就声明 Amends, does not supersede, Worker is the Sandbox.修订而非取代 000001。它没有改掉 000001 的编号而是在新编号下记录过渡期的多盒并发是向 concurrency-1 目标进发的向后兼容桥梁。编号系统因此天然支持决策的修订链旧决策保持原样可查新决策在后续编号中记录对它的修订。三、记录的标准结构Decision / Context / Why / Consequencesindex.md 明确要求每条记录必须写清四件事Write the decision—— 决策本身the context it was made in—— 做出决策时的背景why this option won over the alternatives—— 为什么这个选项战胜了备选方案what it commits you to—— 这个决策让你承诺承担了什么后果。仓库内的记录几乎全部遵循这一骨架。以 000009-approval-links-require-a-post-confirmation-on-a-dedicated-route.md 为例Decision审批邮件不再直接放两个裸 GET 链接而是指向专用的/:id/waitpoints/:waitpointId/confirm路由GET/HEAD 只渲染确认页绝不消费 waitpoint只有按钮触发的 POST 才会恢复流程。Context暂停流程的恢复端点是无鉴权、单次使用的唯一防护是难以猜测的 id。而邮件安全扫描器Microsoft Safe Links、Mimecast、Proofpoint会在投递前用 GET 预取 URL预取与真人点击无法区分导致 waitpoint 被提前消费、流程被以任意结果恢复Pylon #5253 回归。Why不改变状态的 GET 对扫描器是安全的只有有意的 POST 才决定结果同时新路由不动旧路由已投递的邮件继续可用Slack 因其按钮由服务端 POST 触发而天然免疫。Consequences新审批邮件对扫描器安全预取只渲染页面绝不恢复流程确认页事后只显示已回应而不显示具体决定因为 waitpoint 恢复即删除、决定不持久化持久化需要 schema 变更明确划出范围。index.md 特别强调 Why 是整条记录中最不可省略的部分The why is the part that stops the same argument being had again in six months, and it is the part nobody remembers without a record. 为什么是阻止六个月后同一场争论重演的部分也是没有记录就没有人记得住的部分。正因为如此每条记录的 Why 小节都会明确列出被否决的备选方案及其落选理由。例如000001 记录了被取代的 LOCAL_POOL / GCP_CLOUD_RUN 探索worker 作为池管理器通过 HTTP 分发其最大风险是需要 Docker socket 与远程 HTTP 边界。000006-pieces-are-distributed-as-links-resolved-lazily.md 拒绝了 PR #13865 的预热的批量同步 全局nameversionS3 key方案理由是冷启动成本、缺少租户隔离、鉴权更弱。000008-streaming-file-writes-go-through-the-app-one-path.md 否决了给沙箱直接发 S3 凭证沙箱要运行任意 piece 代码也否决了引擎侧编排的分片直传协议新协议 状态机 孤儿清理面。四、一次真实的决策修订000008 的 Aug 2026 修正决策记录不是写完就冻结的教条编号机制允许在同一编号下追加修订说明。000008流式文件写入统一走应用提供了一个教科书级的例子原始决策是ctx.files.write()接受Readable流式写入以无Content-Length的分块 PUT 发给应用应用用aws-sdk/lib-storage以约 5 MB 分片流式落 S3或缓冲为 DBbytea。但记录内追加了Amended Aug 2026修正段the engine no longer sends that chunked PUT. It drains aReadableto aBuffer(capped byAP_MAX_FILE_SIZE_MB) and always declares aContent-Length.原因是缓冲代理会在上游加上该请求头导致应用做重定向signed URL时无法重放一个已经被消费过的 body。而单次写入本就远低于沙箱内存预算流式传输没有买到任何东西反而付出了整段传输重试和 S3→DB 回退的代价。应用侧的流式 ingest 保持不变因为它在没有 signed-URL 重定向的部署里依然对所有部署生效。这条修正展示了决策记录的自我纠错能力原始决策、修正内容、修正理由、受影响边界引擎侧 vs 应用侧全部在同一条记录内留痕读者不会被仓库里看起来矛盾的代码弄糊涂——文档层面已经解释了矛盾从何而来。相关细节可继续参阅 File Storage 的 gotchas 段落。五、从记录看架构主题的演进链把多条记录串起来读就能还原出 Activepieces 几个关键架构主题的决策链条。5.1 执行架构000001 → 000002000001 确立终态worker 即沙箱每 worker 一任务靠副本数水平扩展。每个副本被限制在 0.5 CPU / 1 GB一个任务一个受限容器意味着 OOM 只杀死一个 worker进程内槽位复用带来的共享堆棘轮效应不可能跨任务发生单一执行路径消除了 seam、远程传输、provisioner 和 HTTP 信封。000002-transitional-multi-box-concurrency-honor-ap-worker-concurrency.md 则是过渡桥梁直接只发布 concurrency-1 会让现有AP_WORKER_CONCURRENCYN部署一夜之间吞吐降到 1/N因此 worker 先用createSandboxRuntime({ concurrency })维护 N 个进程内沙箱盒、按workerIndex路由任务默认值恢复为 5。记录同时警告N1 时 N 个引擎子进程共享一个容器 cgroup单个失控流程可能 OOM 杀死整个容器——这正是 000001 想要消除的共享容量棘轮所以临时性是有意为之绝不能成为架构。5.2 分发与可复现性000005 → 000006000005-freeze-piece-versions-in-the-flow-bundle-manifest.mdFlow Bundle 的pieces.json清单在构建时冻结 piece 的解析后版本而不是每次运行重新解析^范围。因为已锁定的流程版本是不可变快照bundle 已冻结流程定义和编译产物让 piece 范围在已锁定版本下悄悄浮动到更新的补丁版本反而更令人意外。冻结后锁定版本字节级可复现还省去了运行时的 per-piecegetPiece往返。草案版本不受影响始终实时解析 piece。000006每个 piece 以单个可下载链接.tgz分发由引擎令牌、平台作用域的GET /v1/engine/pieces/bundle?nameversion端点 307 重定向到签名 S3 对象 / 官方 piece 的 npm tarball / 自定义 ARCHIVE piece 的文件存储。沙箱下载链接后bun install所有 piece 类型走同一条路径piece 字节不经过 worker socket。S3 副本惰性预热预热任务以jobId bundle:platformId|global:name:version去重。平台作用域是强制性的数据隔离规则自定义 piece 的 S3 key 按平台命名空间隔离堵住了原全局 key 方案的跨租户nameversion碰撞。5.3 数据路径与持久化取舍000003 → 000008 → 000010 → 000011000003-engine-posts-run-time-callbacks-directly-to-the-app.md引擎把四个运行时回调updateRunProgress、updateStepProgress、sendFlowResponse、uploadRunLog通过internalApiUrlengineToken直接 HTTP POST 到应用的/v1/engine/*ENGINE 主体删除 engine→worker 中继。uploadRunLog是刻意保留的双源worker 仍需以 WORKER 主体上报引擎自己无法上报的终态crash、OOM、INTERNAL_ERROR由同一应用侧服务承接两端入口。000008文件写入统一走应用这一条路径含 5.1 节所述的 Aug 2026 引擎侧修正。000010异步 Webhook 入队 Redis 即返回 200带x-webhook-id不写 Postgres 行。吞吐由 Redis 延迟决定且能在 Postgres 故障转移期间存活流程解析由 Redis 缓存提供。代价是 Redis 数据集丢失会在持久化窗口内静默丢弃已确认但未开始的 webhook——这是 Redis 中唯一不可重建的数据其余都能从 Postgres 重建因此记录给出的运维结论是 Dont back up Redis; persist it不要备份 Redis要持久化它。持久化参数由运维者的redis.conf调节对应文档见 disaster-recovery.mdx。000011-webhook-files-stream-to-s3-by-dropping-global-multipart-buffering.md删除fastify/multipart的全局attachFieldsToBody和fastify-raw-body的全局缓冲Webhook 路由改用request.parts()流式读入multipart 与二进制流直通 S3。代价是 multipart 的签名校验被放弃HMAC-over-file-upload 罕见且仅当FILE_STORAGE_LOCATIONS3时才真正流式DB 存储缓冲为bytea。5.4 安全与计费治理000009 → 000013000009见第三节用GET 只渲染、POST 才恢复对抗邮件安全扫描器的预取。000013-active-user-seat-floor-is-enforced-db-authoritatively.md活跃用户数不得超过套餐席位上限usersLimit。早期设计试图让 Autumn 控制台console.activepieces.com做独立 backstop但因客户作用域 key 无法调用balances.update403、且控制台读回的正是 AP server 自己写入的数字循环的、最终一致性的拷贝存在 TOCTOU 窗口而放弃。最终决定在唯一一处——AP server 自己的数据库上执行新增/邀请由checkUsersExceededLimit把关usedSeats 活跃用户 预留邀请对应决策 000014降低限额由assertSeatsNotBelowActiveUsers把关对应 000017 的effectiveUsersLimitUI 在降级前主动弹出停用用户对话框后端校验是权威检查。这组记录还展示了决策之间的相互引用000013 引用 000014邀请预留席位与 000017计划降级即时生效共同构成计费限额的完整语义。六、目录定位它就是一个普通文件夹index.md 最后一节特意澄清了目录的实现方式This folder is an ordinary folder. It has anindex.mdbecause every folder page does, and the decisions inside it are its children. Nothing special-cases it.即该目录没有任何特殊处理index.md只是因为文档系统的每个目录页都需要一个索引页而存在各条决策记录就是它的子页面。这个说明对读者有两层含义新增记录的约定即规范不需要任何工具或脚本配合照编号续写 markdown 文件即可链接与检索都是普通的记录之间的相互引用如 000013 指向 000014、000017000008 指向 File Storage就是仓库内的普通相对链接全库可搜、可跳转。七、如何阅读与借鉴这套 ADR 体系对想要快速了解 Activepieces 架构内核的读者推荐按主题而非按编号阅读执行与沙箱000001 → 000002理解worker 即沙箱的终态设计与向后兼容过渡piece 分发与可复现000005 → 000006理解锁定版本如何保持字节级可复现、piece 如何以链接惰性分发数据与事件路径000003 → 000008 → 000010 → 000011理解引擎回调、文件写入、Webhook ACK 与 Webhook 文件流各自的数据路径取舍安全与治理000009、000013理解审批链接防预取、席位上限的单一事实来源。对于其他项目团队这套体系的要点可以概括为三条可迁移的实践编号一次分配永不复用链接永久稳定、顺序即历史、每条记录强制包含 Decision / Context / Why / Consequences 四段把备选方案与落选理由写进 Why让争论只发生一次、允许在同一编号下追加修订说明决策的自我纠错同样留痕而非悄悄改写历史。索引页本身刻意保持简短因为它定义的是约定而约定的证据——几十条结构严谨的决策记录——就散落在 brain/knowledge/decisions 目录中随时可以逐条查阅。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考