破坏性变更

此列表显示了所有包含破坏性变更的版本以及如何升级。

0.85.4

变更了什么？

引用步骤输出

以前，如果你有一个名为 step_1 的步骤，你需要引用为 “step_1[‘the_property_you_want’]“，但现在你必须引用为 “step_1[‘output’][‘the_property_you_want’]“，已有迁移脚本会为你处理此问题，但如果你是通过手动编写/编辑步骤引用而非通过构建器，则必须遵循此新语法。 你现在还可以通过 “step_1[‘error’]” 引用步骤错误，这些变更随错误处理功能一起提供。 此外，构建器中悬停时显示的步骤名称现已移除，你可以右键点击步骤并复制其引用。

在 worker 和应用服务器上强制使用相同版本的 Docker 镜像

以前，如果你的 worker 与应用服务器版本不同，大多数情况下 worker 仍能正常工作，但由于我们的一些变更要求两者版本相同，因此我们添加了此保护措施。

0.84.0

变更了什么？

工作流运行日志大小限制

这是工作流运行日志存储和上限方面的重要行为变更，但无需操作——现有的默认值（AP_MAX_FLOW_RUN_LOG_SIZE_MB=50）保持不变。

  • 大的步骤输出现在被卸载到对象存储而非内嵌在 worker 内存中，由新的 AP_FLOW_RUN_LOG_SLICE_THRESHOLD_KB 环境变量控制（默认 32）。
  • 大的步骤输入值被替换为 (truncated, original size <N>) 占位符记录在日志中，由新的 AP_FLOW_RUN_LOG_INPUT_TRUNCATE_THRESHOLD_KB 环境变量控制（默认 2）。步骤在运行时仍然接收完整值。
  • 步骤输入和输出总和超过 AP_MAX_FLOW_RUN_LOG_SIZE_MB 的运行现在会以新的 LOG_SIZE_EXCEEDED 状态终止，而非静默截断输入。已卸载的输出仍然按其原始大小计入上限。
  • 参见技术限制 → 文件与工作流运行日志了解完整行为、环境变量和默认值。
  • 嵌入现在需要设置允许的嵌入来源，这意味着只有列出在该字段中的域名可以嵌入应用（支持通配符）。还有一个新的环境变量 AP_ALLOWED_EMBED_ORIGINS 用于设置预允许的来源，以及一个新的端点用于添加这些来源——查看文档。

你需要采取行动吗？

  • 嵌入——如果你在某个地方嵌入了自托管的 activepieces，请确保它在允许列表中

0.83.0

变更了什么？

现在创建项目时，平台所有者邮箱不会自动添加到项目的警报接收者列表中，你可以在 UI/API 中手动分配。

0.82.0

变更了什么？

Piece 版本现在固定不变

  • Piece 版本不再使用通配符存储（~1.2.0、^1.2.0）。所有 piece 步骤现在使用确切的版本（例如 1.2.0）。
  • 升级时，迁移脚本会自动从所有现有工作流版本中去除通配符前缀。
  • LOCK_AND_PUBLISH 操作不再在发布时解析 piece 版本——步骤使用工作流中存储的确切版本运行。
  • 构建器中新增了版本切换器 UI，允许用户手动升级或降级 piece 版本。

REST API

  • ADD_ACTION、UPDATE_ACTION 和 UPDATE_TRIGGER 现在在保存前会去除 pieceVersion 中的通配符前缀（~、^）。如果你依赖通配符版本在发布时自动解析，你的步骤现在将固定为基础版本（例如 ~1.2.0 变为 1.2.0）。
  • LOCK_AND_PUBLISH 不再修改任何步骤上的 pieceVersion。草稿中的版本即为将要运行的版本。
  • 新增端点 GET /v1/pieces/:name/versions 用于列出 piece 的所有版本，方便构建自定义版本选择。

并发任务环境变量重命名

  • AP_MAX_CONCURRENT_JOBS_PER_PROJECT → AP_DEFAULT_CONCURRENT_JOBS_LIMIT。默认值从 100 降为 5。

出站 HTTP 现受 SSRF 过滤

  • 服务端 HTTP（OAuth、Vault、Conjur、事件目标、on-call pager、MCP 验证器）现在会拦截私有、回环和云元数据 IP。通过将内部主机的 IP/CIDR 添加到 AP_SSRF_ALLOW_LIST 来访问。

你需要采取行动吗？

  • 固定 piece 版本——如果你通过 REST API 使用通配符版本（~ 或 ^）创建或更新工作流，请切换到确切版本；通配符会被静默去除。如果你的发布流程依赖 LOCK_AND_PUBLISH 解析通配符，请在发布前在每个步骤上设置确切版本。使用 GET /v1/pieces/:name/versions 列出可用版本。
  • 并发任务——将 AP_MAX_CONCURRENT_JOBS_PER_PROJECT 重命名为 AP_DEFAULT_CONCURRENT_JOBS_LIMIT。要保留旧的上限，设置 AP_DEFAULT_CONCURRENT_JOBS_LIMIT=100。
  • SSRF 过滤器——如果你在私有 IP 上自托管 Vault、Conjur、OAuth2 令牌端点或任何内部 Webhook，请在升级前设置 AP_SSRF_ALLOW_LIST（逗号分隔的 IP 或 CIDR，例如 10.0.5.12,192.168.10.0/24）。

0.80.0

变更了什么？

基础设施

  • 引入了新的环境变量 AP_MAX_WEBHOOK_PAYLOAD_SIZE_MB 来控制最大允许的 Webhook 负载大小。默认值为 25 MB。超过此限制的 Webhook 将被拒绝并返回 413 Request Too Long 响应。
  • Nginx 已从 Docker 镜像中移除。Fastify 现在直接提供 API 和 React 前端。所有 API 路由现在原生位于 /api 前缀下。如果你使用 /v1/health 作为健康检查端点（例如在 Kubernetes 探针或负载均衡器检查中），请将其更新为 /api/v1/health。
  • 密钥管理器已重构，0.79.0 版本不再受支持，虽然没人使用过，但值得提一下，在使用此功能前需要升级到 0.80.0。

API

  • 引入了新的 UPDATE_SAMPLE_DATA_INFO 工作流操作，用于独立处理示例数据更新。
  • UPDATE_ACTION 和 UPDATE_TRIGGER 不再接受或应用步骤设置中的 sampleData 更改。在这些请求中发送的任何 sampleData 字段将被忽略，现有示例数据将被保留。
  • 所有动作和触发器新增了必需的 lastUpdatedDate 字段，由服务器自动跟踪。UPDATE_ACTION 或 UPDATE_TRIGGER 请求不接受此字段。

你需要采取行动吗？

  • 如果你想将 Webhook 负载大小限制在 25 MB 默认值以下，请将 AP_MAX_WEBHOOK_PAYLOAD_SIZE_MB 设置为你想要的限制。
  • 如果你通过 UPDATE_ACTION 或 UPDATE_TRIGGER 使用 API 更新步骤上的示例数据，请改用新的 UPDATE_SAMPLE_DATA_INFO 操作。
  • 如果你有指向 /v1/health 的自定义健康检查，请将其更新为 /api/v1/health。

0.78.1

变更了什么？

  • 平台的 Operator 角色现在可以编辑所有项目。

你需要采取行动吗？

  • 仅当你希望限制操作员对每个项目的编辑访问权限时才需要。根据需要审查你的操作员权限。

0.78.0

变更了什么？

  • usageCount 字段已从模板 API 响应和数据库中移除——不再可用。
  • Todos 功能现已弃用，后续将不再支持。

你需要采取行动吗？

  • 如果你正在使用 Todos 功能，请更新你的工作流以使用 Piece 选择器审批标签中可用的新审批渠道。

0.77.0

变更了什么？

  • 对于嵌入计划用户：点击”新建工作流”按钮时不再弹出”使用模板”对话框。
  • /flow-templates API 端点已移除，替换为 /templates。
  • 日志大小配置已更改：AP_MAX_FILE_SIZE_MB 不再控制工作流运行日志。请使用 AP_MAX_FLOW_RUN_LOG_SIZE_MB 替代。

你需要采取行动吗？

  • 如果你使用嵌入计划，请更新你的实现，将用户重定向到 /templates 页面。
  • 查看新端点文档：Templates API Schema。
  • 如果你为 AP_MAX_FILE_SIZE_MB 使用了自定义值，请确保同时相应地设置 AP_MAX_FLOW_RUN_LOG_SIZE_MB。

0.75.0

变更了什么？

  • 当你在构建器中导航到工作流运行时，URL 将变更为 /runs，这可能会影响到嵌入客户，如果他们有仅允许用户导航到 /flows 的路由守卫。
  • 在开发模式下，默认不加载 piece 翻译。设置 AP_LOAD_TRANSLATIONS_FOR_DEV_PIECES=true 以启用。

你需要采取行动吗？

  • 检查你的嵌入导航处理器，看是否会阻止用户查看构建器中的运行记录。
  • 如果你想在开发模式下加载 piece 翻译，请在环境变量中设置 AP_LOAD_TRANSLATIONS_FOR_DEV_PIECES=true。

0.74.0

变更了什么？

  • 用于开发和轻量级部署的默认嵌入式数据库已从 SQLite3 变更为 PGLite（嵌入式 PostgreSQL）。
  • 环境变量 AP_DB_TYPE=SQLITE3 现已弃用，替换为 AP_DB_TYPE=PGLITE。
  • 现有的 SQLite 数据库将在首次启动时自动迁移到 PGLite。
  • 此版本的模板功能存在故障。迁移问题导致模板 ID 更改，破坏了 API 端点。这将在下一个补丁版本中修复。
  • 每个项目的 aiCredits 功能已移除。在下一版本中，它将由与 AI Gateway 的集成替代。

你需要采取行动吗？

  • 如果你正在使用 AP_DB_TYPE=SQLITE3： 将配置更新为使用 AP_DB_TYPE=PGLITE。
  • 如果你正在使用模板： 等待下一个补丁版本修复模板 ID。

0.73.0

变更了什么？

  • MCP 的重大变更：阅读公告。
  • 如果你在平台管理中配置了 SMTP，它不再受支持——你需要使用 AP_SMTP_ 环境变量。

你需要采取行动吗？

  • 如果你当前正在使用 MCP，请查看链接的公告以了解重要的迁移详情和升级指南。

0.71.0

变更了什么？

  • 在独立的 worker 设置中，现在它们可以访问 Redis。
  • AP_EXECUTION_MODE 的 SANDBOXED 模式现已弃用，替换为 SANDBOX_PROCESS。
  • Code Copilot 已弃用。它将在未来以不同的、更强大的形式重新引入。

何时需要操作？

  • 如果你有独立的 worker 设置，应确保 worker 可以访问 Redis。
  • 如果你使用 AP_EXECUTION_MODE 的 SANDBOXED 模式，应将其替换为 SANDBOX_PROCESS。

0.70.0

变更了什么？

  • AP_QUEUE_MODE 现已弃用，替换为 AP_REDIS_TYPE。
  • 如果你使用 Sentinel Redis，应将 AP_REDIS_TYPE 设置为 SENTINEL。

何时需要操作？

  • 如果你使用 AP_QUEUE_MODE，应将其替换为 AP_REDIS_TYPE。
  • 如果你使用 Sentinel Redis，应将 AP_REDIS_TYPE 设置为 SENTINEL。

0.69.0

变更了什么？

  • AP_FLOW_WORKER_CONCURRENCY 和 AP_SCHEDULED_WORKER_CONCURRENCY 现已弃用，所有任务使用单一队列，替换为 AP_WORKER_CONCURRENCY。

何时需要操作？

  • 如果你使用 AP_FLOW_WORKER_CONCURRENCY 或 AP_SCHEDULED_WORKER_CONCURRENCY，应将其替换为 AP_WORKER_CONCURRENCY。

0.66.0

变更了什么？

  • 如果你使用嵌入 SDK，请升级到 0.6.0 版本，embedding.dashboard.hideSidebar 用于隐藏仪表板中工作流表格上方的导航栏，现在它依赖于 embedding.dashboard.hideFlowsPageNavbar。

0.64.0

变更了什么？

  • MCP 管理已从嵌入 SDK 中移除。

0.63.0

变更了什么？

  • Replicate 提供商的文本模型已移除。

何时需要操作？

  • 如果你正在使用 Replicate 的文本模型，应将其替换为其他提供商的模型。

0.46.0

变更了什么？

  • Pieces 中的”属性数组”输入 UI 已更新，特别是影响”动态值”切换功能。

何时需要操作？

  • 此变更无需操作。
  • 你已发布的工作流将继续正常运行。
  • 在编辑已发布的现有工作流（在”Utility AI” piece 的”提取结构化数据”动作中使用”属性数组”输入的”动态值”切换，如”files”参数）时，最终用户需要重新映射值。
  • 有关新 UI 实现的详细信息，请参阅此公告。

0.38.6

变更了什么？

  • Workers 不再依赖 AP_FLOW_WORKER_CONCURRENCY 和 AP_SCHEDULED_WORKER_CONCURRENCY 环境变量。这些值现在从应用服务器获取。

何时需要操作？

  • 如果在 worker 机器上 AP_CONTAINER_TYPE 设置为 WORKER，且在应用服务器上将 AP_SCHEDULED_WORKER_CONCURRENCY 或 AP_FLOW_WORKER_CONCURRENCY 设置为零，workers 将停止处理队列。要修复此问题，请查看将 Worker 与应用分离文档，并设置 AP_CONTAINER_TYPE 以从应用服务器获取必要的值。如果在 worker 机器上未设置容器类型，则这不是破坏性变更。

0.35.1

变更了什么？

  • AppConnection 实体中的 ‘name’ 属性已重命名为 ‘externalId’。
  • AppConnection 实体中新增了 ‘displayName’ 属性。

何时需要操作？

  • 如果你使用连接 API，应将 name 属性更新为 externalId，并添加 displayName 属性。

0.35.0

变更了什么？

  • 所有分支已转换为路由器，且不支持降级。

0.33.0

变更了什么？

  • 动作或触发器中的文件现在存储在数据库/S3 中，以支持从特定步骤重试，并且动作中文件的大小受 AP_MAX_FILE_SIZE_MB 的限制。
  • 触发器中的文件以前作为 base64 编码字符串传递；现在作为数据库/S3 中的文件路径传递。使用 0.29.0 或更早版本中触发器的工作流暂停后将不再工作。

何时需要操作？

  • 如果你在处理动作中的大文件，请考虑将 AP_MAX_FILE_SIZE_MB 增加到更高的值，并确保存储系统（数据库/S3）有足够的容量存放文件。

0.30.0

变更了什么？

  • AP_SANDBOX_RUN_TIME_SECONDS 现已弃用，替换为 AP_FLOW_TIMEOUT_SECONDS。
  • AP_CODE_SANDBOX_TYPE 现已弃用，替换为 AP_EXECUTION_MODE 中的新模式。

何时需要操作？

  • 如果你使用 AP_CODE_SANDBOX_TYPE 为 V8_ISOLATE，应将 AP_EXECUTION_MODE 切换为 SANDBOX_CODE_ONLY。
  • 如果你使用 AP_SANDBOX_RUN_TIME_SECONDS 设置沙箱运行时间限制，应切换为 AP_FLOW_TIMEOUT_SECONDS。

0.28.0

变更了什么？

  • 项目成员：
    • EXTERNAL_CUSTOMER 角色已弃用，替换为 OPERATOR 角色。请查看权限页面获取更多详情。
    • 所有待处理的邀请将被移除。
    • 引入了用户邀请实体以发送邀请。你仍然可以使用项目成员 API 为用户添加角色，但要求用户已存在。如果你想发送电子邮件，请使用用户邀请，用户接受并注册账户后，将在项目成员中创建记录。
  • 身份验证：
    • 允许用户注册不同平台/项目的 SIGN_UP_ENABLED 环境变量已移除。它已被邀请用户加入同一平台/项目替代。所有旧用户应继续正常工作。

何时需要操作？

  • 项目成员：

如果你使用嵌入 SDK 或带有 EXTERNAL_CUSTOMER 角色的创建项目成员 API，应开始使用 OPERATOR 角色替代。

  • 身份验证：

社区版不再支持多个平台/项目。从技术上讲，一切仍然存在，但由于身份验证系统已更改，你需要通过 API 进行 hack。如果你已经创建了用户/平台，它们应继续工作，无需操作。