数据库管理

数据库构成

PlantPulse AI 使用6个数据库，各自服务于不同目的。

数据库	用途	数据类型
PostgreSQL	关系型元数据	用户信息、聊天记录、RAG 元数据、特征存储
Aster TSDB	时序存储	传感器数据、副驾任务、推理历史
Neo4j（两个实例）	图数据	LightRAG 知识图谱 · 数字孪生线的工厂图镜像
Qdrant	向量存储	文档嵌入、设备特征向量
Valkey (Redis)	缓存	会话、临时数据、搜索缓存
RustFS	对象存储	文档文件、图片、报告

PostgreSQL

数据库列表

AI 不会自行启动 PostgreSQL，而是在平台的 PostgreSQL 内创建四个 DB 使用（没有 provision-platform-db.sh 就创建，已有则跳过 — 幂等）。

数据库	使用服务
`pi`	AI 应用的 DB — 每个应用一个模式：`co` = AI Chat Web（用户 · 聊天记录 · 应用 · 设置），`dt` = 数字孪生线（连接器注册表）
`lightrag`	LightRAG 的文档处理状态（`doc_status`）
`rag_ingest`	文档加载流水线（rag-api）的状态。开启图纸 · 视频采集后，相应的表（`rag_drawing_` · `rag_media_`）也会在启动时在此创建
`litellm`	LiteLLM 网关的密钥 · 使用量

接入账号是平台 PG 的账号（PP_PG_USER） — 并没有单独的 AI 专用账号。 pi 的两个模式也通过此账号连接。不会把表放在 public 中。

从 2026.09 以下版本升级时 — `ch` 会被迁移到 `pi.co`

2026.09 以下版本中，副驾表位于 DB ch 的 public 中。2026.10 在启动时会在 compose 之前先运行 bin/migrate-pg-ch-to-pi.sh 来完成迁移 — install · up · update · compose-up 都遵循相同顺序，不需要另外调用。

停止副驾 · 数字孪生线容器。
清理 ch 中残留的会话 — 只终止连接到 ch 的应用账号（PP_PG_USER）的会话。
在一个事务中将 public 的对象迁移到新模式 co。
ALTER DATABASE ch RENAME TO pi。

状态	动作
只有 `pi` · 两者都没有	无需操作
只有 `ch`	按上述顺序迁移
`ch` 与 `pi` 两者都存在	拒绝执行，不做任何改动
`ch` 的 `public` 和 `co` 两边都有对象	拒绝执行（存在手动迁移了一半的痕迹）

cd /opt/kopens/plantpulse-ai-docker
bin/migrate-pg-ch-to-pi.sh --check      # 미리 보기 — 아무것도 바꾸지 않습니다
bin/migrate-pg-ch-to-pi.sh --rollback   # 되돌리기 — pi.co → ch.public, 이름을 ch 로

迁移脚本不会进行转储

升级之前请先将 ch 转储一次到 pg_dump。平台 PG 的磁盘 · 保留由平台负责，此脚本不会代为处理。回退之后，必须使用之前版本的 compose 和副驾镜像启动 — 若用新 compose 启动，会立刻再次执行迁移。

管理

# PostgreSQL 접속 — 코파일럿 스키마
psql -h <플랫폼 PG 호스트> -U <PP_PG_USER> -d pi -c 'SET search_path TO co' -c '\dt'

# 디지털 스레드 스키마
psql -h <플랫폼 PG 호스트> -U <PP_PG_USER> -d pi -c '\dt dt.*'

# 데이터베이스 목록 확인
psql -h <플랫폼 PG 호스트> -U <PP_PG_USER> -c '\l'

Aster TSDB

键空间

键空间	用途
`pi`	PlantPulse AI 主库（副驾任务、推理历史）

管理

# Cassandra CQL 접속
cqlsh 127.0.0.1 9042 -u cassandra -p cassandra

# 키스페이스 목록
DESCRIBE KEYSPACES;

# 테이블 목록
USE pi;
DESCRIBE TABLES;

信息

Aster TSDB 键空间会在首次启动时通过 db/cassandra/support/keyspace-create.sh 脚本自动创建。

Neo4j

从 2026.10 起，Neo4j 会启动两个实例。镜像相同，账号（PI_NEO4J_USER · PI_NEO4J_PASSWORD）也相同，但所存内容和开放端口不同。

容器	存放内容	卷	主机端口
`plantpulse-neo4j`	LightRAG 知识图谱	`pi-neo4j-data`	7474 · 7687
`plantpulse-digital-thread-neo4j`	数字孪生线的工厂图镜像（`Dt*`） — 仅供参考，无正文	`pi-digital-thread-neo4j-data`	无

Neo4j Community 版无法创建多个 DB 或按角色划分权限，为了确保将两种服务明确分离，拆分了实例。数字孪生线一侧只有数字孪生线 API 在 compose 网络内接入，并设有内存上限（堆 512 MB · 页缓存 256 MB）。

密码由 bin/passwd.sh 同时修改两个实例

由于账号是共用的，请勿只修改一侧 → 修改密码 · API 密钥

接入信息 — `plantpulse-neo4j`

项目	值
Browser URL	http://<服务器IP>:7474
Bolt URI	bolt://127.0.0.1:7687
用户	neo4j
密码	neo4j123

管理

在 Neo4j Browser（http://<服务器IP>:7474）中通过 Cypher 查询管理图谱：

// 노드 타입별 카운트
MATCH (n) RETURN labels(n), count(n) ORDER BY count(n) DESC;

// 관계 타입별 카운트
MATCH ()-[r]->() RETURN type(r), count(r) ORDER BY count(r) DESC;

数字孪生线一侧 — `plantpulse-digital-thread-neo4j`

由于端口未开放，无法通过 Browser 访问。状态可在管理控制台的数字孪生线 → 图镜像 界面（Neo4j 探针 · 按标签的节点数）查看。镜像是可以从源（平台台账 · 事件）重新生成的副本 → 数字孪生线

Qdrant

接入信息

项目	值
REST API	http://127.0.0.1:6333
Dashboard	http://127.0.0.1:6333/dashboard
API Key	qdrant-key-123

集合

集合	用途
（LightRAG 自动创建）	RAG 文档向量（由 LightRAG 管理）

RustFS

接入信息

项目	值
API	http://127.0.0.1:9000
Console	http://127.0.0.1:9001
Access Key	minio
Secret Key	minio123!

桶

桶用途

plantpulse-rag rag-api 的单一对象存储。按前缀区分 — manual/ 管理控制台中手动上传的文档原件，drawings/ 图纸结构与页面预览（开启图纸采集时），media/ 视频 · 音频播放版本与录音（开启视频采集时），migration/ 旧桶迁移完成标记。桶名为 compose 默认值，仅当同一平台同时运行两套 AI 安装时，第二套安装才通过主机 env RAG_S3_BUCKET 指定不同名称 → 环境变量设置

桶	用途
`plantpulse-rag`	rag-api 的单一对象存储。按前缀区分 — `manual/` 管理控制台中手动上传的文档原件，`drawings/` 图纸结构与页面预览（开启图纸采集时），`media/` 视频 · 音频播放版本与录音（开启视频采集时），`migration/` 旧桶迁移完成标记。桶名为 compose 默认值，仅当同一平台同时运行两套 AI 安装时，第二套安装才通过主机 env `RAG_S3_BUCKET` 指定不同名称 → 环境变量设置

2026.10 之前的 rag-manual-docs 会自动迁移

旧版本将手动上传的原件存放在 rag-manual-docs 桶中。2026.10 的 rag-api 在启动时会在后台将这些对象复制到 plantpulse-rag 的 manual/ 下。若新位置已存在则不会覆盖，旧桶仅作只读使用，因此即便回退到旧镜像依然能正常读取。进度可在 rag-api /api/v1/config 的 object_store_migration 项中查看。

数据存储路径

AI 栈的本地状态保存在具名 Docker 卷中，而非主机目录。请不要尝试在主机上按路径查找 — 应通过 docker volume inspect 查看。

卷	内容	丢失后果
`pi-lightrag-inputs`	已上传的原始文档	无法重新生成索引
`pi-lightrag-storage`	LightRAG KV 缓存（本地 JSON）	可重新生成
`pi-qdrant-data`	文档嵌入向量	可从原件重新生成
`pi-neo4j-data`	LightRAG 知识图谱	可从原件重新生成
`pi-digital-thread-neo4j-data`	数字孪生线的工厂图镜像	可从源重建 — 但需要重新读取平台事件，恢复会快得多
`pi-ttm-tuned-models`	基于现场数据按安装个别训练的时序模型	没有该现场数据将无法重新生成
`pi-pp-proxy-certs`	代理的 TLS 证书	若是客户提供的实际证书，需要重新获取
`pi-phoenix-data`	LLM 调用追踪记录	过去的追踪记录将丢失
`pi-registry-data`	本地镜像仓库（仅开启 `registry` 配置的节点）	需要重新推送镜像
`pi-asr-audio`	录音服务读取的音频库（仅开启视频 · 音频的安装）	无损失 — `plantpulse-asr-audio` 每次启动都会重新写入

`bin/backup.sh` 所备份的内容

接收 compose 文件中声明的全部卷 — 不另行单独列举。排除的是可重新生成的 日志与缓存（copliot-web-logs · insight-api-logs · llm-cache · emb-cache · rerank-cache · asr-cache），以及每次启动都会重新生成的录音音频库（asr-audio）。registry-data 仅在开启该配置的节点上存在，因此若存在则备份，不存在则跳过。

cd /opt/kopens/plantpulse-ai-docker/bin
./backup.sh --list                  # 볼륨마다 backup · optional · exclude 판정만 찍는다
./backup.sh                         # 전부 → /data1/pp-backup/YYYYMMDD/<볼륨>.tar.gz
COMPONENT=neo4j-data ./backup.sh    # 하나만

选项	默认值	含义
`BACKUP_ROOT`	`/data1/pp-backup`	备份存放位置
`BACKUP_RETENTION_DAYS`	`30`	删除早于该日期的目录 — 仅当该轮次全部成功时

过去只备份四个卷

2026.09 之前的 backup.sh 只手动指定备份四个卷（neo4j-data · qdrant-data · lightrag-storage · lightrag-inputs），遗漏了 TLS 证书卷。 现在是从 compose 中提取列表，因此新增的卷会默认纳入备份。

在运行状态下制作的备份可能不完全一致

可能会得到写入过程中的副本。若需要如升级前那样一致的备份，请先执行 bin/compose-down.sh 降级再进行。恢复操作也应在 compose 停止的状态下进行（示例见 bin/backup.sh 的开头部分）。

PostgreSQL · Aster TSDB · Redis · RustFS 属于平台所有，因此此脚本不会对其进行备份 — 请遵循平台的备份流程。

备份建议

对象	方法	周期
PostgreSQL	`pg_dump`	每日1次
Neo4j	`neo4j-admin dump`	每日1次
RustFS	`rc mirror`	每日1次
Qdrant	Snapshot API	每周1次
`/etc/kopens/plantpulse-ai.env`	文件复制 — 🔴 `PI_LITELLM_SALT_KEY` 位于此处	变更时
AI 本地卷	`bin/backup.sh`（如上）	每日1次

数据库构成​

PostgreSQL​

数据库列表​

从 2026.09 以下版本升级时 — ch 会被迁移到 pi.co​

管理​

Aster TSDB​

键空间​

管理​

Neo4j​

接入信息 — plantpulse-neo4j​

管理​

数字孪生线一侧 — plantpulse-digital-thread-neo4j​

Qdrant​

接入信息​

集合​

RustFS​

接入信息​

桶​

数据存储路径​

bin/backup.sh 所备份的内容​

备份建议​

数据库构成

PostgreSQL

数据库列表

从 2026.09 以下版本升级时 — `ch` 会被迁移到 `pi.co`

管理

Aster TSDB

键空间

管理

Neo4j

接入信息 — `plantpulse-neo4j`

管理

数字孪生线一侧 — `plantpulse-digital-thread-neo4j`

Qdrant

接入信息

集合

RustFS

接入信息

桶

数据存储路径

`bin/backup.sh` 所备份的内容

备份建议