> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Git 版本控制

> 如何使用基于 Git 的版本控制管理知行之桥配置，包括安装、设置和工作流示例。

export const companyName = "知行软件";

export const siteNameShort = "知行之桥";

export const siteName = "知行之桥";

{siteName} 为大部分应用程序配置提供基于 Git 的版本控制，为您的数据集成平台带来企业级的变更管理。此功能使团队能够通过完整的审计追踪来记录配置变更，维护独立的测试和生产环境，并通过回滚到已知的良好状态来快速从问题中恢复。

通过 Git 集成，团队成员可以协作管理 {siteNameShort} 配置，并拥有准确的归属信息和变更历史，在满足合规性要求的同时降低配置错误的风险。组织可以对其 {siteNameShort} 配置应用与应用程序代码同样严格的版本控制实践。

除非手动将文件添加到 .gitignore 文件中，否则所有 {siteNameShort} 文件（如 \*.cfg、XML、JSON 和二进制文件）都会被追踪。有关被追踪文件类型的更多详细信息，请参阅[架构](../architecture)。

<Note>[库](../administration/settings/global-settings-vault)及其内容，以及[用户和角色](../administration/settings/user-roles)不在版本控制范围内。为了避免对令牌、用户名和密码等敏感值进行版本控制，{companyName} 建议将 *所有* 敏感值存储在库中，并在需要这些敏感值的端口中引用库项目。</Note>

## 安装与配置

### 前提条件

在使用版本控制功能之前，必须在所有 {siteNameShort} 环境（包括开发和生产环境）中安装 Git。

还必须创建远程仓库。{siteNameShort} 支持所有主流 Git 平台，包括 GitHub、GitLab、Azure DevOps 和 Bitbucket。

#### 安装 Git

##### Windows

1. 从 <a href="https://git-scm.com/download/win" target="_blank">git-scm.com/download/win</a> 下载 Git 安装程序。
2. 运行安装程序，并按照安装向导使用首选设置进行安装。
3. 打开命令提示符或 PowerShell 并运行以下命令以验证安装：

   ```
   git --version
   ```

您应该能看到显示的已安装 Git 版本。

##### Linux Debian/Ubuntu

运行以下命令：

```
sudo apt-get update
sudo apt-get install git
```

##### Linux Fedora/RHEL/CentOS

运行以下命令：

```
sudo dnf install git
```

运行以下命令以验证安装：

```
git --version
```

安装并验证 Git 后，即可开始使用 {siteNameShort} 的版本控制功能。

### 创建仓库并配置版本控制

创建远程仓库超出了本文档的范围，但 {siteNameShort} 支持所有主流 Git 平台，包括 GitHub、GitLab、Azure DevOps 和 Bitbucket。请查阅仓库文档以获取说明及任何特殊的外部连接要求。例如，在 GitHub 使用 HTTPS 身份验证时，需要使用个人访问令牌 (PAT) 而非密码进行身份验证。

远程仓库创建完成后，请在 **设置 > 高级 > Git 版本控制** 中配置版本控制。详情请参阅 [Git 版本控制设置](../administration/settings/git-version-control-settings)。

## 开发环境

在共享的生产环境中使用 {siteNameShort} 版本控制时，{companyName} 建议为每位团队成员设置独立的开发环境。这能提供最佳的用户体验，并避免多名用户在共享环境中同时推送或拉取更改时可能发生的冲突。

直接在带有版本控制的共享生产环境中工作可能会导致：

* 多名用户同时进行更改时产生合并冲突
* 竞争版本控制操作导致用户体验不佳

通过使用开发环境，每位团队成员可以独立工作，在本地测试更改，并将完成的工作推送到仓库，而不会干扰他人或中断生产运行。

请按照以下步骤配置与生产环境 {siteNameShort} 实例镜像一致的本地开发环境：

1. 从生产环境导出数据加密密钥（有关密钥使用的更多信息，请参阅[了解数据加密密钥和主密钥](./custom-master-key#understanding-data-encryption-keys-and-master-keys)）

   1. 在生产环境中，使用 API 密钥调用 [Admin API exportDataEncryptionKey](../../admin-api/admin-api-actions) 接口。使用 `passphrase` 参数创建导出密码，该密码将在向开发环境导入密钥时使用。
   2. 保存响应内容，因为开发环境需要此数据加密密钥。

2. 从生产环境导出库：

   1. 使用 UI 界面
      1. 导航至 **设置 > 高级 > 迁移 > 导出**
      2. 选择 **自定义导出** 并创建一个 **密码**，然后点击 **下一步**
      3. 在 **系统设置** 页面，仅勾选 **库**
      4. 点击 **导出** 执行导出并下载文件

   2. 使用启用了库选项的 [Admin API export](../../admin-api/admin-api-actions) 接口

3. 在开发环境中安装 {siteNameShort}（如果尚未安装）

   1. 在开发机器上安装 {siteNameShort}
   2. 完成初始设置并创建第一个[用户账户](../administration/settings/user-roles)
   3. 安装开发许可
   4. 创建用于 API 访问的 API 密钥

4. 向开发环境导入数据加密密钥：在开发环境中，使用 API 密钥调用 [Admin API importDataEncryptionKey](../../admin-api/admin-api-actions) 接口，并使用与从生产环境导出密钥时相同的 *passphrase*。这确保了开发环境使用相同的数据加密密钥，并可以解密库内容。

5. 向开发环境导入库

   1. 使用 UI 界面
      1. 导航至 **设置 > 高级 > 迁移 > 导入**
      2. 上传之前导出的库文件
      3. 完成导入过程

   2. 使用 [Admin API import](../../admin-api/admin-api-actions) 接口上传并导入库文件。

6. [拉取](#拉取更改)远程仓库以同步开发环境与生产环境配置

   1. 使用 UI 界面
      1. 按照[前提条件](#前提条件)中的说明安装 Git
      2. 导航至 **设置 > 高级 > Git 版本控制**
      3. 配置远程仓库连接（说明请参阅 [Git 版本控制设置](../administration/settings/git-version-control-settings)）
      4. 从远程仓库拉取最新更改

   2. 使用标准 Git 命令在本地机器上配置仓库连接

开发环境配置完成后，可以：

* 在本地进行并测试更改，而不影响生产环境
* 将更改提交到本地仓库
* 将完成的工作推送到远程仓库
* 拉取其他团队成员所做的更新
* 遵循标准 Git 工作流（如分支和拉取请求）进行协作开发

生产环境现在可以按照受控的计划从远程仓库拉取已批准的更改。

## 版本控制操作

{siteNameShort} 的 Git 集成提供了核心的版本控制操作，允许管理配置更改、与远程仓库同步以及维护多个开发分支。这些操作遵循标准的 Git 工作流，同时专门针对 {siteNameShort} 的配置管理需求进行了优化。

在环境中实施版本控制后，标准的 {siteNameShort} 页脚将变为状态栏，显示 Git 指标和操作，例如本地文件更改数量、远程提交数量以及当前分支。

<img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_footer_toolbar.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=3bb76694d52f283ecb33cd14f02f16aa" alt="Git version control footer toolbar" width="800" data-path="public/images/version_control_footer_toolbar.png" />

### 权限

版本控制功能对所有用户可见，而不仅仅是管理员。[基于角色的访问控制](../administration/settings/user-roles#user-roles)权限决定了可以执行哪些 Git 操作。

* 只读用户：仅能查看状态和历史记录
* 写入用户：可以执行提交、推送、拉取和创建分支操作

### 提交与推送

*提交 (Commit)* 将 {siteNameShort} 中的所有配置更改捕获为一个原子单元，并保存到本地 Git 仓库。提交时，{siteNameShort} 会自动将您的 {siteNameShort} 用户名记录为作者并添加时间戳，确保完整追溯更改人及更改时间。提交时必须填写提交信息以记录更改目的，且必须拥有写入权限。

*推送 (Push)* 将本地提交同步到远程 Git 仓库，使更改对其他团队成员和备份系统可见。如果远程分支包含尚未拉取的更新，推送操作将失败并显示错误信息及后续操作建议。这可以防止覆盖他人的工作并确保正确的合并处理。

提交和推送操作是在一个动作中完成的。详情请参阅[提交并推送新更改](#提交并推送新更改)。

### 拉取

*拉取 (Pull)* 从远程 Git 仓库获取最新更改并更新本地 {siteNameShort} 配置。在拉取之前，必须提交或放弃任何未提交的本地更改——如果检测到未提交的更改，操作将失败。如果本地版本与远程版本之间存在合并冲突，拉取将失败，并提示使用 Git 工具在外部解决冲突（详情请参阅[管理提交与拉取冲突](#管理提交与拉取冲突)）。可以从 Git 工具栏启动拉取操作。详情请参阅[拉取更改](#拉取更改)。

### 分支

分支管理允许为不同目的（如开发、测试和生产环境）维护独立的配置版本。使用工具栏中的分支下拉菜单可以在分支之间切换、创建新分支或删除过期分支。创建新分支时，请指定分支名称并选择要从中创建的源分支（默认使用当前分支）。这可以尝试配置更改而不会影响主环境。详情请参阅[创建分支](#创建分支)和[删除分支](#删除分支)。

### 日志

所有版本控制更改都记录在[活动](../administration/activity)页面的[审计日志](../administration/activity#audit-logs)部分。可以根据需要从该页面下载日志。

<img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_audit_logs.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=a444e1e682edc7e66eb6277a13f28d17" alt="Audit logs for version control changes" width="800" data-path="public/images/version_control_audit_logs.png" />

## 历史查看器

启用版本控制后，**活动** 页面上会出现 **提交历史** 选项卡。它显示完整的提交历史记录，并提供提交哈希、提交信息、作者、日期和时间以及每次提交中更改的文件列表等详细信息。可以在此页面上搜索和过滤内容。

<img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_commit_history.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=b8e7d215df047c82f39e0d1311b28219" alt="Commit history tab on the Activity page" width="800" data-path="public/images/version_control_commit_history.png" />

点击 **提交 (Commit)** 哈希可打开 **提交详情** 页面。该页面默认打开 **文件更改** 选项卡，显示提交中文件的差异视图，以便准确查看更改内容。点击 **详情** 选项卡可查看作者、提交信息和时间戳。

<img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_commit_details.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=9d1bd836e65129b241f1d3fb0af314de" alt="Commit details with file diff view" width="600" data-path="public/images/version_control_commit_details.png" />

**文件更改** 选项卡上的 **转到资源** 链接将带至 {siteNameShort} 中发生文件更改的部分。例如，如果正在查看 [AS2](../../connectors/as2) 端口的 `port.cfg` 文件差异，点击该链接将跳转到该 AS2 端口。

## 版本控制工作流示例

以下示例演示了在使用 {siteNameShort} 的 Git 集成时常见的版本控制场景。这些工作流涵盖了基本操作：从远程仓库拉取更新、创建和删除分支、提交并推送更改、恢复更改、在本地和远程更改冲突时解决冲突，以及放弃不需要的修改。

### 拉取更改

可以通过多种方式从远程拉取更改：

* 点击工具栏上的 **拉取 (Pull)** 直接拉取提交而不进行预览

* 点击工具栏上的提交数量打开 **拉取远程提交** 预览

  <img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_pull.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=b9d43638a90d3d8107dd968763e6a191" alt="Pull remote commits preview" width="800" data-path="public/images/version_control_pull.png" />

* 导航至 **活动** 页面上的 **提交历史** 选项卡，点击左侧的远程提交数量链接或右侧的 **拉取 (Pull)** 按钮，以打开 **拉取远程提交** 预览

**拉取远程提交** 预览列出了所有待拉取的提交。点击某个提交可查看其详情，将鼠标悬停在文件数量上可查看该提交中包含哪些文件。点击 **拉取提交 (Pull Commits)** 完成任务。

<img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_pull_remote_commits.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=d3f63e749cf7ede7c64d378501e2f5f0" alt="Pull remote commits confirmation dialog" width="600" data-path="public/images/version_control_pull_remote_commits.png" />

### 创建分支

要创建新分支，请点击工具栏上的分支图标（也可以在此处切换分支）。

<img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_switch_branch.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=d0bcea436fdee81dd49fa45ab9e06eba" alt="Branch switcher on the toolbar" width="300" data-path="public/images/version_control_switch_branch.png" />

点击 **添加分支** 并输入分支 **名称**。选择要从中复制的分支，然后点击 **添加**。

<img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_add_branch.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=63cab903724022214a8405df2da37eb4" alt="Add branch dialog" width="500" data-path="public/images/version_control_add_branch.png" />

### 删除分支

要删除分支，请点击工具栏上的分支图标。将鼠标悬停在要删除的分支上，然后点击垃圾桶图标。

<img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_delete_branch.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=952106571e1de6295ad48bc47a7002d1" alt="Delete branch dialog" width="300" data-path="public/images/version_control_delete_branch.png" />

### 提交并推送新更改

在 {siteNameShort} 中进行更改时，工具栏会显示已更改的文件总数：

<img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_footer_toolbar.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=3bb76694d52f283ecb33cd14f02f16aa" alt="Git toolbar showing number of changed files" width="800" data-path="public/images/version_control_footer_toolbar.png" />

点击 **提交并推送 (Commit & Push)** 打开 **本地文件更改** 面板。它显示有关已更改文件的详细信息。在将更改提交并推送到远程之前，必须提供提交信息。

<Note>与其他一些基于 Git 的版本控制实现不同，提交和推送是一个单一步骤——不会先提交到本地然后再推送。</Note>

<img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_commit.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=77b023606c8aa0fb8c6f6b873459fbca" alt="Local file changes pane with commit message field" width="800" data-path="public/images/version_control_commit.png" />

提交并推送更改后，工具栏中的确认消息会告知操作结果。

### 从先前版本恢复更改

要将资源恢复到先前的状态，请导航至 **活动** 页面上的 **提交历史** 选项卡。点击 **文件更改** 列右侧的省略号，然后点击 **恢复**。查看当前状态与建议恢复点状态之间的差异，然后点击 **下一步**。请注意，如果继续恢复，这些文件中任何未提交的更改将永久丢失。点击 **恢复资源** 完成任务。

### 管理提交与拉取冲突

当有本地更改需要推送，同时也有远程更改需要拉取时，可能会产生冲突。工具栏会反映冲突情况并提供操作建议。同样的错误消息也会出现在 **提交** 和 **拉取远程提交** 预览页面上。

<img src="https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/version_control_commit_pull_conflict.png?fit=max&auto=format&n=ilnLy7gsSdFqbKmI&q=85&s=def23f271732023165b87d0828a4f318" alt="Commit and pull conflict message in toolbar" width="800" data-path="public/images/version_control_commit_pull_conflict.png" />

一种选择是手动管理冲突，另一种选择是将当前更改提交到不同的分支，从而允许将远程更改拉取到当前分支。

点击 **请提交到新分支** 打开页面，在此可以选择要提交到的不同分支。选择（或创建）新分支后，可以使用 **提交并推送更改** 推送更改。

### 放弃更改

要放弃当前更改，请点击工具栏中的垃圾桶图标。这将打开 **放弃更改** 面板，可以在其中准确选择要放弃的更改。点击 **下一步**，确认选择无误，然后点击 **放弃更改**。完成后会出现确认消息，工具栏中的更改数量将相应减少。