7 分鐘閱讀 | 最後修改: 0001-01-01, 0:00:00 am

OpenResty XRay™ 自主部署版 (docker-compose)

簡介

本文件介紹如何使用 Docker Compose 安裝和部署 OpenResty XRay 自主部署版本。

目錄

概覽

xray-arch

在此架構中，控制檯服務端執行在 Docker 容器中，透過 docker-compose 進行管理。所有服務執行在單臺物理機或虛擬機器上，Agent 端則執行在目標機器上。

XRay 服務端由三個核心元件構成，每個元件包含若干子服務：

  • OpenResty XRay Console：
    • xray-console：提供 XRay 管理介面的 Web 服務
    • xray-console-pg：Web 服務的資料庫後端
  • OpenResty XRay BuildBox：
    • build-box-[dist]：構建 XRay 工具的後端服務，其中 dist 代表對應的作業系統發行版
  • OpenResty XRay Tenant DB：
    • xray-tenant-db：為 xray-console 服務和 build-box-[dist] 提供查詢介面，按照"私有庫 → 公共庫"的順序進行查詢。該服務僅向公共庫發起查詢請求，不會上傳任何資料到公共庫
    • xray-tenant-db-pl：提供客戶私有軟體資料庫
    • xray-tenant-db-pg：客戶私有軟體資料庫的資料庫後端

安裝

控制檯服務

1. 硬體需求

«««< HEAD

  • 網路：不必具有公網 IP 或暴露監聽埠，但需要能夠訪問網際網路，並且執行 Agent 的機器可以訪問該機器
  • 記憶體：建議至少 4GB，推薦 16GB
  • CPU：建議至少 2C，推薦 4 核
  • 硬碟：建議至少 500GB，推薦 1TB 以上。持久化資料儲存在 /data 目錄下，會隨著使用時長不斷增長 =======
  • 網路：無需公網 IP 或暴露監聽埠，但需要能夠訪問網際網路，且執行 Agent 的機器可以訪問該伺服器
  • 記憶體：建議至少 4GB，推薦 16GB
  • CPU：建議至少 2 核，推薦 4 核
  • 硬碟：建議至少 500GB，推薦 1TB 以上。持久化資料儲存在 /data 目錄下，會隨使用時長不斷增長

52e2a441 (change: optimized Upgrade Documentation for the On-Premises Version of OpenResty XRay.)

注意：根據實際經驗，單臺 Agent 週期取樣的資料，30 天的資料增長量約為 10GB。

2. 訪問公網說明

控制檯服務需要連線網際網路以訪問 XRay PkgDB 服務。該服務提供常見 Linux 發行版軟體倉庫的查詢與下載功能，使 XRay 能夠分析系統中絕大部分開源軟體和開源庫。

特別說明：訪問公網過程中僅涉及查詢和下載操作，不會上傳任何私有資料到公網服務端。

3. 作業系統要求

推薦使用原生支援 Docker 的 Linux 發行版：

  • Ubuntu >= 18.04
  • CentOS >= 7
  • Fedora >= 32
  • Debian >= 10
  • RHEL == 7

4. 安裝 Docker 和 Docker Compose

Docker 安裝文件：https://docs.docker.com/engine/install/

注意：安裝 Docker 後，請啟用 Docker 服務。

Docker Compose 安裝文件：https://docs.docker.com/compose/install/

5. 部署證書（可選）

如需使用自定義證書，請將 XRay 服務端對應域名的證書放置在以下路徑：

  • /data/orxray-console/cert/ssl.crt
  • /data/orxray-console/cert/ssl.key

這些證書用於：

  • 瀏覽器透過 HTTPS 訪問控制檯服務
  • Agent 端與控制檯服務之間的通訊

如跳過此步驟，控制檯服務將使用內建的自簽名證書。

6. IP 白名單訪問控制（可選）

如需為 Console Web 服務配置 IP 白名單訪問控制，請按以下步驟操作：

  1. 建立目錄 /data/orxray-console/acl
  2. 在該目錄下建立 whitelist.conf 檔案

配置檔案格式如下（詳細說明請參考 https://nginx.org/en/docs/http/ngx_http_access_module.html）：

allow 10.0.0.3;
allow 192.168.1.0/24;

# 可以新增更多 IP 或 CIDR

deny all; # 必須新增此行，拒絕所有非白名單 IP 的訪問

注意：修改配置後需要重啟 console 服務才能生效。

7. 配置檔案詳解

config.env 檔案中包含以下重要的環境變數：

XRay Console 配置

  • XRAY_CONSOLE_HOST：XRay 控制檯的主機名，例如 xray.example.com
  • XRAY_CONSOLE_PORT：XRay 控制檯的埠號，預設為 443。可透過修改此變數調整 docker-compose 暴露的監聽埠

XRay HTTP Proxy 配置（可選）

如網路環境需要透過 HTTP 代理連線網際網路，請配置以下變數：

  • XRAY_HTTP_PROXY：HTTP 和 HTTPS 流量的代理伺服器地址，例如 http://proxyserver.example.com:8080
  • XRAY_HTTP_PROXY_AUTHORIZATION：HTTP 代理伺服器的認證頭部，即 Proxy-Authorization 的值

XRay Tenant Database 配置

  • XRAY_TENANT_DB_PORT：XRay Tenant 資料庫的埠號，預設為 80。可透過修改此變數調整 docker-compose 暴露的監聽埠

Time Series Database 清理策略配置

  • TSDB_CLEANUP_PERIOD_DAYS：Time Series Database 清理週期（天）。例如設定為 90，表示 90 天后進行清理
  • TSDB_ARCHIVE_RETENTION_DAYS：Time Series Database 歸檔資料保留天數。例如設定為 10，表示保留 10 天的歸檔資料

日誌保留策略配置

  • LOG_RETENTION_DAYS：日誌保留天數。例如設定為 15，表示保留 15 天的日誌
  • LOG_ARCHIVE_CLEANUP_DAYS：歸檔日誌清理天數。例如設定為 30，表示 30 天后清理歸檔日誌

請根據實際需求調整這些環境變數的配置。

8. 部署與啟動

步驟 1：登入 Docker Registry

使用郵件中提供的使用者名稱和密碼登入私有 Docker Registry：

docker login registry.openresty.com.cn

步驟 2：準備配置檔案

將郵件附件中的配置檔案放置到以下位置：

  • docker-compose.yml → /opt/orxray/docker-compose.yml
  • config.env → /opt/orxray/config.env

步驟 3：啟動服務

$ docker-compose -f /opt/orxray/docker-compose.yml --env-file /opt/orxray/config.env -p orxray config -q \
    && docker-compose -f /opt/orxray/docker-compose.yml --env-file /opt/orxray/config.env -p orxray up -d

步驟 4：檢查啟動狀態

執行以下命令，確認輸出的 State 欄位均為 UP：

$ docker-compose -f /opt/orxray/docker-compose.yml --env-file /opt/orxray/config.env -p orxray ps

至此，控制檯服務端部署完成，可透過配置的域名訪問，例如：https://example.com

注意：如透過反向代理伺服器訪問管理後臺，需要進行以下配置：

  1. 在反向代理伺服器上啟用 WebSocket 支援，否則會影響 Agent 與控制檯服務端的通訊
  2. 在反向代理伺服器上啟用 X-Real-IP 頭部傳遞訪問 IP 地址，以便控制檯服務端獲取 Agent 端的真實 IP 地址

9. Arm64 支援（可選）

如需 OpenResty XRay 支援 arm64 架構，可使用 docker-compose-arm.yml 檔案進行部署。

前置條件

確保在 x86_64 架構的機器上已部署 docker-compose.yml 服務，並對內網開放以下埠：

  • XRAY_CONSOLE_PORT（預設為 443）
  • XRAY_TENANT_DB_PORT（預設為 80）

部署步驟

在同一內網的 arm64 架構機器上部署 docker-compose-arm.yml，並按以下步驟配置：

  1. 開啟 config.env 檔案
  2. 新增或修改以下環境變數：
    • XRAY_CONSOLE_IP：x86_64 機器的內網 IP 地址
    • XRAY_CONSOLE_PORT：XRay 控制檯的埠號，預設為 443
    • XRAY_TENANT_DB_IP：x86_64 機器的內網 IP 地址
    • XRAY_TENANT_DB_PORT：XRay Tenant 資料庫的埠號，預設為 80

配置示例：

# config.env file
# ...

XRAY_CONSOLE_IP=192.168.1.100
XRAY_CONSOLE_PORT=443
XRAY_TENANT_DB_IP=192.168.1.100
XRAY_TENANT_DB_PORT=80

在 arm64 伺服器上執行以下命令完成部署：

$ docker-compose -f /opt/orxray/docker-compose-arm.yml \
    --env-file /opt/orxray/config.env -p orxray up -d

部署完成後，OpenResty XRay 即可支援 arm64 架構。

Agent

«««< HEAD XRay Agent 端執行在目標機器上，Agent 安裝後與自主部署的控制檯服務端進行通訊，而 Agent 安裝也是由控制檯服務端配合完成的：

XRay Agent 執行在目標機器上，安裝後與自主部署的控制檯服務端進行通訊。Agent 的安裝由控制檯服務端配合完成。

52e2a441 (change: optimized Upgrade Documentation for the On-Premises Version of OpenResty XRay.)

安裝步驟

  1. 在瀏覽器中訪問控制檯服務端後臺
  2. 使用郵件中提供的使用者名稱和密碼登入
  3. 登入後可看到安裝嚮導及支援的作業系統
  4. 按照安裝嚮導的提示完成 Agent 安裝

安裝完成後，可在左側 User 頁籤修改密碼及新增使用者。

運維

控制檯服務日誌檢視

$ docker-compose -f /opt/orxray/docker-compose.yml --env-file /opt/orxray/config.env -p orxray logs -t

檢查配置檔案合法性

$ docker-compose -f /opt/orxray/docker-compose.yml --env-file /opt/orxray/config.env -p orxray config -q

升級服務

步驟 1：下載最新配置檔案

從郵件附件下載最新的 docker-compose.yml 配置檔案。

步驟 2：執行升級

將新的配置檔案複製到部署目錄，並重啟服務：

$ cp docker-compose.yml /opt/orxray/docker-compose.yml
$ docker-compose -f /opt/orxray/docker-compose.yml --env-file /opt/orxray/config.env -p orxray config -q \
    && docker-compose -f /opt/orxray/docker-compose.yml --env-file /opt/orxray/config.env -p orxray down \
    && docker-compose -f /opt/orxray/docker-compose.yml --env-file /opt/orxray/config.env -p orxray up -d

時序資料庫升級

如果從低於 26.2.1 的版本升級到 26.2.1 及以上版本，需要執行以下命令進行時序資料庫升級：

$ docker exec -it orxray-xray-console-pg-1 bash /docker-entrypoint-upgrade.d/upgrade_tsdb_data.sh

注意：此操作僅在跨越 26.2.1 版本升級時執行一次即可。

檢查服務狀態

$ docker-compose -f /opt/orxray/docker-compose.yml --env-file /opt/orxray/config.env -p orxray ps

資料持久化與備份

/data 目錄說明

/data 目錄是掛載在宿主機上的持久化資料卷，儲存 XRay 服務執行過程中的持久化資料，包括資料庫檔案、日誌檔案、歸檔檔案等。即使 XRay 相關容器重啟，只要宿主機上的 /data 目錄未被刪除，其中的資料就會被保留。

歸檔資料管理

/data/orxray-console/archive 子目錄儲存資料庫和 job 的歸檔資料檔案。系統每天定時備份前一天的資料。歸檔檔案超過指定儲存天數後會被自動清除。

以下環境變數可配置歸檔資料的儲存時間：

  • TSDB_ARCHIVE_RETENTION_DAYS：資料庫歸檔資料的儲存天數，預設為 10 天
  • LOG_ARCHIVE_CLEANUP_DAYS：job 歸檔檔案的儲存天數，預設為 30 天

最佳實踐

  • 根據實際磁碟空間和資料保留需求，合理設定上述引數
  • 定期對 /data 目錄進行備份
  • 建議使用專門的磁碟掛載該目錄，避免 XRay 持久化資料過多而耗盡系統盤空間