Piece 同步与版本管理

Piece 的打包、分发以及与工作流版本的绑定机制

Piece 是标准的 npm 包。由此衍生出两个事实：

  • 新 Piece 无需服务器升级 — 同步作业会自动拉取新版本。
  • 每个步骤绑定到确切版本 — 工作流不会自动升级。更新通过构建器显式进行。
flowchart LR
    REG["npm registry<br/>(@activepieces/piece-*)"]
    CAT["本地 Piece 目录"]
    STEP["工作流步骤<br/>pieceVersion: 0.5.3"]
    UI["构建器版本对话框"]

    REG -- "每小时同步<br/>(OFFICIAL_AUTO)" --> CAT
    CAT -- "添加时使用确切版本" --> STEP
    UI -- "显式升级" --> STEP

    classDef src fill:#eef,stroke:#88a
    classDef catalog fill:#efe,stroke:#7a7
    classDef flow fill:#fee,stroke:#a77
    class REG src
    class CAT catalog
    class STEP,UI flow

打包

类型来源安装者
官方Activepieces 云注册表自动同步
自定义（npm）npm 注册表，限定一个平台平台管理员
私有（归档）.tgz 上传平台管理员

自定义和私有 Piece 需要手动管理 — 请参阅管理 Piece。

自动同步

AP_PIECES_SYNC_MODE行为
OFFICIAL_AUTO每小时与云注册表进行协调。所有部署的默认行为。

自定义和私有 Piece 不会受到同步作业的影响。

服务器兼容性

每个 Piece 在其定义中声明了 minimumSupportedRelease（以及可选的 maximumSupportedRelease）— 即与之兼容的 Activepieces 服务器版本范围。目录会根据运行中的服务器版本来过滤 Piece，因此超出范围的 Piece 不会在构建器中列出，也不会从注册表中提供。

**自托管用户：请升级到 `0.82.0` 或更新版本。** 每个新 Piece 现在都声明了 `minimumSupportedRelease ≥ 0.82.0`，这是伴随最新 piece-context 版本而来的最低要求。低于 `0.82.0` 的服务器将无法获取任何新发布的 Piece 或错误修复。Cloud 始终使用最新版本。

版本绑定

添加步骤时会记录当时的确切 Piece 版本（例如 0.5.3）。该绑定将一直保持，直到有人手动更改。要升级，请打开构建器中的步骤，点击其名称旁边的版本号，然后选择新版本。当变更跨越次版本或主版本边界时，对话框会发出警告。

相关