> ## 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} 配置應用與應用程式程式碼同樣嚴格的版本控制實踐。

{siteNameShort} 支援連線 GitHub、GitLab、Azure DevOps 或 Bitbucket 等託管平臺的**遠端**倉庫。

自託管安裝還支援直接執行在 {siteNameShort} 伺服器上的**本地**倉庫，無需外部 Git 基礎設施。

除非手動將檔案新增到 .gitignore 檔案中，否則所有 {siteNameShort} 檔案（如 \*.cfg、XML、JSON 和二進位檔案）都會被追蹤。有關被追蹤檔案型別的更多詳細資訊，請參閱[架構](../architecture)。

<Note>[庫](./settings/global-settings-vault)及其內容，以及[使用者](./settings/users)和[角色](./settings/user-roles)不在版本控制範圍內。為了避免對權杖、使用者名稱和密碼等敏感值進行版本控制，{companyName} 建議將 *所有* 敏感值儲存在庫中，並在需要這些敏感值的連接器中引用庫專案。</Note>

## 安裝與配置

### 前提條件

在使用版本控制功能之前，必須在所有 {siteNameShort} 環境（包括開發和生產環境）中安裝 Git。

如果使用遠端倉庫，還必須在配置版本控制前建立該倉庫。{siteNameShort} 支援 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} 的版本控制功能。

### 配置版本控制

導航至**設定 > 高階 > Git 版本控制**配置版本控制。完整設定說明請參閱 [Git 版本控制設定](./settings/git-version-control-settings)。

點選**配置**後選擇**配置型別**：

* **遠端**：連線託管 Git 倉庫，支援跨環境推送、拉取和協作。
* **本地**：在 {siteNameShort} 伺服器上建立獨立倉庫，無需遠端 URL 或憑據。

遠端倉庫需要提供 URL 和身分驗證憑據。建立遠端倉庫不在本文件範圍內；請參考 Git 平臺文件。例如，GitHub HTTPS 身分驗證必須使用個人存取權杖（PAT），不能使用密碼。

## 開發環境

<Note>本節僅適用於**遠端**倉庫。本地倉庫沒有需要同步的遠端端，因此不需要單獨的開發環境。</Note>

在共享的生產環境中使用 {siteNameShort} 版本控制時，{companyName} 建議為每位團隊成員設定獨立的開發環境。這能提供最佳的使用者體驗，並避免多名使用者在共享環境中同時推送或拉取更改時可能發生的衝突。

直接在帶有版本控制的共享生產環境中工作可能會導致：

* 多名使用者同時進行更改時產生合併衝突
* 競爭版本控制操作導致使用者體驗不佳

透過使用開發環境，每位團隊成員可以獨立工作，在本地測試更改，並將完成的工作推送到倉庫，而不會干擾他人或中斷生產執行。

請按照以下步驟配置與生產環境 {siteNameShort} 例項映像一致的本地開發環境：

1. 從生產環境匯出資料加密金鑰（有關金鑰使用的更多資訊，請參閱[瞭解資料加密金鑰和主要金鑰](../installation/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. 完成初始設定並建立第一個[使用者帳戶](./settings/users)
   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 版本控制設定](./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" />

### 權限

版本控制功能對所有使用者可見，而不僅僅是管理員。[基於角色的存取控制](./settings/user-roles)權限決定了可以執行哪些 Git 操作。

* 只讀使用者：僅能檢視狀態和歷史記錄
* 寫入使用者：可以執行提交、推送、拉取和建立分支操作

### 提交與推送

*提交 (Commit)* 將 {siteNameShort} 中的所有配置更改捕獲為一個原子單元，並儲存到本地 Git 倉庫。提交時，{siteNameShort} 會自動將您的 {siteNameShort} 使用者名稱記錄為作者並新增時間戳，確保完整追溯更改人及更改時間。提交時必須填寫提交資訊以記錄更改目的，且必須擁有寫入權限。

*推送 (Push)* 將本地提交同步到遠端 Git 倉庫，使更改對其他團隊成員和備份系統可見。如果遠端分支包含尚未拉取的更新，推送操作將失敗並顯示錯誤資訊及後續操作建議。這可以防止覆蓋他人的工作並確保正確的合併處理。

遠端倉庫的提交和推送在一個動作中完成。詳情請參閱[提交併推送新更改](#提交併推送新更改)。本地倉庫沒有推送步驟，工具列顯示**提交**。

### 拉取

<Note>拉取僅適用於遠端倉庫。本地倉庫沒有可供拉取的遠端端。</Note>

*拉取 (Pull)* 從遠端 Git 倉庫取得最新更改並更新本地 {siteNameShort} 配置。在拉取之前，必須提交或放棄任何未提交的本地更改——如果檢測到未提交的更改，操作將失敗。如果本地版本與遠端版本之間存在合併衝突，拉取將失敗，並提示使用 Git 工具在外部解決衝突（詳情請參閱[管理提交與拉取衝突](#管理提交與拉取衝突)）。可以從 Git 工具列啟動拉取操作。詳情請參閱[拉取更改](#拉取更改)。

### 分支

分支管理允許為不同目的（如開發、測試和生產環境）維護獨立的配置版本。使用工具列中的分支下拉功能表可以在分支之間切換、建立新分支或刪除過期分支。建立新分支時，請指定分支名稱並選擇要從中建立的源分支（預設使用當前分支）。這可以嘗試配置更改而不會影響主環境。詳情請參閱[建立分支](#建立分支)和[刪除分支](#刪除分支)。

### 日誌

所有版本控制更改都記錄在[活動](./activity)頁面的[審計日誌](./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/kUAbHW4b4w3lCUYJ/public/images/version_control_commit_details_263.png?fit=max&auto=format&n=kUAbHW4b4w3lCUYJ&q=85&s=04e18bdce05119a550f0eea553ad8459" alt="包含檔案差異的提交詳情" width="600" data-path="public/images/version_control_commit_details_263.png" />

差異檢視顯示所有已更改設定的新舊值。密碼和機密資訊會被遮蔽，庫引用帶有鑰匙圖示。**檔案更改**索引標籤上的**轉到資源**連結會開啟更改對應的 {siteNameShort} 頁面。例如，檢視 [MySQL](../../connectors/mysql) 連接器的差異時，該連結會開啟對應連接器。

## 版本控制工作流程範例

以下範例演示了在使用 {siteNameShort} 的 Git 整合時常見的版本控制場景。這些工作流程涵蓋了基本操作：從遠端倉庫拉取更新、建立和刪除分支、提交併推送更改、恢復更改、在本地和遠端更改衝突時解決衝突，以及放棄不需要的修改。

### 拉取更改

<Note>此工作流程僅適用於遠端倉庫。</Note>

可以透過多種方式從遠端拉取更改：

* 點選工具列上的 **拉取 (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>遠端倉庫的提交和推送是一個步驟，不會先在本地提交再單獨推送。本地倉庫沒有遠端端，因此只提供**提交**。</Note>

<img src="https://mintcdn.com/qiao/kUAbHW4b4w3lCUYJ/public/images/version_control_commit_263.png?fit=max&auto=format&n=kUAbHW4b4w3lCUYJ&q=85&s=0220147df4100dd90d3ac8789ad54ca0" alt="包含提交資訊欄位的本地檔案更改窗格" width="800" data-path="public/images/version_control_commit_263.png" />

提交併推送更改後，工具列中的確認訊息會告知操作結果。

### 從先前版本恢復更改

要將資源恢復到先前的狀態，請導航至 **活動** 頁面上的 **提交歷史** 索引標籤。點選 **檔案更改** 列右側的省略號，然後點選 **恢復**。檢視當前狀態與建議恢復點狀態之間的差異，然後點選 **下一步**。請注意，如果繼續恢復，這些檔案中任何未提交的更改將永久丟失。點選 **恢復資源** 完成任務。

### 管理提交與拉取衝突

<Note>本節僅適用於遠端倉庫。本地倉庫沒有會產生分歧的遠端分支，因此不會發生遠端提交衝突。</Note>

當有本地更改需要推送，同時也有遠端更改需要拉取時，可能會產生衝突。工具列會反映衝突情況並提供操作建議。同樣的錯誤訊息也會出現在 **提交** 和 **拉取遠端提交** 預覽頁面上。

<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" />

一種選擇是手動管理衝突，另一種選擇是將當前更改提交到不同的分支，從而允許將遠端更改拉取到當前分支。

點選 **請提交到新分支** 開啟頁面，在此可以選擇要提交到的不同分支。選擇（或建立）新分支後，可以使用 **提交併推送更改** 推送更改。

### 放棄更改

要放棄當前更改，請點選工具列中的垃圾桶圖示。這將開啟 **放棄更改** 面板，可以在其中準確選擇要放棄的更改。點選 **下一步**，確認選擇無誤，然後點選 **放棄更改**。完成後會出現確認訊息，工具列中的更改數量將相應減少。

## 從本地倉庫移轉到遠端倉庫

如果希望保留本地提交歷史並連線遠端伺服器：

1. 在 GitHub、GitLab 或 Bitbucket 等平臺建立新的空倉庫。

2. 在 {siteNameShort} 伺服器上進入資料目錄並執行：

   ```bash theme={null}
   git remote add origin <remote-repo-url>
   ```

3. 導航至**設定 > 高階 > Git 版本控制**。{siteNameShort} 會識別新增的遠端端；編輯配置並新增**使用者名稱**和**密碼/權杖**。狀態顯示**已連線**後，本地倉庫的歷史提交即可在遠端端檢視。