Skip to main content
Manager API 運行在埠 8443，預設啟用 TLS。所有端點（健康檢查除外）都需要透過 Bearer token 進行身份驗證。

​
Bearer Token 身份驗證

Manager API 使用共享靜態 token 進行身份驗證。此 token 透過 MANAGER_AUTH_TOKEN 環境變數設定，並使用 SHA-256 時間安全比較以防止計時攻擊。 
curl -X GET https://localhost:8443/api/agents \
  -H "Authorization: Bearer YOUR_MANAGER_TOKEN" \
  -H "Content-Type: application/json"
Manager token 授予對所有 Manager API 端點的完全存取權限。請像對待 root 密碼一樣對待它：
  • 永遠不要將其提交到版本控制
  • 使用強隨機值（至少 32 個字元）
  • 定期輪換
  • 透過環境變數設定，不要放在設定檔中

​
Token 驗證

每個請求都會經過以下步驟驗證：
  1. 提取 Authorization 標頭
  2. 驗證 Bearer 前綴
  3. 對提供的 token 進行 SHA-256 雜湊
  4. 時間安全比較與儲存的雜湊值
  5. 如果比較失敗則以 401 拒絕
時間安全比較確保攻擊者無法透過測量回應時間來推斷正確的 token。每個無效的 token 被拒絕所需的時間相同，無論有多少字元匹配。

​
速率限制

範圍限制時間窗口
每個 IP60 次請求1 分鐘
當受到速率限制時，API 回傳： 
{
  "ok": false,
  "error": "Too many requests. Please try again later."
}
附帶標頭：
標頭值
X-RateLimit-Limit60
X-RateLimit-Remaining0
Retry-After限制重設前的秒數

​
安全標頭

Manager API 在每個回應上設定以下安全標頭：
標頭值用途
X-Content-Type-Optionsnosniff防止 MIME 類型嗅探
X-Frame-OptionsDENY防止透過 iframe 進行點擊劫持
X-XSS-Protection1; mode=block在舊版瀏覽器中啟用 XSS 過濾器
Strict-Transport-Securitymax-age=31536000; includeSubDomains強制使用 HTTPS 1 年
Content-Security-Policydefault-src 'self'限制資源載入
X-Request-Id唯一 UUID請求追蹤識別碼

​
CORS 設定

跨來源資源共享透過 CORS_ALLOWED_ORIGINS 環境變數設定。 
# 允許特定來源
CORS_ALLOWED_ORIGINS=https://dashboard.panguard.ai,https://admin.example.com

# 允許所有來源（僅限開發環境）
CORS_ALLOWED_ORIGINS=*
在正式環境中永遠不要使用 CORS_ALLOWED_ORIGINS=*。請始終指定應該有權存取 Manager API 的確切來源。

​
CORS 標頭

標頭值
Access-Control-Allow-Origin已設定的來源
Access-Control-Allow-MethodsGET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-HeadersAuthorization, Content-Type, X-Request-Id
Access-Control-Max-Age86400（24 小時）

​
健康檢查

​
GET /health

回傳服務健康狀態。不需要身份驗證。 
curl -X GET https://localhost:8443/health

{
  "ok": true,
  "data": {
    "status": "healthy",
    "version": "1.2.0",
    "uptime": 86400,
    "agents": {
      "total": 12,
      "online": 10
    }
  }
}
使用 /health 端點進行負載平衡器健康檢查和監控系統。它回應快速且不需要身份驗證。