--- url: /v6.2/mongodb-guide.md --- # MongoDB BI Connector 参考指南 # 1. 概述 # 2. 安装 * 系统: 本文档基于 Centos 7.x 安装 * mongodb bi connector 版本: mongodb-bi-linux-x86_64-rhel70-v2.14.2.tgz ## 2.1 安装要求 安装 mongodb bi connector 需要系统已经安装了 openssl，如未安装，可以使用 yum 命令安装 ```bash yum -y install openssl ``` ## 2.2 安装 安装 mongodb，非常简单，执行下面的命令，解压即可: ```bash tar -xzvf mongodb-bi-linux-x86_64-rhel70-v2.14.2.tgz ``` ## 2.3 配置 mongosqld 的配置文件使用了 yaml 格式，大部分参数也有对应的命令行参数。 ### 2.3.1 日志参数 ```yml systemLog: logAppend: logRotate: "rename" 或 "reopen" path: quiet: verbosity: ``` 参数说明: 参数|类型|默认值|对应的命令行参数|说明 -|-|-|-|- systemLog.logAppend|boolean||--logAppend|输出日志到`systemLog.path`指定的日志文件, 且必须设置`systemLog.logRotate`| systemLog.path|string|rename|--logRotate|指定日志该怎样 rotate, 有两个选项: **rename** : 关闭已有的文件，并重命名，在文件名后面追加一个[RFC3339格式](https://www.ietf.org/rfc/rfc3339.txt)的时间戳。同时生成一个新的日志文件。 **reopen** : 关闭文件后后再打开。| systemLog.path|string||--logPath|指定存储输出日志的文件| systemLog.quiet|boolean||--quiet|隐藏所有的日志输出| systemLog.verbosity|integer||--verbose / -v|设置该选项，会输出更详细的日志| ### 2.3.2 schema 参数 ```yml schema: path: maxVarcharLength: ``` 参数说明: 参数|类型|默认值|对应的命令行参数|说明 -|-|-|-|- schema.path|string||--schema|指定 schema 文件或目录| schema.maxVarcharLength|integer||--maxVarcharLength|指定 varchar 字段的最大字符长度，如果超出长度，会截取到指定的长度，并打印一条警告日志| ### 2.3.2 数据样例参数 ```yml schema: sample: size: prejoin: namespaces: uuidSubtype3Encoding: <[old|csharp|java]> stored: mode: <[custom|auto]> source: name: refreshIntervalSecs: ``` 参数说明: 参数|类型|默认值|对应的命令行参数|说明 -|-|-|-|- schema.stored.mode|integer|custom|--schemaMode|配置 mongosqld 的样例模型，必须与`schema.stored.source`一起使用，有两个选项: **custom** : mongosqld 从 MongoDB 数据库中读取以存储的 schema **auto** : mongosqld 对 schema 进行取样，并写到 MongoDB 数据库| schema.stored.source|string||--schemaSource|指定存储 schema 信息的数据库| schema.stored.name|string|defaultSchema|--schemaName|用于读写的 schema 名称| schema.sample.size|integer|1000|--sampleSize|收集 schema 信息时，每个数据库取样的文档数量| schema.sample.prejoin|boolean||--prejoin|schema 选项，用于将数组和非数组数据组合到单个表中| schema.sample.namespaces|string 或者 string array||--sampleNamespaces|指定数据库和集合，用于包含或排除创建 schema 的数据抽样过程| schema.sample.uuidSubtype3Encoding|string||--uuidSubtype3Encoding / -b|指定用于生成 UUID 二进制子类型的编码，包含: **old** : 旧 BSON 二进制子类型表示 **csharp** : C#或.NET 遗留 UUID 表示 **java** : Java 旧版 UUID 表示| schema.refreshIntervalSecs|integer|0|--schemaRefreshIntervalSecs|mongosqld 重新取样创建 schema 的间隔秒数，默认为0，表示连接期间，初始化时取样后，不再取样。值必须是正整数| ### 2.3.3 Runtime 参数 ```yml runtime: memory: maxPerStage: maxPerServer: maxPerConnection: ``` 参数说明: 参数|类型|默认值|对应的命令行参数|说明 -|-|-|-|- runtime.memory.maxPerStage|integer|||指定查询执行阶段可以使用的最大内存(单位: Byte)| runtime.memory.maxPerServer|integer|||指定 mongosqld 进程可以使用的最大内存(单位: Byte)| runtime.memory.maxPerConnection|integer|||指定 mongosqld 客户端连接可以使用的最大内存(单位: Byte)| ### 2.3.4 网络参数 ```yml net: bindIp: port: unixDomainSocket: enabled: pathPrefix: filePermissions: ssl: mode: allowInvalidCertificates: PEMKeyFile: PEMKeyPassword: CAFile: minimumTLSVersion: ``` 参数说明: 参数|类型|默认值|对应的命令行参数|说明 -|-|-|-|- net.bindIp|string|127.0.0.1|--addr 的主机部分|指定监听的主机地址，多个地址以","分隔| net.port|integer|3307|--addr 的端口部分|指定监听的端口| net.unixDomainSocket.enabled|boolean||`true` : 表示监听 unix 域套接字 `false`表示禁用监听域套接字，等同于命令行参数`--noUnixSocket`| net.unixDomainSocket.pathPrefix|string|/tmp|--unixSocketPrefix|指定 mongosqld Unix 域套接字的目录，mongosqld 会在该路径下创建一个 mysql.sock 套接字，如果未指定，则会创建 /tmp/mysql.sock 套接字| net.unixDomainSocket.filePermissions|string|448|--filePermissions|指定 Unix 域套接字文件的权限| net.ssl.allowInvalidCertificates|boolean||--sslAllowInvalidCertificates|允许 MySQL 客户端提供无效的客户端 TLS/SSL 证书| net.ssl.mode|string|disabled|--sslMode|启用或者禁用 TLS/SSL 连接 mongosqld。包括以下3个选项: **disabled** : mongosqld 不接受使用 TLS/SSL 保护的连接 **allowSSL** : mongosqld 接受使用 TLS/SSL 保护的连接(意味着也接收不使用 TLS/SSL 的连接) **requireSSL** : mongosqld**只**接受使用 TLS/SSL 保护的连接| net.ssl.PEMKeyFile|string||--sslPEMKeyFile|指定包含了 TLS/SSL 证书和 MySQL 客户端 key 的`.pem`文件，可以使用相对或者绝对路径指定| net.ssl.PEMKeyPassword|string||--sslPEMKeyPassword|指定密码，用于解密`net.ssl.PEMKeyFile`指定的私钥| net.ssl.CAFile|string|--sslCAFile|指定 mongosqld `.pem`文件，该文件包含了证书颁发机构的根证书链。可以使用相对路径或绝对路径指定| net.ssl.minimumTLSVersion|string|TLS1_1|--minimumTLSVersion|指定 TLS 的最小版本，有3个选项: **TLS1\_0**、**TLS1\_1**、**TLS1\_2**| ### 2.3.5 安全参数 ```yml security: enabled: defaultMechanism: defaultSource: gssapi: hostname: serviceName: ``` 参数说明: 参数|类型|默认值|对应的命令行参数|说明 -|-|-|-|- security.enabled|boolean||--auth|要求对客户端请求进行认证| security.defaultMechanism|string|SCRAM-SHA-1|--defaultAuthMechanism|指定默认的认证机制，包括 **SCRAM-SHA-1**、**SCRAM-SHA-256**、**PLAIN**、**GSSAPI**| security.defaultSource|string|admin|--defaultAuthSource|指定 MongoDB 认证的默认 source| security.gssapi.hostname|string|`net.bindIp`指定的第一个 IP|--gssapiHostname|配置 Kerberos 认证的 FQDN| security.gssapi.serviceName|string|mongosql|--gssapiServiceName|使用 Kerberos 注册的服务名| security.gssapi.constrainedDelegation|string|False|--gssapiConstrainedDelegation|使用代理 credential 进行 Kerberos 授权，启用 constrained delegation| ### 2.3.6 MongoDB 主机参数 ```yml mongodb: versionCompatibility: net: uri: ssl: enabled: allowInvalidCertificates: allowInvalidHostnames: PEMKeyFile: PEMKeyPassword: CAFile: CRLFile: FIPSMode: auth: username: password: source: mechanism: gssapiServiceName: ``` 参数说明: 参数|类型|默认值|对应的命令行参数|说明 -|-|-|-|- mongodb.versionCompatibility|string||--mongo-versionCompatibility|根据给定的 MongoDB 的版本，限制 mongosqld 所能提供的功能。只有当副本集和各个成员使用了不同的版本，或者滚动升级 MongoDB 时才有必要| mongodb.net.uri|string|mongodb://localhost:27017|--mongo-uri|指定 MongoDB 的连接字符串| mongodb.net.ssl.enabled|boolean|False|表示是否使用 TLS/SSL 连接 MongoDB 实例| mongodb.net.ssl.allowInvalidCertificates|boolea||--mongo-sslAllowInvalidCertificates|允许 MongoDB 提供无效的 TLS/SSL 证书| mongodb.net.ssl.allowInvalidHostnames|boolean||--mongo-sslAllowInvalidHostnames|允许 mongosqld 使用不同于 TLS/SSL 证书中的 hostname 连接 MongoDB| mongodb.net.ssl.PEMKeyFile|string||--mongo-sslPEMKeyFile|指定包含了 TLS/SSL 证书和 mongosqld 连接 MongoDB 时的 key 的`.pem`文件。可以使用相对路径和绝对路径| mongodb.net.ssl.PEMKeyPassword|string||--mongo-sslPEMKeyPassword|指定包含连接 MongoDB 的证书和私钥的文件路径| mongodb.net.ssl.CAFile|string||--mongo-sslCAFile|指定 MongoDB 的`.pem`文件，该文件包含了证书颁发机构的根证书链。可以使用相对路径或绝对路径指定| mongodb.net.ssl.CRLFile|string||--mongo-sslCRLFile|指定包含了废除证书列表的 MongoDB`.pem`文件| mongodb.net.ssl.FIPSMode|boolean||--mongo-sslFIPSMode|在安装的 OpenSSL 库中启用 FIPS 模式| mongodb.net.ssl.minimumTLSVersion|string||--mongo-minimumTLSVersion|指定 TLS 的最小版本，有3个选项: **TLS1\_0**、**TLS1\_1**、**TLS1\_2**| mongodb.net.auth.username|string||--mongo-username / -u|指定用户名，用于发现模式，只有在启用了--auth 的情况下才需要。必须是有效的 MongoDB 用户，且具有`listDatabases`权限| mongodb.net.auth.password|string||--mongo-password / -p|指定用户密码| mongodb.net.auth.source|string|admin|--mongo-authenticationSource|指定用于认证的数据库| mongodb.net.auth.mechanism|string|SCRAM-SHA-1|--mongo-authenticationMechanism|指定认证机制，包括 **SCRAM-SHA-1**、**SCRAM-SHA-256**、**PLAIN**、**GSSAPI**| mongodb.net.auth.gssapiServiceName|string|mongodb|--mongo-gssapiServiceName|设置 Kerberos SPN，用于 Kerberos 认证| ### 2.3.7 进程管理参数 ```yml processManagement: service: name: displayName: description: ``` 参数说明: 参数|类型|默认值|对应的命令行参数|说明 -|-|-|-|- processManagement.service.name|string||--serviceName|运行 mongosqld 的系统服务名| processManagement.service.displayName|string||--serviceDisplayName|运行 mongosqld 的系统服务的显示名称| processManagement.service.description|string||--serviceDescription|运行 mongosqld 的系统服务的描述| ## 2.4 配置文件示例 下面是一个配置文件的样例: ```yml systemLog: logAppend: false path: "/var/log/mongosqld/mongosqld.log" verbosity: 2 security: enabled: true mongodb: net: uri: "mongo.example.com:27017" auth: username: "root" password: "changeme" net: bindIp: 192.0.2.14 port: 3307 ssl: mode: "allowSSL" PEMKeyFile: "/vagrant/certificates/mongosqld-server.pem" CAFile: "/vagrant/certificates/ca.crt" schema: sample: namespaces: "inventory.*" processManagement: service: name: mongosqld displayName: mongosqld description: "BI Connector SQL proxy server" ``` # 3. 启动 1. 使用命令行参数的方式启动 ```bash bin/mongosqld --mongo-uri "mongodb://127.0.0.1:27017" --auth -u root -p 123456 --addr "0.0.0.0:3307" ``` 2. 使用配置文件的方式启动 ```bash bin/mongosqld --config /mongosqld.conf ``` # 4. 容器化 ## 4.1 制作镜像 1. 编写 dockerfile ```dockerfile FROM ubuntu:xenial COPY mongo* /usr/local/bin/ RUN apt-get update \ && apt-get install -y --no-install-recommends ca-certificates numactl procps gnupg dirmngr gnupg-curl \ && apt-get install -y rsyslog \ && service rsyslog start EXPOSE 3307 ENTRYPOINT ["mongosqld"] ``` 2. 编写 build.sh 脚本 ```bash #! /bin/sh cd $(dirname $0) set -ex DOCKER_FILE=mongodb-bi.Dockerfile IMAGE_NAME=mongodb-bi-connector IMAGE_VERSION=2.14.2 MONGODB_BI="mongodb-bi-linux-x86_64-ubuntu1604-v${IMAGE_VERSION}" MONGODB_BI_URL="https://info-mongodb-com.s3.amazonaws.com/mongodb-bi/v2/${MONGODB_BI}.tgz" wget -N ${MONGODB_BI_URL} tar -xzvf ${MONGODB_BI}.tgz docker build -f $DOCKER_FILE -t ${IMAGE_NAME}:${IMAGE_VERSION} ${MONGODB_BI}/bin/ ``` 3. 创建镜像 执行如下命令 ```bash sh build.sh ``` ## 4.2 启动 假设已经安装了一个 mongodb，其安装信息如下 |配置|值| |-|-| |地址|192.16.1.10| |端口|27017| |用户名|mongodb| |密码|mongodb| 则启动命令如下 ```bash docker run --name mongodb-bi -i -t -p 3307:3307 -d mongodb-bi-connector:2.l4.2 --mongo-uri "mongodb://192.168.1.10:27017" --auth -u mongodb -p mongodb --addr "0.0.0.0:3307" ``` # 附录 ## 官方网站 https://docs.mongodb.com/bi-connector/current/local-quickstart/