安全性與部署

DevUI 被設計為 本地開發的範例應用程式。 本頁涵蓋了安全考量與最佳實務，若您需要將 DevUI 暴露於 localhost 之外。

Warning

DevUI 並非為生產環境設計。 對於生產部署，請使用 Agent Framework SDK 建立自己的自訂介面，並搭配適當的安全措施。

即將推出

C# 的 DevUI 文件即將推出。 請稍後回來查看，或參考 Python 文件以獲得概念指引。

使用者介面模式

DevUI 提供兩種控制功能存取的模式：

開發者模式（預設）

完整存取所有功能：

  • 帶有追蹤資訊的除錯面板
  • 熱重載以促進快速開發（/v1/entities/{id}/reload）
  • 部署工具 （/v1/deployments）
  • 冗長錯誤訊息用於除錯
devui ./agents  # Developer mode is the default

使用者模式

簡化且受限的介面：

  • 聊天介面與對話管理
  • 實體列表與基本資訊
  • 開發者 API 被停用（熱重載、部署）
  • 通用錯誤訊息（伺服器端記錄細節）
devui ./agents --mode user

Authentication

Bearer 權杖驗證預設為啟用。 對於回送位址繫結，DevUI 會產生一個權杖並在主控台中顯示：

devui ./agents

對於可重複的權杖，請設定 DEVUI_AUTH_TOKEN 或使用 --auth-token。 非迴圈綁定需要明確的權杖，且若無權杖則會以封閉方式失敗：

# Custom token via CLI
devui ./agents --auth-token "your-secure-token"

# Custom token via environment variable
export DEVUI_AUTH_TOKEN="your-secure-token"
devui ./agents --host 0.0.0.0

所有 API 請求都必須在 Authorization 標頭中包含該權杖：

curl http://localhost:8080/v1/entities \
  -H "Authorization: Bearer your-secure-token"

僅將 --no-auth 用於隔離的 loopback 開發。 DevUI 會拒絕未經驗證的非回環綁定，甚至連回環無驗證模式也會移除對敵對網站所送出請求的保護。

如果你需要向終端使用者開放 DevUI（不建議用於生產環境）：

DEVUI_AUTH_TOKEN="<secure-dev-token>" devui ./agents --mode user --host 0.0.0.0

此配置：

  • 限制面向開發者的 API
  • 需要驗證
  • 綁定至所有網路介面

安全特性

DevUI 包含多項安全措施：

Feature 說明
本地主機綁定 預設綁定到 127.0.0.1
使用者模式 限制開發者 API
Authentication Bearer 權杖認證預設啟用
無驗證模式 僅允許在 localhost 或 127.0.0.1 上使用
網路綁定 需要 DEVUI_AUTH_TOKEN 或 --auth-token
本地實體載入 只會從本地目錄或記憶體中載入實體
沒有遠端執行 沒有遠端程式碼執行功能

最佳做法

認證管理

  • 將 API 金鑰與秘密存放在檔案中.env
  • 切勿將.env檔案提交到原始碼控制系統中。
  • 使用 .env.example 檔案來記錄必要的變數
# .env.example (safe to commit)
OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/

# .env (never commit)
OPENAI_API_KEY=sk-actual-key
AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/

網路安全性

  • 開發時請保持 DevUI 綁定在 localhost。
  • 如果需要外部存取，可以使用反向代理（nginx、Caddy）。
  • 透過反向代理啟用 HTTPS。
  • 在代理層級實作正確的認證

實體安全性

  • 執行前會檢查所有代理/工作流程程式碼
  • 只載入來自受信任來源的實體
  • 使用有副作用的工具（檔案存取、網路通話）要小心。

資源清理

用於關機時正確關閉認證與資源的登錄清理掛鉤：

import os
from azure.identity.aio import DefaultAzureCredential
from agent_framework import Agent
from agent_framework.openai import OpenAIChatCompletionClient
from agent_framework_devui import register_cleanup, serve

credential = DefaultAzureCredential()
client = OpenAIChatCompletionClient(
    model=os.environ["AZURE_OPENAI_CHAT_COMPLETION_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=credential,
)
agent = Agent(name="MyAgent", client=client)

# Register cleanup hook - credential will be closed on shutdown
register_cleanup(agent, credential.close)
serve(entities=[agent])

MCP 工具考量

使用 MCP（模型情境協定）工具搭配 DevUI：

# Correct - DevUI handles cleanup automatically
mcp_tool = MCPStreamableHTTPTool(url="http://localhost:8011/mcp", client=chat_client)
agent = Agent(tools=mcp_tool)
serve(entities=[agent])

這很重要

在使用 MCP 工具製作 DevUI 代理時，不要使用 async with 上下文管理器。 連線會在執行前關閉。 MCP 工具採用延遲初始化，首次使用時自動連接。

備註

Go 對此功能的支援即將推出。 最新狀態請參閱 Agent Framework Go 倉庫 。

後續步驟

  • 上次更新時間：