Activepieces 集成 HashiCorp Vault构建、认证配置与密钥管理动作全解析【免费下载链接】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导读本文以开源仓库 activepieces 中的 HashiCorp Vault 官方集成piece为对象完整讲解该模块的构建方式、连接认证配置、四个内置密钥管理动作读/写/删/列以及底层 HTTP 调用原理。读完本文你将掌握如何在 Activepieces 中构建并接入 HashiCorp Vault理解 Token 与 AppRole 两种认证方式的差异以及 KV v1 / v2 两种密钥引擎在 URL 与数据结构上的本质区别可直接照搬到自己的自动化流程中。本文内容以仓库文档 packages/pieces/community/hashi-corp-vault/README.md 为骨架所有实现细节均取自该模块源码可对照 src/index.ts、src/lib/auth.ts、src/lib/common/index.ts 以及 src/lib/actions/ 下的四个动作文件逐一验证。一、构建 piece 库HashiCorp Vault 集成是 Activepieces 众多社区 piece 之一位于packages/pieces/community/hashi-corp-vault包名为activepieces/piece-hashi-corp-vault。仓库中该模块的 README 明确给出了构建命令turbo run build --filteractivepieces/piece-hashi-corp-vault这是基于 Turborepo 的过滤构建--filter会只构建当前这个 piece而不触碰仓库中其他数百个 piece适合单独开发、调试与发布该模块。从 package.json 可以看到该模块的完整脚本{ name: activepieces/piece-hashi-corp-vault, version: 0.0.8, type: commonjs, main: ./dist/src/index.js, types: ./dist/src/index.d.ts, scripts: { build: tsc -p tsconfig.lib.json cp package.json dist/, bundle: node ../../../../dist/packages/cli/src/index.js pieces bundle, lint: eslint src/**/*.ts } }build先用 TypeScript 编译器按tsconfig.lib.json编译到dist/再把package.json复制进dist/保证发布产物自带包描述bundle调用 Activepieces CLI 把 piece 打包成可分发的 bundlelint对该模块源码执行 ESLint。构建产物的入口是dist/src/index.js即下文要分析的 src/index.ts。二、Piece 总览一个提供 5 类动作的开发者工具集成在 src/index.ts 中通过createPiece注册了这个集成export const hashiCorpVault createPiece({ displayName: HashiCorp Vault, description: Securely manage secrets and sensitive data with HashiCorp Vault, auth: hashiCorpVaultAuth, minimumSupportedRelease: 0.36.1, authors: [onyedikachi-david], categories: [PieceCategory.DEVELOPER_TOOLS], actions: [readSecret, writeSecret, deleteSecret, listSecrets, createCustomApiCallAction({...})], triggers: [], });关键信息displayName/description在 Activepieces 构建器界面中展示的名称与简介minimumSupportedRelease: 0.36.1要求 Activepieces 版本不低于 0.36.1 才能安装使用categories: [PieceCategory.DEVELOPER_TOOLS]归类为开发者工具方便在 piece 市场中被检索actions共 5 个动作——读密钥、写密钥、删密钥、列密钥外加一个通用的Custom API Call自定义 API 调用动作triggers为空数组说明该集成当前只提供动作、不提供触发器无法作为流程的启动节点。Custom API Call覆盖官方动作之外的任意 Vault 接口除四个内置动作外src/index.ts 还注册了一个由框架提供的通用动作createCustomApiCallAction。它的authMapping会根据认证方式动态生成请求头选择 Token 认证时直接使用连接里保存的 token选择 AppRole 认证时先调用POST {baseUrl}/v1/auth/{appRolePath}/loginbody 携带role_id与secret_id换取client_token再把 token 注入请求头无论哪种方式最终都会返回X-Vault-Token请求头若配置了 Namespace还会附带X-Vault-Namespace。也就是说凡是官方动作未覆盖的 Vault 接口如动态 secret、PKI、Transit 等都可以通过这一个通用动作以连接的身份直接调用baseUrl取自连接配置中的 Vault URL。三、连接配置Token 与 AppRole 两种认证方式连接connection是 Activepieces 中保存凭证的单元。Vault 集成的连接定义在 src/lib/auth.ts使用的是PieceAuth.CustomAuth即完全自定义的连接表单。字段如下字段类型必填默认值说明Vault URLShortText是—Vault 实例地址如https://vault.example.com:8200Authentication MethodStaticDropdown是token可选token或appRoleVault TokenSecretText视方法而定—Token 认证时必填Role IDShortText视方法而定—AppRole 认证时必填Secret IDSecretText视方法而定—AppRole 认证时必填AppRole Mount PathShortText否approleAppRole 认证方法的挂载路径NamespaceShortText否—Vault Namespace企业版功能未使用留空KV Secrets Engine VersionStaticDropdown是v2可选v1或v2几个值得注意的设计点敏感字段用PieceAuth.SecretTextVault Token 与 Secret ID 均以密文形式存储与展示避免密钥在构建器界面明文暴露而 Role ID、URL、Namespace 属于非敏感标识使用普通ShortText。认证方式决定必填项表单的validate函数会在保存连接时校验——Token 方式要求提供 Vault TokenAppRole 方式要求同时提供 Role ID 与 Secret ID缺少任一字段都会返回valid: false及对应错误提示。保存即校验连接测试validate不仅是表单校验还会真实发起一次到 Vault 的请求Token 方式直接使用 tokenAppRole 方式先执行一次登录换取client_token随后调用GET {baseUrl}/v1/auth/token/lookup-self验证 token 是否有效任一步骤失败都会返回Connection failed: 错误信息因此保存连接时就能确认网络、URL、Namespace 与凭证是否全部正确。AppRole 挂载路径可自定义默认approle若你的 Vault 将 AppRole 挂载在其他路径如my-approle可在连接中指定登录 URL 会相应变为{baseUrl}/v1/auth/my-approle/login。KV 引擎版本影响后续所有动作的 URL 与数据结构这是本集成最核心的配置项详见第五节。四、四个内置密钥管理动作四个动作均定义在 src/lib/actions/ 目录下公共逻辑复用 src/lib/common/index.ts。1. Read Secret读取密钥定义于 read-secret.ts动作名为read_secret。参数Secret Engine必填默认secret密钥引擎的挂载名Secret Path必填密钥路径如myapp/databaseVersion可选默认 0仅 KV v2 生效指定读取的历史版本号0 或省略表示最新版本。行为细节对 KV v2请求会打到/data/端点并仅在version 0时追加?version{version}查询参数对 KV v1请求打到/v1/{engine}/{path}端点Version 参数被忽略404 不报错路径不存在时返回success: false、空 data 及提示信息Secret not found at this path而不是抛出异常——这使动作在流程中表现为可分支处理的未找到结果其余错误如 403、网络失败会抛出Failed to read secret: ...异常让流程进入失败分支该动作在元数据中标记为idempotent: true幂等重复执行结果一致适合 AI Agent 在运行时安全地反复调用。KV v2 返回结构{ success: true, data: { username: myuser, password: mypassword }, metadata: { version: 3, created_time: ... }, lease_duration: 0, renewable: false }2. Write Secret写入/更新密钥定义于 write-secret.ts动作名为write_secret。参数Secret Engine必填默认secretSecret Path必填存储路径如myapp/databaseSecret Data必填JSON 对象要写入的键值数据默认示例为{ username: myuser, password: mypassword }。行为细节KV v2 下请求体被包装为{ data: secretData }发送到/data/端点每次写入都会生成新版本因此标记为idempotent: false重复执行会不断产生历史版本KV v1 下请求体直接是原始 JSON发送到/v1/{engine}/{path}写入成功返回{ success: true, path, metadata }其中metadata取自响应中的data字段失败抛出Failed to write secret: ...。3. Delete Secret删除密钥定义于 delete-secret.ts动作名为delete_secret。参数Secret Engine 与 Secret Path均必填。行为细节KV v2 下删除请求打到/metadata/端点即连同元数据与全部历史版本一起删除KV v1 下直接删除/v1/{engine}/{path}404 视为已删除路径不存在时返回{ success: true, deleted: false, message: Secret not found at this path (may already be deleted) }不抛异常保证幂等语义删除成功返回{ success: true, deleted: true, path }。4. List Secrets列出密钥定义于 list-secrets.ts动作名为list_secrets。参数Secret Engine必填默认secretPath可选默认空字符串要列出的路径如myapp/留空则列出引擎根目录。行为细节请求打到/metadata/端点并追加?listtrueKV v2KV v1 则为/v1/{engine}/{path}?listtrue返回{ success: true, keys: string[], path }keys是该路径下直接子级的键名与子路径列表以/结尾的即子目录不递归404 时返回空数组keys: []与提示信息同样不抛异常该动作非常适合作为先枚举、再逐个读取的发现步骤且标记为幂等。五、底层实现URL 构造与认证令牌获取所有动作的公共逻辑集中在 src/lib/common/index.ts理解它就能理解整个集成的行为。令牌获取getVaultTokenexport async function getVaultToken(auth): PromiseVaultAuthResult { const baseUrl auth.props.url.replace(/\/$/, ); const namespace auth.props.namespace || undefined; const apiVersion auth.props.apiVersion || v2; // Token 方式直接使用连接中的 token // AppRole 方式POST {baseUrl}/v1/auth/{appRolePath}/login // body: { role_id, secret_id } → 取 response.auth.client_token }几个实现要点URL 尾斜杠归一化url.replace(/\/$/, )去掉末尾/避免与后续拼接的/v1/...产生双斜杠AppRole 登录失败会包装错误如果登录响应中拿不到client_token会抛出Failed to obtain token from AppRole login网络/HTTP 异常则抛出AppRole authentication failed: ...Token 方式缺少 token 时直接抛错Vault Token is required for token authentication把配置错误提前暴露在执行期之前返回值统一为{ token, baseUrl, namespace, apiVersion }供各动作使用。请求头构造buildVaultHeaders{ X-Vault-Token: token, Content-Type: application/json, ...(namespace { X-Vault-Namespace: namespace }), ...customHeaders, }这是 HashiCorp Vault HTTP API 的标准认证头token 通过X-Vault-Token传递企业版多租户的 Namespace 通过X-Vault-Namespace传递。所有动作都复用此函数保证请求头一致。URL 构造buildSecretUrl—— KV v1 与 v2 的核心差异const cleanPath secretPath.replace(/^\/|\/$/g, ); // 去掉首尾斜杠 if (apiVersion v2) { // read / write → {baseUrl}/v1/{engine}/data/{path} // delete / list → {baseUrl}/v1/{engine}/metadata/{path} } else { // 所有操作 → {baseUrl}/v1/{engine}/{path} }这是本集成最重要的原理汇总如下操作KV v1 端点KV v2 端点读/写/v1/{engine}/{path}/v1/{engine}/data/{path}删/列/v1/{engine}/{path}/v1/{engine}/metadata/{path}KV v2 引入版本管理后数据层与元数据层分离data端点处理键值数据本身支持按版本读写metadata端点处理版本历史与删除?listtrue用于枚举。这也是为什么连接配置中必须显式选择 KV 引擎版本——选错版本会直接导致 404 或数据结构不匹配。六、多语言与界面文案该 piece 的界面文案通过 src/i18n/translation.json 集中管理并提供了德语de、西班牙语es、法语fr、日语ja、荷兰语nl、葡萄牙语pt、中文zh等翻译文件分布在 src/i18n/ 目录下。所有连接字段名、动作名、参数描述以及 Custom API Call 的界面文案均从该翻译表读取保证多语言环境下的界面一致性。七、典型使用场景与安全建议结合源码可以归纳出几个高价值的应用模式密钥集中托管流程按需读取把数据库口令、API Key 等敏感信息存入 Vault流程中通过 Read Secret 按需拉取配合连接的 SecretText 字段token、secretId避免敏感值出现在流程配置与日志中。动态凭据轮换用 Write Secret 记录由流程生成的新凭据利用 KV v2 的版本机制保留历史审计与回滚都有据可查。AI Agent 运行时取密四个动作均声明了aiMetadata描述读/删/列为幂等写为非幂等并标注audience: both意味着它们可被 AI Agent 作为工具在运行时调用且 Agent 能理解读路径不存在应视为成功而非报错这类语义。机器身份优先用 AppRole相比长期有效的 TokenAppRole 的 Role ID / Secret ID 更适合 CI/CD 与流程自动化场景且登录拿到的client_token只在当次请求生命周期内使用。企业版多租户记得填 Namespace配置 Namespace 后所有请求含 AppRole 登录、token 校验、四个动作、Custom API Call都会自动携带X-Vault-Namespace请求头。安全层面的两个要点一是 Vault URL 应使用 HTTPS 端点如https://vault.example.com:8200二是连接中的 Token / Secret ID 以密文存储不要把它们写入流程的明文变量或日志输出中。八、延伸阅读构建命令与模块说明packages/pieces/community/hashi-corp-vault/README.mdPiece 注册与 Custom API Callpackages/pieces/community/hashi-corp-vault/src/index.ts连接认证与校验逻辑packages/pieces/community/hashi-corp-vault/src/lib/auth.ts令牌获取、请求头与 URL 构造packages/pieces/community/hashi-corp-vault/src/lib/common/index.ts四个动作实现read-secret.ts、write-secret.ts、delete-secret.ts、list-secrets.ts包脚本与依赖package.json多语言文案src/i18n/translation.json如需了解 Activepieces 的 piece 开发框架本身createPiece、PieceAuth.CustomAuth、createAction等 API可继续阅读仓库中的 packages/pieces/framework 相关源码与文档。【免费下载链接】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），仅供参考 Activepieces 集成 HashiCorp Vault：构建、认证配置与密钥管理动作全解析
Activepieces 集成 HashiCorp Vault构建、认证配置与密钥管理动作全解析【免费下载链接】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导读本文以开源仓库 activepieces 中的 HashiCorp Vault 官方集成piece为对象完整讲解该模块的构建方式、连接认证配置、四个内置密钥管理动作读/写/删/列以及底层 HTTP 调用原理。读完本文你将掌握如何在 Activepieces 中构建并接入 HashiCorp Vault理解 Token 与 AppRole 两种认证方式的差异以及 KV v1 / v2 两种密钥引擎在 URL 与数据结构上的本质区别可直接照搬到自己的自动化流程中。本文内容以仓库文档 packages/pieces/community/hashi-corp-vault/README.md 为骨架所有实现细节均取自该模块源码可对照 src/index.ts、src/lib/auth.ts、src/lib/common/index.ts 以及 src/lib/actions/ 下的四个动作文件逐一验证。一、构建 piece 库HashiCorp Vault 集成是 Activepieces 众多社区 piece 之一位于packages/pieces/community/hashi-corp-vault包名为activepieces/piece-hashi-corp-vault。仓库中该模块的 README 明确给出了构建命令turbo run build --filteractivepieces/piece-hashi-corp-vault这是基于 Turborepo 的过滤构建--filter会只构建当前这个 piece而不触碰仓库中其他数百个 piece适合单独开发、调试与发布该模块。从 package.json 可以看到该模块的完整脚本{ name: activepieces/piece-hashi-corp-vault, version: 0.0.8, type: commonjs, main: ./dist/src/index.js, types: ./dist/src/index.d.ts, scripts: { build: tsc -p tsconfig.lib.json cp package.json dist/, bundle: node ../../../../dist/packages/cli/src/index.js pieces bundle, lint: eslint src/**/*.ts } }build先用 TypeScript 编译器按tsconfig.lib.json编译到dist/再把package.json复制进dist/保证发布产物自带包描述bundle调用 Activepieces CLI 把 piece 打包成可分发的 bundlelint对该模块源码执行 ESLint。构建产物的入口是dist/src/index.js即下文要分析的 src/index.ts。二、Piece 总览一个提供 5 类动作的开发者工具集成在 src/index.ts 中通过createPiece注册了这个集成export const hashiCorpVault createPiece({ displayName: HashiCorp Vault, description: Securely manage secrets and sensitive data with HashiCorp Vault, auth: hashiCorpVaultAuth, minimumSupportedRelease: 0.36.1, authors: [onyedikachi-david], categories: [PieceCategory.DEVELOPER_TOOLS], actions: [readSecret, writeSecret, deleteSecret, listSecrets, createCustomApiCallAction({...})], triggers: [], });关键信息displayName/description在 Activepieces 构建器界面中展示的名称与简介minimumSupportedRelease: 0.36.1要求 Activepieces 版本不低于 0.36.1 才能安装使用categories: [PieceCategory.DEVELOPER_TOOLS]归类为开发者工具方便在 piece 市场中被检索actions共 5 个动作——读密钥、写密钥、删密钥、列密钥外加一个通用的Custom API Call自定义 API 调用动作triggers为空数组说明该集成当前只提供动作、不提供触发器无法作为流程的启动节点。Custom API Call覆盖官方动作之外的任意 Vault 接口除四个内置动作外src/index.ts 还注册了一个由框架提供的通用动作createCustomApiCallAction。它的authMapping会根据认证方式动态生成请求头选择 Token 认证时直接使用连接里保存的 token选择 AppRole 认证时先调用POST {baseUrl}/v1/auth/{appRolePath}/loginbody 携带role_id与secret_id换取client_token再把 token 注入请求头无论哪种方式最终都会返回X-Vault-Token请求头若配置了 Namespace还会附带X-Vault-Namespace。也就是说凡是官方动作未覆盖的 Vault 接口如动态 secret、PKI、Transit 等都可以通过这一个通用动作以连接的身份直接调用baseUrl取自连接配置中的 Vault URL。三、连接配置Token 与 AppRole 两种认证方式连接connection是 Activepieces 中保存凭证的单元。Vault 集成的连接定义在 src/lib/auth.ts使用的是PieceAuth.CustomAuth即完全自定义的连接表单。字段如下字段类型必填默认值说明Vault URLShortText是—Vault 实例地址如https://vault.example.com:8200Authentication MethodStaticDropdown是token可选token或appRoleVault TokenSecretText视方法而定—Token 认证时必填Role IDShortText视方法而定—AppRole 认证时必填Secret IDSecretText视方法而定—AppRole 认证时必填AppRole Mount PathShortText否approleAppRole 认证方法的挂载路径NamespaceShortText否—Vault Namespace企业版功能未使用留空KV Secrets Engine VersionStaticDropdown是v2可选v1或v2几个值得注意的设计点敏感字段用PieceAuth.SecretTextVault Token 与 Secret ID 均以密文形式存储与展示避免密钥在构建器界面明文暴露而 Role ID、URL、Namespace 属于非敏感标识使用普通ShortText。认证方式决定必填项表单的validate函数会在保存连接时校验——Token 方式要求提供 Vault TokenAppRole 方式要求同时提供 Role ID 与 Secret ID缺少任一字段都会返回valid: false及对应错误提示。保存即校验连接测试validate不仅是表单校验还会真实发起一次到 Vault 的请求Token 方式直接使用 tokenAppRole 方式先执行一次登录换取client_token随后调用GET {baseUrl}/v1/auth/token/lookup-self验证 token 是否有效任一步骤失败都会返回Connection failed: 错误信息因此保存连接时就能确认网络、URL、Namespace 与凭证是否全部正确。AppRole 挂载路径可自定义默认approle若你的 Vault 将 AppRole 挂载在其他路径如my-approle可在连接中指定登录 URL 会相应变为{baseUrl}/v1/auth/my-approle/login。KV 引擎版本影响后续所有动作的 URL 与数据结构这是本集成最核心的配置项详见第五节。四、四个内置密钥管理动作四个动作均定义在 src/lib/actions/ 目录下公共逻辑复用 src/lib/common/index.ts。1. Read Secret读取密钥定义于 read-secret.ts动作名为read_secret。参数Secret Engine必填默认secret密钥引擎的挂载名Secret Path必填密钥路径如myapp/databaseVersion可选默认 0仅 KV v2 生效指定读取的历史版本号0 或省略表示最新版本。行为细节对 KV v2请求会打到/data/端点并仅在version 0时追加?version{version}查询参数对 KV v1请求打到/v1/{engine}/{path}端点Version 参数被忽略404 不报错路径不存在时返回success: false、空 data 及提示信息Secret not found at this path而不是抛出异常——这使动作在流程中表现为可分支处理的未找到结果其余错误如 403、网络失败会抛出Failed to read secret: ...异常让流程进入失败分支该动作在元数据中标记为idempotent: true幂等重复执行结果一致适合 AI Agent 在运行时安全地反复调用。KV v2 返回结构{ success: true, data: { username: myuser, password: mypassword }, metadata: { version: 3, created_time: ... }, lease_duration: 0, renewable: false }2. Write Secret写入/更新密钥定义于 write-secret.ts动作名为write_secret。参数Secret Engine必填默认secretSecret Path必填存储路径如myapp/databaseSecret Data必填JSON 对象要写入的键值数据默认示例为{ username: myuser, password: mypassword }。行为细节KV v2 下请求体被包装为{ data: secretData }发送到/data/端点每次写入都会生成新版本因此标记为idempotent: false重复执行会不断产生历史版本KV v1 下请求体直接是原始 JSON发送到/v1/{engine}/{path}写入成功返回{ success: true, path, metadata }其中metadata取自响应中的data字段失败抛出Failed to write secret: ...。3. Delete Secret删除密钥定义于 delete-secret.ts动作名为delete_secret。参数Secret Engine 与 Secret Path均必填。行为细节KV v2 下删除请求打到/metadata/端点即连同元数据与全部历史版本一起删除KV v1 下直接删除/v1/{engine}/{path}404 视为已删除路径不存在时返回{ success: true, deleted: false, message: Secret not found at this path (may already be deleted) }不抛异常保证幂等语义删除成功返回{ success: true, deleted: true, path }。4. List Secrets列出密钥定义于 list-secrets.ts动作名为list_secrets。参数Secret Engine必填默认secretPath可选默认空字符串要列出的路径如myapp/留空则列出引擎根目录。行为细节请求打到/metadata/端点并追加?listtrueKV v2KV v1 则为/v1/{engine}/{path}?listtrue返回{ success: true, keys: string[], path }keys是该路径下直接子级的键名与子路径列表以/结尾的即子目录不递归404 时返回空数组keys: []与提示信息同样不抛异常该动作非常适合作为先枚举、再逐个读取的发现步骤且标记为幂等。五、底层实现URL 构造与认证令牌获取所有动作的公共逻辑集中在 src/lib/common/index.ts理解它就能理解整个集成的行为。令牌获取getVaultTokenexport async function getVaultToken(auth): PromiseVaultAuthResult { const baseUrl auth.props.url.replace(/\/$/, ); const namespace auth.props.namespace || undefined; const apiVersion auth.props.apiVersion || v2; // Token 方式直接使用连接中的 token // AppRole 方式POST {baseUrl}/v1/auth/{appRolePath}/login // body: { role_id, secret_id } → 取 response.auth.client_token }几个实现要点URL 尾斜杠归一化url.replace(/\/$/, )去掉末尾/避免与后续拼接的/v1/...产生双斜杠AppRole 登录失败会包装错误如果登录响应中拿不到client_token会抛出Failed to obtain token from AppRole login网络/HTTP 异常则抛出AppRole authentication failed: ...Token 方式缺少 token 时直接抛错Vault Token is required for token authentication把配置错误提前暴露在执行期之前返回值统一为{ token, baseUrl, namespace, apiVersion }供各动作使用。请求头构造buildVaultHeaders{ X-Vault-Token: token, Content-Type: application/json, ...(namespace { X-Vault-Namespace: namespace }), ...customHeaders, }这是 HashiCorp Vault HTTP API 的标准认证头token 通过X-Vault-Token传递企业版多租户的 Namespace 通过X-Vault-Namespace传递。所有动作都复用此函数保证请求头一致。URL 构造buildSecretUrl—— KV v1 与 v2 的核心差异const cleanPath secretPath.replace(/^\/|\/$/g, ); // 去掉首尾斜杠 if (apiVersion v2) { // read / write → {baseUrl}/v1/{engine}/data/{path} // delete / list → {baseUrl}/v1/{engine}/metadata/{path} } else { // 所有操作 → {baseUrl}/v1/{engine}/{path} }这是本集成最重要的原理汇总如下操作KV v1 端点KV v2 端点读/写/v1/{engine}/{path}/v1/{engine}/data/{path}删/列/v1/{engine}/{path}/v1/{engine}/metadata/{path}KV v2 引入版本管理后数据层与元数据层分离data端点处理键值数据本身支持按版本读写metadata端点处理版本历史与删除?listtrue用于枚举。这也是为什么连接配置中必须显式选择 KV 引擎版本——选错版本会直接导致 404 或数据结构不匹配。六、多语言与界面文案该 piece 的界面文案通过 src/i18n/translation.json 集中管理并提供了德语de、西班牙语es、法语fr、日语ja、荷兰语nl、葡萄牙语pt、中文zh等翻译文件分布在 src/i18n/ 目录下。所有连接字段名、动作名、参数描述以及 Custom API Call 的界面文案均从该翻译表读取保证多语言环境下的界面一致性。七、典型使用场景与安全建议结合源码可以归纳出几个高价值的应用模式密钥集中托管流程按需读取把数据库口令、API Key 等敏感信息存入 Vault流程中通过 Read Secret 按需拉取配合连接的 SecretText 字段token、secretId避免敏感值出现在流程配置与日志中。动态凭据轮换用 Write Secret 记录由流程生成的新凭据利用 KV v2 的版本机制保留历史审计与回滚都有据可查。AI Agent 运行时取密四个动作均声明了aiMetadata描述读/删/列为幂等写为非幂等并标注audience: both意味着它们可被 AI Agent 作为工具在运行时调用且 Agent 能理解读路径不存在应视为成功而非报错这类语义。机器身份优先用 AppRole相比长期有效的 TokenAppRole 的 Role ID / Secret ID 更适合 CI/CD 与流程自动化场景且登录拿到的client_token只在当次请求生命周期内使用。企业版多租户记得填 Namespace配置 Namespace 后所有请求含 AppRole 登录、token 校验、四个动作、Custom API Call都会自动携带X-Vault-Namespace请求头。安全层面的两个要点一是 Vault URL 应使用 HTTPS 端点如https://vault.example.com:8200二是连接中的 Token / Secret ID 以密文存储不要把它们写入流程的明文变量或日志输出中。八、延伸阅读构建命令与模块说明packages/pieces/community/hashi-corp-vault/README.mdPiece 注册与 Custom API Callpackages/pieces/community/hashi-corp-vault/src/index.ts连接认证与校验逻辑packages/pieces/community/hashi-corp-vault/src/lib/auth.ts令牌获取、请求头与 URL 构造packages/pieces/community/hashi-corp-vault/src/lib/common/index.ts四个动作实现read-secret.ts、write-secret.ts、delete-secret.ts、list-secrets.ts包脚本与依赖package.json多语言文案src/i18n/translation.json如需了解 Activepieces 的 piece 开发框架本身createPiece、PieceAuth.CustomAuth、createAction等 API可继续阅读仓库中的 packages/pieces/framework 相关源码与文档。【免费下载链接】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），仅供参考