数据库管理

概述

本页介绍已安装的 PlantPulse 平台使用的数据存储的配置、连接方法、状态检查和基本调优策略。

平台内置 4 种数据存储，按用途分类运维。

存储	用途	默认端口	备注
Cassandra	时序 / 大容量数据（标签数据点、事件）	9042 (CQL)	密钥空间 pp。平台单一的大容量 DB 引擎
PostgreSQL	元数据存储（主控 / 配置数据）	5432	数据库 pp、模式 pp
Valkey（Redis 兼容）	缓存 / 会话 / 实时状态	6379	可用 redis-cli 连接
MinIO	对象存储（S3 兼容）	9000 (S3) / 9001（控制台）	文件 / 大容量输出存储

此外还有分析层（Spark / Kyuubi）使用的 Hive Metastore + Iceberg 表格式，平台内部管理，无需单独运维。

注意：Cassandra 的 7000（集群 gossip）、7199（JMX）端口仅用于内部通信。不要向外部暴露。

连接方法

以下命令均在数据湖容器内部执行。四种存储都在 plantpulse-datalake 同一容器内运行，打开 shell 即可进入该容器。

cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh

连接账户和密码由环境变量（PP_CASSANDRA_USER/PASSWORD、PP_PG_USER/PASSWORD、PP_REDIS_PASSWORD 等）管理。

项目	位置
实际应用值	主机的密钥边车 /etc/kopens/plantpulse-platform.env（权限 0600）
修改值的方法	bin/passwd.sh — 直接修改文件不会生效 → 密码轮换

路径确认 — 密钥边车的正本是 /etc/kopens/plantpulse-platform.env 唯一文件（权限 0600）。旧版安装中 /opt/kopens/ 下可能残留同名文件，但不会被读取，安装脚本会恢复为正本 → 环境变量参考

Cassandra (cqlsh)

cd /opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/bin
./cqlsh -u <PP_CASSANDRA_USER> 127.0.0.1 9042

-- 키스페이스 / 테이블 확인
DESCRIBE KEYSPACE pp;
SELECT table_name FROM system_schema.tables WHERE keyspace_name = 'pp';

PostgreSQL (psql)

使用 PostgreSQL 18，客户端二进制位于 /usr/pgsql-18/bin。

/usr/pgsql-18/bin/psql -h 127.0.0.1 -U <PP_PG_USER> -d pp

-- 메타스토어 스키마 확인 (기본 search_path 는 pp 스키마)
\dn
\dt pp.*

Valkey (redis-cli)

redis-cli -h 127.0.0.1 -p 6379 -a '<PP_REDIS_PASSWORD>' ping

警告：仅用于查询（SELECT / DESCRIBE / ping）。不要修改数据或更改模式，详见注意事项。

状态检查

Cassandra 节点状态

pd node 动词包装 nodetool 并提供。

cd /opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin
./pd node status

正常状态下节点显示为 UN（Up / Normal）。如出现 DN（Down）节点，需要重启存储或检查日志。

PostgreSQL 状态

/usr/pgsql-18/bin/pg_isready -h 127.0.0.1 -p 5432
/usr/pgsql-18/bin/psql -h 127.0.0.1 -U <PP_PG_USER> -d pp -c "SELECT version();"

集成状态仪表板 / 健康 API

# 포트별 서비스 상태 + CPU / 메모리 / 디스크 요약
cd /opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin
./status.sh

# 헬스 API — cassandra / postgres 컴포넌트 상태 포함
curl -kfsS https://127.0.0.1:4950/api/health | jq

检查健康 API 响应中 cassandra、postgres 组件是否正常（UP）。

模式 / 数据布局

项目	位置	内容
Cassandra 密钥空间	pp	时序数据表（tm_*）
PostgreSQL 模式	数据库 pp / 模式 pp	主控 / 配置表（mm_*）
数据文件路径	/data1/pp-data	Docker 卷 pp-data 挂载

PostgreSQL 元数据存储模式已在镜像构建时预装，安装后无需单独创建模式。连接时 search_path 已设置为 pp 模式，可直接按表名查询。

所有数据存储在 /data1/pp-data（卷 pp-data）下，删除容器或更新镜像时数据会被保留。

调优基本值（出厂设置）

Cassandra 按平台工作负载采用以下基本值出厂配置。

项目	出厂基本值	说明
JVM 堆	-Xms16G -Xmx16G	初始 / 最大堆相同（防止动态调整）
GC	ZGC (Generational)	低延迟垃圾回收器
文件缓存	file_cache_enabled: false	利用 OS 页缓存，无 off-heap 限制
Direct 内存	-XX:MaxDirectMemorySize=6G	memtable off-heap + IO 缓冲用途

重要 — 配置修改路径：各服务路径下的配置文件（如 Cassandra 的 cassandra.yaml、jvm-server.options）是从 plantpulse-datalake-cli/config/templates/ 的模板渲染生成的。直接修改这些文件会在下次重启 / 重配（configure）时被模板值覆盖，变更会丢失。

需要修改调优值时，必须按以下步骤进行。

1. 修改主机 /etc/kopens/conf 中的模板（挂载到容器的 plantpulse-datalake-cli/config/templates）或 bin/env.sh 的 PP_* 变量
2. 在数据湖容器内执行 ./configure.sh — 重新渲染模板并部署到各服务路径
3. 重启相关服务（例：pd restart storage）

模板位于主机目录，运维人员可在主机直接编辑，重新安装时编辑内容也会保留。

如果需要修改基本值，建议先咨询技术支持团队。

备份概述

包括数据库在内的所有数据都存储在 pp-data 卷中，卷级备份是最简单、最安全的方法。

cd /opt/kopens/plantpulse-platform-docker/bin

# 기본 세트 (pp-data · pp-security) 를 한 번에
./backup.sh

# 볼륨 하나만 — <volume-name> [보관일수] [백업경로]
./tools/backup-volume.sh pp-data 7 /data1/pp-backup/docker-volume

backup.sh 的默认集合中，pp-backup 是备份的目标，pp-temp 对恢复无用而被排除。如需备份，可用参数指定。

点对点恢复、单库备份、外部存储同步等详细步骤参见管理员指南 - 备份与恢复页面。

注意事项

• 禁止直接对运营 DB 执行 DDL — 不要直接执行表创建 / 修改 / 删除（CREATE / ALTER / DROP / TRUNCATE）。模式由平台通过版本迁移管理，任意修改会导致更新失败或数据丢失。
• 避免直接修改数据 — 主控数据（mm_*）应通过管理控制台修改。直接 DB UPDATE 会导致缓存 / 关联服务不一致。
• 禁止使用嵌入式 / 替代 DB — 不支持用其他 DB 产品或嵌入式 DB 替换内置 Cassandra / PostgreSQL 的配置。
• 禁止直接删除数据文件 — 不要为释放磁盘空间而直接删除 /data1/pp-data 下的文件。需要数据清理时请联系技术支持团队。
• 账户 / 端口修改用环境变量 — 修改 DB 账户或端口时，应通过环境变量（PP_*）覆盖方式进行，不要直接修改配置文件。

技术支持

如有数据库运维相关问询，欢迎随时联系。

部门	联系方式
技术支持	webmaster@kopens.com