orpheagentVersion 1.1.9

API 端點

OrpheAgent RESTful API、WebSocket、身分驗證及資料平面端點說明。

OrpheAgent API 端點

OrpheAgent 提供 RESTful API 與 WebSocket 端點，用於管理設定、系統資訊、控制平面、資料平面、服務狀態及設備驗證。除另有說明外，下列路徑皆以 /api/v1 為 Base URL。

Swagger UI

將 {ORPHEAGENT_HOST} 替換為執行 OrpheAgent 的主機 IP 位址或網域名稱後，可使用下列網址開啟 Swagger UI：

http://{ORPHEAGENT_HOST}/swagger/index.html#/

Non-release build：以 debug foreground 模式啟動 Agent 時提供 Swagger UI。
```
orphe-agent up -f -d
```
Release build：不註冊 Swagger UI。

身分驗證

受保護的端點會檢查 Authorization header。請求來源為 127.0.0.1 時，中介層會略過 token 驗證；WebSocket 與瀏覽器流程也可透過 token query parameter 傳入同一組 token。

表格中的「驗證」欄依原始 API 文件標示；— 代表原始文件未宣告驗證需求。

開發 (Develop)

方法	端點	功能	驗證
GET	`/develop/ws/terminal`	開啟網頁終端機執行工作階段的 WebSocket 連線。	需要
GET	`/develop/debug/memory`	回傳 Go runtime 的記憶體統計資料。	需要
POST	`/develop/debug/memory/free`	執行垃圾回收、將記憶體歸還作業系統，並回傳更新後的統計資料。	需要

儀表板 (Dashboards)

方法	端點	功能	驗證
GET	`/dashboards/get`	擷取 CPU、記憶體與磁碟使用量等系統儀表板資訊。	需要

系統 (System)

方法	端點	功能	驗證
GET	`/system/info`	擷取 OrpheAgent 軟體版本及相關資訊。	需要
GET	`/system/update/check`	檢查是否有較新的 OrpheAgent 版本。	需要
POST	`/system/update/install`	在背景下載並安裝最新版本。	需要
GET	`/system/update/progress`	擷取目前更新作業的進度。	需要

控制平面 (Control Plane)

方法	端點	功能	驗證
GET	`/controlplane/status`	擷取供裝狀態與 OrpheLink 連線狀態。	需要
GET	`/controlplane/dht`	擷取控制平面的 DHT 啟用狀態。	需要
POST	`/controlplane/dht`	啟用或停用控制平面的 DHT。	需要
GET	`/controlplane/relayaddrs`	擷取控制平面的自有中繼位址。	需要
POST	`/controlplane/relayaddrs`	更新控制平面的自有中繼位址。	需要

設定 (Configuration)

方法	端點	功能	驗證
POST	`/config`	儲存完整設定。	需要
POST	`/config/basic`	僅儲存主機名稱與 Provision Key。	需要
GET	`/config`	載入目前設定。	需要

網路 (Network)

方法	端點	功能	驗證
GET	`/network/statistics/ws`	透過 WebSocket 提供網路流量統計。	—
GET	`/network/nat/type`	偵測並回傳目前的 NAT 類型。	—

跳轉服務 (Jump to Service)

方法	端點	功能	驗證
POST	`/jumptoservice/config`	儲存 Jump-to-Service 設定。	需要
GET	`/jumptoservice/config`	載入 Jump-to-Service 設定。	需要
DELETE	`/jumptoservice/config/:name`	刪除指定名稱的 Jump-to-Service 設定。	需要

服務 (Service)

方法	端點	功能	驗證
GET	`/service/status/ws`	透過持久 WebSocket 串流傳送 OrpheAgent 與 OrpheLink 的連線狀態。	需要
GET	`/service/toggle`	擷取控制平面與資料平面的開關狀態。	需要
POST	`/service/toggle`	啟用或停用控制平面和／或資料平面。	需要

設備驗證 (Device Auth)

方法	端點	功能	驗證
GET	`/deviceauth/status`	擷取設備 Magic Link 驗證狀態，以及是否允許啟用資料平面。	需要
POST	`/deviceauth/send`	要求 Controller 寄送驗證 Magic Link；`/deviceauth/resend` 為相同端點的 alias。	需要

Magic Link 不會自動寄送。Agent 會回報 magicLinkAutoSend: false；設備於睡眠喚醒或控制平面重新啟動後，會停留在 awaiting_request，直到使用者執行 orphe-agent device-auth --send 要求寄送連結。

設定檔 (Profile)

方法	端點	功能	驗證
POST	`/profile`	建立設定檔。	需要
GET	`/profile`	擷取設定檔清單。	需要
DELETE	`/profile`	刪除設定檔。	需要
POST	`/profile/use`	將指定設定檔設為目前使用中的設定檔。	需要

資料平面 (Data Plane)

節點與鄰居

方法	端點	功能	驗證
GET	`/dataplane/node`	擷取資料平面的節點資訊。	需要
POST	`/dataplane/node`	更新資料平面的節點資訊。	需要
POST	`/dataplane/neighbor/add`	新增鄰居。	需要
POST	`/dataplane/neighbor/edit/:id`	編輯指定鄰居。	需要
POST	`/dataplane/neighbor/delete/:id`	刪除指定鄰居。	需要

資料平面控制

方法	端點	功能	驗證
POST	`/dataplane/start`	啟動資料平面。	需要
POST	`/dataplane/stop`	停止資料平面。	需要
POST	`/dataplane/restart`	重新啟動資料平面。	需要
GET	`/dataplane/status`	擷取目前的資料平面狀態。	需要
GET	`/dataplane/status/ws`	透過持久 WebSocket 串流傳送節點、鄰居、流量、作業系統、設備名稱及 P2P 連線品質等狀態。	需要
POST	`/dataplane/status/:status`	更新資料平面狀態。	需要

路由與中繼

方法	端點	功能	驗證
GET	`/dataplane/routesubnettoexit`	擷取路由至出口節點的子網路。	需要
POST	`/dataplane/routesubnettoexit`	設定要路由至出口節點的子網路。	需要
GET	`/dataplane/relayaddrs`	擷取資料平面使用的中繼位址。	需要
POST	`/dataplane/relayaddrs`	更新資料平面的中繼位址。	需要

通訊埠轉發

方法	端點	功能	驗證
GET	`/dataplane/portforwarding/list`	列出所有通訊埠轉發規則。	需要
POST	`/dataplane/portforwarding/add`	新增通訊埠轉發規則。	需要
POST	`/dataplane/portforwarding/delete/:name`	依名稱刪除通訊埠轉發規則。	需要

存取控制清單 (ACL)

方法	端點	功能	驗證
POST	`/dataplane/acl/mode/:mode`	設定資料平面的 ACL 模式。	需要
GET	`/dataplane/acl/mode`	擷取目前的 ACL 模式。	需要
GET	`/dataplane/acl/list`	列出所有 ACL 規則。	需要
POST	`/dataplane/acl`	新增 ACL 規則。	需要
DELETE	`/dataplane/acl`	刪除 ACL 規則。	需要

服務、MTU 與穿隧模式

方法	端點	功能	驗證
GET	`/dataplane/services/list`	列出資料平面的所有服務。	需要
POST	`/dataplane/services/edit`	編輯資料平面中的服務。	需要
POST	`/dataplane/services/edit/{id}`	編輯指定鄰居或節點 ID 的服務。	需要
GET	`/dataplane/mtu`	擷取 MTU 設定。	需要
POST	`/dataplane/mtu`	更新 MTU 設定。	需要
GET	`/dataplane/tunnelmode`	擷取目前的穿隧模式（高吞吐量或低延遲）。	需要
POST	`/dataplane/tunnelmode`	設定資料平面的穿隧模式。	需要

SNAT、子網路與終端設備

方法	端點	功能	驗證
GET	`/dataplane/snat`	擷取目前的 SNAT 設定。	需要
POST	`/dataplane/snat/{status}`	設定資料平面的 SNAT 狀態。	需要
GET	`/dataplane/subnetlist`	擷取資料平面的子網路清單。	需要
GET	`/dataplane/enddevicelist`	擷取資料平面的終端設備清單。	需要

DHT 與 NAT 類型

方法	端點	功能	驗證
GET	`/dataplane/dht/{id}`	擷取指定節點的 DHT 啟用狀態。	需要
POST	`/dataplane/dht/{id}`	啟用或停用指定節點的 DHT。	需要
GET	`/dataplane/nat/type/{id}`	擷取指定節點的 NAT 類型。	需要

出口節點與 LAN 共用

方法	端點	功能	驗證
GET	`/dataplane/exitnode/list`	從鄰居清單擷取可用的出口節點。	需要
GET	`/dataplane/exitnode/config/{id}`	擷取指定節點的出口節點設定。	需要
POST	`/dataplane/exitnode/config/{id}`	設定指定節點使用的出口節點。	需要
GET	`/dataplane/lan/subnetsharing/config/{id}`	擷取指定節點的 LAN 子網路共用設定。	需要
POST	`/dataplane/lan/subnetsharing/config/{id}`	設定指定節點的 LAN 子網路共用。	需要

Route to Exit 與設備設定

方法	端點	功能	驗證
GET	`/dataplane/routetoexit/config/{id}`	擷取指定節點的 Route-to-Exit 設定。	需要
POST	`/dataplane/routetoexit/config/{id}`	將指定節點的流量導向設定的出口節點。	需要
POST	`/dataplane/config/rename/{id}`	重新命名指定節點的設備設定。	需要

Portal 驗證與打洞事件

方法	端點	功能	驗證
POST	`/dataplane/portal/login`	處理 Portal 登入驗證。	—
GET	`/dataplane/holepunchevent/ws`	透過 WebSocket 即時傳送 NAT 位址交換、打洞嘗試與對等節點連線狀態。	需要