上游探索

upstream.discovery 外掛透過服務註冊中心、容器編排系統或雲端 API，把一個服務解析為目前支撐它的伺服器。使用者把 nginx upstream 繫結到一個服務後，Nginx UI 依繫結的重新整理間隔呼叫外掛，把結果寫成 upstream 區塊儲存到自己的檔案中，並在伺服器變化時重新載入 nginx。

方法	必要	用途
discovery.resolve	是	把一個服務解析為它目前的伺服器。

外掛必須請求 network 權限。

宣告提供者

"capabilities": ["upstream.discovery"],
"permissions": ["network"],
"discovery": {
  "providers": [
    {
      "code": "registry",
      "name": "Service registry",
      "configuration": {
        "fields": [
          { "key": "address", "display_name": "Registry address", "required": true },
          { "key": "token", "display_name": "ACL token", "secret": true },
          { "key": "healthy_only", "type": "bool", "display_name": "Only healthy instances" }
        ]
      }
    }
  ]
}

code、name 和 configuration.fields 的用法與通知通道相同。

解析

{
  "jsonrpc": "2.0", "id": 50, "method": "discovery.resolve",
  "params": { "provider": "registry", "config": { "address": "https://registry.example.com:8500", "token": "tok_live_xxx" }, "service": "api" }
}

service 使用提供者自己的術語：服務名稱、標籤選擇器或標記。回覆目前支撐它的每一台伺服器：

{
  "jsonrpc": "2.0", "id": 50,
  "result": {
    "targets": [
      { "address": "10.0.1.12", "port": 8080, "weight": 1, "tags": ["zone-a"] },
      { "address": "10.0.2.7", "port": 8080, "weight": 2, "tags": ["zone-b", "canary"] },
      { "address": "2001:db8::17", "port": 8443 }
    ],
    "ttl_seconds": 30
  }
}

欄位	意義
targets[].address	不帶方括號的 IPv4 或 IPv6 位址，或主機名稱。不含連接埠或協定。
targets[].port	TCP 連接埠，1 到 65535。
targets[].weight	相對權重，1 到 1000。0 或不填表示 1。
targets[].tags	僅供顯示的標籤。
ttl_seconds	結果的有效期。0 表示由間隔決定。

空清單表示該服務目前沒有伺服器。無法解析服務時，回覆錯誤，使 Nginx UI 保留現有的伺服器：原因在於設定（包括認證被拒絕，以及提供者不認識的 service，此時指出 service）時回覆帶 data.field 的 -32003，其他情況回覆 -32000。請把 config 的每個值都當作機密。

Nginx UI 如何處理結果

• 它只保留位址能解析為 IP 位址或有效主機名稱、連接埠和權重都在範圍內的目標，捨棄其餘目標並回報數量。其他文字（包括 tags）都不會進入設定。沒有有效目標時，它保留目前的檔案並記錄失敗，因為沒有伺服器的 upstream 是無效的。

• 它把每個繫結寫入 <nginx 設定目錄>/upstreams/<名稱>.conf，upstream 名稱由使用者選擇：

  # generated by nginx-ui
  upstream api {
      server 10.0.1.12:8080 weight=1;
      server 10.0.2.7:8080 weight=2;
      server [2001:db8::17]:8443 weight=1;
      keepalive 32;
  }

  最後幾行是使用者為該繫結輸入的額外指令。

• 只有檔案變化時才重新載入 nginx，重新載入前先測試設定，測試失敗時還原先前的檔案。

• 它向使用者顯示需要在 http 層加入的那一行：include upstreams/<名稱>.conf;。

繫結預設每 60 秒重新整理一次，最短間隔為 10 秒；上次結果的 ttl_seconds 更短時會提前重新整理。discovery.resolve 最多等待 30 秒，最近一次解析的結果顯示在繫結旁邊。