Oracle REST Data Services (26.1.0) Docker 镜像文档

描述

Oracle REST Data Services (ORDS) 是一个中间层 Java 应用程序，提供数据库管理 REST API、基于浏览器的客户端 SQL Developer Web、PL/SQL 网关、SODA for REST，以及发布 RESTful Web 服务以与 Oracle 数据库中的数据库对象和存储过程交互的能力。访问 ORDS 产品页面 了解更多详情。

重要公告

从 ORDS 25.1.0 版本开始，ords-developer 镜像已被弃用。请阅读本文档以熟悉此最新官方 ords 镜像。

使用此镜像

启动 Oracle REST Data Services 实例

要启动 ORDS 实例，请执行以下命令：

podman run --name <container_name> -v <host_config_volume>:/etc/ords/config container-registry.oracle.com/database/ords:latest

其中 <container_name> 是容器名称，<host_config_volume> 是包含 ORDS 配置详情的卷。

[!NOTE]

• 上述命令是 ORDS 容器的最基本执行方式；假设 <host_config_volume> 卷中存在有效的 ORDS 配置。
• 本文档中，尖括号 < > 内的词语表示代码行中的变量。
• 要了解高级用例，请参阅 自定义配置 部分。
• 本文档使用 Podman 作为指定的容器运行时，但任何 OCI 兼容的¹容器运行时也可使用。

自定义配置

ORDS 容器支持各种配置参数，以方便自定义配置。

示例

运行 ORDS 实例

此示例展示如何构造 podman run 命令来运行 ORDS 实例，使用可用的 ORDS 安装自定义配置选项。

podman run -d --name <container_name> \
  -p <host_https_port>:8443 -p <host_mongo_port>:27017 \
  -e FORCE_SECURE=TRUE \
  -e DEBUG=TRUE \
  -e DB_WAIT_RETRIES=<number_of_retries> \
  -e DBHOST=<database_hostname> \
  -e DBPORT=<database_port> \
  -e DBSERVICE=<database_service_name> \
  -e CONN_STRING=<custom_jdbc_url> \
  -e ORACLE_PWD=<sys_password> \
  -v [<host_config_volume>:]/etc/ords/config \
  -v [<host_apex_volume>:]/opt/oracle/apex \
  -v [<host_entrypoint_volume>:]/ords-entrypoint.d:ro \
  container-registry.oracle.com/database/ords:latest

从运行的数据库容器获取 DBHOST、DBPORT、DBSERVICENAME 和 CONN_STRING 值：

• 数据库主机名（使用最新 23ai/free 镜像时）：podman container inspect <container_name> --format "{{.Config.Hostname}}"
• 数据库端口（使用最新 23ai/free 镜像时）：podman inspect <container_name> --format '{{ (index (index .NetworkSettings.Ports "1521/tcp") 0).HostPort }}'
• 数据库服务名（使用最新 23ai/free 镜像时）：podman logs <container_name>，然后搜索可插拔数据库名称。23ai 的 PDB 默认值为 FREEPDB1。
• 连接字符串（也称为 db.customURL）示例：
  • 简单示例：dbhostname:dbport/dbservicename
  • LDAP 示例：ldap://ldap-server:636/cn=TNSnames,cn=OracleContext,dc=my_domain,dc=com/PDBNAME

参数说明：
-d：以分离模式启动容器
--name: 容器名称（默认：自动生成）
-p: 主机端口到容器端口的映射。
  - HTTP 默认端口为 8080
  - 若 SECURE 标志为 TRUE，则为 8443
  - Mongo 监听器为 27017
-e DBHOST: 数据库的 IP/主机名，容器必须能够访问。需要 DBPORT 和 DBSERVICENAME。
-e DBPORT: 数据库监听连接的端口号。需要 DBHOST 和 DBSERVICENAME。
-e DBSERVICENAME: 要安装和配置 ORDS 的数据库服务名。需要 DBPORT 和 DBHOST。
-e CONN_STRING: 数据库自定义 URL "jdbc:oracle:thin:@"。此参数替代 DBHOST、DBPORT 和 DBSERVICENAME。
-e ORACLE_PWD: Oracle 数据库 SYS 用户密码。
-e APEX_PWD: 可选：Apex 公共用户账户密码。
-e ORACLE_USER_NAME: 可选：允许使用 SYS 以外的备用用户账户安装 ORDS（如果需要）。
-e ORACLE_USER_PWD: 可选：当设置 ORACLE_USER_NAME 时，指定备用用户的密码。
-e FORCE_SECURE: 若 FORCE_SECURE 标志为 TRUE 且配置目录 /etc/ords/config/ssl 中未提供有效证书文件，ORDS 实例将无法启动。
-e DEBUG: 若 DEBUG 标志设置为 TRUE，ORDS 实例将设置配置 debug.printDebugToScreen true；若设置为 FALSE，则设置 debug.printDebugToScreen false。
-v /etc/ords/config: ORDS 配置的数据卷。必须可由容器内的 Unix "oracle"（uid: 54321）用户写入。
-v /opt/oracle/apex: 可选：Oracle Application Express (APEX) 文件卷。若将此卷的 images 文件夹挂载到 ORDS 实例，ORDS 将设置 standalone.static.path 为 /opt/oracle/apex/images。必须可由容器内的 Unix "oracle"（uid: 54321）用户读取。
-v /ords-entrypoint.d: 可选：包含 ORDS 实例启动前要运行的自定义脚本的卷。脚本（*.sh）将按字母顺序运行。必须可由容器内的 Unix "oracle"（uid: 54321）用户读取。

使用预设配置运行 ORDS 实例

[!NOTE] 使用此选项时无需设置数据库变量。

podman run -d --name <container_name> \
  -p <host_https_port>:8443 -p <host_mongo_port>:27017 \
  -e FORCE_SECURE=TRUE -e DEBUG=TRUE \
  -v [<host_config_volume>:]/etc/ords/config \
  -v [<host_apex_volume>:]/opt/oracle/apex \
  -v [<host_entrypoint_volume>:]/ords-entrypoint.d:ro \
  container-registry.oracle.com/database/ords:latest

参数说明：
-d：以分离模式启动容器。
--name: 容器名称（默认：自动生成）
-p: 主机端口到容器端口的映射。
  - HTTP 默认端口为 8080
  - 当 SECURE 标志为 TRUE 时，HTTPS 端口为 8443
  - Mongo 监听器为 27017
-e FORCE_SECURE: 注意：当 FORCE_SECURE 标志设置为 TRUE，但 /etc/ords/config/ssl 配置目录中未提供有效证书文件时，ORDS 实例将无法启动。
-e DEBUG: 若 DEBUG 标志设置为 TRUE，ORDS 实例将设置 ORDS 配置 debug.printDebugToScreen true。
-v /etc/ords/config: ORDS 配置的数据卷。必须可由容器内的 Unix "oracle"（uid: 54321）用户写入。
-v /opt/oracle/apex: 可选：Oracle Application Express (APEX) 文件卷。将 images 文件夹挂载到 ORDS 实例会将 standalone.static.path 设置为 /opt/oracle/apex/images。必须可由容器内的 Unix "oracle"（uid: 54321）用户读取。
-v /ords-entrypoint.d: 可选：包含 ORDS 实例启动前要运行的自定义脚本的卷。脚本（*.sh）将按字母顺序运行。必须可由容器内的 Unix "oracle"（uid: 54321）用户读取。

使用 ORDS CLI

示例 1：此示例展示如何使用 ORDS CLI 命令配置客户管理的 ORDS（使用 ADB-S 服务）。

[!NOTE] 本示例中使用 Docker。

1. 步骤 1：创建卷、下载***并创建密钥文件。

mkdir -p <host_directory>/ords_atp_config
   chmod 777 ords_atp_config
   cat secrets.txt
   chmod 755 password.txt

[!NOTE]

要下载自治数据库实例的***，请查看 下载客户端凭据 的说明。有关密钥文件中密码的更多信息，请查看 安装和配置客户管理的 ORDS 文档。

2. 步骤 2：安装客户管理的 ORDS。

cat password.txt | docker run --rm -i \
     -v <host_directory>/ords_atp_config:/etc/ords/config \
     -v <host_directory>/atp_wallet.zip:/atp_wallet.zip \
     container-registry.oracle.com/database/ords:latest install adb --admin-user <admin_user> --db-user <db_user> --gateway-user <gateway_user> -*** /atp_wallet.zip -***-service-name <wallet_service_name> --feature-sdw true --password-stdin

3. 步骤 3：创建 SSL 自签名证书，CN（通用名称）应为请求的域，可以是 localhost 或 FQDNS。

mkdir -p <host_directory>/ords_atp_config/ssl
   openssl req -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -out <host_directory>/ords_atp_config/ssl/cert.crt -keyout $<host_directory>/ords_atp_config/ssl/key.key -subj "/C=US/ST=State/L=City/O=my_corp Corp/OU=my_unit/CN=localhost"
   chmod -R 777 <host_directory>/ords_atp_config/ssl

4. 步骤 4：启动客户管理的 ORDS。

docker run --rm -i \
     -p 8443:8443 \
     -v <host_directory>/ords_atp_config:/etc/ords/config \
     -v <host_directory>/atp_wallet.zip:/atp_wallet.zip \
     -v <host_directory>/apex_files/24.2/apex:/opt/oracle/apex \
     container-registry.oracle.com/database/ords:latest

示例 2：此示例展示如何使用 ORDS CLI 命令轮换数据库密码。

1. 步骤 1：获取当前密码。

docker run \
     -v <host_config_volume>:/etc/ords/config \
     container-registry.oracle.com/database/ords:latest config get --secret db.password

2. 步骤 2：更新密码。

docker run -it \
     -v <host_config_volume>:/etc/ords/config \
     container-registry.oracle.com/database/ords:latest config secret db.password

[!NOTE] 有关 ORDS CLI 命令的更多详情，请参见 帮助中心。

示例 Compose 文件

name: demo
services:
  db23:
    hostname: database
    image: container-registry.oracle.com/database/free:latest
    environment:
      - ORACLE_PDB=FREEPDB1
      - ORACLE_PWD=oracle
      - DBHOST=database
    volumes:
      - db_files:/opt/oracle/oradata/
    ports:
      - <host_db_port>:1521
  ords-node1:
    restart: on-failure
    hostname: ords-node
    image: container-registry.oracle.com/database/ords:latest
    environment:
      - DBSERVICENAME=FREEPDB1
      - DBHOST=database
      - DBPORT=1521
      - ORACLE_PWD=oracle
      #修改 JDK_JAVA_OPTIONS 以调整 JVM 内存
      #- JDK_JAVA_OPTIONS=-Xms1024M -Xmx1024M
    volumes:
      - ords_config:/etc/ords/config
      - <host_apex_volume>:/opt/oracle/apex
    ports:
      - <host_ords_port>:8080
    healthcheck:
      test: curl --noproxy "localhost" -f -k [***] || exit 1
      interval: 30s
      timeout: 10s
      retries: 150
    depends_on:
      db23:
        condition: service_healthy
volumes:
  ords_config:
  db_files:

[!NOTE] 在 JVM 内存分配较低的 Podman 或 Docker 机器上运行 ORDS 容器可能导致容器因 Java 内存不足异常而崩溃。您可以调整 JDK_JAVA_OPTIONS 以避免此问题（如上述示例 compose.yaml 文件所示）。

在安全端口 8443 上启动 ORDS 容器

要以安全模式（即 HTTPS，端口 8443）启动 ORDS 容器，请将 SSL 证书和密钥文件放在 ORDS 配置卷中：

<host_config_volume>/ssl/cert.crt
<host_config_volume>/ssl/key.key

或者，将文件挂载到 /etc/ords/config/ssl 目录：

-v [<host_ssl_cert>:]/etc/ords/config/ssl/cert.crt:ro \
-v [<host_ssl_key>:]/etc/ords/config/ssl/key.key:ro \

[!NOTE] SSL 证书和密钥文件必须可由容器内的 Unix "oracle"（uid: 54321）用户读取。容器将检测这些文件并在端口 8443（而非 8080）上启动 ORDS 服务。

[!NOTE] 若 FORCE_SECURE 标志已设置为 TRUE 且证书文件不可用，容器将以错误退出。但是，若 FORCE_SECURE 标志未设置且证书文件不可用/缺失，容器将使用非安全（HTTP）端口 8080 启动。

在启动 ORDS 实例前运行脚本

您可以配置 Docker/Podman 镜像在 ORDS 启动时运行脚本（支持 .sh 扩展名）。要包含启动时运行的脚本，请将主机上存放这些脚本的目录挂载到 /ords-entrypoint.d 卷。

访问 ORDS 日志

使用以下命令访问 ORDS 控制台日志（其中 <container_name> 是容器名称）：

podman logs <container_name>

Footnotes

1. 关于 Open Container Initiative (OCI)。 ↩