본문으로 건너뛰기

자주 묻는 질문 (FAQ)

증상이나 질문으로 찾으세요. 답은 짧게 적고, 자세한 절차는 링크로 갑니다.

설정​

사이드카를 고쳤는데 반영이 안 됩니다​

컨테이너 안에는 사이드카 파일이 없습니다. 값은 compose 가 컨테이너를 다시 만들 때 환경변수로 들어갑니다. docker restart 는 같은 환경변수로 다시 켤 뿐입니다.

cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh

그래도 안 되면 ① bin/env.sh --print 로 어느 파일이 이기고 있는지 ② compose 가 그 이름을 데이터레이크에 넘기는지를 봅니다 → 반영이 안 될 때

컨테이너 안에서 설정 파일을 고쳤는데 되돌아갔습니다​

정상입니다. PP_HOME 아래 conf/ 는 전부 생성물이고 pd start 가 매번 템플릿에서 다시 씁니다. 고치는 자리는 호스트의 /etc/kopens/conf/<파일>.template 입니다 → 템플릿 고치기

export PP_PG_PASSWORD=… bin/up.sh 가 조용히 무시됩니다​

사이드카가 이미 그 이름을 들고 있으면 사이드카가 이깁니다. 설치가 끝난 노드에서 값을 바꾸는 방법은 bin/passwd.sh 뿐입니다 → 비밀번호 · API 키 바꾸기

이미지를 올렸는데 새 설정 기본값이 안 들어왔습니다​

/etc/kopens/conf 는 호스트 파일이라 저절로 바뀌지 않습니다. 기동 도구가 배포마다 3-way 로 맞추되, 운영자가 고친 파일은 유지하고 [WARN] operator edit kept, but THE IMAGE DEFAULT CHANGED 로 알립니다. 그 파일은 손으로 합쳐야 합니다.

docker exec plantpulse-datalake pd config diff --templates     # differs / missing 인 파일
TEMPLATE_FORCE_SEED=1 ./restart-datalake.sh                    # 통째로 이미지 기본값으로 (백업은 도구가 남긴다)

다른 박스(엣지 · AI · 워커)가 이 데이터레이크에 못 붙습니다​

노드 파일에 이 호스트의 LAN 주소를 적었는지 보세요. 비워 두면 compose 네트워크 안 주소(10.99.0.100)라 같은 박스 안에서만 통합니다.

sudo vi /etc/kopens/platform.node.env      # PP_MASTER_IP=<이 호스트의 LAN IP>
./restart-datalake.sh

Kafka 만 안 붙으면 광고 주소입니다 → 노드 파일

렌더가 exit 8 로 거부합니다​

광고 주소가 127.0.0.1 입니다. 노드 파일의 PP_HOST_IP · PP_MASTER_IP · PP_KAFKA_ADVERTISED_HOST 에 실제 주소를 주세요. 오류 메시지가 고칠 이름을 말합니다.

렌더가 exit 3 또는 exit 4 로 멈춥니다​

  • exit 3 — 필수 시크릿이 비어 있습니다. 메시지에 이름이 전부 나옵니다. 사이드카에 넣고 재생성.
  • exit 4 — 템플릿의 ${PP_*} 에 값이 없습니다. 메시지에 이름@템플릿:줄 로 나옵니다. 노드 파일에 값을 주거나 템플릿을 고칩니다.

컴포넌트 하나(예: Hive)를 끌 수 있나요​

pd 에는 PD_OPTIONS='{"enable-hive": false}' 스위치가 있지만, 현재 compose 스택은 이 변수를 컨테이너에 넘기지 않습니다. 사이드카나 노드 파일에 적어도 컨테이너에 닿지 않으므로 아무것도 꺼지지 않습니다. 제품 쪽 보완이 필요한 사항으로 보고돼 있습니다. 옛 이름 PP_OPTIONS 는 어디서도 읽히지 않습니다.

언어를 한국어로 바꾸려면​

사이드카에 PP_LANG=ko 를 적고 restart.sh(앱에도 닿는 값이라 전체 재시작). 관리 콘솔은 별개로 주소 끝에 ?lang=ko 를 붙입니다.

비밀번호 · 계정​

비밀번호를 바꿨더니 플랫폼이 안 뜹니다​

서버 쪽 계정과 사이드카 중 한쪽만 바뀐 상태입니다. 어느 값이 유효한지부터 확인하세요.

docker exec plantpulse-datalake bash -c 'PGPASSWORD="<구값>" psql -U plantpulse -h 127.0.0.1 -c "SELECT 1;"'
docker exec plantpulse-datalake bash -c 'PGPASSWORD="<신값>" psql -U plantpulse -h 127.0.0.1 -c "SELECT 1;"'

구 값으로 붙으면 서버 쪽이 안 바뀐 것이고, 신 값으로 붙으면 사이드카만 고치면 됩니다. 앞으로는 passwd.sh 로 → 비밀번호 · API 키 바꾸기

passwd.sh 가 «variable not in the registry» 로 거부합니다​

그 키는 회전 대상이 아닙니다. --list 에 나오는 11개만 됩니다. 나머지는 수동 절차입니다. 오타면 비슷한 키를 제안해 줍니다.

회전이 중간에 실패했습니다​

같은 명령을 그대로 다시 실행하세요. 저널이 어디까지 됐는지 알고 이어서 합니다. 롤백은 없습니다. probe=NEITHER 나 verify 실패 면 사람이 그 컴포넌트에 직접 접속해 상태를 확인해야 합니다.

워커 노드가 있는데 passwd.sh 가 거부합니다​

의도된 동작입니다. 마스터만 회전하면 워커가 옛 값으로 남아 클러스터가 반쪽이 됩니다. 수동 절차로 바꾸고 워커마다 사이드카 갱신 + 재시작을 반복하세요.

관리 콘솔 로그인 화면이 «설정되지 않았습니다» 라고 합니다​

PP_DATALAKE_ADMIN_PASSWORD 가 비어 있습니다. 장애가 아닙니다.

bin/passwd.sh PP_DATALAKE_ADMIN_PASSWORD     # --list 에 이 키가 있으면
# 없으면 (2026-09-05 이전 패키지) 사이드카에 줄을 적고 ./restart-datalake.sh

→ 웹 화면 로그인 계정

데이터 게이트웨이 · CEP 콘솔 로그인이 안 됩니다​

PP_DATA_GATEWAY_WEB_PASSWORD · PP_CEP_WEB_PASSWORD 는 기본값이 없어 비어 있으면 그 콘솔만 닫힙니다. 사이드카에 적고 restart-datalake.sh → 질의 콘솔

Grafana 비밀번호를 바꿨는데 컨테이너를 다시 만들었더니 되돌아갔습니다​

알려진 결함입니다. Grafana 의 데이터 디렉터리가 볼륨이 아니라 이미지 트리 안에 있습니다 → Grafana

SQL 도구 카드가 사라졌습니다​

plantpulse-sql 이 2026-09-07 에 폐기됐습니다. SQL 은 데이터 게이트웨이 콘솔(https://<서버IP>:5501/)에서 실행합니다. 관리 콘솔의 도구 화면에 Data Gateway 카드가 있습니다.

기동 · 상태​

pd status 에 STOPPED 가 하나 있는데 방금 기동했습니다​

기동 창입니다. analytics 의 Kyuubi 가 마지막에 뜨는데 spark-master 부터 54초쯤 걸립니다. 1분 뒤 다시 보세요. 계속이면 pd logs --lines 100 <서비스>.

docker ps 는 Up 인데 서비스가 전부 죽어 있습니다​

메모리 OOM 을 의심하세요. PID 1 이 systemd 라 Java 만 죽고 컨테이너는 살아 있습니다.

dmesg -T | grep -i "memory cgroup"
docker inspect plantpulse-datalake --format '{{.State.OOMKilled}}'

→ 메모리 한계 올리기

pd stop 이 STILL RUNNING(exit 7) 으로 끝났습니다​

바로 pd start 하지 마세요. pd kill --dry-run 으로 남은 것을 보고 pd kill → pd status 로 비었음을 확인 → pd start.

pd start 가 «already running» 으로 거부합니다​

이미 떠 있습니다. 다시 띄우려면 pd stop 부터. FORCE=1 은 살아 있는 프로세스 위에 같은 포트로 또 띄우니 쓰지 마세요.

첫 부팅이 10분 넘게 걸립니다​

첫 부팅은 Cassandra 스키마 생성으로 storage 만 500초까지 걸릴 수 있습니다. 컨테이너 기동 유예가 900초인 이유입니다. bin/logs.sh -f plantpulse-datalake 로 진행을 보세요.

콘솔에 «Another job is already running on this node» 가 뜹니다​

2026-09-04 이전 admin-api 이미지의 증상입니다. pd env 의 IMAGE_BUILT_AT 을 보고 옛것이면 update.sh. 새 이미지에서도 «검사 실행» 버튼은 한 번에 하나만 받으니 잠깐 뒤 다시 누르세요.

pd 를 호스트에서 치면 «command not found» 입니다​

pd 는 컨테이너 안에만 있습니다. docker exec plantpulse-datalake pd … 또는 bin/shell.sh 로 들어가서 치세요.

데이터​

데이터가 안 들어옵니다​

MQTT → Kafka → 소비자 사슬의 어디가 막혔는지 pd flow 로 봅니다.

docker exec plantpulse-datalake pd flow

LAG 가 크면 소비자(서버 · CEP · 배치)가 느리거나 멈춘 것이고, NA 는 «한 번도 읽은 적이 없다» 입니다 — MEMB 가 0 이면 소비자가 안 떠 있는 것, 0 보다 큰데 토픽이 비었으면 정상. 관리 콘솔의 토폴로지 화면이 같은 것을 그림으로 보여 줍니다.

디스크가 찹니다 / 안 줄어듭니다​

docker exec plantpulse-datalake pd storage        # 얼마나 있나 — 볼륨 · WAL · 슬롯 · 스냅샷
docker exec plantpulse-datalake pd retention      # 언제 사라지나 — TTL · 토픽 보존 · 콜드 티어
  • Cassandra snapshots 가 크면 pd node cleanup(스냅샷 삭제 — 파괴적).
  • slot.orphan 이 보이면 제거된 워커의 복제 슬롯이 WAL 을 붙잡고 있습니다 — 호스트 ops-check.sh --reclaim.
  • 멈춘 모듈의 로그면 pd clean.
  • pd retention 의 TTL none 은 «만료 없음» 이 아니라 «테이블 기본값 없음» 입니다. 행마다 TTL 이 찍히는 테이블(ts_data_points)은 멀쩡히 만료됩니다.
  • cold_tier 의 last advance 가 48시간 넘게 안 움직이면 아카이브 잡이 멈춘 것입니다 — 뜨거운 디스크가 안 줄어드는 진짜 원인일 때가 많습니다.

Kafka 가 «advertises 127.0.0.1» 로 DOWN 입니다​

노드 파일의 주소가 비어 있습니다 → 노드 파일. 컨테이너 안 broker.properties · server.properties 는 카프카 배포판의 예제 파일이니 보고 놀라지 마세요 — 브로커가 읽는 것은 kafka.properties 하나입니다.

시계열 데이터가 며칠 만에 사라집니다​

시계열 한 점의 수명은 PP_TSE_DATAPOINT_TTL 입니다(기본 365일). 2026-09-05 이전에는 31일 리터럴이었습니다. 값은 쓰기 시점에 찍히므로 올려도 이미 쓰인 행은 되살아나지 않습니다 → 변수 레퍼런스

백업​

백업이 찍히고 있는지 어떻게 보나요​

docker exec plantpulse-datalake pd backup schedule      # 잡 다섯의 일정 · 마지막 결과
docker exec plantpulse-datalake pd backup list          # 세트 목록

관리 콘솔의 백업 화면이 같은 것을 보여 줍니다 → 백업 · 복원

야간 백업 시각을 바꾸려면​

docker exec plantpulse-datalake pd backup schedule set --job postgres-diff --calendar "*-*-* 02:45:00"

컨테이너를 다시 만들어도 살아남습니다.

cassandra-full 이 계속 fail (exit 120 (medusa)) 입니다​

2026-09-04 이전 이미지는 Medusa 설정을 아무도 쓰지 않아 매일 실패했습니다. 지금은 Cassandra 기동 때 pd 가 다시 씁니다 — pd restart storage 뒤 pd backup run --engine cassandra --type full 로 확인하세요.

로그​

로그는 어디서 보나요​

호스트에서 bin/logs.sh plantpulse-datalake(마지막 200줄, -f 로 추적), 컨테이너 안에서 pd logs [서비스]. 앱 컨테이너 로그는 pd logs 에 없고 logs.sh <서비스> 로 봅니다 → 로그와 헬스

누가 언제 서비스를 내렸는지 알고 싶습니다​

이벤트 저널 plantpulse-datalake-admin-api/logs/pd-events.jsonl, 또는 관리 콘솔의 이벤트 화면. 콘솔에서 실행한 명령은 operator:<이름> 으로 남습니다. 콘솔에서 바꾼 설정은 감사 화면에 남습니다.

더 볼 곳​