7 分钟阅读 | 最后修改: 2025-09-30, 8:12:56 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 的持久化数据过多而耗尽系统盘的空间。