常见问题
本页汇总了PlantPulse Platform运维人员的常见问题与解答。如需更详细的处理步骤，请参考问题排查页面。
安装 / 许可证
Q. 应该选择Docker安装还是二进制安装？
A. 在没有特殊原因的情况下，强烈推荐一行式安装（基于Docker）。一条命令可自动完成从OS设置、防火墙到容器启动的全部过程，更新和回滚也很便捷。仅在无法使用Docker的环境下才推荐二进制安装。
Q. 能在隔离网络中安装吗？
A. 可以。在联网节点上用./airgap-bundle.sh生成bundle，然后通过USB或内部文件服务器将其转移到隔离网络中，最后执行./airgap-load.sh即可。详细步骤请参考Docker安装 - 隔离网络(Airgap)安装章节。
Q. 如何获取许可证？
A. 镜像仓库凭证和许可证由KOPENS运维团队颁发。请通过webmaster@kopens.com咨询。
Q. 最小/推荐配置是多少？
A. 单节点基准配置：
| 项目 | 最小 | 推荐 |
|---|---|---|
| CPU | 16 vCPU | 32 vCPU |
| 内存 | 64GB | 200GB |
| 磁盘 | 200GB | 1TB+ (根据数据量) |
| OS | Oracle Linux 8 / RHEL 9 / Ubuntu 22.04 / Amazon Linux 2023 | 同上 |
详细配置请参考系统要求页面。
Q. 支持哪些操作系统？
A. 以下操作系统支持一行式安装：
- Oracle Linux 8.x
- RHEL / Rocky Linux 8.x, 9.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. 以一行式安装为基准，从OS设置、Docker安装、镜像下载到容器启动约需10~20分钟（因网络速度而异）。之后容器内部启动还需额外3~5分钟（Cassandra模式迁移 + JVM预热）。
Q. 安装完成后从哪里访问？
A. 请在浏览器中访问以下地址：
http://[서버IP]:7500
[서버IP]是env.sh中DOCKER_PP_EXTERNAL_IP的值。- 默认管理员账号：
admin/admin123! - 登录后务必立即修改密码。
Q. 启动后健康状态显示为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. 如何启动/停止/重启Platform？
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
存储、分析、消息传递等基础设施组件在数据湖容器内共同运行，需要进入容器后运行单独脚本。
./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
有八个容器，只看一个日志容易漏掉原因。不带参数的./logs.sh会按时间顺序混合显示所有八个容器的日志。
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. 通过无中断更新命令处理。
cd /opt/kopens/plantpulse-platform-docker/bin
./update.sh
自动执行：docker pull → graceful关闭 → 用新镜像重新创建 → 健康状态验证 → 失败时自动回滚。数据单独存储在卷中，是安全的。
Q. 更新后出现问题如何回滚？
A. ./update.sh在健康状态验证失败时自动回滚。自动回滚后仍有问题，或需要手动回滚时，将env.sh中的PP_IMAGE_TAG修改为之前的稳定版本，然后重新执行./update.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
每个容器都有独立的限值。数据湖是DOCKER_DATALAKE_MEMORY（默认80G），应用则有DOCKER_SERVER_MEMORY、DOCKER_BATCH_MEMORY等服务级变量 → 环境变量参考
可以用docker stats --no-stream查看哪个容器达到了限值。
数据 / 性能
Q. 数据存储在哪里？
A. 存储在主机的Docker卷中。
| 卷 | 用途 |
|---|---|
pp-data | 主数据 (Cassandra, PostgreSQL, MinIO) |
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. 可以。通过Cassandra 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. Cassandra磁盘使用量过大。
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（权限0600）。
路径确认 — 密钥sidecar的权威源是
/etc/kopens/plantpulse-platform.env（权限0600）。旧版安装在/opt/kopens/下可能有同名文件，但不会被读取，安装脚本会将其重置为权威源 → 环境变量参考
Q. 如何管理用户/权限？
A. 可在控制台的安全管理菜单中管理用户、角色和权限。详细内容请参考用户管理和安全设置页面。
Q. 如何更换HTTPS证书？
A. 证书存储在pp-security卷中。建议定期更换。详细步骤请参考安全设置页面。
Q. 需要向外暴露哪些端口？
A. 对于用户/外部系统访问，建议仅暴露80、443、7443、4950。如果设备直接连接，则需添加1883/1884(MQTT)和11004/11005(OPC-UA)。其他端口(DB、Kafka、集群、JMX)应限制为仅在专网访问。详细列表请参考端口配置信息。
健康和管理控制台在**4950(HTTPS)和4949(明文)**两个端口都可用。4949是明文，不信任的网络中应使用4950。
Q. 多节点环境中节点间通信如何保护？
A. JGroups、Cassandra、Kafka等集群内部通信会自动应用源限制，仅允许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。但由于Cassandra时序数据采用KST epoch存储，韩国运营时必须保留PP_TZ=Asia/Seoul。
Q. PlantPulse支持用户自选韩文/英文UI吗？
A. 不支持。Platform采用每个服务器实例单一地域设置模式。在JVM启动时通过环境变量固定，不支持用户级别的切换。请按如下方式运营：韩国box = ko，全球box = en。
外部系统集成
Q. 如何与OPC-UA服务器连接？
A. 在控制台的连接管理菜单中注册OPC-UA服务器信息(URL、认证、安全策略)，然后映射需采集的标签。详细步骤请参考连接管理页面。
Q. 如何从MQTT设备发送数据？
A. 连接到主机IP的1883(PLAINTEXT)或18884(TLS)端口的MQTT代理(HiveMQ)即可。认证信息是env.sh中的PP_MQ_USER / PP_MQ_PASSWORD。
Q. 如何通过API与外部系统集成？
A. 所有功能都通过REST API提供。请参考开发者指南 - API使用手册。
监控 / 报警
Q. 如何将Platform状态集成到外部监控系统？
A. 外部监控系统可polling健康端点和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. 能否通过邮件或短信接收报警？
A. 邮件通过SMTP设置支持。可在控制台的报警 > 通知设置中配置。短信/消息(Slack等)集成可通过外部webhook或Flow引擎配置。
支持 / 咨询
Q. 在哪里获得帮助？
A. 请先查看以下资料：
上述资料无法解决问题时，请通过webmaster@kopens.com发送诊断tarball进行咨询。
Q. 应该提供哪些信息？
A. 请参考问题排查 - 支持请求所需信息章节。./doctor.sh生成的诊断tarball包含大部分必需信息(密码等敏感信息会自动脱敏)。
Q. 在哪里查看最新文档？
A. 可在https://kopens.gitbook.io/plantpulse-platform/查看最新文档。