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

# 連線保險庫（Vault）

> 把 API 金鑰、權杖與 MCP 伺服器登入資訊存進連線保險庫一次，讓 Agent、知識庫與應用（App）直接使用，程式碼裡永遠看不到它們

**連線保險庫**（Connection Vault）是以工作區為範圍的憑證容器。每個憑證是一個*插槽*：可以是 Agent 要呼叫工具的 **MCP 伺服器**，也可以是 **密鑰**（API 金鑰、權杖、密碼、簽章密鑰），在執行時由 DataGen 以環境變數注入沙盒。

憑證永遠不會出現在程式碼、提示詞或 git 裡。管理員設定一次工作區共用的值，成員可以使用但看不到。必須屬於成員個人的值（例如自己的資料庫密碼、自己的 Gmail 登入）則由每位成員自行填入。

## 工作區中的連線保險庫

每個工作區都有一個 **Default** 連線保險庫。沒有指定連線保險庫的項目（例如設為 **工作區預設** 的 Agent、沒有綁定連線保險庫的 API 金鑰）都會使用它。若要把不同組憑證分開，可以建立更多連線保險庫，例如 `production` 與 `staging`，或每個團隊各一個。

<Frame>
  <img src="https://mintcdn.com/datagen/rusBmwP8bd_Srmdm/images/data-agent/vault-credentials.png?fit=max&auto=format&n=rusBmwP8bd_Srmdm&q=85&s=adc9941a09cfebffa431989ad29d6d1b" alt="連線保險庫 -- Default 連線保險庫的憑證分頁" width="1787" height="848" data-path="images/data-agent/vault-credentials.png" />
</Frame>

從左側欄開啟 **連線保險庫**。每個連線保險庫有以下分頁：

| 分頁 | 內容 |
| - | - |
| **憑證** | 憑證插槽：MCP 伺服器與密鑰。 |
| **工具包** | 使用此連線保險庫憑證進行驗證的工具允許清單。請見 [工具](/zh/agents/tools)。 |
| **MCP 登錄** | 可加入此連線保險庫的 MCP 伺服器目錄。 |

### 建立連線保險庫

<Steps>
  <Step title="開啟連線保險庫清單">
    開啟 **連線保險庫**，點選 **新增保險庫**。
  </Step>

  <Step title="命名">
    輸入 **名稱**（例如 `production`，在工作區內不可重複），以及選填的 **描述（選填）**。
  </Step>

  <Step title="建立">
    點選 **建立保險庫**，然後開啟該連線保險庫新增憑證。
  </Step>
</Steps>

***

## 新增憑證

開啟連線保險庫，進入 **憑證** 分頁，點選 **新增憑證**。

<Frame>
  <img src="https://mintcdn.com/datagen/rusBmwP8bd_Srmdm/images/data-agent/vault-add-credential.png?fit=max&auto=format&n=rusBmwP8bd_Srmdm&q=85&s=ec95b324b1fbb968d745caa546fec379" alt="新增憑證對話框 -- 選擇密鑰，再設定名稱、目標與類型" width="634" height="787" data-path="images/data-agent/vault-add-credential.png" />
</Frame>

### 欄位

| 欄位 | 適用於 | 用途 |
| - | - | - |
| **來源** | 全部 | **MCP 伺服器** -- Model Context Protocol 伺服器，目標為其 URL。**密鑰** -- 原始具名值，目標為其名稱。 |
| **名稱** | 全部 | 顯示在憑證清單中、供人閱讀的標籤，例如 `OpenAI key`。 |
| **鍵值** | MCP 伺服器 | 你為此憑證取的名稱，在此連線保險庫中不可重複。用來區分同一個伺服器上的不同帳號，例如 `gmail-work` 與 `gmail-personal`。會依名稱自動預填。 |
| **目標** | 全部 | MCP 伺服器：其 URL（`http://` 或 `https://`）。若此連線保險庫還沒有這個 URL 的連接器，會隨憑證一併建立。密鑰：值要注入成的**環境變數名稱**（請見 [密鑰如何變成環境變數](#密鑰如何變成環境變數)）。 |
| **驗證方式** | 全部 | **OAuth**、**Bearer 權杖**、**API 金鑰** 或 **無驗證**。MCP 伺服器預設為 OAuth。密鑰的值會原樣注入，通常選 API 金鑰。 |
| **類型** | 全部 | **與工作區共用** 或 **個人**（見下文）。 |
| **值** | 僅工作區共用 | 憑證本身。靜態加密；成員可以使用但永遠看不到。OAuth 與無驗證不需填寫。 |
| **允許成員使用自己的權杖** | 僅工作區共用 | 自行佈建值的成員，在自己的執行中會使用自己的值；其他人仍使用共用值。 |
| **可送往** | 密鑰（功能可用時） | 此密鑰的對外傳送（egress）政策。請見 [對外傳送政策](#對外傳送政策)。 |

### 工作區共用 vs 個人

用一個問題判斷：*這個值對每位成員都一樣嗎？*

<CardGroup cols={2}>
  <Card title="與工作區共用" icon="users">
    你提供一個值，所有人都能使用但看不到。適用於服務帳號、公司的 API 金鑰，以及資料庫主機、埠號等連線資訊。
  </Card>

  <Card title="個人" icon="user">
    此插槽只是一個宣告。每位成員會看到該列帶有 **連接** 按鈕，並填入自己的值。適用於個人登入、個人的資料庫角色與 OAuth。
  </Card>
</CardGroup>

* 個人值**以連線保險庫為範圍**：成員在此處的值，與他在另一個連線保險庫中同名的值是分開的。
* **OAuth 一律為個人。** 選擇 OAuth 會自動把類型切換為個人；每位成員各自完成授權流程。
* **工作區共用 + 允許成員使用自己的權杖** 適用於中間情境：預設使用一組共用權杖，但開發者在該列點選 **使用我自己的權杖** 後，他的執行就會使用自己的權杖。

### 填入個人值

在個人插槽的那一列點選 **連接**（或點選 **更新** 取代既有的值）：

* **OAuth** -- 會開啟彈出視窗讓你登入供應商。DataGen 儲存你的存取權杖與重新整理權杖，加密且以此連線保險庫為範圍。你的供應商密碼永遠不會被儲存。若彈出視窗被封鎖，請允許此網站的彈出視窗。
* **API 金鑰 / Bearer 權杖** -- 貼上你的值。只有你能使用；管理員與其他成員永遠看不到。

### 狀態欄

| 狀態 | 意義 |
| - | - |
| **由管理員提供** | 工作區共用的值已設定。 |
| **管理員尚未設定值** | 工作區共用插槽還沒有值，只有管理員能處理。 |
| **已以您的身分連接** | 你已填入此個人插槽。 |
| **未連接** | 你尚未填入此個人插槽。 |
| **使用您的權杖** | 允許覆寫的共用插槽正在使用你自己的值。 |
| **不需憑證** | 此插槽使用無驗證。 |

表格上方的橫幅會告訴你，此連線保險庫中的憑證是否都已可供你使用，或有幾個需要處理。

***

## 密鑰如何變成環境變數

當 Agent、知識庫建構器或應用（App）啟動沙盒時，DataGen 會解析其連線保險庫中的每個**密鑰**插槽，並把每一個匯出為環境變數。**目標**就是變數名稱，並經過兩項正規化：

* 連字號（`-`）轉為底線（`_`）
* 名稱轉為大寫

| 目標 | 沙盒中的環境變數 |
| - | - |
| `OPENAI_API_KEY` | `OPENAI_API_KEY` |
| `openai_api_key` | `OPENAI_API_KEY` |
| `stripe-secret` | `STRIPE_SECRET` |

請用程式碼或函式庫實際讀取的大寫名稱來填寫目標，例如 `PGHOST` 或 `OPENAI_API_KEY`，讓連線保險庫表格與程式碼看到的名稱一致。程式碼讀取方式和其他環境變數相同：

```python theme={null}
import os

api_key = os.environ["OPENAI_API_KEY"]
```

**MCP 伺服器**憑證不會匯出為環境變數。Agent 呼叫該伺服器上的工具時，DataGen 才會附上憑證；[工具包](/zh/agents/tools) 決定 Agent 可以呼叫此連線保險庫中的哪些工具。

***

## 輪替、更新與刪除

| 操作 | 誰可以 | 結果 |
| - | - | - |
| **輪替**（共用列） | 管理員 | 貼上 **新值**。加密值會被取代，先前的值無法復原。正在執行中的執行會沿用舊值直到結束；新的執行會自動採用新值。 |
| **更新**（個人列） | 成員本人 | 取代你自己的值。OAuth 會重新執行授權流程 -- OAuth 權杖無法用貼上字串的方式輪替。 |
| **刪除**（垃圾桶圖示） | 管理員 | 為所有人移除此插槽。對話框會列出綁定此連線保險庫的 Agent；輸入憑證名稱以確認。此插槽的個人值會一併遺失。 |

<Tip>
  只要憑證的值曾被貼到聊天、日誌或工單中，就應該輪替。不需要重新部署 -- 下一次執行就會讀到新值。
</Tip>

### 角色

| 角色 | 可以 |
| - | - |
| **管理員** | 所有操作：建立連線保險庫、新增憑證、輪替共用值、刪除憑證、管理工具包、**重新整理工具**。 |
| **建構者** | 建立連線保險庫與新增憑證。無法輪替或刪除既有的共用憑證。 |
| **操作員** | 填入與更新自己的個人值及個人覆寫值。 |
| **檢視者** | 唯讀。 |

***

## 對外傳送政策

<Note>
  對外傳送（egress）政策只在部署了 DataGen egress proxy、且你的帳號已啟用此功能時才會生效。否則 **可送往** 欄位與新增時的 **可送往** 設定會被隱藏，或對話框會顯示 **未啟用** 提示，所有密鑰仍會原樣提供給 Agent。
</Note>

對外傳送政策決定沙盒中的程式碼能否讀到密鑰的真實值。設定政策後，Agent 只會看到替代字串，DataGen 在請求送出時才換上真實值 -- 且只針對你允許的主機。可在密鑰列的 **可送往** 欄位設定，或在新增憑證時的 **可送往** 設定：

| 模式 | 效果 |
| - | - |
| **只送往這些主機** | 只有送往 **主機（每行一個）** 所列主機的請求，替代字串才會換成真實值，例如 `api.example.com` 或 `*.example.com`。 |
| **任何主機（隱藏值）** | 值不會出現在沙盒中，但任何拿到替代字串的程式，仍能把它送到任何網站。 |
| **直接提供真正的值** | Agent 能讀到真實值，也能把它送到任何地方。 |
| **使用內建設定** | 套用 DataGen 對此變數名稱的預設設定。（新增憑證時，對應的「不變更」選項為 **沿用目前設定**。） |

* 只會替換標頭與網址查詢字串中的值。放在請求內容中的密鑰、簽章用密鑰、資料庫連線字串，一律原樣提供。
* 政策套用於**工作區中所有同名的密鑰**，跨所有連線保險庫。
* 變更會從 Agent 的下一個 turn 開始生效。

***

## Agent、知識庫與應用如何使用連線保險庫

| 位置 | 設定 | 未設定時 |
| - | - | - |
| **Agent** | **保險庫與工具套件** 卡片 -> **保險庫**，再點 **儲存保險庫與套件** | **工作區預設** -- Default 連線保險庫 |
| **知識庫建構器** | 知識庫設定 -> **保險庫** | **工作區預設** -- Default 連線保險庫 |
| **應用（App）** | App 建構器 -> **連線保險庫** | **不使用憑證庫** -- 應用收不到任何憑證 |
| **資料建構器** | 資料 -> **建構器設定** -> **連線保險庫** | -- |
| **Harness** | 自訂 LLM 供應商的 **驗證權杖密鑰** | 請見 [Harness](/zh/foundation/harness) |

* **Agent 執行**會依「執行身分」的成員解析個人值。
* **應用**會以開啟它的成員身分解析連線保險庫（包含個人插槽），因此每位成員的應用工作階段都使用自己的值。

***

## 常見問題

<AccordionGroup>
  <Accordion title="執行失敗並顯示「Vault not ready」">
    執行在沙盒啟動前會解析連線保險庫中的**每一個密鑰插槽**。只要有任何插槽對執行身分的成員沒有值 -- 例如空的共用插槽，或該成員從未連接的個人插槽 -- 執行就會立即失敗並顯示 `Vault not ready: <names>`。到連線保險庫頁面填入列出的插槽後再重新執行。請讓連線保險庫保持精簡：即使某個個人插槽只有一個 Agent 需要，對尚未填入它的成員而言，它仍會擋住此連線保險庫上的所有 Agent。
  </Accordion>

  <Accordion title="沙盒裡找不到環境變數">
    檢查目標：它會轉為大寫，且連字號會轉為底線，所以 `my-key` 會變成 `MY_KEY`。也請確認 Agent、知識庫或應用綁定的是存放該插槽的連線保險庫 -- 設為 **不使用憑證庫** 的應用什麼都拿不到。
  </Accordion>

  <Accordion title="連線保險庫插槽與工作區密鑰同名">
    以連線保險庫插槽為準。工作區密鑰（工作區設定 -> **密鑰**）只會補上連線保險庫沒有提供的名稱。
  </Accordion>

  <Accordion title="共用 OAuth">
    OAuth 憑證一律為個人。若要整個工作區共用同一個帳號，請改用其他驗證方式，例如 Bearer 權杖或 API 金鑰。
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="沙箱環境" icon="box" href="/zh/foundation/sandbox-environments">
    把 Agent 程式碼需要的套件預先建置成可重複使用的映像檔。
  </Card>

  <Card title="從程式碼查詢資料庫" icon="database" href="/zh/data/query-from-code">
    實作範例：把 `PG*` 密鑰存進連線保險庫並查詢 Postgres。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.