7 分钟阅读 | 最后修改: 2026-02-27, 8:32:49 pm

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 持久化数据过多而耗尽系统盘空间