从远程存储同步密钥
Semaphore 可以连接到外部密钥管理器——例如 HashiCorp Vault、OpenBao、AWS Secrets Manager、Azure Key Vault 或 Devolutions Server（DVLS）——并自动把其中的密钥导入到密钥库（Key Store）。你无需手动把凭据复制到 Semaphore 并保持更新，只需把 Semaphore 指向远程存储，它就会为你维护一份本地镜像。
**同步路径（Sync paths）**是一组规则，用于告诉 Semaphore 要从远程存储导入哪些密钥，以及导入后如何命名。一个密钥管理器可能在许多文件夹中保存着成千上万个密钥；同步路径让你只选择自己关心的子树，并控制所创建密钥的命名。
核心概念
- 远程存储——到外部密钥管理器的已配置连接，包括其地址以及 Semaphore 读取它时使用的凭据。
- 同步——从远程存储读取密钥，并将其与 Semaphore 中已存储的密钥进行对齐的过程。
- 同步路径——单条导入规则，由路径、前缀和分隔符组成。
同步路径的工作方式
每条同步 路径有三个字段：
- Path——远程存储中要导入的位置。这是 Semaphore 列出并读取的基础文件夹、前缀或子树。其下找到的所有内容都会成为导入候选。
- Prefix——添加到每个生成的密钥名称前面的字符串。用它为导入的密钥添加命名空间，以免与来自其他路径或其他存储的密钥冲突（例如
prod-）。 - Separator——用于把密钥远程位置的各个部分连接成单个密钥名称的字符。由于远程密钥可能位于多层文件夹之下，分隔符决定了该层级如何被展平为一个可读的名称。
同步运行时，Semaphore 遍历 path，对找到的每个密钥，用 separator 拼接密钥的位置并在前面加上 prefix，从而构建出密钥名称。所创建密钥的类型（SSH 密钥、登录名/密码或纯文本密钥字符串）会根据远程密钥的结构自动推断。
你可以在单个存储上定义多条同步路径。每条路径独立导入，因此你可以从同一个密钥管理器的多个互不相关的区域拉取密钥，并为每条路径指定各自的前缀和命名风格。
各提供商都应用了合理的默认值——例如，HashiCorp Vault、OpenBao 和 AWS Secrets Manager 默认使用 / 作为分隔符，Azure Key Vault 使用 -，Devolutions Server 使用 \——因此大多数情况下你只需要填写路径。
运行同步
同步有两种触发方式：
- **手动。**打开存储并使用 Sync now 操作。Semaphore 会立即按照已配置的同步路径对该存储进行对齐。这适用于首次导入或需要立刻拉取某项变更的场景。
- 按计划自动运行。为存储启用 Sync keys，并以分钟为单位设置同步间隔。之后 Semaphore 会在后台按该频率重新运行同步。间隔为
0时禁用自动同步，只保留手动选项。
每个存储都会记录上次同步的时间以及上次尝试是否失败，因此你随时可以查看镜像的状态。
在高可用部署中，自 动同步会在各节点之间协调，因此某次同步同一时间只会在一个节点上运行——不会出现重复导入。
同步对密钥的影响
同步是完整镜像，而不是一次性复制。每次运行时，Semaphore 都会把远程存储与之前导入的密钥进行对齐：
- 在同步路径下找到的新密钥会被创建为密钥。
- 已有的已导入密钥会被更新为当前的远程值。
- 之前已导入但在远程存储中已不存在的密钥会被删除。
只有由 Semaphore 导入的密钥才会受到影响——你手动创建的密钥永远不会被同步修改或删除。
由于导入的密钥是远程密钥的受管副本，删除存储（或禁用其同步）也会同时删除来自该存储的密钥。
两种作用域：共享密钥和环境变量
同步路径可以在两个位置配置：
- 存储级别——导入的密钥成为共享密钥，在项目中所有使用密钥的地方都可用。
- 环境级别——变量组（Variable Group）可以指向某个存储及其同步路径，把密钥作为限定在该变量组范围内的环境变量导入。
两者的机制完全相同，只是导入密钥的目标位置不同。
注意事项与限制
- 仅外部存储类型（HashiCorp Vault、OpenBao、AWS Secrets Manager、Azure Key Vault、Devolutions Server）支持同步。内置的 Database 存储本身就保存密钥，没有可同步的内容。
- 远程存储自身的凭据（Semaphore 用于认证的令牌或密钥）会被安全地存储，并与其导入的密钥分开保存。
- 如果关闭了同步且不再有任何路径，该存储的同步配置会被清除。