🔗 OpenResty Edge 安裝常見問題

🔗 系統要求與架構

🔗 OpenResty Edge 包含哪些主要元件？它們各自的作用是什麼？

OpenResty Edge 主要包含三個核心元件：Edge Admin （管理控制檯）、Edge Log Server（日誌和指標伺服器）和 Edge Node（閘道器節點）。此外還有兩個資料儲存元件：Edge Admin Database 和 Edge Log Server Database。

🔗 安裝 OpenResty Edge 需要什麼樣的硬體配置？

正式環境至少需要三臺機器，分別安裝 Edge Admin + Admin DB、Log Server + Log Server DB 和 Edge Node。對於 10 個節點以內的叢集，Edge Admin 和 Log Server 推薦至少 4 核 16G 記憶體 200G SSD，Edge Node 根據業務量而定，一般 1 核心配 2G 記憶體。

🔗 我的網路環境有防火牆限制，需要開放哪些埠和域名？

需要將 openresty.com 、openresty.org 、pkg.openresty.com 、api.openresty.com 的 443 埠加入白名單。各元件間也需要開放特定埠：Edge Admin 需要開放 443 和 12345 埠，Log Server 需要開放 12346 和 8089 埠。

🔗 安裝過程

🔗 如何獲取 OpenResty Edge 的安裝包？

可以從 OpenResty 的下載中心 (https://openresty.com.cn/cn/dashboard/downloads) 獲取線上安裝包所需的配置包 (openresty-edge-VERSION.tar.gz) 和完整的離線安裝包 (openresty-edge-bundle-VERSION.tar.gz) 。

🔗 安裝完成後如何獲取 Edge Admin 管理介面的登入賬號和密碼？

可以使用安裝器的“Get Default Info”功能獲取預設登入資訊，或者聯絡技術支援重置密碼。

🔗 安裝完成後如何驗證各元件是否正常工作？

可以透過 systemctl status 命令檢查各服務狀態，例如 sudo systemctl status oredge-admin，也可以檢視各元件的日誌目錄，如 /usr/local/oredge-admin/logs 中是否有異常資訊。

🔗 配置與高可用

🔗 如何提高 Edge Admin 和 Log Server 的可用性？

可以配置兩份 Edge Admin 服務為雙主模式，或部署多個 Log Server 例項。Edge Admin 需要修改 config.ini 中的 clone_admin 配置，Edge Node 需要配置 admin 段下的 host2 欄位。Log Server 多例項需要在 Edge Admin 和 Edge Node 的配置中新增多個 endpoints。

🔗 如何保障資料安全？有哪些資料備份方案？

建議定期備份資料庫，可以參考文件中的資料庫備份章節。也可以搭建資料庫叢集，實現主從自動切換，提高資料庫可用性。

🔗 安裝後如何更新 Edge Admin 的 SSL 證書？

可以手動替換 /usr/local/oredge-admin/conf/ssl/ssl.crt 和 /usr/local/oredge-admin/conf/ssl/ssl.key 檔案，或者在安裝時透過 -s 和 -k 引數指定證書路徑。 另外也可以使用 Edge Node 來代理 Edge Admin 的流量，為 Edge Admin 簽發 SSL 證書。

🔗 故障排查

🔗 Edge Node 安裝後顯示“not yet approved”錯誤怎麼辦？

這是正常現象，表示 Edge Node 已成功連線 Edge Admin，需要在 Edge Admin 管理後臺中批准該節點加入。可以參考閘道器叢集文件進行操作。

🔗 OpenResty Edge™ SDK 客戶常見問題

🔗 使用 SDK 時，最關鍵的認證資訊（地址、埠、使用者名稱、密碼）從哪裡獲取

這些資訊與您登入 Edge Admin Web 控制檯的資訊完全一致。Edge2Client 初始化所需的引數即是您後臺的訪問地址和登入憑證。如果您的 Admin 使用了非標準的 HTTPS 埠，請務必在地址中明確指定。

🔗 我的開發環境使用自簽名證書，SDK 連線時報 SSL 錯誤，如何處理

這是非常常見的場景。您只需在呼叫 client.login() 前，執行 client.set_ssl_verify(False) 即可跳過證書驗證。但在生產環境，強烈建議配置由權威 CA 簽發的有效證書以確保安全。

🔗 我呼叫 API 修改了配置，為何沒生效？正確的釋出流程是怎樣的

SDK 的所有配置變更都是事務性的，不會自動釋出。這是一種安全設計，防止誤操作影響線上服務。正確的流程是“修改 -> 釋出 -> 驗證”：

1. 修改：呼叫 new_rule(), put_app() 等介面執行變更。
2. 釋出：呼叫 client.new_release() 將所有待定變更建立一個新版本並使其生效。
3. 驗證：（可選但推薦）呼叫 client.sync_status() 檢查配置是否已同步到所有節點。

🔗 使用 SDK 進行自動化操作（如批次更新規則、IP 名單）的最佳實踐是什麼？

1. 冪等性: 在執行建立操作前，先查詢目標是否存在，避免重複建立。在執行更新時，確保指令碼可重複執行。
2. 健壯性：在所有 API 呼叫外層都使用 try...except 捕獲異常，並記錄詳細日誌。
3. 效能考量：對於大規模批次操作（如一次更新上千個 IP） ，建議將資料分批處理，並在批次間加入短暫延時（如 1 秒），避免因請求頻率過高而觸發 Admin 的保護機制。

🔗 如何將 SDK 整合到我的 CI/CD 流水線（如 Jenkins, GitLab CI）中，實現配置即程式碼（Configuration as Code）？

這是 SDK 最有價值的應用場景。通常的做法是：

1. 程式碼化配置：將您的 Edge 應用配置（如上游、規則等）用特定格式（如 YAML, JSON）儲存在程式碼倉庫中。
2. 編寫同步指令碼：開發一個 Python 指令碼，該指令碼讀取程式碼化的配置檔案，並呼叫 SDK 介面，將配置應用到 Edge Admin 中。
3. 整合到 CI/CD：在您的 CI/CD 流水線中增加一個階段（Stage），當配置程式碼發生變更時，自動觸發該 Python 指令碼，完成對 Edge 的配置變更和釋出。
4. 憑證管理：將登入 Edge Admin 的高許可權密碼存放在 CI/CD 系統的金鑰管理工具中，並透過安全的方式傳遞給指令碼，避免明文儲存。

🔗 OpenResty Edge 動態指標常見問題 (FAQ)

🔗 “動態指標”功能的核心價值是什麼？什麼場景下我應該使用它？

它的核心價值是提供標準儀表盤無法滿足的、深度定製的業務和安全洞察力。當您遇到以下場景時，就應該使用它：

• 追蹤特定業務指標：例如，統計 VIP 使用者的請求數、某個新上線活動的 API 呼叫成功率、不同安卓版本的請求分佈等。
• 進行精細化安全分析：例如，找出攻擊某個特定 URI 最多的 Top 10 IP 地址，或統計被 WAF 攔截的請求中，來自某個特定國家的比例。
• 實現自定義的效能監控：例如，計算某個上游服務的 P99 響應延遲，而非僅僅是平均值。

🔗 在寫查詢前，我如何知道都能用哪些資料表和欄位？有資料字典嗎？

這是最關鍵的第一步。您可以依賴的資料來源主要是 reqs （請求日誌）和 waf_hits （WAF 日誌）這兩個虛擬表。要知道它們包含哪些確切的可用欄位（例如 client_ip, status, uri, resp_header('Content-Type') 等），最權威的方式是查閱 OpenResty Edge 官方文件中關於動態指標章節。

🔗 我想統計一個業務指標，比如“根據 JWT 裡的 user_id 欄位，統計請求量最大的 Top 10 使用者”，能做到嗎？

可以，這正是動態指標的強大之處。假設您的 user_id 在名為 X-Jwt-Claim-User-Id 的請求頭中，查詢可以這樣寫：

-- 假設user_id在請求頭'X-Jwt-Claim-User-Id'中
SELECT ngx_var('http_x_jwt_claim_user_id') as user_id, count(*) as count
FROM reqs
WHERE ngx_var('http_x_jwt_claim_user_id') != ''
GROUP BY user_id
ORDER BY count DESC
LIMIT 10;

關鍵在於利用 ngx_var() 函式來獲取自定義請求頭（http_ 字首）或其他 Nginx 變數，從而將業務邏輯與日誌資料關聯起來。

🔗 動態指標查詢是在哪裡執行的？會不會影響線上閘道器的效能？

這是一個非常重要的安全問題。動態指標的查詢是在 Edge Log Server（日誌伺服器）上執行的，它處理的是從閘道器節點旁路採集的日誌資料。因此，無論您的查詢多複雜，都不會對處理即時業務流量的 Edge Node（閘道器節點）造成任何效能影響。您可以放心地使用這一功能進行復雜的資料分析。

🔗 OpenResty Edge Edgelang 常見問題

🔗 我應該在什麼場景下使用 Edgelang ，而不是使用標準的頁面規則 UI？

這是最核心的決策問題。您應該在遇到標準 UI 規則無法滿足的、複雜的、動態的或對效能有極致要求的場景時，考慮使用 Edgelang。

• 標準規則 UI: 適用於常見的、靜態的邏輯，例如“當 URI 是 /path 時，跳轉到 new-url”。它簡單、直觀、開箱即用。
• Edgelang: 適用於需要“程式設計”邏輯的場景，例如：
  • 條件複雜：需要基於多個請求頭、Cookie 、客戶端 IP 地理位置等資訊進行組合判斷。
  • 響應處理：需要動態修改響應體內容（比如在 HTML 中插入 JS 指令碼）或響應頭。
  • 動態路由：需要根據請求的特定引數（如使用者 ID、區域碼）來動態選擇上游服務。
  • 效能最佳化：當您有上百條規則時，Edgelang 編譯器會將它們最佳化成高效的單個程式碼塊，其效能通常優於上百條獨立頁面規則的順序執行。

🔗 Edgelang 最強大的應用場景是什麼？能給個例子嗎？

Edgelang 最強大的地方在於其 對請求和響應的深度程式設計和控制能力。最典型的“殺手級”應用場景是 A/B 測試 和 灰度釋出。

示例：基於使用者 ID 實現灰度釋出 假設您想讓使用者 ID 尾號為“7”的使用者訪問新版上游服務 new-backend-upstream，其他使用者訪問舊版。

# 規則：灰度釋出
# 當請求的 cookie 中包含 userid，且 userid 以 '7' 結尾時
req-cookie("userid"), req-cookie("userid") suffix "7" =>
  set-upstream-name("new-backend-upstream");

這個邏輯用標準 UI 規則也可以實現，但用 Edgelang 就更加簡潔和高效。

🔗 我寫好了一段 Edgelang 程式碼，如何部署和執行它？

Edgelang 程式碼並不是獨立部署的，而是作為頁面規則的一個動作來執行。流程如下：

1. 編寫程式碼：在程式碼編輯器中編寫您的 Edgelang 規則。
2. 建立頁面規則：在 Edge Admin 的某個應用下，建立一個新的頁面規則。
3. 設定條件：（可選）為您希望執行 Edgelang 的請求設定觸發條件，例如 URI路徑字首是 /api/。
4. 選擇動作：在規則的“動作”部分，選擇“執行 Edgelang”這個動作。
5. 貼上程式碼：將您寫好的 Edgelang 程式碼貼上到動作的輸入框中。
6. 儲存併發布：儲存併發布這條頁面規則。

之後，當有請求匹配您設定的條件時，您嵌入的 Edgelang 程式碼就會被執行。

🔗 Edgelang 的執行順序是怎樣的？它和 WAF、快取等其他規則如何協作？

Edgelang 作為頁面規則的一部分，其執行遵循 Nginx 的處理階段（Phases）和頁面規則的優先順序。一個簡化的請求處理流程如下：

1. 頁面規則（包括 Edgelang 或 WAF）：請求將進入頁面規則的處理邏輯。此時，包含 Edgelang 或 WAF 的規則會根據其優先順序 （在 UI 上可以拖動排序）和觸發條件被執行。
2. 快取：Edgelang 可以控制後續的行為。例如，您可以在 Edgelang 規則中呼叫 enable-proxy-cache() 動作來決定是否對某個請求啟用快取。

🔗 Edgelang 的效能和安全性如何？如果我寫了有問題的程式碼怎麼辦？

• 效能：極高。Edgelang 編譯器會將您的規則（甚至是跨多條規則）進行深度分析和最佳化，生成非常高效的 Lua 程式碼。其效能通常優於大量獨立頁面規則的組合。
• 安全性:
  • 編譯時檢查：Edgelang 編譯器會在您儲存規則時進行嚴格的語法和邏輯檢查，大部分低階錯誤（如語法錯誤、函式名寫錯）會在此時被發現並阻止儲存。
  • 沙箱環境：Edgelang 的執行被限制在一個安全的沙箱環境中，它只能呼叫手冊中列出的內建函式和動作，無法執行任意系統命令或危險操作。
  • 測試：雖然目前沒有獨立的“空跑”模式，但最佳實踐是在一個非生產的應用或服務上先行部署和測試您的 Edgelang 規則，驗證其邏輯正確性後，再應用到生產環境。