pd — 数据湖 CLI
pd(PlantPulse DataLake) 是数据湖容器内用于启动、停止、诊断八个服务，渲染配置以及进行备份的单一入口命令。管理控制台显示的几乎所有内容都是此命令的 --json 输出。
| 项目 | 值 |
|---|---|
| 模块 | plantpulse-datalake-cli |
| 位置 | 容器内 /opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd （位于 PATH 中） |
| 主机上 | 没有 — 必须使用 docker exec plantpulse-datalake pd … |
docker exec plantpulse-datalake pd status # 하나만 칠 때
/opt/kopens/plantpulse-platform-docker/bin/shell.sh # 여러 개 칠 때 — 셸을 열고 pd … 만 친다
整个平台的启动/停止/重启在主机的 /opt/kopens/plantpulse-platform-docker/bin/ 上进行 — 即 up.sh、down.sh、restart.sh、restart-datalake.sh、status.sh。pd 是比它低一层，处理容器内部服务的工具。当容器本身启动时会执行 pd start，关闭时会执行 pd stop，因此操作员很少需要手动执行 pd start。大多数情况下是“查看状态”和“重启单个服务”。
30 秒摘要
安全等级：读取 = 不改变任何内容 · 修改 = 改变状态 · 破坏性 = 删除数据或进程。
| 动词 | 一句话 | 等级 |
|---|---|---|
pd status [서비스] [--wait] | 端口表。所有行均为 RUNNING 时退出码为 0 | 读取 |
pd doctor | 环境、密钥、模板、运行时树检查（PASS / FAIL / N/A） | 读取 |
pd env | 此节点的目录、镜像身份 — 仅声明，不测量 | 读取 |
pd version | 从已安装内容读取的版本号 — 不是此文件的常量，而是 jar MANIFEST 中的 | 读取 |
pd logs [--list] [--lines N] [서비스…] | 跟随服务日志 | 读取 |
pd storage | 卷、WAL、复制槽、存储大小、Kafka 保留 | 读取 |
pd retention | 表 TTL、主题保留、冷层、归档作业 | 读取 |
pd flow | Kafka 消费者组延迟 | 读取 |
pd downtime | 超出计划而宕机的区间 — 仅重新启动 | 读取 |
pd config list、diff、diff --templates | 模板 → 路径表 · 运行时 vs 渲染 · 主机模板 vs 镜像默认值 | 读取 |
pd config show <대상> | 服务实际读取的渲染文件。凭据会被隐藏 | 读取 |
pd workflow status、list、history | 两个工作流引擎（Temporal、Kestra）— 引擎与轮询器，持有的调度，最近的运行与失败原因。只读 | 读取 |
pd node status、info、cql、psql … | Aster TSDB / PostgreSQL 查询与 Shell | 读取 |
pd backup list、schedule、status | 物理备份集、调度表、当前运行的任务 | 读取 |
pd backup restore … --dry-run | 仅恢复计划 | 读取 |
pd start [서비스]、stop、restart [--clean] | 按顺序启动 · 逆序停止（停止证明）· 两者 | 修改 |
pd config render | 实际写入配置产物 | 修改 |
pd secret rotate VAR=값 | 凭据轮换 — 由主机的 passwd.sh 调用。 请勿手动执行 | 修改 |
pd secret probe-mqtt | 使用提供的凭据实际连接 MQTT 代理（轮换过程使用的验证） | 读取 |
pd backup、pd backup run --engine E --type full|diff | 逻辑转储 · 一次性物理备份 | 修改 |
pd backup schedule set|reset | 备份作业的 Quartz cron 与启用开关 | 修改 |
pd node add、rf、repair、compact、flush、drain … | Aster TSDB 维护 — 添加或移除节点时，请遵循 pd node rf 的顺序 | 修改 |
pd clean | 停止模块的日志、临时文件删除 | 破坏性（日志） |
pd kill [--dry-run] | 对 PP_HOME 下的所有进程执行 SIGKILL | 破坏性 |
pd recover [파일] | DROP 掉 pp 数据库并用逻辑转储恢复 | 破坏性 |
pd backup restore … --yes | 用物理备份将数据目录恢复 | 破坏性 |
pd node cleanup、remove <host-id> | 删除快照、从集群中移除节点 | 破坏性 |
选项集与任何动词的意义相同。
| 选项 | 含义 |
|---|---|
--json | 生成单个 JSON 文档而非表格。控制台读取的格式。接受此选项的动词是确定的；若添加到其他动词则退出码为 2，拒绝执行 |
--show-secrets | 仅 config diff。不将密码隐藏为 ***。不能与 --json 一起使用 |
PD_DEBUG=1 | DEBUG 日志。前缀如 PD_DEBUG=1 pd start |
服务与启动顺序
八个服务按既定顺序启动。权威来源是独立的 services/order.txt。pd start 从上到下，pd stop 相反。
| 顺序 | 服务 | MASTER | WORKER | 内部组件 | pd status 行（端口） |
|---|---|---|---|---|---|
| 1 | storage | ○ | ○ | valkey → postgres → cassandra → rustfs（仅 MASTER） | 6379 · 5432 · 9042 · 9000 |
| 2 | analytics | ○ | ○ | spark-master → hive → gravitino → kyuubi（WORKER 为 spark-worker · kyuubi） | 7077 · 4440 · 9083 · 19001 · 10000 |
| 3 | messaging | ○ | — | kafka · mqtt（HiveMQ） | 9092 · 1883 |
| 4 | timeseries | ○ | — | engine（TSE）· dashboard（PlantPulse Dashboard） | 7800 · 3000 |
| 5 | cep | ○ | — | Tomcat | 7400 |
| 6 | workflow | ○ | — | temporal → kestra | 7233 · 8233 · 8380 |
| 7 | data-gateway | ○ | — | Tomcat | 5500 |
| 8 | admin-api | ○ | ○ | 管理控制台后端 | 4949 |
- 每个服务启动后，等待健康检查返回 UP 再进入下一个（上限：storage 1800 秒，analytics 600 秒，其余 300 秒）。
storage和analytics是门卫。如果它们未启动，则不再尝试后续步骤，退出码为 5。其余服务则将发出警告并继续（最后退出码为 6）。- 自 2026-09-05 起，
timeseries仅限 MASTER 使用。
生命周期
pd status # 전체 표 — 마지막 줄 "0 STOPPED" 면 정상
pd status storage # 서비스 하나의 헬스체크
pd status storage --wait # UP 이 될 때까지 대기
pd start cep # 죽은 서비스 하나 다시 띄우기
pd stop cep # 서비스 하나 내리기 — «멈췄다» 를 증명한다 (30초 + SIGTERM 15초 + SIGKILL 10초)
pd restart cep # stop → (정지가 증명되면) 5초 → start
pd restart cep --clean # 사이에 pd clean
pd restart # 전부 — 몇 분 걸린다. storage 가 먼저 돌아온다
pd status 有四种状态。
| 状态 | 含义 |
|---|---|
RUNNING | 端口已打开 |
STOPPED | 端口已关闭。启动后最初的几十秒是窗口期，请 1 分钟后再次查看 |
UNKNOWN | 未能测量 — 当没有端口测量工具时。不是已停止 |
DISABLED | 通过 PD_OPTIONS 关闭。不改变退出码 |
pd stop 退出码为 7，请勿立即执行 pd startSTILL RUNNING 表示未成功证明停止。如果在存活进程上启动，将导致端口冲突和数据损坏。请使用 pd kill --dry-run 查看剩余内容，然后通过 pd kill、pd status 确认已清空，再进行 pd start。不要使用 FORCE=1 pd start。
容器的 Docker HEALTHCHECK 不会调用 pd status（因为速度慢且有时不稳定）。相反，它会检查 postgres、cassandra 是否能响应实际查询以及所有端口是否打开。因此，“docker ps 是 healthy 而 pd status 是 STOPPED”可能是启动窗口期或一次未命中；而“unhealthy 但 pd status 全部 RUNNING”则表示端口已打开，但无法响应查询（pd logs storage）。
诊断
pd doctor # 여섯 절 검사. 마지막 줄 FAIL 0 이면 된다
pd env # 디렉터리 · 이미지 정체 (0.25초)
pd logs --list # 따라갈 파일 목록만
pd logs --lines 50 cep # cep 만, 마지막 50줄부터
pd storage # 볼륨 90% 이상이면 FAIL
pd retention # 왜 안 줄어드나 — TTL · 토픽 보존 · 콜드 티어
pd flow # 데이터가 안 들어온다 — 컨슈머 lag
pd downtime # 자꾸 죽는 것 같다 — 계획 밖 정지 기록
pd doctor 包含六个部分：[1] inputs（密钥、节点文件、镜像）、[2] tools、[3] config templates（是否全部渲染）、[4] runtime tree、[5] TLS material、[6] core ports。N/A 表示“此处无法测量”，并在括号中注明原因。容器内没有 sidecar 文件是正常的 — 值是通过环境变量传入的。
pd flow 的 NA 不是“落后了”，而是**“从未读取过”。如果 MEMB 列为 0，表示消费者未启动；如果大于 0 但主题为空，是正常情况（没有要读的内容）；如果大于 0 且主题有数据，则是真正的可疑信号**。
配置
pd config list # 이 모드의 템플릿 → 경로 표
pd config diff # 런타임 파일 vs 지금 렌더하면 나올 것 (0 같음 / 1 다름 / 3 시크릿 없음 / 4 렌더 실패)
pd config diff --templates # 호스트 템플릿 vs 이미지 기본값 (same / differs / local / missing)
pd config render # 실제로 쓴다 — 그 뒤 pd restart <서비스> 까지가 한 세트
修改值的步骤和“应该改哪里”参见 修改配置的方法。请勿直接修改容器内的产物 —— 下次执行 pd start 时就会消失。
Aster TSDB · PostgreSQL 节点操作
pd node status # nodetool status — UN 이 정상, DN 이면 죽은 노드
pd node status --json # + PostgreSQL 복제 · Valkey 복제 · 워커 명부
pd node info # 노드 상세
pd node cql # cqlsh (cassandra 계정)
pd node psql # psql (postgres OS 사용자)
pd node errors # cassandra debug.log 의 최근 WARN/ERROR
pd node topic # kafka 토픽 "event" describe
pd node tpstats | compactionstats | proxyhistograms | table-stats [ks] | table-histograms <ks> <tbl> | sstable-size <ks> <tbl> | disk
| 修改的动词 | 等级 | 一句话 |
|---|---|---|
pd node add | 修改 | 根据存活节点数提高 keyspace RF（最大 3）并 repair。在添加 worker 后执行一次 master |
pd node repair、repair-table <ks> <tbl> | 修改（繁重） | 处理节点间数据不一致 |
pd node flush、drain | 修改 | 将内存写入刷新到磁盘。drain 随后拒绝写入，因此仅在停机前执行 |
pd node compact [ks] [tbl] | 修改（繁重） | SSTable 合并 |
pd node cleanup | 破坏性 | 删除所有快照 + 删除此节点不再拥有的数据 |
pd node remove <host-id> | 破坏性 | 从集群中移除宕机节点。不要对存活节点执行。先降低 RF — 见下文 |
pd node rf [--check] [<노드수>] | 修改 | 重新评估集群，并将**所有键空间的复制系数（RF）**调整为该数量 |
pd node upgrade、init-cms、train-zstd、cache-clear | 修改 | 安装过程、版本升级、清除 OS 页面缓存 |
pd node rf — 将复制系数调整至集群
添加或移除节点时，请勿手动修改 RF。 这一个动词会重新评估集群，计算目标 RF， 并将其应用到所有键空间。每个方向都有指定的调用位置。
| 时机 | 顺序 |
|---|---|
| 增加时 | pd node add → pd node rf → nodetool repair |
| 减少时 | pd node rf <빠진 뒤의 노드수> → 节点离开 → nodetool cleanup |
| 宕机节点 | pd node rf → pd node remove <host-id> |
损坏状态是 RF 大于节点数。先降低则不会进入该状态。
如果按相反顺序操作，会形成 RF 3 落在 2 节点集群的窗口，在此期间若再丢失一个节点，
QUORUM 读·写将全部失败。包括 system_auth 在内 —— 任何人都无法登录查看
发生了什么。
nodetool decommission、removenode 会根据当前 RF 来转移离开节点的范围。
先降低则需转移的数据减少，剩余节点将按新 RF 所要求的那样拥有数据。
<노드수> 参数的存在正是为了此顺序 —— 降低 RF 时离开节点仍在集群中，
因此目标是“该节点移除后的数量”。对于已宕机且不在集群中的节点进行 remove
时，可以不使用参数。
因短暂关闭的节点，RF 不会降低。如果成员为 3，存活为 2，则发出警告，但 RF 保持为 3 —— 因为节点恢复后会回到原状。
如果节点少于三个，则 RF 也相应减少（1 节点 → RF 1）。当第三个节点加入并重新运行 pd node rf
时，会升至 3。 RF 大于节点数会使所有 QUORUM 查询失败，因此不会保持这样。
--check 仅重新评估pd node rf --check 不改变任何内容，仅检查当前 RF 是否与集群匹配。
当无法测量时，以“无法判定”而非“匹配”结束（退出码 2）—— 如果无法读取数据中心名称
或无法统计节点数，则不做猜测。因为若名称错误，复制会静默失效。
对于使用了 pd 不识别的复制策略的键空间，会不处理并列出名称 ——
不会静默跳过。
提升时执行 repair，减少后执行 cleanup 也是有原因的。新副本是从空状态开始的，
因此需要填充（repair）；而减少后需要丢弃不再拥有的范围（cleanup）。
备份与恢复
pd backup # PostgreSQL 논리 덤프 → /data1/pp-data/postgres/dump/
pd backup list | schedule | status
pd backup run --engine postgres --type diff
pd backup restore --engine postgres --set <세트> --dry-run # 계획 먼저
pd recover [덤프파일] # pp DB 하나를 논리 덤프로 되돌림 (파괴적)
步骤参见 备份与恢复。
退出码
| 代码 | 含义 |
|---|---|
| 0 | 成功。status 全部 RUNNING，doctor 无 FAIL，config diff 无差异 |
| 1 | 一般失败、“不同”、“有问题” |
| 2 | 用法错误 — 未知动词、服务、选项，--json 被拒绝，PP_HOME 未指定 |
| 3 | 必需密钥缺失 — 消息中包含所有名称。backup run、restore 中为“其他备份正在运行” |
| 4 | 渲染失败 — 未替换的 ${PP_*}，列出所有名称 |
| 5 | 门卫服务（storage、analytics）未启动，启动中止 |
| 6 | 启动已完成，但部分服务未就绪 |
| 7 | 未能证明停止（STILL RUNNING） |
| 8 | 广播地址为回环地址（127.0.0.1）— 渲染被拒绝 |
日志格式与日志
pd 输出的每一行都遵循单一格式 — [시각] [DATALAKE-CLI] [레벨] [동사] 메시지。INFO 输出到 stdout，其余输出到 stderr。
pd start、stop、restart、backup 会将一行 JSON 写入事件日志 plantpulse-datalake-admin-api/logs/pd-events.jsonl，控制台将其显示为事件时间线。控制台执行的命令由 actor 记录为 operator:<name>。
PD_OPTIONS — 选择性关闭组件
变量存在，但当前 compose 栈不会将此值传递给容器。 因此目前不支持 选择性关闭组件 → FAQ
服务器、批处理、数据仓库、OPC-UA、AASX 在各自的容器中运行。数据湖容器中没有这些模块。请在主机上重启应用。
cd /opt/kopens/plantpulse-platform-docker/bin
./restart-server.sh # 또는 restart-batch.sh · restart-warehouse.sh · restart-one.sh <서비스>