部署高可用 ODC - 开发者中心 ODC V4.2.3

加载和运行 ODC 镜像

完成 OceanBase 开发者中心（OceanBase Developer Center，ODC）元数据库的初始化后，高可用部署首先需在各个节点上分别拉取和运行 ODC 镜像以安装 ODC 应用。

加载镜像

注意

ODC V4.2.0 及之后的版本的镜像已同时发布到 Docker Hub，如果运行 ODC 的机器可以访问 Docker Hub，则无需下载镜像，可以直接启动 ODC Docker，具体请参见下述 运行镜像 内容。
如果无法直接访问 Docker Hub，则仍需下载和加载镜像文件。

在 OceanBase 软件下载中心的 运维工具 栏，按需下载 ODC 镜像。
在宿主机上获得镜像文件后，在命令行工具中运行下述语句加载镜像：
```
gunzip -c obodc-{$version}.tar.gz | docker load
```

运行镜像

在宿主机上获得 ODC 镜像后，在命令行工具中运行镜像的示例语句如下所示：

#!/usr/bin/env bash
docker run -v /var/log/odc:/opt/odc/log -v /var/data/odc:/opt/odc/data \
-d -i --net host --cpu-period 100000 --cpu-quota 400000 --memory 8G --name "obodc" \
-e "DATABASE_HOST=xxx.xx.xx.xx" \
-e "DATABASE_PORT=60805" \
-e "DATABASE_USERNAME=[用户名]@[租户名称]#[集群名称]" \
-e "DATABASE_PASSWORD=******" \
-e "DATABASE_NAME=odc_metadb" \
-e "ODC_PROFILE_MODE=alipay" \
-e "ODC_ADMIN_INITIAL_PASSWORD=******" \
oceanbase/odc:4.2.2

注意

Shell 环境下，字符串中包含 !、$ 等特殊字符时，变量值需要使用单引号。例如：DATABASE_PASSWORD='11111!'。

参数说明如下表所示：

参数	说明
-v	宿主机的 `/var/log/odc` 目录映射到 ODC 容器内的 `/opt/odc/log` 目录。 `/var/log/odc` 为宿主机的目录，如不存在需先创建，创建目录的参考命令 `mkdir -p /var/log/odc`。宿主机的 `/var/data/odc` 目录挂载到 ODC 容器内的 `/opt/odc/data` 目录。`/var/data/odc` 为宿主机的目录，可自定义，如不存在需先创建，创建目录的参考命令 `mkdir -p /var/data/odc`。
--net	指定容器的网络配置，指定该参数值为 `host` 即直接使用宿主机网络。您也可以使用 `--publish`（`-p`）参数配置端口映射，但是部分环境可能出现因为 Docker 内 DNS 解析出错而启动容器失败，此时请使用 `--net host` 方式启动 Docker。
--cpu-period --cpu-quota	`---cpu-period` 用来指定容器对 CPU 的使用要在多长时间内做一次重新分配。单位：微秒。 `---cpu-quota` 用来指定在这个周期内，最多可以有多少时间用来运行当前容器。单位：微秒。配合使用可指定容器使用的 CPU 核数。cpu-quota/cpu-period 的值即为 Docker 可以使用的 CPU 核数，示例语句中 400000/100000=4 表示最多可以使用 4 个核。
--memory	设置容器使用的内存最大值。
--name	指定容器名称。
DATABASE_HOST	元数据库 IP 地址。
DATABASE_PORT	元数据库端口号。
DATABASE_USERNAME	元数据库用户名。OceanBase 数据库用户名的格式：db_user@tenant_name#cluster_name。
DATABASE_PASSWORD	连接数据库的密码。
DATABASE_NAME	元数据库名。
ODC_PROFILE_MODE	指定模式。默认指定：`alipay`。
ODC_ADMIN_INITIAL_PASSWORD	指定 ODC 管理员账号的初始密码。注意设置的初始密码需要须满足以下条件：至少 2 个数字。至少 2 个大写字母。至少 2 个小写字母。至少 2 个特殊字符，特殊字符的范围为 ._+@#$%。不包含空格和其他特殊字符，长度为 8-32。

除上述参数外，运行镜像时您还可以根据需求使用下述参数：

参数	说明
ODC_LOG_DIR	指定日志目录。默认路径：`/opt/odc/log`。
ODC_JVM_HEAP_OPTIONS	指定 JVM 内存配置。默认值：`-XX:MaxRAMPercentage=60.0 -XX:InitialRAMPercentage=60.0`，表示使用 60% 的的内存，可通过指定参数 `ODC_JVM_HEAP_OPTIONS` 自定义 JVM 内存配置。例如：配置为 `-Xmx2048m -Xms2048m`，表示设置堆内存为 2G。
ODC_JVM_GC_OPTIONS	指定 JVM GC 策略。默认指定：`-XX:+UseG1GC -XX:+PrintAdaptiveSizePolicy -XX:+PrintGCDetails -XX:+PrintGCTimeStamps -XX:+PrintGCDateStamps -Xloggc:/opt/odc/log/gc.log -XX:+UseGCLogFileRotation -XX:GCLogFileSize=50M -XX:NumberOfGCLogFiles=5`。
ODC_JVM_OOM_OPTIONS	指定 JVM OutOfMemory 策略。默认指定：`-XX:+ExitOnOutOfMemoryError`。
ODC_JVM_EXTRA_OPTIONS	指定其它需要的 JVM 配置参数。默认值：空。
ODC_SERVER_PORT	指定 ODC-Server 的 HTTP 监听端口。默认值：8989。
ODC_HOST	指定 ODC 运行时的 IP 地址，该参数在高可用部署场景下做为远程过程调用的目的地址。
ODC_MAPPING_PORT	指定 ODC 运行时的端口号，避免因部署环境导致的端口号无法使用的问题。该参数适用于在 Docker 中部署 ODC 时进行端口映射的场景。
ODC_APP_EXTRA_ARGS	其它需要指定的 App 参数。例如 `--server.servlet.session.timeout=10m`，表示 Session 过期时间为 10 分钟。默认值：空。

部署 SSL 证书

浏览器通过 HTTP 协议访问 Web 版 ODC，所以首次通过浏览器访问 Web 版 ODC 时，会收到连接不安全的警告信息。若您想要安全访问 ODC，可部署 SSL 证书以使用 HTTPS 协议进行访问。您可以申请 CA 证书或自行配置 HTTPS 自签证书。若您不需要通过 HTTPS 协议访问 ODC，可直接进行 Nginx 的部署操作。

申请 CA 证书

推荐您申请 CA 证书，您可以在阿里云可以购买 SSL 证书和服务，详情请参见 SSL 证书。

在使用企业内部网络的场景下，您可以咨询 IT 管理员内部 CA 证书的申请使用流程。

配置 SSL 自签证书

ODC 镜像包中包含了生成证书和密钥的执行文件 generate-odc-ssl-certificate.sh，在宿主机运行执行文件即可生成证书。自签证书能够实现加密通信，但是操作系统默认不信任自签证书，您可以在浏览器中把证书添加到 受信任的根证书颁发机构 目录中配置证书信任。

下述为执行文件的运行示例，其中 domain 项的配置必须和您的 ODC 站点使用的域名保持匹配，否则浏览器会认为是不匹配的证书：

$./generate-odc-ssl-certificate.sh
Enter your domain [www.example.com]:
Enter your province [Zhejiang]:
Enter your city [Hangzhou]:
Enter your company name [OceanBase]:
Enter your company unit name [DBA]:
generate certificate...
Generating a 2048 bit RSA private key
.......................................+++
.......................
......+++
writing new private key to '/etc/pki/nginx/odcserver.key'
-----
end of string encountered while processing type of subject name element #5
problems making Certificate Request
check generated files:
-rw-r--r-- 1 root root 1424 Jun  3 15:18 server.crt
-rw-r--r-- 1 root root 1708 Jun  3 15:18 server.key

执行文件 generate-odc-ssl-certificate.sh 的内容如下所示，您也可以直接执行下述命令生成自签证书。

#!/usr/bin/env bash
# for generate self certificated ssl certificate files

echo try create directory '/etc/pki/nginx' if not exists...
sudo mkdir -p /etc/pki/nginx
cd /etc/pki/nginx || exit

#read configurations
read -rp "Enter your domain [www.example.com]: " DOMAIN
read -rp "Enter your province [Zhejiang]: " PROVINCE
read -rp "Enter your city [Hangzhou]: " CITY
read -rp "Enter your company name [OceanBase]: " COMPANY
read -rp "Enter your company unit name [DBA]: " UNIT

echo generate certificate...
SUBJ="/C=CN/ST=${PROVINCE}/L=${CITY}/O=${COMPANY}/OU=${UNIT}/CN=${DOMAIN}"
sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
    -keyout /etc/pki/nginx/odcserver.key \
    -out /etc/pki/nginx/odcserver.crt \
    -subj "${SUBJ}"

echo "check generated files (use ls -l odcserver.*):"
ls -l odcserver.*

部署 Nginx 代理

在所有节点均完成部署 OceanBase 开发者中心（OceanBase Developer Center，ODC）镜像后，需在其中一个 ODC 节点上部署一个 Nginx 代理，通过 Nginx 将用户请求路由到不同的节点应用上。部署 Nginx 代理需在一个节点上拉取并运行 Nginx 镜像，运行后将配置文件拷贝到本地进行修改，在本地修改完配置文件后，先停运 Nginx 镜像再重启镜像以应用修改后的配置的文件。

加载镜像

选择一个节点加载并运行 Nginx 镜像，目前镜像可通过两种方式获得：

在宿主机上从 Docker 仓库中直接拉取镜像。
下载镜像包到本地，再拷贝至宿主机中解压。

从 Docker 仓库中直接拉取镜像

请确保宿主机上已安装 Docker 且可访问外网，在命令行工具中运行下述语句从 Docker 仓库中拉取 Nginx 镜像：

docker pull nginx

拷贝镜像包至宿主机中解压

在可访问外网且已安装 Docker 的机器中运行下述语句，下载镜像包至本地：
```
docker save nginx:latest | gzip - >nginx.tar.gz
```
拷贝镜像包至宿主机中，运行下述语句加载镜像：
```
gunzip -c nginx.tar.gz | docker load
```

配置 conf 文件

在启动 Nginx 镜像前，需修改配置文件。ODC 的镜像包中已提供配置文件模板，可复制模板到本地并进行编辑。配置文件模板根据您是否已部署自签证书而略有不同，请按需复制对应的模板并进行修改。

配置不包含自签证书的 conf 文件

运行下述语句从镜像包中复制配置文件到宿主机再进行编辑，复制路径可自定义（其中 ~ 是配置文件在本地的路径）：

docker cp -a <odc_image_name>:/opt/odc/conf/nginx.conf.template  ~/<conf_local_path>

配置文件模板如下所示，请关注文件中注释需修改的部分。

# Nginx conf template for http deployment
# For more information on configuration, see:
#   * Official English Documentation: http://nginx.org/en/docs/

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
include /usr/share/nginx/modules/*.conf;

events {
    worker_connections 1024;
}

http {
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile            on;
    tcp_nopush          on;
    tcp_nodelay         on;
    keepalive_timeout   65;
    types_hash_max_size 2048;

    #set 0 to disable request body size check, for support large size file upload
    client_max_body_size 0;

    include             /etc/nginx/mime.types;
    default_type        application/octet-stream;

    # for websocket configuration
    map $http_upgrade $connection_upgrade {
        default upgrade;
        '' close;
    }

    # load balancing configuration
    # notice under_score character are not allowed for upsteram name, 400 Bad Request happens if used
    # please use ip_hash strategy
    # one server line for each odc-server node
    upstream odcbackends {
      ip_hash;
      # PLEASE CHANGE to real odc-server address
      # 请修改为实际的 odc-server 地址（非必改内容）
      server xxx.x.x.x:8989;
      # add more servers here
    }

    #https server, proxy to odc-server 8989 port
    server {
        listen 80;
        # uncomment below if ipv6 enabled
        # 如启用 ipv6，请取消以下注释
        #listen [::]:80;

        # PLEASE CHANGE to your site domain
        # 请修改为实际的站点域名（非必改内容）
        server_name  odc.oceanbase.com;

        location / {
            proxy_pass http://odcbackends;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
            proxy_read_timeout 1800;
            proxy_send_timeout 1800;
            proxy_connect_timeout 75;
            proxy_next_upstream off;
        }
    }

}

配置包含自签证书的 conf 文件

运行下述语句从镜像包中拷贝配置文件到宿主机再进行编辑，复制路径可自定义（其中～是配置文件在本地的路径）：

docker cp -a <odc_image_name>:/opt/odc/conf/nginx.conf.https.template  ~/<conf_local_path>

配置文件模板如下所示，请关注文件中注释需修改的部分。

# Nginx conf template for https deployment
# For more information on configuration, see:
#   * Official English Documentation: http://nginx.org/en/docs/

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
include /usr/share/nginx/modules/*.conf;

events {
    worker_connections 1024;
}

http {
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile            on;
    tcp_nopush          on;
    tcp_nodelay         on;
    keepalive_timeout   65;
    types_hash_max_size 2048;

    #set 0 to disable request body size check, for support large size file upload
    client_max_body_size 0;

    include             /etc/nginx/mime.types;
    default_type        application/octet-stream;

    # for websocket configuration
    map $http_upgrade $connection_upgrade {
        default upgrade;
        '' close;
    }

    # load balancing configuration
    # notice under_score character are not allowed for upsteram name, 400 Bad Request happens if used
    # please use ip_hash strategy
    # one server line for each odc-server node
    upstream odcbackends {
      ip_hash;
      # PLEASE CHANGE to real odc-server address
      # 请修改为实际的 odc-server 地址（非必改内容）
      server xxx.x.x.x:8989;
      #add more servers here
    }

    # redirect http to https
    server {
        listen 80 default_server;

        # uncomment below if ipv6 enabled
        # 如启用 ipv6，请取消以下注释
        #listen [::]:80 default_server;

        location / {
            return 301 https://$host$request_uri;
        }
    }

    # https server, proxy to odc-server 8989 port
    server {
        listen 443 ssl http2;
        # uncomment below if ipv6 enabled
        # 如启用 ipv6，请取消以下注释
        #listen [::]:443 ssl http2;

        # PLEASE CHANGE to your site domain
        # 请修改为实际的站点域名（非必改内容）
        server_name  odc.oceanbase.com;

        # you can use /opt/odc/bin/generate-odc-ssl-certificate.sh
        # to generate self certificated SSL certificates
        # 您可以使用 /opt/odc/bin/generate-odc-ssl-certificate.sh 生成自签证书

        # PLEASE CHANGE certificate file location if unmatched
        # 如不匹配，请修改证书文件路径
        ssl_certificate /etc/pki/nginx/odcserver.crt;
        ssl_certificate_key /etc/pki/nginx/odcserver.key;
        ssl_session_timeout 1d;
        ssl_session_cache shared:MozSSL:10m;  # about 40000 sessions
        ssl_session_tickets off;

        # intermediate configuration
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
        ssl_prefer_server_ciphers off;

        # HSTS (ngx_http_headers_module is required) (63072000 seconds)
        add_header Strict-Transport-Security "max-age=63072000" always;

        location / {
            proxy_pass http://odcbackends;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
            proxy_read_timeout 1800;
            proxy_send_timeout 1800;
            proxy_connect_timeout 75;
            proxy_next_upstream off;
        }
    }

}

说明

修改负载均衡配置，确保 proxy 超时配置时长充足，修改配置后需重启 nginx。
建议 proxy_connect_timeout 参数不超过 75 秒，请参见 proxy_connect_timeout。
设置 proxy_next_upstream off 旨在禁止 nginx 将请求转发至下一个 ODC 节点，导致用户需重新登录，且某些功能不可用，如异步任务结果集下载等与文件上传下载相关的功能。

启动镜像

在本地修改配置文件后，在命令行工具中运行下述语句以重启 Nginx 镜像（其中～是配置文件在本地的路径）：

docker run --network host --name nginx -v ～/<conf_local_path>:/etc/nginx/nginx.conf -v /etc/pki/nginx/:/etc/pki/nginx/ -d nginx

语句中的参数说明如下所示：

参数	说明
--network host	表示使用宿主机网络端口，无需配置端口映射。如不希望直接使用宿主机端口，可使用 `-p` 参数配置端口映射。例如 `-p 8080:80` 表示宿主机的 8080 端口映射为 Docker 内的 80 端口，`-p 8443:443` 表示宿主机的 8443 端口映射为 Docker 内的 443 端口。
--name nginx	指定容器的名称为 nginx，方便后续管理，或可使用其它名称，如 odc-nginx。
-v ~/<conf_local_path>:/etc/nginx/nginx.conf	进行磁盘挂载，将宿主机内的本地文件映射到 Docker 内。其中 `<conf_local_path>` 为配置 conf 文件时复制到宿主机的本地路径，然后将其映射至 Docker 内的 /etc/nginx/nginx.conf 文件中。
-v /etc/pki/nginx/:/etc/pki/nginx/	将宿主机的 /etc/pki/nginx/ 路径映射到 Docker 内的 /etc/pki/nginx/ 路径。
-d nginx	表示后台运行 Docker。

配置证书信任

浏览器不会直接信任自签证书，需要您手动在浏览器中手动进行证书信任的配置。

注意

由于 Chrome 不支持信任自签证书，所以您完成证书信任的操作后，仍会收到连接不安全的提示信息。

Windows 下配置证书信任

以谷歌浏览器 Chrome 为例，浏览器配置证书信任的步骤如下所示：

在浏览器中访问 ODC，提示连接非私密连接时，单击地址栏左侧 不安全 按钮，在弹出的列表中单击证书按钮查看证书详情。
在弹出的证书窗口中，选择 详细信息 页签，然后单击页签右下角的 复制到文件 按钮。
在弹出的 证书导出向导 窗口中，单击 下一步 。
进入导出文件格式设置窗口，选择 DER 格式，单击 下一步 。
进入指定导出文件窗口，单击窗口中的浏览按钮，在弹出的文件资源管理器窗口中选择导出路径并在 文件名 文本框中指定文件名称，在文件资源管理器窗口中单击右下角的保存按钮回到导出文件窗口，单击 下一步 。
进入导出向导完成窗口，单击右下角的完成按钮以导出证书到本地。
在第 5 步指定的导出路径中找到被导出的证书文件，右键证书文件，在弹出的列表中选择 安装证书 。
进入证书导入向导，单击 下一步 。
进入证书存储窗口，选择 将所有证书都放入下列存储 ，并单击选项下的浏览按钮，在弹出的存储列表窗口中，选择 受信任的颁发机构 ，然后单击窗口中的确定按钮。回到证书存储窗口，单击 下一步 。
进入导入向导完成窗口，单击右下角的完成按钮。
证书信任配置完成，尝试重新重新在浏览器中访问 ODC。

macOS 下配置证书信任

以谷歌浏览器 Chrome 为例，浏览器配置证书信任的步骤如下所示：

在浏览器中访问 ODC，提示连接非私密连接时，单击地址栏左侧 不安全 按钮，在弹出的列表中单击证书按钮查看证书详情。
网页中将显示证书的内容。
在本地创建后缀为 .cer 的文件，将网页中的证书内容复制到文件中，并保存文件。
在 macOS 系统中单击 应用程序 -> 实用工具 -> 钥匙串访问 以进入 钥匙串配置 窗口。在窗口的左侧导航栏中单击系统，然后在上方导航栏中单击 + 按钮，在弹出的窗口中选择上一步创建好的证书文件以添加证书到系统中。
添加完成后，双击 odc.oceanbase.com,odc.oceanbse.net 证书。在弹出的证书详情窗口中，单击信任配置项，在弹开的配置列表中将 使用此证书时 项配置为 始终信任 。
关闭证书详情窗口，关闭时会提示您输入密码以让修改生效，按步骤输入密码完成配置。
证书信任配置完成，尝试重新在浏览器中访问 ODC。