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

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

名稱

OpenResty XRay 自主部署 Docker-Compose 版本安裝與部署指南

目錄

概覽

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. 硬體需求

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

注意：根據目前的經驗，1 臺 Agent 週期取樣的資料，30 天的資料增長量約為 10GB

2. 訪問公網的說明

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

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

3. 作業系統

由於使用了 Docker 服務，我們推薦使用原生支援 Docker 的 Linux 發行版，包括：

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

4. 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 白名單用作訪問控制的話，你可以按照下面的步驟進行操作。請在 /data/orxray-console 建立目錄，/data/orxray-console/acl，並將 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 代理伺服器，例如 http://proxyserver.example.com:8080。
  • XRAY_HTTP_PROXY_AUTHORIZATION: 這個環境變數是用來配置 HTTP 和 HTTPS 流量的 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，表示 Time Series Database 應在 90 天后進行清理。
  • TSDB_ARCHIVE_RETENTION_DAYS：設定 Time Series Database 保留歸檔資料的天數。例如，設定為 10，表示 Time Series Database 應保留 10 天的歸檔資料。

日誌保留策略配置

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

這些環境變數的配置應根據你的實際需求進行調整。

8. 部署與啟動

首先，使用郵件中提供的 Docker-Registry 使用者名稱密碼，登入我們提供的私有 Docker Registry。

docker login registry.openresty.com.cn

然後，使用郵件附件中提供的 docker-compose.yml 作為配置檔案，推薦放在 /opt/orxray/docker-compose.yml 位置，並將附件中的 config.env 檔案 放在 /opt/orxray/config.env 位置。

啟動命令：

$ 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

檢查啟動狀態，執行下列命令，檢視輸出的 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 (預設值為 80) 及 XRAY_TENANT_DB_PORT (預設值為 443) 埠。

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

  1. 開啟 config.env 檔案。
  2. 新增或修改以下環境變數：
    • XRAY_CONSOLE_IP：設定為 x86_64 機器的內網 IP 地址。
    • XRAY_CONSOLE_PORT：設定為你的 XRay 控制檯的埠號，預設為 443。你可以透過修改此環境變數來調整 docker-compose 暴露出來的監聽埠。
    • XRAY_TENANT_DB_IP：設定為 x86_64 機器的內網 IP 地址。
    • XRAY_TENANT_DB_PORT：設定為你的 XRay tenant 資料庫的埠號，預設為 80。你可以透過修改此環境變數來調整 docker-compose 暴露出來的監聽埠。

例如：

# 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

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

在瀏覽器訪問控制端服務端後臺，使用郵件中提供的使用者名稱密碼來進行登入。登入後，可以看到安裝嚮導，及支援的作業系統，按照安裝嚮導的提示，進行 Agent 的安裝即可。

安裝 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

升級服務

升級服務會透過郵件傳送附件 docker-compose.upgrade.yml，執行以下操作：

$ cp docker-compose.upgrade.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 up -d

檢查服務狀態

$ 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 的持久化資料過多而耗盡系統盤的空間。