增加了namespace导入导出工具

M³多模数据平台安装部署手册(tui版本).md

@@ -0,0 +1,623 @@
+# M³多模数据平台安装部署手册(tui版本)
+
+**内部资料，注意保管**
+
+**面向对象多模态AI数据平台V1.0**
+**系统安装部署手册**
+**V1.5.2**
+
+唯简科技（北京）有限公司
+
+------
+
+## 目录
+
+1. 前言
+   1.1 编写目的
+   1.2 用户对象
+2. 综述
+   2.1 概述
+   2.2 产品介绍
+   2.3 产品组件
+   2.4 系统要求
+3. 系统部署
+   3.1 安装步骤
+   3.2 系统登录
+   3.3 删除已安装系统
+   3.4 更新组件
+4. 服务状态
+5. 服务日志
+6. 修改数据平台访问端口
+7. 数据导入导出工具
+   7.1 导入mql文件
+   7.2 导出mql文件
+8. namespace导出导入
+9. 性能优化配置策略说明
+
+------
+
+## 1. 前言
+
+### 1.1 编写目的
+
+本文档主要介绍唯简科技面向对象多模态AI数据平台的具体实施方法。通过阅读本文档，用户可以自行安装部署该产品。
+
+### 1.2 用户对象
+
+本文档主要面向系统实施人员，包括：
+
+- 实施人员：公司内部实施部门或甲方实施人员；
+- 测试人员：公司内部测试部门或甲方测试人员。
+
+------
+
+## 2. 综述
+
+### 2.1 概述
+
+本文档的编写目的是描述北京唯简科技科技有限公司（简称：唯简科技）面向对象多模态AI数据平台的安装部署介绍，帮助开发、测试、管理各环节角色了解、搭建产品测试环境和生产环境。
+
+### 2.2 产品介绍
+
+唯简科技面向对象多模态AI数据平台主要由多模图数据存储引擎、统一数据治理、统一作业调度和企业小应用开发与发布框架四部分组成。
+
+唯简科技面向对象多模态AI数据平台具有如下特点：
+
+- 支持结构化表数据、图数据、时序数据、文档数据、向量数据的统一存储；
+- 支持面向对象的建模；
+- 集群化部署，解决单点问题；
+- 支持AI接口的快速封装；
+- 提升采集处理能力并扩展国产设备支持。
+
+### 2.3 产品组件
+
+| 功能               | 组件名称  | 说明                                                         |
+| :----------------- | :-------- | :----------------------------------------------------------- |
+| 分布式存储组件     | cassandra | 数据存储组件，可以根据需求进行横向扩展提高入库速度和存储容量，支持集群部署 |
+| 分布式配置组件     | etcd      | 配置服务，支持集群部署                                       |
+| 分布式消息队列组件 | nats      | 消息队列，支持集群部署                                       |
+| 分布式数据管理组件 | odbserver | 数据管理组件，支持集群部署                                   |
+| 分布式数据处理组件 | parser    | 规则数据流式处理组件，支持横向扩展提高数据处理能力，支持集群部署 |
+| 分布式作业调度组件 | sched     | 定时任务进行平台数据处理，支持集群部署                       |
+| 分布式数据接入组件 | toe       | 集成接入第三方数据采集                                       |
+| 分布式Web服务组件  | web       | web容器组件，支持横向扩展提高并发访问能力，支持集群部署      |
+
+### 2.4 系统要求
+
+#### 2.4.1 操作系统要求
+
+面向对象多模态AI数据平台支持Linux系统，企业级部署建议操作系统为RedHat、Centos7以上版本，或者Suse10以上版本。对信创操作系统支持为麒麟V10操作系统。
+
+#### 2.4.2 服务器配置要求
+
+| 配置     | CPU                 | 内存    | 硬盘                   |
+| :------- | :------------------ | :------ | :--------------------- |
+| 推荐配置 | 8 Core * 2.0GHz以上 | 32G以上 | 100G以上，根据需求增加 |
+| 最小配置 | 4 Core * 2.0GHz以上 | 16G以上 | 100G以上，根据需求增加 |
+| 测试配置 | 2 Core * 2.0GHz以上 | 8G以上  | 100G以上，根据需求增加 |
+
+> 注：支持使用虚拟机，存储必须使用San存储或本地存储。
+
+#### 2.4.3 基础软件要求
+
+| 软件       | 版本                                                  |
+| :--------- | :---------------------------------------------------- |
+| git        | 操作系统相应版本，用于自动化脚本和文档的版本管理      |
+| python     | 2.7，用于底层数据访问和维护                           |
+| 编译工具链 | build-essential, gcc, g++, cmake, make                |
+| 数学库     | libopenblas-dev, liblapack-dev                        |
+| 主机名设置 | 要求执行hostname输出主机名为真实主机名，而非localhost |
+
+#### 2.4.4 端口开通要求
+
+| 模块名称  | 内部端口       | 服务端口  |
+| :-------- | :------------- | :-------- |
+| cassandra | 9160/7000/7001 | 9042      |
+| etcd      | 2380           | 2379      |
+| nats      | 4244           | 4222/8222 |
+| odbserver | 11009          | 11001     |
+| parser    | -              | -         |
+| sched     | -              | -         |
+| web       | -              | 8080/8443 |
+| toe       | -              | -         |
+
+#### 2.4.5 NTP要求
+
+唯简科技面向对象多模态AI数据平台各服务组件都是分布式集群部署，各节点以统一、同步的标准时间用于记录各种数据的产生时序，如：文件创建和访问时间、数据库处理时间等。所以，网络时间同步协议(NTP)是系统安装部署的基础要求。
+
+> 注：如现场无法提供NTP服务地址，可通过指定集群内某节点为NTP服务器。
+
+------
+
+## 3. 系统部署
+
+### 3.1 安装步骤
+
+#### 3.1.1 上传安装程序
+
+此处使用root用户。
+
+bash
+
+```
+# 创建临时目录，并上传介质到该目录
+$ cd /opt
+$ mkdir soft
+```
+
+
+
+#### 3.1.2 解压介质
+
+此处使用root用户。
+
+bash
+
+```
+$ unzip matrix_install_Vx.xx.zip
+$ cd matrix_install_Vx.xx
+```
+
+
+
+#### 3.1.3 获得加密用户密码，用于修改配置文件使用
+
+此处使用root用户。
+
+bash
+
+```
+$ ./mxtui
+```
+
+![image1](./assets/install_tui/image1.png)
+
+> 注：执行的时候，确认mxtui有执行权限。
+
+./media/image1.png
+
+**控制键说明：**
+
+| 控制按键                | 功能               |
+| :---------------------- | :----------------- |
+| Enter                   | 选择/执行          |
+| Esc                     | 返回上一级         |
+| F6                      | 切换输出窗口       |
+| Tab 或者 下方向键       | 下一个输入项       |
+| Shift+Tab 或者 上方向键 | 上一个输入项       |
+| 左右方向键              | 切换下拉选项       |
+| 空格键                  | 复选框选择 或 取消 |
+
+#### 3.1.4 选择 Install Configuration 按回车
+
+![image2](./assets/install_tui/image2.png)
+
+#### 3.1.5 选择 Add install node 按回车
+
+依次将安装节点信息填写后，选择 Save 后，按回车。
+
+![image3](./assets/install_tui/image3.png)
+![image4](./assets/install_tui/image4.png)
+
+#### 3.1.6 选择 Modify install node 或 Delete install node 修改和删除节点
+
+![image5](./assets/install_tui/image5.png)
+![image6](./assets/install_tui/image6.png)
+
+#### 3.1.7 选择 Install system 启动安装程序
+
+![image7](./assets/install_tui/image7.png)
+![image8](./assets/install_tui/image8.png)
+![image9](./assets/install_tui/image9.png)
+
+#### 3.1.8 启动基础组件
+
+选择 `Start/Stop Maintenance`：
+
+![image10](./assets/install_tui/image10.png)
+
+选择 `Start component`：
+
+![image11](./assets/install_tui/image11.png)
+
+选择 `All hosts`：
+
+![image12](./assets/install_tui/image12.png)
+
+选择 `foundation`、`nats`、`etcd`、`odbserver`：
+
+![image13](./assets/install_tui/image13.png)
+![image14](./assets/install_tui/image14.png)
+
+查看基础组件启动情况：
+选择 `Start/Stop Maintenance -> Status component`
+
+![image15](./assets/install_tui/image15.png)
+
+#### 3.1.9 平台进行初始化
+
+选择 `Install Configuration -> Init system`
+
+![image16](./assets/install_tui/image16.png)
+
+点击 `Execute` 按钮
+
+![image17](./assets/install_tui/image17.png)
+![image18](./assets/install_tui/image18.png)
+
+#### 3.1.10 启动其它服务
+
+参考 3.1.8 描述，启动其他组件（parser、sched、toe、watchcat）。
+
+![image19](./assets/install_tui/image19.png)
+![image20](./assets/install_tui/image20.png)
+
+#### 3.1.11 启动向量库服务
+
+bash
+
+```
+# 使用集群命令启动（root用户）
+# ./mxtool cluster exec '/opt/matrix/web/bleve-explorer/bleve-explorer.sh start' --host <主机名>
+See the /opt/soft/mxtool.log file for debug information.
+# 注意：/opt 根据设定安装路径进行修改
+
+# 单独机器启动脚本命令（matrix用户）
+$ su - matrix
+$ /opt/matrix/web/bleve-explorer/bleve-explorer.sh start
+# 注意：/opt 根据设定安装路径进行修改
+```
+
+
+
+### 3.2 系统登录
+
+#### 3.2.1 默认租户登录
+
+系统的默认租户名称为 `unio`。打开浏览器，在url地址栏输入登录地址 `http://ip:8080/unio`。username默认为 `admin`，password默认为 `admin`。
+
+考虑到兼容性及效果，建议使用Chrome内核浏览器（80版本以上）。
+
+https://media/image21.png
+
+### 3.3 删除已安装系统
+
+bash
+
+```
+# 使用集群命令启动（root用户）
+# ./mxtool cluster remove
+See the /opt/soft/mxtool.log file for debug information.
+```
+
+
+
+### 3.4 更新组件
+
+bash
+
+```
+# 使用（root用户）
+# 上传组件到服务器/tmp下
+
+# 更新web组件
+# ./mxtool cluster update --source /tmp/web --dest $MATRIXHOME/web --concurrent --force web
+
+# 更新odbserver组件
+# ./mxtool cluster update --source /tmp/odbserver --dest $MATRIXHOME/odbserver --concurrent --force odbserver
+
+See the /opt/soft/mxtool.log file for debug information.
+```
+
+
+
+------
+
+## 4. 服务状态
+
+在安装目录的 `sbin` 下执行：
+
+bash
+
+```
+$ ./matrix.sh status   # 查看启动状态
+cassandra running 6775 matrix
+etcd running 7016 matrix
+nats running 7051 matrix
+odbserver running 3165 matrix
+parser stopped 2125 matrix
+sched stopped 1205 matrix
+web stopped 1795 matrix
+toe stopped 3195 matrix
+```
+
+
+
+------
+
+## 5. 服务日志
+
+bash
+
+```
+# ssh matrix@ipaddress -p port
+
+# cassandra运行日志
+$ cd $MATRIXROOT/cassandra/log
+cat debug.log
+cat system.log
+
+# etcd运行日志
+$ cd $MATRIXROOT/var/logs/etcd
+$ cat log.log   # 消息日志
+$ cat out.log   # 错误日志
+
+# nats运行日志
+$ cd $MATRIXROOT/var/logs/nats
+$ cat log.log   # 消息日志
+$ cat out.log   # 错误日志
+
+# parser运行日志
+$ cd $MATRIXROOT/var/logs/parser
+$ cat log.log   # 消息日志
+$ cat out.log   # 错误日志
+
+# toe运行日志
+$ cd $MATRIXROOT/var/logs/toe
+$ cat log.log   # 消息日志
+$ cat out.log   # 错误日志
+
+# odbserver运行日志
+$ cd $MATRIXROOT/var/logs/odbserver
+$ cat log.log   # 消息日志
+$ cat out.log   # 错误日志
+
+# sched运行日志
+$ cd $MATRIXROOT/var/logs/sched
+$ cat log.log   # 消息日志
+$ cat out.log   # 错误日志
+
+# web运行日志
+$ cd $MATRIXROOT/var/logs/web
+$ cat log.log   # 消息日志
+$ cat out.log   # 错误日志
+
+# bleve运行日志
+$ cd $MATRIXROOT/var/logs/bleve
+$ cat out.log   # 错误日志
+```
+
+
+
+------
+
+## 6. 修改数据平台访问端口
+
+1. 登录平台
+2. 点击 "配置管理"
+3. 点击左侧树 `matrix -- etc -- web - <主机名> - app.ini` 修改按钮
+
+https://media/image22.tiff
+
+将 `HTTP_PORT`、`MASTER_PORT` 修改为需要的端口（1000以上）
+
+1. 重启web组件
+
+------
+
+## 7. 数据导入导出工具
+
+工具路径：`$MATRIXROOT/bin`
+文件名：`odbtool`
+
+帮助文档：
+
+bash
+
+```
+./odbtool -help
+
+NAME:
+   odbtool - The odb tool
+
+USAGE:
+   odbtool [global options] command [command options] [arguments...]
+
+VERSION:
+   1.0.17
+
+COMMANDS:
+   mql        Execute mql
+   cql        Execute cql
+   export     Export data to mql file or xlsx file
+   import     Import data from mql file or xlsx file
+   help, h    Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+   --keyspace value, -k value   Select keyspace (default: "matrix")
+   --addr value, -a value       ODB address or Cassandra address
+   --user value, -u value       ODB or Cassandra username
+   --pass value, -p value       ODB or Cassandra password
+   --help, -h                   show help
+   --version, -v                print the version
+```
+
+
+
+### 7.1 导入mql文件
+
+bash
+
+```
+./odbtool -k oootest -u admin -p admin import -help
+
+NAME:
+   odbtool import - Import data from mql file or xlsx file
+
+USAGE:
+   odbtool import [command options] [arguments...]
+
+OPTIONS:
+   --file value   Import file path (.mql or .xlsx)
+```
+
+
+
+**导入举例：**
+
+bash
+
+```
+./odbtool -k oootest -u admin -p admin import --file /opt/matrix/var/test/entity.mql
+# -k oootest     keyspace名称
+# -u admin       odb用户名
+# -p admin       odb密码
+# import         导入命令
+# --file         mql文件
+```
+
+
+
+**断点续传：**
+
+bash
+
+```
+# 第一次执行时：-c 表示导入出错，立即停止
+/opt/matrix/agent/bin/odbtool -k icbctest import --file ./testinsert.mql -c
+# Import file ./testinsert.mql.
+# Import data success: 80, failure: 0.redis: 2026/04/21 18:44:01 pubsub.go:168: redis: discarding bad PubSub connection: read tcp 172.26.38.247:38536->172.26.38.247:11001: read: connection reset by peer
+# 2026-04-21 18:44:31.407 No client available
+# Import data success: 80, failure: 1.
+# Import mql (报错信息......error: [Unsure]
+# Error position index: 81
+
+# 第二次执行：-s 81 表示导入从81行开始
+/opt/matrix/agent/bin/odbtool -k icbctest import --file ./testinsert.mql -c -s 81
+# Import file ./testinsert.mql.
+# Continue from position: 81
+# Import data success: 594, failure: 0.
+```
+
+
+
+### 7.2 导出mql文件
+
+bash
+
+```
+./odbtool -k oootest -u admin -p admin export -help
+
+NAME:
+   odbtool export - Export data to mql file or xlsx file
+
+USAGE:
+   odbtool export [command options] [arguments...]
+
+OPTIONS:
+   --ftype value      Export file type (mql or xlsx) (default: "mql")
+   --class value      Export class
+   --recursive, -r    Recursive subclass
+   --limit value      Data limit size (default: -1)
+   --where value      Query where conditions
+   --template, -t     Export template
+   --ignf value       Ignore fields
+   --ignc value       Ignore classes
+   --reldef           Export relation defined
+   --out value        Output file
+```
+
+
+
+**导出举例：**
+
+bash
+
+```
+./odbtool -k oootest -u admin -p admin export --class /m3event -r --out /opt/matrix/var/test/entity1.mql
+# Export class /m3event
+# Class /m3event size 0
+# Export class /m3event/entity
+# Class /m3event/entity size 0
+# Export class /m3event/entity/component
+# Class /m3event/entity/component size 1
+# Class /m3event/entity/component size 0
+# Export class /m3event/entity/link
+# Class /m3event/entity/link size 1
+# Class /m3event/entity/link size 0
+# Export class /m3event/entity/node
+# Class /m3event/entity/node size 1
+# Class /m3event/entity/node size 0
+# Export file to /opt/matrix/var/test/entity1.mql
+
+# -k oootest        keyspace名称
+# -u admin          odb用户名
+# -p admin          odb密码
+# export /m3event   导出命令
+# --class           导出的class
+# -r                循环向下导出
+# --file            输出mql文件路径
+```
+
+------
+
+## 8. namespace导出导入工具
+
+**导入脚本使用方法：**
+./odbtool.sh
+用法:
+  导出: ./odbtool.sh export --keyspace <keyspace> --username <user> --password <pwd> --class <class> [--recursive] [--host <host>]
+  导入: ./odbtool.sh import --keyspace <keyspace> --zip <file.zip> [--concurrent <num>]
+
+选项说明:
+  --keyspace       keyspace 名称 (默认: matrix)
+  --username       用户名 (默认: admin)
+  --password       密码 (默认: admin)
+  --class          根类名称 (如 /m3event)
+  --recursive      是否递归导出所有子类 (默认: 只导出指定类)
+  --host           Matrix API 主机地址 (默认: localhost:8080)
+  --zip            导入时指定 ZIP 包路径
+  --concurrent     导入数据时的并发线程数 (默认: CPU 核心数 * 2)
+
+**示例:**
+  **导出: **
+./odbtool.sh export --keyspace oktest --class /m3event --recursive --host 172.26.38.247:8080  
+  **导入: **
+./odbtool.sh import --keyspace oootest --zip ./matrix_export.zip --concurrent 8
+
+------
+
+## 9. 性能优化配置策略说明
+
+### 1) CPU 16核及以上，内存 >= 64G 且 < 128G
+
+修改文件：`$MATRIXROOT/cassandra/conf/cassandra.yaml`
+
+- `concurrent_writes` 修改为 128
+
+https://media/image23.png
+
+- `file_cache_size_in_mb` 修改为 4096
+
+https://media/image24.png
+
+修改文件：`$MATRIXROOT/cassandra/conf/jvm-servers.options`
+
+- `-Xms` 改为 22G
+- `-Xmx` 改为 22G
+
+https://media/image25.png
+
+### 2) CPU 16核及以上，内存 >= 128G
+
+修改文件：`$MATRIXROOT/cassandra/conf/cassandra.yaml`
+
+- `concurrent_writes` 修改为 356
+- `file_cache_size_in_mb` 修改为 8192
+
+修改文件：`$MATRIXROOT/cassandra/conf/jvm-servers.options`
+
+- `-Xms` 改为 44G
+- `-Xmx` 改为 44G
+
+> **注：修改以上配置后，需要重启 cassandra 组件（参考 3.1 章）**