FAQ
这里汇集了 PlantPulse 平台运营人员经常询问的问题及解答。如需更详细的操作步骤，请参阅 问题解决 页面。
安装 / 许可证
Q. 应该选择哪种安装方法？
A. One-line 安装 是标准方法。仅需一行命令即可完成从 OS 设定到防火墙、容器启动的所有处理，更新和回滚也使用同一工具。如果是隔离网络，请参阅 Docker 安装的隔离网络步骤；如需部署在 Kubernetes 上，请参阅 Kubernetes 安装。
Q. 在隔离网络中也可以安装吗？
A. 可以。在连接互联网的节点上使用 ./airgap-bundle.sh 生成 Bundle，然后通过 USB 或内部文件服务器将其转移到隔离网络，最后执行 ./airgap-load.sh 即可。详细步骤请参阅 Docker 安装 - 隔离网络(Airgap)安装 章节。
Q. 如何获取许可证？
A. 镜像 registry 凭据和许可证由 KOPENS 运营团队颁发。请联系 webmaster@kopens.com。
Q. 最低 / 推荐配置是多少？
A. 单节点标准：
| 区分 | 最低 | 推荐 |
|---|---|---|
| CPU | 16 vCPU | 32 vCPU |
| 内存 | 128GB (Data Lake Master 96GB 以上，不支持 64GB) | 256GB |
| 磁盘 | 200GB | 1TB+ (视数据量而定) |
| OS | RHEL · Rocky · Oracle Linux 8/9/10 · Ubuntu 22.04+ · Amazon Linux 2023 | 同左 |
详细规格请参阅 系统要求 页面。
Q. 支持哪些 OS？
A. 以下 OS 支持 One-line 安装：
- RHEL · Rocky Linux · Oracle Linux 8.x · 9.x · 10.x
- Ubuntu 22.04 及以上
- Amazon Linux 2 · 2023
在未经验证的 OS 中，可以使用 SKIP_OS=1 选项跳过 OS 设定并进行手动设定。
Q. 也可以使用 Podman 运行吗？
A. 可以。将 bin/env.sh 的 DOCKER_CMD="docker" 修改为 DOCKER_CMD="podman" 后，所有脚本将以 Podman 方式运行。
安装 / 启动
Q. 安装需要多长时间？
A. 以 One-line 安装为准，从 OS 设定 + Docker 安装 + 镜像下载 + 容器启动 大约需要 10~20 分钟（取决于网络速度）。之后，容器内部启动还需额外 3~5 分钟（Aster TSDB 模式迁移 + JVM warm-up）。
Q. 安装后从哪里 접속？
A. 请通过浏览器访问以下地址：
http://[서버IP]/
- 代理容器仅开放 一个 80 端口。没有单独的管理控制台端口。
[서버IP]是安装时指定的服务器地址。- 默认管理员账户：
admin/admin123! - 登录后请务必修改密码。
Q. 启动后 health 显示为 unhealthy。
A. 启动需要 3~5 分钟。如果 5 分钟后仍为 unhealthy 状态，请参阅 问题解决 - 容器启动问题。
Q. 修改了 env.sh 但没有生效。
A. env.sh 的修改仅在启动时生效。必须执行以下命令重启才能应用。
cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh
Q. 如何设置服务器重启后自动启动？
A. 容器按照 --restart unless-stopped 策略运行，因此只要 Docker 守护进程启动，容器就会自动随之启动。Docker 守护进程本身已设置为通过 systemctl enable docker 在启动时自动启动。
运营 / 管理
Q. 如何启动 / 停止 / 重启平台？
A. 在主机的 /opt/kopens/plantpulse-platform-docker/bin/ 中执行：
./up.sh # 기동 — 준비될 때까지 대기 (종료 코드 0 = 쓸 수 있다)
./down.sh # 중지 (데이터 보존)
./restart.sh # 재시작 (graceful drain + 준비 대기)
./status.sh # 상태 요약 (0 = 정상 / 2 = 비정상)
详细内容请参阅 启动指南 页面。
Q. 可以在不重启整体的情况下，仅重启部分组件吗？
A. 可以。但 根据是应用还是基础设施，方法有所不同。
六个应用分别在各自的容器中运行，因此重新启动该容器即为重启。
cd /opt/kopens/plantpulse-platform-docker
docker compose -f compose/docker-compose.yml restart plantpulse-server-web
存储、分析、消息传递等基础设施组件在 Data Lake 容器内共同运行，因此需要进入容器执行独立脚本。
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd restart storage
exit
详细列表请参阅 启动指南 — 组件级重启。
Q. 在哪里查看日志？
A. 可以在主机查看容器标准日志，也可以在容器内部查看各模块的详细日志。
# 전체 컨테이너 로그를 한 화면에 (서비스 이름 접두, 시간순)
./logs.sh
# 특정 컨테이너만
./logs.sh plantpulse-server-web -n 200
# 데이터레이크 안 컴포넌트 로그 파일
./logs.sh cassandra
# 볼 수 있는 대상 전체 목록
./logs.sh --list
# 모듈별 로그를 호스트로 한 번에 복사
./tools/copy-log-to-local.sh
由于共有 8 个容器，仅查看单个日志很容易遗漏原因。不带参数的 ./logs.sh 会将 8 个容器的日志按时间顺序混合显示。
Q. 如何进行备份？
A. 可以按 Docker 卷单位进行 tar.gz 备份。
cd /opt/kopens/plantpulse-platform-docker/bin
./backup.sh # 기본 세트 (pp-data · pp-security)
./tools/backup-volume.sh pp-data 7 /data1/pp-backup/docker-volume # 볼륨 하나만
建议的备份周期请参阅 运营管理 - 备份与恢复。
Q. 发布新版本后如何更新？
A. 在同一台服务器上再次运行安装 One-liner（无需删除或清理）。新版本的运营脚本 · compose · 镜像将一同导入，数据将保留在卷中。
sudo -i
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash
./update.sh 不是官方流程 — 该方法仅更换镜像，无法识别新版本中新增的服务。备份与确认方法请参阅 升级。
Q. 更新后出现问题如何回滚？
A. One-liner 在升级前会备份 Stack，如果升级失败，将 自动还原至前一版本（包括数据还原至备份时间点 — 升级期间进入的数据将不保留）。修复原因后重新运行同一 One-liner。如果升级成功但随后需要还原，请使用 bin/upgrade-rollback.sh <백업 위치> 回滚 — 升级。
Q. 可以增加工作节点来构建集群吗？
A. 可以。工作节点列表的正本为 compose/workers.roster，增加节点由专用脚本完成。
cd /opt/kopens/plantpulse-platform-docker/bin
bin/worker-add.sh # 빈 id·주소 자동 선택 (링 합류까지 확인합니다)
详细内容请参阅 集群安装 页面。
Q. 如何增加容器内存？
A. 修改 env.sh 的 DOCKER_PP_MEMORY 后，执行以下操作之一。
./restart.sh
每个容器有独立的限制值。Data Lake 为 DOCKER_DATALAKE_MEMORY (默认 96G)，应用则有如 DOCKER_SERVER_MEMORY · DOCKER_BATCH_MEMORY 等按服务划分的变量 → 环境变量参考
通过 docker stats --no-stream 可以确认哪个容器达到了限制。
数据 / 性能
Q. 数据存储在哪里？
A. 存储在主机的 Docker 卷中。
| 卷 | 用途 |
|---|---|
pp-data | 主数据 (Aster TSDB, PostgreSQL, RustFS) |
pp-temp | 临时处理文件 |
pp-backup | 自备份 |
pp-security | 证书 / 密钥 |
pp-template | 模板数据 |
实际主机路径为 /data1/docker-data/volumes/ (可通过 env.sh 的 DOCKER_DATA_DIR 进行更改)。
Q. 删除容器后数据还会保留吗？
A. 是的，./remove.sh 仅删除容器，卷将继续保留。重新安装后可直接使用之前的数据。若要完全删除卷，必须执行 ./tools/remove-all-volumes.sh。
Q. 可以调整数据保留周期吗？
A. 可以通过 Aster TSDB TTL 设定来调整时序数据的保留周期。可在控制台的系统设定或 properties 中进行更改。详细内容请参阅 性能调优 及 属性参考。
Q. 响应速度变慢了，如何诊断？
A. 请按以下顺序巡检。
# 1. 컨테이너 자원 사용량
docker stats --no-stream
# 2. 호스트 부하
top
df -h
# 3. critical 로그 확인
./ops-check.sh
# 4. Cassandra 컴팩션 / 디스크 I/O
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node compactionstats
详细调优请参阅 性能调优 页面。
Q. Aster TSDB 磁盘占用过高。
A. 可以通过以下命令清理。
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node cleanup # 불필요 데이터 정리
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node compact # 수동 컴팩션
长期建议考虑调整保留周期 (TTL) 或扩展磁盘。
安全 / 用户
Q. 默认密码是什么，在哪里修改？
A. 默认管理员账户为 admin / admin123!。登录后请立即在右上角用户图标 > 修改密码菜单中更改。
数据库 / 消息传递等服务账户密码通过 bin/env.sh 的 PP_*_PASSWORD 变量管理，初次安装时保存在 /etc/kopens/plantpulse-platform.env (mode 0600)。
路径确认 — Secret Sidecar 的正本仅为
/etc/kopens/plantpulse-platform.env(权限0600)。在旧版本安装中，/opt/kopens/下可能保留有同名文件，但系统不会读取，安装脚本会将其还原为正本 → 环境变量参考
Q. 如何进行用户 / 权限管理？
A. 可以在控制台的 安全管理 菜单中管理用户、角色 (role) 和权限。详细内容请参阅 用户管理 及 安全设定 页面。
Q. 如何更改 HTTPS 证书？
A. 证书存储在 pp-security 卷中。建议定期更换。详细步骤请参阅 安全设定 页面。
Q. 应该开放哪些端口到外部？
A. 对于用户 / 外部系统访问，建议仅开放 80, 443, 4950。如果设备直接连接，则增加 1883/1884 (MQTT) · 11004/11005 (OPC-UA)。其余端口 (DB, Kafka, 集群, JMX) 请限制仅在私有网络内访问。详细列表请参阅 端口配置信息。
状态检查和管理控制台均可通过 4950 (HTTPS) 和 4949 (明文) 访问。由于 4949 是明文，在不可信网络中请使用 4950。
Q. 在多节点环境下，节点间通信如何保护？
A. JGroups, Aster TSDB, Kafka 等集群内部通信会自动应用 source 限制，仅允许来自 RFC 1918 私有网络 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) 及 Tailscale CGN 频段 (100.64.0.0/10) 的访问。
多语言 / 时区
Q. 可以使用英文 UI 运行吗？
A. 可以。在 env.sh 中执行：
export PP_LANG=en
export PP_TZ=America/New_York # 운영 지역 타임존
修改后执行 ./restart.sh。但由于 Aster TSDB 时序数据以 KST epoch 形式加载，在韩国运营时必须保持 PP_TZ=Asia/Seoul。
Q. PlantPulse 是否支持按用户切换韩文 / 英文 UI？
A. 不支持。平台采用 每个服务器实例单一区域设置 (Locale) 模型。在 JVM 启动时通过环境变量固定，不支持用户级切换。请按 «韩国版 = ko, 全球版 = en» 进行运营。
外部系统集成
Q. 如何与 OPC-UA 服务器连接？
A. 在控制台的 连接管理 菜单中注册 OPC-UA 服务器信息 (URL, 认证, 安全策略)，并映射要采集的标签。详细步骤请参阅 连接管理 页面。
Q. MQTT 设备如何发送数据？
A. 通过主机 IP 的 1883 (PLAINTEXT) 或 18884 (TLS) 端口连接到 MQTT Broker (HiveMQ) 即可。认证信息为 env.sh 的 PP_MQ_USER / PP_MQ_PASSWORD。
Q. 如何通过 API 与外部系统集成？
A. 所有功能均提供 REST API。请参阅 开发者指南 - API 使用手册。
监测 / 报警
Q. 如何将平台状态集成到外部监测系统？
A. 监测系统可以通过 polling 方式获取 Health 端点和 ops-check 结果。
# Healthcheck 엔드포인트 (모니터링용)
curl -kfsS https://[서버IP]:4950/api/health
# 운영 health + critical log (스크립트 호출)
ssh root@[서버IP] /opt/kopens/plantpulse-platform-docker/bin/ops-check.sh
详细内容请参阅 系统监测 页面。
Q. 报警可以通过电子邮件或 SMS 接收吗？
A. 电子邮件通过 SMTP 设定支持。在每个报警设定中的 外部转发通道 中开启 发送邮件 · 发送 SMS (SMS 需配置网关后方可发送)。实际发送记录保留在 报警详情 的报警接收者面板中。即时通讯 (Slack 等) 集成可通过外部 webhook 或 Flow 引擎配置。
支持 / 咨询
Q. 在哪里可以获得帮助？
A. 请优先确认以下资料：
若上述资料仍无法解决问题，请将诊断 tarball 发送至 webmaster@kopens.com 进行咨询。
Q. 需要随附哪些信息？
A. 请参阅 问题解决 - 请求支持时所需信息 章节。./doctor.sh 生成的诊断 tarball 包含了大部分所需信息 (密码等敏感信息已自动掩码)。
Q. 在哪里查看最新文档？
A. 您可以在 https://kopens.gitbook.io/plantpulse-platform/ 随时确认最新文档。