# 使用命令行部署 OCP Express

本文根据环境中是否存在 OceanBase 集群分为两种场景介绍如何使用命令行部署 OCP Express。

<main id="notice" type='notice'>
  <h4>注意</h4>
  <p>OCP Express 要求集群中所有的 OBServer 节点都要有对应的 OBAgent，否则 OCP Express 不能正常工作。</p>
</main>

## 前提条件

* OceanBase：V4.0.0.0 及以上版本。

* OBAgent：V1.3.0 及以上版本。

* OBD：V2.0.0 及以上版本，若您环境中 OBD 为 V2.0.0 以下版本，可参考  [常见问题](../5.faq/1.faq.md) 中 **如何升级 OBD** 一节升级 OBD。

* Java：部署 OCP Express 的机器上需先安装配置 Java 环境，目前仅支持 JDK1.8 版本。详细操作可参考 [常见问题](../5.faq/1.faq.md) 中 **部署 OCP Express 前如何配置 Java 环境**。

* 内存：需为 OCP Express 预留 512 MB 以上内存，长期稳定运行建议 762 MB 以上。

<main id="notice" type='explain'>
  <h4>说明</h4>
  <p>本文默认所使用的机器可以连接公网，或者已配置好所需软件（OceanBase、OBAgent、ODP、OCP Express 等）。配置所需软件的详细操作可参考 <a href="../2.quick-start/1.install-obd.md"> 安装并配置 OBD</a> 中 <b>配置 OBD</b>。</p>
</main>

## OCP Express 资源规格

### OCP Express 配置要求

OCP Express 服务在运行过程中会产生大量的计算和存储开销，因此需要根据待管理的对象规格进行资源规划。下表以每个集群中包含 10 个租户为标准，计算出 OCP Express 机器的资源消耗。您可根据实际情况进行计算，选择合适的资源配置。

| 管理的机器数量（台）| CPU（核）| 内存（GB）| 磁盘（GB）|
|-------------------|---------|-----------|----------|
|   ≤ 10            |  1      |   2       |  20      |
|   ≤ 20            |  2      |   4       |  20      |
|   ≤ 50            |  4      |   8       |  20      |

<main id="notice" type='explain'>
  <h4>说明</h4>
  <p>OCP Express 机器的最终配置请结合上述开销数据与系统其他资源消耗综合规划，基于系统稳定性考虑，建议 OCP Express 机器的最低配置为 4 核 8 GB，当单个主机的租户数量 ≤ 10 时，仍建议 CPU 和内存保持为 4 核 8 GB。</p>
</main>

### MetaDB 资源

MetaDB 用于存储 OCP Express 的元数据和监控数据，推荐在 OceanBase 集群中创建独立的租户用于 Meta DB。

OCP Express 中管理的 OBServer 数量不同，所需的资源也不相同。下表以每个集群中包含 10 个租户为标准，计算出 MetaDB 租户每个副本的 CPU、内存和磁盘资源。您可根据实际情况进行计算，选择合适的资源配置。

| 管理的机器数量（台）| CPU（核）| 内存（GB）| 磁盘（GB）|
|-------------------|---------|-----------|----------|
|   ≤ 10            |  1      |   4       |  50      |
|   ≤ 20            |  2      |   8       |  100     |
|   ≤ 50            |  4      |   16      |  200     |

<main id="notice" type='explain'>
  <h4>说明</h4>
  <p>这里给出的资源消耗只是一个粗略的预估，实际的 MetaDB 资源消耗根据业务用量会有差异。</p>
</main>

## 场景一：部署 OceanBase 集群和 OCP Express

若您要同时部署 OceanBase 集群和 OCP Express，需在 oceanbase-ce 组件下配置 OCP Express 使用所需的租户信息。ocp-express 组件的配置可直接在配置文件中声明依赖于其他组件（oceanbase-ce、obproxy-ce、obagent），此时您只需配置 `home_path` 和 `memory_size`，其余参数会根据依赖的组件进行获取补全。
oceanbase-ce 组件下相关配置如下：

```yaml
oceanbase-ce:
  servers:
    - name: server1
      ip: 172.xx.xxx.4
  global:
    home_path: xxxx
    ...
    ocp_meta_tenant:
      tenant_name: ocp_meta
      max_cpu: 2
      memory_size: 6442450944
    ocp_meta_db: ocp_meta
    ocp_meta_username: ocp_user
    ocp_meta_password: 
    ...
```

|  配置项            | 是否必选  |         描述                         |
|--------------------|----------|--------------------------------------|
| ocp_meta_tenant->tenant_name        |  可选    | 为 OCP Express 创建的 meta 租户名称。  |
| ocp_meta_tenant->max_cpu            |  可选    | 为 meta 租户分配的最大 CPU。           |
| ocp_meta_tenant->memory_size        |  可选    | 为 meta 租户分配的内存容量。            |
| ocp_meta_db        |  可选    | OCP Express 中数据存储所需的数据库。    |
| ocp_meta_username  |  可选    | OCP Express 的 meta 用户名。           |
| ocp_meta_password  |  可选    | 用户密码。                             |

这里举例列举了几个重要配置，`ocp_meta_tenant` 下的配置都会作为创建租户时的参数传入。具体有哪些参数可以参考创建租户命令支持的参数，详情请参见 [集群命令组](../3.obd-command/1.cluster-command-groups.md) 中 `obd cluster tenant create` 命令介绍。

<main id="notice" type='explain'>
  <h4>说明</h4>
  <p>上述配置项都不配置的情况下，OBD 会按照默认规格为 OCP Express 创建 meta 租户。但是由于用户的租户数量是无法预知的，所以推荐用户根据需要自行修改 meta 租户的规格，推荐的计算公式如下：</p>
  <ul>
  <li>
  <p>data_disk=3.5 + 节点数*0.5，单位为 GB。</p>
  </li>
  <li>
  <p>log_disk=4.5 + 节点数*0.5 + 租户数*0.5，单位为 GB。</p>
  </li>
  </ul>
</main>

在 oceanbase-ce 组件的 bootstrap 阶段，如果发现用户配置了上述字段或者当前集群中存在 ocp-express 组件，OBD 会自动创建对应的 meta 租户以及用户。

ocp-express 组件配置如下：

```yaml
ocp-express:
  depends:
    - oceanbase-ce
    - obproxy-ce
    - obagent
  servers:
    - name: server2
      ip: 172.xx.xxx.5
  global:
    # The working directory for ocp-express. ocp-express is started under this directory. This is a required field.
    home_path: /home/oceanbase/ocp-server
    # log_dir: /home/oceanbase/ocp-server/log # The log directory of ocp express server. The default value is {home_path}/log.
    memory_size: 1G # The memory size of ocp-express server.  The recommend value is 512MB * (expect node num + expect tenant num) * 60MB.
    logging_file_total_size_cap: 10GB # The total log file size of ocp-express server
```

各配置项介绍如下表：

|  配置项      | 是否必选  |         描述                         |
|--------------|----------|--------------------------------------|
| home_path    |  必选    | OCP Express 的工作目录，OCP Express 在该目录下启动。  |
| memory_size  |  必选    | OCP Express 服务器的内存容量，推荐算法为：memory_size = 512MB +（期望的节点数 * 期望的租户数）* 60MB </br>期望的租户数需要包含 sys 和 ocp meta 租户本身。           |
| logging_file_total_size_cap | 可选 | 日志文件总大小，默认为 1GB。<blockquote>**注意**：</br>该参数的单位需使用 GB 或 MB，若使用 G 或 M 单位会报错，无法成功部署 OCP Express。</blockquote>  |

修改配置文件之后，执行如下命令部署并启动集群：

```shell
# 部署集群
obd cluster deploy <deploy name> -c config.yaml
# 启动集群
obd cluster start <deploy name>
```

集群启动后，根据输出的 `ocp-express` 的登录地址和账号密码登录 OCP Express，首次登录会提示修改密码，修改后按照修改的账号密码登录即可使用 OCP Express。

## 场景二：为 OceanBase 集群增加 OCP Express

若您本身已经部署了 OceanBase 集群，想要单独增加 OCP Express，可参考本节内容单独部署。

1. （可选）若集群中 OBAgent 版本低于 V1.3.0，需参考如下命令升级 OBAgent。

   ```shell
   # 查看 OBAgent 的 hash 值
   obd mirror list oceanbase.community.stable | grep -e " obagent "
   # 升级 OBAgent
   obd cluster upgrade test -c obagent -V 1.3.0 --usable=<obagent_hash> 
   ```

   您需将命令中的 `obagent_hash` 替换为 OBAgent 对应版本的 hash 值。

2. 为 OCP Express 创建一个 meta 租户、用户和数据库，并为用户授予所需权限。

   1. 创建 meta 租户

      ```shell
      obd cluster tenant create <deploy name> -n <tenant_name> --max-cpu=2 --memory-size=4G --log-disk-size=3G --max-iops=10000 --iops-weight=2 --unit-num=1 --charset=utf8
      ```

      `obd cluster tenant create` 命令的详细介绍可参考 [集群命令组](../3.obd-command/1.cluster-command-groups.md) 中 `obd cluster tenant create` 命令介绍。

      您也可以登入 OceanBase 数据库中为 OCP Express 创建租户，详细操作请参考 [创建用户租户](https://www.oceanbase.com/docs/community-observer-cn-0000000000965467)。

   2. 创建用户并授予权限

      ```shell
      create user <ocp_user> identified by '<ocp_password>';
      grant all on *.* to <ocp_user>;
      ```

   3. 创建数据库

      ```shell
      create database <database_name>;
      ```

3. 修改配置文件

   具体配置文件示例如下：

   ```yaml
   ## Only need to configure when remote login is required
   # user:
   #   username: your username
   #   password: your password if need
   #   key_file: your ssh-key file path if need
   #   port: your ssh port, default 22
   #   timeout: ssh connection timeout (second), default 30
   ocp-express:
     servers:
       - name: server1
         ip: xxx.xxx.xxx.xxx
     global:
       # The working directory for ocp-express. ocp-express is started under this directory. This is a required field.
       home_path: /home/oceanbase/ocp-server
       log_dir: /home/oceanbase/ocp-server/log # The log directory of ocp express server. The default value is {home_path}/log.
       memory_size: 1G # The memory size of ocp-express server.  The recommend value is 512MB * (expect node num + expect tenant num) * 60MB.
       jdbc_url: jdbc:oceanbase://xxx.xxx.xxx.xxx:2881/meta_db # jdbc connection string to connect to the meta db
       jdbc_username: username # username to connect to meta db
       jdbc_password: '<meta db password>' # password to connect to meta db
       port: 8180 # The http port to use.
       cluster_name: obcluster # the cluster name of oceanbase cluster. Refer to the configuration item appname of oceanbase
       ob_cluster_id: 1  # the cluster id of oceanbase cluster. Refer to the configuration item cluster_id of oceanbase
       root_sys_password: <password for root@sys> 
       agent_username: <obagent> #  The username of obagent
       agent_password: <password> # The password of obagent
       logging_file_total_size_cap: 10GB # The total log file size of ocp-express server
       server_addresses:  # The cluster info for oceanbase cluster
       - address: 127.0.0.1 # The address of oceanbase server
         svrPort: 2882 # The rpc port of oceanbase server
         sqlPort: 2881 # The mysql port of oceanbase server
         agentMgrPort: 8089 # The port of obagent manager process
         agentMonPort: 8088 # The port of obagent monitor process
   ```

   |  配置项            | 是否必选  |         描述                         |
   |--------------------|----------|--------------------------------------|
   | home_path        |  必选   | OCP Express 的工作目录，OCP Express 在该目录下启动。  |
   | log_dir            |  可选    | OCP Express 服务器的日志目录，默认值为 `home_path` 参数下的 log。           |
   | memory_size        |  必选    | OCP Express 服务器的内存容量，推荐算法为：memory_size = 512M +（期望的节点数 * 期望的租户数）* 60MB </br>期望的租户数需要包含 sys 和 ocp meta 租户本身。            |
   | jdbc_url        |  必选    | 连接 meta 租户的 JDBC 连接字符串，请确保连接串中使用到的数据库已创建。    |
   | jdbc_username  |  必选    | 连接 meta 租户的用户名，请确保该用户已创建。<blockquote> **说明**：</br> 这里的用户名格式为 useraname@tenant_name，如果只写 username 而省略租户名，则默认使用 username@sys 连接。sys 租户不允许被当作 meta 租户使用。</blockquote>                |
   | jdbc_password  |  必选    | 连接 meta 租户的用户密码。                             |
   | port          | 可选  | 访问 OCP Express 的 HTTP 端口。  |
   | cluster_name        |  必选   | OceanBase 集群的集群名称，需和 oceanbase-ce 组件中的 `appname` 配置项相同。  |
   | ob_cluster_id           |  必选    | OceanBase 集群的集群 ID，需和 oceanbase-ce 组件中的 `cluster_id` 配置项相同。           |
   | root_sys_password        |  必选    | OceanBase 集群中 root@sys 用户的密码。            |
   | agent_username        |  必选    | OBAgent 的用户名。    |
   | agent_password  |  必选    | OBAgent 的密码。                |
   | logging_file_total_size_cap | 可选 | 日志文件总大小，默认为 1GB。<blockquote>**注意**：</br>该参数的单位需使用 GB 或 MB，若使用 G 或 M 单位会报错，无法成功部署 OCP Express。</blockquote>  |
   | server_addresses->address  |  必选    | OBServer 节点的 IP 地址。                             |
   | server_addresses->svrPort        |  必选   | OBServer 节点的 rpc 端口，需和  oceanbase-ce 组件中对应节点的 `rpc_port` 配置项相同。  |
   | server_addresses->sqlPort            |  必选    | OBServer 节点的 mysql 端口，需和 oceanbase-ce 组件中对应节点的 `mysql_port` 配置项相同。           |
   | server_addresses->agentMgrPort        |  必选    | OBAgent 管理进程的端口，需根据 OBAgent 中实际设置的端口进行修改。            |
   | server_addresses->agentMonPort        |  必选    | OBAgent 监控进程的端口，需根据 OBAgent 中实际设置的端口进行修改。    |

4. 修改配置文件后，执行如下命令部署并启动集群。

   ```shell
   # 部署集群
   obd cluster deploy <deploy name> -c config.yaml
   # 启动集群
   obd cluster start <deploy name>
   ```

5. 集群启动后，根据输出的 `ocp-express` 的登录地址和账号密码登录 OCP Express，首次登录会提示修改密码，修改后按照修改的账号密码登录即可使用 OCP Express。
