金鑰與密鑰
將您 app 的私人憑證儲存在 Atoms 雲 → 金鑰 中，可避免其值出現在 Chat 和原始碼中，並可分別管理 Test 與 Production 的值。
在使用 金鑰 之前，請先將專案連接到 Atoms 雲。如果尚未連接，請要求智能體連接 Atoms 雲，或參閱 Atoms 雲。
在 Atoms 雲 中使用金鑰
開始之前
在新增金鑰之前，請確認：
- 您正在桌面版網頁上使用 Atoms。
- 專案已連接到 Atoms 雲。
- 您是工作區擁有者。只有工作區擁有者可以新增金鑰。
如果 金鑰 或 新增金鑰 無法使用，請確認您已開啟預期的專案，且該專案已連接到 Atoms 雲。如果 新增金鑰 仍然無法使用，請確認您是工作區擁有者。如果 Atoms 顯示套餐或使用可用性訊息，請依照畫面上的可用性或升級流程操作，然後再試一次。
新增 Test 金鑰
- 在桌面裝置上開啟專案。
- 在與 App 預覽 所在相同的工作區工具列中，選取 Atoms 雲。
- 在 Atoms 雲 側邊欄中選取 金鑰。
- 開啟 Test 金鑰，然後選取 在此專案中。
- 選取 新增金鑰。
- 完成必填欄位：
- 名稱： 輸入清楚的參考名稱，例如 RESEND_API_KEY。請使用字母、數字和底線，並以字母或底線開頭。
- 值： 完整輸入供應商提供的憑證。
- 說明： 說明此金鑰的用途，例如 用於傳送帳戶電子郵件。請勿包含憑證值。
- 如果您想在其他專案中重複使用此金鑰，請選取 儲存到資料庫。
- 選取 新增。當金鑰儲存完成後，Atoms 會顯示 金鑰已成功新增。
新增 Test 金鑰
只有工作區擁有者可以新增金鑰。如果您需要新增金鑰，請聯絡工作區擁有者。
在 Chat 中使用已儲存的金鑰
請參照已儲存的金鑰，而不是在訊息中輸入其值。
- 在桌面版 Atoms 中開啟專案的 Chat，並輸入
#。 - 選取 金鑰。
- 搜尋已儲存的金鑰，然後選取其名稱。
- 告訴智能體此金鑰的用途，以及您希望整合執行的操作。
# 選單會加入已儲存金鑰的參照，而不會將其值插入您的訊息中。
在 Chat 中參照已儲存的金鑰
測試已儲存的金鑰
- 在 App 預覽 中，執行一個會使用該金鑰的簡單操作。
- 確認它會產生預期結果，例如寄送測試電子郵件或回傳測試資料。
- 檢查任何可見的錯誤或日誌，並確認其中未暴露金鑰的值。
如果服務為您提供不同的測試金鑰與正式金鑰，請在建置 app 時使用測試金鑰。只有在 app 發佈後才使用正式金鑰。如果測試失敗，請檢查供應商的控制台，確認該金鑰已啟用，且有權限執行所要求的操作。在疑難排解時，切勿將金鑰的值貼到 Chat 中。
了解金鑰的運作方式
在新增金鑰之前，先了解 Atoms 會儲存什麼，以及如何保護您的憑證，會很有幫助。
Atoms 會儲存什麼
Atoms 雲 → 金鑰 會儲存您的 app 用來連接外部服務的憑證，例如 API 金鑰與存取 Token。
每個已儲存的金鑰都包含名稱、說明和私人值。名稱與說明可協助智能體了解何時使用該金鑰，而私人值則會對 Chat 隱藏。
在哪裡取得金鑰
Atoms 不會建立或提供外部服務的憑證。您必須向相關服務供應商取得。選擇權限、測試金鑰以及確認是否會過期時，請遵循供應商的指示。
保持私人憑證的機密性
切勿將私人憑證貼到 Chat、原始碼、在瀏覽器中執行的程式碼、螢幕截圖、日誌或支援訊息中。請將其儲存在 金鑰 中，然後以名稱參照已儲存的項目。
如果私人值已經暴露，請視為已洩漏，並透過供應商將其撤銷或輪替。
私人憑證與可安全用於瀏覽器的憑證
金鑰 不會將已儲存的值標示為 公開 或 私人。將值儲存在 金鑰 中，並不會自動讓它適合用於面向瀏覽器的程式碼。如果您的 app 在瀏覽器中使用該值，訪客可能可以檢視它。
在決定將憑證用於何處之前，請先查閱供應商文件：
- 只有在供應商明確表示可安全公開時，才可在面向瀏覽器的程式碼中使用該值。
- 請將私人憑證保留在伺服器端或後端邏輯中，避免暴露給 app 訪客。
選擇金鑰的環境與儲存位置
新增金鑰時，您需要分別做出兩個決定：
- 哪個環境會使用此金鑰。
- 金鑰是保留在此專案中，還是可供其他專案使用。
選擇環境
| 選項 | 使用時機 |
|---|---|
| Test 金鑰 | 在 App 預覽 中開發與測試 app 時使用。如果您沒有另外新增 Production 值，已發佈的 app 也會使用 Test 值。 |
| Production 金鑰 | 當已發佈的 app 需要獨立的正式憑證時使用。Production 值會在發佈流程中新增，並與 Test 值分開管理。 |
選擇金鑰的儲存位置
| 選項 | 何時使用 |
|---|---|
| 在此專案中 | 當金鑰只應由目前專案使用時，請選擇此項。 |
| 金鑰資料庫 | 當您明確希望在多個專案間重複使用金鑰時，請選擇此項。新增或更新 Test 金鑰時，選取 儲存到資料庫，即可讓它在資料庫中可用。 |
環境與儲存位置彼此獨立。將 Test 金鑰儲存到 金鑰資料庫 可讓它重複使用，但不會將它轉換為 Production 值。
預設請使用 在此專案中。只有在您確定該金鑰應跨專案共用時，才將其儲存到資料庫。
使用獨立的 Production 值
當您發佈使用已儲存金鑰的專案時，發佈流程可能會要求您設定 Production 金鑰。預設情況下，已發佈的 app 會使用 Test 值。若要使用不同的憑證，請選取 Production，並為該金鑰儲存獨立的值。
以下情況請使用獨立的 Production 值：
- 供應商提供不同的測試憑證與正式憑證。
- 您不希望開發期間使用的憑證被已發佈的 app 使用。
Production 值是透過發佈流程建立的。您無法在 Production 金鑰 分頁中選取 新增金鑰 來建立。為已發佈的 app 設定 Production 值後，您可以在 Atoms 雲 → 金鑰 → Production 金鑰 下查看。
在發佈或更新 app 後，請在已發佈網站上重複相關使用者流程，以確認 Production 金鑰運作正常。完整部署流程請參閱 發佈與部署。
更新或輪替憑證
更新已儲存的 Test 值
- 開啟 Atoms 雲 → 金鑰 → Test 金鑰。
- 視項目儲存位置而定，開啟 在此專案中 或 金鑰資料庫。
- 選取金鑰的 值 或 說明，輸入更新後的資訊，然後選取 更新。
- 等待出現 儲存成功，然後再次測試受影響的流程。
計劃性的金鑰輪替
當現有憑證仍然安全，而您想在不中斷 app 的情況下替換它時，請依照以下步驟操作：
- 透過服務供應商建立替代憑證。
- 在 Atoms 中替換 Test 值，然後在 App 預覽 中測試受影響的功能。
- 如果已發佈的 app 使用獨立的 Production 值，請替換它並發佈更新。
- 在已發佈網站上測試相同功能。
- 確認替代憑證運作正常後，透過供應商撤銷舊憑證。
如果憑證可能已暴露
請將該憑證視為已洩漏，並立即採取行動：
- 透過服務供應商將其撤銷或停用。
- 建立替代憑證。
- 在 Atoms 中更新相關的 Test 與 Production 值。
- 在 App 預覽 與已發佈 app 中再次測試受影響的功能。
- 盡可能從原始碼、Chat、螢幕截圖與日誌中移除任何已暴露的副本。
從 Atoms 刪除金鑰或移除其值，並不會撤銷原始憑證。您必須透過服務供應商將其撤銷。
移除憑證
在刪除已儲存的金鑰之前，請確認您的 app 已不再依賴它：
- 移除使用該金鑰的功能，或以另一個已儲存的金鑰取代其參照。
- 透過服務供應商撤銷原始憑證，使其無法再被使用。
- 開啟 Atoms 雲 → 金鑰，找到未啟用的項目，選取 刪除，然後確認。
刪除金鑰後無法復原。它也可能會破壞仍參照該金鑰的預覽或較舊的檢查點。如果 刪除 無法使用，表示該金鑰仍標示為使用中。請先移除或取代所有對它的參照，再重新嘗試。
常見問題
我的 Test 金鑰在 App Viewer 中可用，但發佈後卻無法使用。為什麼？
如果您的 Test 金鑰在 App Viewer 中可用，但已發佈的 app 因金鑰遺失或為空而失敗：
- 檢查相關的 Test 或 Production 值是在上次發佈之前還是之後儲存的。如果是在之後儲存，請重新發佈，讓變更生效。
- 確認已儲存的金鑰具有正確的 Test 或 Production 值。除非已設定獨立的 Production 值，否則已發佈的 app 會使用 Test 值。
- 檢查下游服務錯誤以取得線索。「Unauthorized」通常表示該環境的金鑰為空或不正確。
如果問題仍然存在，請聯絡支援團隊，並提供：
- 專案連結或正式網址
- 受影響的金鑰名稱，以及是 Test 還是 Production 值有問題
- 下游服務的完整錯誤訊息
- 已去除敏感資訊的設定頁面截圖
- 金鑰設定是在發佈之前還是之後儲存的
重要：只提供金鑰名稱。請勿提供密鑰值、密碼或 Token。