企业官网建设流程全解析

• 桌面应用
• 开发工具
• 运维

XPipe Vault 是 XPipe 内置的“连接信息共享仓库”机制：你可以把 SSH 连接、身份凭据等连接信息存入一个专属 Git 仓库，并在所有 XPipe 实例中双向同步。本文基于仓库文档 vault.md 与相关源码，完整讲解 Vault 的加密方案、Git 同步配置、分类级同步开关，以及克隆到其他系统时的 PAT 认证与常见故障排查，读完后你将能安全地配置并使用 Vault 管理跨机器的连接信息。

Vault 是什么：一份"可共享的连接信息仓库"

XPipe Vault 本质上是一个存放"被标记为共享"的连接信息的 Git 仓库。官方文档开篇即强调：这个仓库请务必保持私有（Keep this repository private!），因为它包含你所有的连接信息。

它的核心特性包括：

• 多实例双向同步：你可以在所有 XPipe 应用实例中以相同方式与这个仓库同步，在任何一个实例中做的修改都会反映到仓库中，其他实例拉取后即可获得最新状态；
• 显式控制共享范围：默认情况下没有任何连接分类被设置为同步，只有你主动打开某个分类的同步开关后，该分类下的连接才会被提交进 Git 仓库；
• 本地连接默认不同步：位于本机（Local Machine）下的连接只存在于本地系统，不会进入同步仓库。

从源码结构看，Vault 同步链路由DataStorageSyncHandler接口统一定义，包含pullManually()、pushManually()、validateConnection()、afterStorageLoad()等核心方法，并由 proc 模块提供实现，具体见 DataStorageSyncHandler.java。

密钥加密机制：三类敏感信息保护方案

XPipe 允许你选择不存储任何密钥：敏感信息（如密码）既可以从外部来源（如密码管理器）获取，也可以在连接时通过提示窗口输入。但如果你选择把密码等机密保存在 XPipe 内，所有敏感信息在保存时都会被加密，加密方式有三种，可在 Vault 访问设置菜单中配置：

1. 动态生成的密钥文件vaultkey

系统会为 Vault 动态生成一个密钥文件，名为vaultkey。该文件是解密数据的必要条件——只有携带这个文件的系统才能解密对应数据。

从源码 DataStorageVaultKey.java 可以看到其生成与加载机制：

• 生成：generate()方法使用UUID.randomUUID()生成唯一 ID，并用SecureRandom生成 32 字节随机盐（salt），再基于该盐派生加密密钥；
• 加载：load(Path file)按行解析文件内容，第一行是 ID，第二行是 Base64 编码的盐，再据此重建密钥；
• 写入：write()将 ID 与盐以两行文本形式写入vaultkey文件。

这意味着vaultkey文件必须妥善保管：数据只能通过该文件解密，文件丢失则无法访问加密数据。

2. 自定义口令（Passphrase）

你也可以在 Vault 设置菜单中为当前用户设置自定义口令。文档明确提醒：这种方案的安全性完全取决于你选择的密码强度（This option can only as secure as the password you choose），因此应选择足够复杂的口令。

3. 基于角色的密钥（团队 Vault）

对于团队 Vault，可以使用基于角色的密钥加密：只有拥有某个角色及其密钥的成员才能解密相应数据，实现团队内的细粒度访问控制。

默认加密范围与"全量加密"选项

默认情况下，只有机密信息（secrets）被加密，普通连接数据不加密——主机名、用户名等以明文形式存储，这与许多同类工具的做法一致。

如果你希望更进一步，Vault 访问设置菜单中提供了"加密所有连接数据"的选项。对应实现见 VaultAccessCategory.java：

• 切换encryptAllVaultData开关后，会调用DataStorage.get().refreshStoreEntriesEncryption()重新刷新所有存储条目的加密状态，并异步执行saveAsync()持久化；
• 关闭加密时需要二次确认弹窗，防止误操作导致明文落盘；
• 此外还有hideVaultEntryNames选项，可隐藏 Vault 条目名称；
• 该区域整体受enableGitStorage开关控制（未启用 Git 存储时不可用）。

refreshStoreEntriesEncryption()在 DataStorage.java 中的实现会遍历所有存储条目刷新加密状态，并循环处理依赖条目的连锁变更，直到无后续变化为止。

配置 Git 同步：从远程仓库到手动推送

Vault 的 Git 同步设置在设置界面的 Sync 分类（vaultSync）中，对应实现为 SyncCategory.java，主要配置项包括：

界面还提供：

• 连接测试按钮：调用DataStorageSyncHandler.validateConnection()校验远程仓库连通性；
• 浏览 Vault：通过DesktopHelper.browseFile(DataStorage.get().getStorageDir())直接打开本地存储目录。

手动同步模式

当syncMode设置为MANUAL时，会出现三个手动控制按钮（源码createManualControls()）：

• Pull changes：调用DataStorage.get().pullManually()从远程拉取变更；
• Push changes：调用DataStorage.get().pushManually()推送本地变更到远程；
• Open terminal：在存储目录（DataStorage.get().getStorageDir()）中打开系统终端，方便手工执行 Git 命令排查。

这些操作通过BooleanScope.executeExclusive保证互斥执行，避免拉推并发冲突。

分类级同步：按分类精确控制共享内容

Vault 的同步是按连接分类（category）粒度控制的。默认所有分类都不同步，需要你显式开启：

1. 打开Connections标签页，在左侧分类概览中找到目标分类；
2. 右键点击分类，或鼠标悬停在分类上点击⚙️图标，再点击🔧配置按钮打开分类配置菜单；
3. 将Sync with git repository设为Yes，该分类下所有可同步连接即会加入 Git 仓库。

继承规则：分类的同步设置默认从其父分类继承，除非显式覆盖。

源码层面，DataStoreCategoryConfig中定义了Boolean sync字段，并通过merge()实现多级配置合并——从配置列表末尾向前遍历，取第一个非空值，从而实现"子分类未显式设置时回退到父分类"的继承语义，详见 DataStoreCategoryConfig.java。

判定一个分类是否参与同步的逻辑在 DataStorage.java 的shouldSync(DataStoreCategory category)中：

• 空的"独立身份（Synced Identities）"分类不会同步；
• 分类必须canShare()为真；
• 最终依据getEffectiveCategoryConfig(category).getSync()是否为TRUE。

而对单个条目的shouldSync(entry, wasSynced)（DataStorage.java）还会逐级向上检查父分类：只要任一父分类不可同步，该条目即排除；本地机器上可同步的条目（LocalStore且 provider 支持从本机同步）则允许同步。

在其他系统克隆 Vault 仓库

现代 Git 托管平台大多要求使用**个人访问令牌（PAT）**代替传统密码进行命令行认证，各平台入口如下（均为文字路径，具体 URL 以各平台当前文档为准）：

• GitHub：Settings -> Developer settings -> Personal access tokens（classic）；
• GitLab：User Settings -> Access Tokens（个人访问令牌页面）；
• BitBucket：Personal settings -> App passwords/ Access tokens；
• Gitea：Settings -> Applications -> Manage Access Tokens。

权限建议：将 token 对仓库的权限设置为Read and Write，其余权限可设为Read。

使用要点：

• 即使 Git 客户端提示输入"密码"，也应输入 token（除非你的托管商仍支持传统密码）；
• 若不想每次都输入凭据，可以使用任意 Git 凭据管理器（credential manager）缓存认证信息；
• 许多现代 Git 客户端会自动保存凭据，无需额外配置。

故障排查：常见问题与解决思路

"添加连接后没有同步到仓库"

这是默认行为而非故障：默认没有分类开启同步。请按上文"分类级同步"步骤，为对应分类打开Sync with git repository开关，并确认连接类型本身可同步。

"本地连接没有同步"

本地机器（local machine）下的连接不会同步，因为它们只存在于本地系统。你可以同步 SSH 等远程类型的连接。

部分默认归属本地的连接条目（例如 SSH config 文件）可以通过同步底层数据（如把相关文件一并纳入仓库）来间接同步，每种连接条目的具体细节可在 XPipe 官方文档（docs.xpipe.io）中查询对应条目类型说明。

安全实践小结

综合文档与源码，使用 Vault 的建议如下：

1. 保持 Vault 仓库私有：仓库包含连接信息，切勿公开；
2. 按需开启分类同步：只对确实需要跨机器共享的分类打开同步开关；
3. 优先外部密钥源：密码尽量从密码管理器获取或连接时输入，让 XPipe 不落盘任何机密；
4. 保管好vaultkey文件：若使用自动生成的密钥文件，文件丢失即无法解密；若使用自定义口令，务必选择高强度口令；
5. 必要时全量加密：对主机名、用户名等普通连接数据也需要保密时，在 Vault 访问设置中开启"加密所有连接数据"。

Vault 把 Git 的分布式同步能力与分级加密策略结合起来，让你既能在多台机器间无缝复用连接配置，又能精确控制哪些信息进入仓库、以何种强度保护——这正是 XPipe 管理大规模服务器基础设施时的关键底座之一。

• 桌面应用
• 开发工具
• 运维