본문으로 건너뛰기

설정 바꾸는 법

무엇을 바꾸느냐에 따라 고치는 파일과 반영 방법이 다릅니다. 먼저 아래 표에서 자기 경우를 찾으세요.

바꾸려는 것예고치는 곳반영
비밀번호 · API 키PostgreSQL 비밀번호, CEP API 키bin/passwd.sh도구가 재시작까지 합니다
이 박스의 주소 · 정체다른 박스가 붙는 주소, Kafka 광고 주소, NAT 공인 IP/etc/kopens/platform.node.envbin/restart-datalake.sh
모든 노드 공통의 비밀 아닌 값언어 · 타임존, 백업 스케줄 스위치, 콘솔 로그 엔드포인트/etc/kopens/plantpulse-platform.envbin/restart-datalake.sh
컨테이너 자원데이터레이크 메모리 한계/etc/kopens/platform.node.env (DOCKER_DATALAKE_MEMORY)bin/restart-datalake.sh
엔진 설정의 «줄»postgresql.conf 파라미터, Kafka 보존 기간, Cassandra 힙/etc/kopens/conf/<파일>.templatebin/restart-datalake.sh 또는 컨테이너 안 pd config render + pd restart <서비스>
백업 스케줄야간 백업 시각컨테이너 안 pd backup schedule set즉시
공개 포트호스트에 여는 포트compose/docker-compose.ymlbin/restart-datalake.sh — 주의
바꾼 뒤 확인은 항상 같습니다
cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh                                       # 0 = 정상
docker exec plantpulse-datalake pd config diff    # 런타임 파일 = 렌더 결과인가 (0 = 같다)
docker exec plantpulse-datalake pd doctor         # FAIL 0

1. 비밀번호 · API 키​

파일을 열지 마세요. passwd.sh 가 서버 쪽 계정 변경 → 사이드카 갱신 → 설정 재렌더 → 재시작을 한 명령으로 합니다.

cd /opt/kopens/plantpulse-platform-docker
bin/passwd.sh --list                 # 바꿀 수 있는 키
bin/passwd.sh PP_PG_PASSWORD         # 값은 프롬프트로 (권장)

자세한 것은 비밀번호 · API 키 바꾸기에 있습니다.

2. 이 박스의 주소와 정체 — 노드 파일​

/etc/kopens/platform.node.env 는 이 박스에만 참인 값을 적는 파일입니다. 다른 박스로 복사하면 안 됩니다 — 실제로 한 박스의 파일을 복사한 다른 박스가 조용히 잘못된 역할로 재설치된 적이 있습니다.

변수언제 적나비우면
PP_MASTER_IP다른 박스(엣지, AI, 워커)가 이 데이터레이크에 붙어야 할 때 — 이 호스트의 LAN 주소compose 네트워크 안 주소(10.99.0.100) — 같은 박스 안에서만 통합니다
PP_KAFKA_ADVERTISED_HOSTNAT 뒤이거나 제2 인터페이스로 Kafka 에 붙을 때만기동 때 도구가 유도합니다(운영자 값 > PP_MASTER_IP > 호스트 기본 IP). 보통 비워 둡니다
DOCKER_PP_EXTERNAL_IPNAT 환경의 공인 IP. TLS 인증서 SAN 에 들어갑니다비워 둡니다 — 잘못된 IP 를 넣으면 인증서가 한 장도 생성되지 않습니다
PP_NODE_ID박스가 둘 이상일 때, 이 박스의 짧고 고유한 이름컨테이너 호스트 이름에서 파생 — 박스가 둘이면 서로를 밀어냅니다. 두 번째 박스를 붙이기 전에 정하세요
sudo vi /etc/kopens/platform.node.env
#   PP_MASTER_IP=192.168.10.20

cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh        # 데이터레이크만 재생성 + 준비 대기 + 의존 앱 판정
광고 주소가 127.0.0.1 이면 렌더가 거부합니다 (exit 8)

서버가 클라이언트에게 «여기로 다시 붙어라» 하고 주는 주소(Kafka advertised.listeners, Cassandra broadcast_rpc_address, Temporal broadcastAddress)가 루프백이면, 그 서버는 제자리에서는 멀쩡하고 다른 컨테이너는 전부 자기 자신에게 돌아갑니다. 포트 검사는 전부 UP 인데 클라이언트는 하나도 못 붙는 모양입니다. 오류 메시지가 고칠 이름을 말해 줍니다 — 노드 파일의 PP_HOST_IP · PP_MASTER_IP · PP_KAFKA_ADVERTISED_HOST 입니다.

3. 모든 노드 공통의 비밀 아닌 값 — 사이드카​

사이드카 /etc/kopens/plantpulse-platform.env 는 시크릿만을 위한 파일이 아닙니다. 비밀 아닌 공통 값도 VAR=값 한 줄로 적으면 bin/env.sh 가 읽고 compose 로 넘깁니다. 어떤 변수를 쓸 수 있는지는 compose/platform.env.example 에 주석과 함께 전부 있습니다 — 거기서 줄을 골라 옮겨 적습니다.

자주 쓰는 것:

변수기본값뜻
PP_LANGen한국어 운영이면 ko
PP_TZAsia/Seoul시계열이 이 타임존 epoch 로 적재되므로 한국 운영은 유지
PP_BACKUP_SCHEDULE_ENABLEDtruefalse 면 백업 타이머 다섯이 «skipped» 로만 기록하고 끝납니다
PP_DATALAKE_ADMIN_LOGS_ENABLEDtruefalse 면 콘솔의 로그 화면(엔드포인트)만 내려갑니다
PP_KEYSPACE · PP_DB_NAME · PP_TOPIC_PREFIXpp데이터레이크가 «만들고» 앱이 «읽는» 식별자. 설치 뒤에는 바꾸지 마세요
sudo vi /etc/kopens/plantpulse-platform.env
#   PP_LANG=ko

cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh                 # 언어 · 타임존은 앱에도 닿으므로 전체 재시작
사이드카의 머리글 두 줄은 건드리지 마세요

# generated: 와 # last rotation: 은 도구가 관리합니다. 나머지 줄은 VAR=값 이면 됩니다. 옛 export VAR=값 줄도 읽히지만, 다음 갱신 때 새 형식으로 다시 써집니다.

4. 컨테이너 메모리​

데이터레이크 컨테이너의 메모리 한계는 DOCKER_DATALAKE_MEMORY 입니다. 기본 80G, 호스트가 그보다 작으면 RAM 의 90% 로 자동 계산됩니다. 박스마다 다른 값이니 노드 파일에 적습니다.

sudo vi /etc/kopens/platform.node.env
#   DOCKER_DATALAKE_MEMORY=64g

cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh
너무 작게 주면 «Up 인데 죽은» 상태가 됩니다

컨테이너 안 PID 1 은 systemd 라, Java 프로세스만 cgroup 에 OOM-kill 되고 docker ps 는 계속 Up 을 보여 줍니다. 킬 기록은 호스트의 dmesg 에만 남습니다. 2026-09-04 에 64g 한계에서 실제로 일어났고(실측 피크 63.9G) 기본값이 80G 로 올라갔습니다.

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

5. 엔진 설정의 «줄» — 템플릿​

postgresql.conf 에 파라미터를 더하거나 Kafka 의 보존 기간을 바꾸는 것처럼 값이 아니라 줄을 고칠 때는 호스트의 템플릿을 고칩니다. 어느 템플릿이 어느 파일이 되는지는 템플릿 목록에 있습니다.

# 1. 호스트에서 템플릿 편집
sudo vi /etc/kopens/conf/postgresql.conf.template

# 2-a. 데이터레이크 전체 재시작 — 기동 때 자동 렌더
cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh

# 2-b. 또는 서비스 하나만 — 컨테이너 안에서
docker exec plantpulse-datalake pd config diff        # 무엇이 바뀔지 먼저 본다
docker exec plantpulse-datalake pd config render      # 생성물을 실제로 쓴다
docker exec plantpulse-datalake pd restart storage    # 그 서비스만 재기동

# 3. 확인
docker exec plantpulse-datalake pd config diff        # 0 = 런타임이 렌더 결과와 같다

pd config render 만 치고 재기동을 안 하면 «반영됐다» 가 아닙니다. 파일만 바뀐 것입니다. pd restart <서비스> 까지가 한 세트입니다.

이미지가 새 기본값을 실어 올 때 — 3-way 시드​

/etc/kopens/conf 는 호스트 파일이라 이미지가 새 기본값을 실어 와도 저절로 바뀌지 않습니다. 그래서 기동 도구가 배포마다 파일 단위로 셋을 비교합니다 — 이번 이미지의 기본값, 지난 배포의 기본값(/etc/kopens/conf.dist), 호스트 파일.

경우도구가 하는 일
운영자가 안 건드린 파일, 기본값이 바뀜새 기본값으로 교체
운영자가 고친 파일, 기본값도 바뀜운영자 파일 유지 + [WARN] operator edit kept, but THE IMAGE DEFAULT CHANGED + 기본값의 변경 diff 출력
운영자가 고친 파일, 기본값 그대로유지 (조용히)
이미지에 새 템플릿이 생김설치
이미지가 템플릿을 뺌호스트 파일은 남기고 경고

restart.sh · update.sh 의 출력에서 [WARN] operator edit kept 줄을 보면, 내 편집과 새 기본값을 손으로 합쳐야 합니다. 새 기본값 파일 위치를 같은 줄이 알려 줍니다.

내 템플릿이 이미지 기본값과 어디가 다른지는 컨테이너 안에서 봅니다.

docker exec plantpulse-datalake pd config diff --templates
#   same     — 같다
#   differs  — 호스트 사본이 다르다 (렌더는 이쪽을 쓴다)
#   local    — 운영자가 추가한 파일
#   missing  — 이미지엔 있는데 호스트엔 없다

호스트 디렉터리를 통째로 이미지 기본값으로 되돌리려면(백업은 도구가 /etc/kopens/conf.backup/<시각>/ 에 남깁니다):

cd /opt/kopens/plantpulse-platform-docker/bin
TEMPLATE_FORCE_SEED=1 ./restart-datalake.sh
2026-09-03 이전 배치의 /etc/kopens/conf 는 스스로 재시드됩니다

옛 plantpulse-startup 배치(파일 이름에 .template 접미사가 없음)가 남아 있으면 pd 가 렌더할 것이 없습니다. 기동 도구가 그것을 감지해 백업 뒤 이미지에서 다시 시드하고, [WARN] stale template layout 으로 알립니다. 옛 편집은 백업에만 남고 자동으로 옮겨지지 않습니다.

6. 백업 스케줄​

파일을 고치지 않습니다. 컨테이너 안 pd backup schedule set 이 systemd 타이머를 검증하고 씁니다. 관리 콘솔의 백업 화면 «Schedule editor» 가 같은 명령을 부릅니다.

docker exec plantpulse-datalake pd backup schedule                                   # 지금 일정
docker exec plantpulse-datalake pd backup schedule set --job postgres-diff --calendar "*-*-* 02:45:00"
docker exec plantpulse-datalake pd backup schedule set --job purge --enabled false
docker exec plantpulse-datalake pd backup schedule reset --job postgres-diff         # 기본값으로

잡 이름은 다섯 — postgres-diff · postgres-full · cassandra-diff · cassandra-full · purge. 캘린더는 systemd 문법입니다(*-*-* 02:45:00 매일, Sun *-*-* 01:00:00 일요일). 틀린 식은 아무것도 쓰지 않고 거부합니다. 선택은 /data1/pp-data/backup/schedule.json 에 남아 컨테이너를 다시 만들어도 살아남습니다 → 백업 · 복원

7. 공개 포트​

호스트에 여는 포트는 compose/docker-compose.yml 의 plantpulse-datalake 서비스 ports: 가 정합니다. 바꿀 때 두 가지를 보세요.

  • 컨테이너 안에서 listen 하는 포트는 defaults.env(PP_*_PORT)와 템플릿이 정합니다. 발행 포트만 바꾸면 «컨테이너는 6379 에 bind, compose 는 6399 를 발행» 처럼 어긋납니다. 둘을 같이 봐야 합니다.
  • 1883 / 1884(MQTT)는 데이터레이크가 아니라 프록시 컨테이너가 발행합니다. 데이터레이크에 같은 포트를 추가하면 bind 충돌로 기동이 실패합니다.

포트 전체 목록과 방화벽은 포트 및 서비스 관리를 보세요.

반영이 안 될 때 — 순서대로 확인​

확인내용
① 어느 파일이 이기고 있나bin/env.sh --print 의 # source: 열. 노드 파일 > 사이드카 > 셸 > 기본값
② 컨테이너에 닿는 이름인가compose 가 적지 않은 이름은 안 들어갑니다 → 변수 레퍼런스
③ 컨테이너를 다시 만들었나사이드카 · 노드 파일 값은 컨테이너 재생성 때만 들어갑니다. docker restart 로는 안 됩니다 — restart-datalake.sh 를 쓰세요
④ 렌더됐나pd config diff 가 0 인가. 1 이면 pd config render 뒤 재기동
⑤ 비밀번호인가파일 편집으로 바뀌지 않습니다 → passwd.sh
⑥ 템플릿이 옛것인가pd config diff --templates 에 differs · missing → 위 3-way 시드

하지 마세요​

  • 컨테이너 안 PP_HOME/…/conf/* 를 편집하지 마세요. 다음 기동에 사라지고, 사라지기 전까지는 어느 쪽이 진짜인지 아무도 모릅니다.
  • docker restart plantpulse-datalake 로 값 변경을 반영하려 하지 마세요. 환경변수는 컨테이너를 다시 만들 때 정해집니다. restart-datalake.sh 가 그 일을 합니다.
  • FORCE=1 pd start 를 쓰지 마세요. 살아 있는 프로세스 위에 같은 포트로 또 띄웁니다.
  • PP_KEYSPACE · PP_DB_NAME · PP_TOPIC_PREFIX 를 설치 뒤에 바꾸지 마세요. 새 이름의 빈 저장소가 만들어지고 옛 데이터는 옛 이름에 남습니다.

관련 문서​