將您應用程式的私人憑證儲存在 Atoms 雲 → 金鑰 中，讓其值不會出現在 Chat 和原始碼中，並可分別管理 Test 與 Production 的值。

在使用 金鑰 之前，請先將專案連接到 Atoms 雲。如果尚未連接，請要求智能體連接 Atoms 雲，或參考 Atoms 雲。

在 Atoms 雲中使用金鑰

開始之前

新增金鑰前，請確認：

• 您正在桌面版網頁上使用 Atoms。
• 該專案已連接到 Atoms 雲。
• 您是工作區擁有者。只有工作區擁有者可以新增金鑰。

如果無法使用 金鑰 或 New Key，請確認您已開啟預期的專案，且該專案已連接到 Atoms 雲。如果 New Key 仍無法使用，請確認您是工作區擁有者。如果 Atoms 顯示套餐或使用量可用性訊息，請依照畫面上的可用性或升級流程操作後再試一次。

新增 Test 金鑰

1. 在桌面裝置上開啟專案。
2. 在與 App 預覽 所在相同的工作區工具列中，選取 Atoms 雲。
3. 在 Atoms 雲側邊欄中選取 金鑰。
4. 開啟 Test Keys，然後選取 In This Project。
5. 選取 New Key。
6. 完成必填欄位：
   • Name: 輸入清楚的參考名稱，例如 RESEND_API_KEY。請使用字母、數字和底線，並以字母或底線開頭。
   • Value: 請完全依照供應商提供的內容輸入憑證。
   • Description: 說明此金鑰的用途，例如 Used to send account emails。請勿包含憑證值。
7. 如果您想在其他專案中重複使用此金鑰，請選取 Save to Library。
8. 選取 Add。當金鑰儲存完成後，Atoms 會顯示 Key added successfully。

新增 Test 金鑰

只有工作區擁有者可以新增金鑰。如果您需要新增金鑰，請聯絡工作區擁有者。

在 Chat 中使用已儲存的金鑰

請參照已儲存的金鑰，而不是在訊息中輸入其值。

1. 在桌面版 Atoms 中開啟專案的 Chat 並輸入 #。
2. 選取 金鑰。
3. 搜尋已儲存的金鑰，然後選取其名稱。
4. 告訴智能體此金鑰的用途，以及您希望整合執行什麼操作。

# 選單會加入已儲存金鑰的參照，而不會將其值插入您的訊息中。

在 Chat 中參照已儲存的金鑰

測試已儲存的金鑰

1. 在 App 預覽 中，執行一個會使用該金鑰的簡單操作。
2. 確認它產生預期結果，例如寄送測試電子郵件或回傳測試資料。
3. 檢查任何可見的錯誤或日誌，並確認其中未暴露金鑰的值。

如果服務為您提供不同的測試與正式金鑰，請在建置應用程式時使用測試金鑰。只有在應用程式發佈後才使用正式金鑰。如果測試失敗，請檢查供應商的儀表板，確認該金鑰已啟用且有權限執行所要求的操作。進行疑難排解時，切勿將金鑰的值貼到 Chat 中。

了解金鑰的運作方式

在新增金鑰之前，先了解 Atoms 會儲存哪些內容，以及如何保護您的憑證，會很有幫助。

Atoms 會儲存什麼

Atoms 雲 → 金鑰 會儲存您的應用程式用來連接外部服務的憑證，例如 API 金鑰和存取 Token。

每個已儲存的金鑰都有名稱、描述和私人值。名稱與描述可協助智能體了解何時使用該金鑰，而私人值則會對 Chat 隱藏。

在哪裡取得金鑰

Atoms 不會建立或提供外部服務的憑證。您必須向相關服務供應商取得。選擇權限、測試金鑰以及檢查是否會過期時，請遵循供應商的指示。

請妥善保密私人憑證

切勿將私人憑證貼到 Chat、原始碼、在瀏覽器中執行的程式碼、螢幕截圖、日誌或支援訊息中。請將其儲存在 金鑰 中，然後以名稱參照已儲存的項目。

如果私人值已經外洩，請視為已遭洩漏，並透過供應商將其撤銷或輪替。

私人憑證與瀏覽器安全憑證

金鑰 不會將已儲存的值標示為 Public 或 Private。將值儲存在 金鑰 中，並不會自動讓它可安全用於面向瀏覽器的程式碼。如果您的應用程式在瀏覽器中使用該值，訪客可能可以檢視到它。

在決定憑證應用於何處之前，請先查看供應商文件：

• 只有在供應商明確表示可安全公開時，才可在面向瀏覽器的程式碼中使用該值。
• 請將私人憑證保留在伺服器端或後端邏輯中，以免暴露給應用程式訪客。

選擇金鑰的環境與儲存位置

新增金鑰時，您需要做出兩個獨立的決定：

• 哪個環境會使用此金鑰。
• 此金鑰是保留在此專案中，還是提供給其他專案使用。

選擇環境

選項	使用時機
Test Keys	在 App 預覽 中開發與測試應用程式時使用。如果您沒有另外新增 Production 值，已發佈的應用程式也會使用 Test 值。
Production Keys	當已發佈的應用程式需要獨立的正式憑證時使用。Production 值會在發佈流程中新增，並與 Test 值分開管理。

選擇金鑰的儲存位置

選項	何時使用
In This Project	如果此金鑰只應由目前專案使用，請選擇此項。
Key Library	如果您明確希望在多個專案間重複使用某個金鑰，請選擇此項。新增或更新 Test 金鑰時，選取 Save to Library，即可讓它在資料庫中可用。

環境與儲存位置彼此獨立。將 Test 金鑰儲存到 Key Library 會讓它可重複使用，但不會將它變成 Production 值。

預設請使用 In This Project。只有在您確定該金鑰應在多個專案間共用時，才將其儲存到資料庫。

使用獨立的 Production 值

當您發佈使用已儲存金鑰的專案時，發佈流程可能會要求您設定 Production Keys。預設情況下，已發佈的應用程式會使用 Test 值。若要使用不同的憑證，請選取 Production，並為該金鑰儲存獨立的值。

在以下情況下，請使用獨立的 Production 值：

• 供應商提供不同的測試與正式憑證。
• 您不希望開發期間使用的憑證被已發佈的應用程式使用。

Production 值是透過發佈流程建立的。您無法從 Production Keys 分頁選取 New Key 來建立。為已發佈的應用程式設定好 Production 值後，您可以在 Atoms 雲 → 金鑰 → Production Keys 下查看。

發佈或更新應用程式後，請在已發佈的網站上重複相關的使用者流程，以確認 Production 金鑰運作正常。完整部署流程請參閱 Publish and deploy。

更新或輪替憑證

更新已儲存的 Test 值

1. 開啟 Atoms 雲 → 金鑰 → Test Keys。
2. 依據項目儲存的位置，開啟 In This Project 或 Key Library。
3. 選取該金鑰的 Value 或 Description，輸入更新後的資訊，然後選取 Update。
4. 等待出現 Save success，然後再次測試受影響的流程。

計畫性的金鑰輪替

當現有憑證仍然安全，而您想在不中斷應用程式的情況下替換它時，請依照以下步驟操作：

1. 透過服務供應商建立替代憑證。
2. 在 Atoms 中替換 Test 值，然後在 App 預覽 中測試受影響的功能。
3. 如果已發佈的應用程式使用獨立的 Production 值，請替換它並發佈更新。
4. 在已發佈的網站上測試相同功能。
5. 確認替代憑證運作正常後，透過供應商撤銷舊憑證。

如果憑證可能已外洩

請將該憑證視為已遭洩漏並立即採取行動：

1. 透過服務供應商將其撤銷或停用。
2. 建立替代憑證。
3. 更新 Atoms 中相關的 Test 與 Production 值。
4. 在 App 預覽 和已發佈的應用程式中再次測試受影響的功能。
5. 盡可能從原始碼、Chat、螢幕截圖和日誌中移除任何已暴露的副本。

刪除金鑰或從 Atoms 中移除其值，並不會撤銷原始憑證。您必須透過服務供應商將其撤銷。

移除憑證

刪除已儲存的金鑰前，請確認您的應用程式已不再依賴它：

1. 移除使用該金鑰的功能，或以另一個已儲存的金鑰取代其參照。
2. 透過服務供應商撤銷原始憑證，使其無法再被使用。
3. 開啟 Atoms 雲 → 金鑰，找到未啟用的項目，選取 Delete，然後確認。

刪除金鑰後無法復原。它也可能導致仍參照該金鑰的預覽或舊檢查點失效。如果無法使用 Delete，表示該金鑰仍被標記為啟用中。請先移除或替換所有對它的參照，再重新嘗試。

常見問題

我的 Test 金鑰在 App 預覽 中可以運作，但發佈後卻不行。為什麼？

如果您的 Test 金鑰在 App 預覽 中可正常運作，但已發佈的應用程式因金鑰缺失或為空而失敗：

1. 請檢查相關的 Test 或 Production 值是在上次發佈之前還是之後儲存的。如果是在之後儲存，請重新發佈，讓變更生效。
2. 確認已儲存的金鑰具有正確的 Test 或 Production 值。除非已設定獨立的 Production 值，否則已發佈的應用程式會使用 Test 值。
3. 查看下游服務錯誤以尋找線索。「Unauthorized」通常表示該環境的金鑰為空或不正確。

如果問題仍然存在，請聯絡支援團隊並提供：

• 專案連結或正式網址
• 受影響的金鑰名稱，以及是 Test 還是 Production 值有問題
• 下游服務的完整錯誤訊息
• 已遮蔽敏感資訊的設定頁面截圖
• 金鑰設定是在發佈之前還是之後儲存的

重要：僅提供金鑰名稱。請勿傳送密鑰值、密碼或 Token。