서비스 운영
AI 스택은 docker compose 하나입니다. 운영 명령은 전부 설치 본체의 bin/ 에 있고,
compose 를 대신 불러 줍니다.
cd /opt/kopens/plantpulse-ai-docker/bin
자주 쓰는 것
| 하려는 일 | 명령 | 비고 |
|---|---|---|
| 띄운다 | ./up.sh | 종료 코드 0 이면 «준비됨» 입니다 |
| 내린다 | ./down.sh | |
| 다시 띄운다 | ./restart.sh | 0 이면 재시작 후 준비됨 |
| 지금 상태를 본다 | ./status.sh | compose 스택 상태 요약 |
| 자세히 진찰한다 | ./health.sh | 서비스별 상세 리포트 |
| 로그를 따라 본다 | ./logs.sh | |
| 이미지를 새로 받아 올린다 | ./update.sh | 받고 나서 재시작까지 |
up.sh · restart.sh 는 컨테이너가 뜬 것이 아니라 쓸 수 있게 된 것을 0 으로
알립니다. 스크립트로 자동화할 때 별도의 대기 루프를 넣지 않아도 됩니다.
무엇이 잘못됐는지 짚을 때
./doctor.sh
🔴 doctor.sh 는 아무것도 바꾸지 않습니다. 읽고 판단만 합니다. 그래서 장애 중에
안심하고 먼저 돌릴 수 있습니다 — 고치는 것은 사람이 결정합니다.
env 파일의 줄 가운데 기동을 막는 것은 «bad» 로, 그대로 두어도 아무것도 바뀌지 않는 옛 이름 · 중복 줄(기동 전 판정의
[warn] — alias · oldname · media-same)은 «old or redundant lines» 로 따로 보여 줍니다. 후자는 장애 원인이
아닙니다. 정리하는 명령은 bin/lint-env.sh 가 찍어 줍니다 → 환경 변수 설정
컨테이너 하나만 다룰 때
스택 전체를 흔들 필요가 없으면 스크립트에 서비스 이름을 줍니다.
cd /opt/kopens/plantpulse-ai-docker/bin
./status.sh # 무엇이 떠 있나
./restart.sh plantpulse-rag-api # 0 이면 재시작 후 준비됨
./logs.sh plantpulse-lightrag
docker compose 를 맨손으로 부르지 마십시오compose 파일은 compose/ 밑에, 설정은 /etc/kopens/plantpulse-ai.env 에 있습니다. 설치 디렉터리에서
docker compose … 를 그냥 치면 파일을 못 찾거나, 찾더라도 다른 설정으로 돕니다 — up 이면 배포한
이미지가 되돌아갈 수 있습니다. 스크립트들은 compose 파일과 설정 파일을 명시해서 부릅니다.
컨테이너 이름과 각자의 역할은 설치 개요 의 표에 있습니다.
컨테이너 안으로 들어가야 하면:
bin/shell.sh plantpulse-rag-api
로그
./logs.sh # 스택 전체를 따라 본다
./logs.sh plantpulse-llm # 서비스 하나
컨테이너 로그는 도커가 회전시킵니다(compose 에 설정돼 있음). 호스트에서 따로 지울 파일이 쌓이지 않습니다.
컨테이너는 비root 로 돕니다
2026.10 부터 compose 의 모든 서비스가 실행 사용자(user:)를 명시하고, root 로 도는 것은 GPU 지표를
읽는 plantpulse-dcgm 하나뿐입니다(GPU 프로파일링 필드를 읽으려면 root 와 SYS_ADMIN 이 필요합니다).
| 무엇 | 실행 사용자 (uid:gid) |
|---|---|
| 우리 이미지 — 입구 프록시 · 코파일럿 · 관리 콘솔 · RAG · 시계열 인사이트 · 문서 이해 · 비전 · 디지털 스레드 등 | 10001:0 |
vLLM(plantpulse-llm · -emb · -rerank, 영상 · 음성을 켠 설치의 plantpulse-asr) · plantpulse-asr-audio | 10001:0 |
| Neo4j 둘 | 7474:7474 |
| Qdrant | 1000:1000 |
| Phoenix | 65532:65532 |
| Docling | 1001:0 |
plantpulse-dcgm | root (예외) |
입구 프록시(plantpulse-proxy)도 비root 가 되면서 컨테이너 안쪽 포트가 8080 · 9443 · 8443 으로
바뀌었습니다. 호스트에서 보이는 80 · 443 · 5960 은 그대로입니다 →
서비스 포트 맵
옛 설치에서 root 로 만들어진 쓰기 볼륨은 비root 프로세스가 쓰지 못합니다. 도커는 이미 있는 볼륨의
소유자를 바꿔 주지 않고, 쓰기 실패는 대개 조용하거나(로그 파일 대신 콘솔에만 남는 식) 즉사입니다(Qdrant 는
root 소유 저장소에서 바로 죽습니다). 그래서 up.sh · restart.sh · update.sh 가 거치는 기동 스크립트가
compose 를 올리기 전에 bin/volumes-nonroot.sh 를 부릅니다.
| 서비스 | 맞추는 자리 | 맞추는 소유자 |
|---|---|---|
plantpulse-copilot-web · plantpulse-timeseries-insight-api | 앱 로그 | 10001:0 |
plantpulse-timeseries-insight-server | 앱 로그 · 설치별 파인튜닝 가중치 | 10001:0 |
plantpulse-lightrag | 색인 저장소 · 입력 원본 | 10001:0 |
vLLM 셋(녹취 plantpulse-asr 는 켜진 설치에서만) | 컴파일 캐시 | 10001:0 |
plantpulse-asr-audio (켜진 설치에서만) | 오디오 라이브러리 볼륨(pi-asr-audio) | 10001:0 |
plantpulse-neo4j · plantpulse-digital-thread-neo4j | 데이터 | 7474:7474 |
plantpulse-qdrant | 벡터 저장소 | 1000:1000 |
plantpulse-phoenix | 데이터 | 65532:65532 |
plantpulse-proxy | 인증서(pp-proxy-certs) | 10001:0 |
plantpulse-registry (프로필을 켰을 때만) | 이미지 저장소 | 10001:0 |
그 서비스의 사용자가 아닌 파일이 하나라도 있을 때만 바꾸므로, 처음 한 번 일하고 그 뒤로는 확인만 하고 지나갑니다. 맞추지 못하면 기동을 멈춥니다(소유권이 틀린 채 뜨면 쓰기가 조용히 실패하므로).
docker compose up 을 맨손으로 부르면 이 단계를 건너뜁니다2026.09 이하에서 올린 호스트는 첫 기동을 반드시 bin/up.sh(또는 update.sh · restart.sh)로 하십시오.
기본으로 뜨지 않는 것 — compose 프로필
| 프로필 | 컨테이너 | 쓰임 |
|---|---|---|
registry | plantpulse-registry · plantpulse-registry-ui | 폐쇄망 허브 노드의 로컬 이미지 저장소 |
media | plantpulse-asr · plantpulse-asr-audio | 영상 · 음성 녹취(음성으로 묻기 포함). 호스트 env 의 PI_MEDIA_ENABLED=true 한 줄로 켭니다 — 운영 스크립트(up.sh · restart.sh · status.sh · logs.sh …)가 그 값을 보고 프로필을 붙입니다 → 영상 · 음성 수집 |
media 는 프로필 이름을 직접 주지 말고 PI_MEDIA_ENABLED 로 켜십시오 — 그 스위치가 rag-api · 문서 이해의 값과 녹취 모델
받기까지 함께 정합니다. 호스트 env 에 COMPOSE_PROFILES 를 적으면 기동 전 판정이 unknown 으로 기동을 세웁니다.
plantpulse-asr-audio 는 오디오 라이브러리를 볼륨에 옮기고 끝나는 일회성 서비스입니다. status.sh 에서
«Exited (0)» 이면 정상이고 정상으로 셉니다. 0 이 아닌 코드로 끝났으면 plantpulse-asr 도 뜨지 않습니다.
백업과 비밀번호
| 하려는 일 | 명령 | 문서 |
|---|---|---|
| 백업을 뜬다 | ./backup.sh (무엇을 받는지는 ./backup.sh --list — 로그 · 캐시와 녹취 오디오 라이브러리 볼륨은 뺍니다) | 데이터베이스 관리 |
| 비밀번호 · 키를 바꾼다 | ./passwd.sh | 비밀번호 · API 키 변경 |
| 설치를 걷어낸다 | ./remove.sh | 되돌릴 수 없습니다 |
데이터베이스는 플랫폼 것을 씁니다
PostgreSQL · Aster TSDB · Redis(Valkey) · RustFS 는 AI 스택이 띄우지 않습니다.
플랫폼 설치본을 공용으로 씁니다(PP_DATALAKE_ADMIN_URL 의 호스트). 이 넷이 죽으면 AI 도 함께 멈추므로,
장애 때는 서비스 포트 맵 으로 어느 쪽 문제인지부터 가르십시오.
2026.10 부터 그 계정 · 비밀번호는 컨테이너가 기동할 때 플랫폼에서 받습니다. 플랫폼이 안 닿으면 받는 쪽 컨테이너가 FATAL 로 멈추고, 플랫폼에서 비밀번호를 바꿨다면 해당 컨테이너를 다시 시작하는 것으로 끝납니다 → 환경 변수 설정