본문으로 건너뛰기

비밀번호 · API 키 변경

PlantPulse AI 는 그래프 스토리지(Neo4j) 계정과 내부 서비스를 잇는 API 키 몇 개를 씁니다. 초기값은 모든 설치에서 같으므로 커미셔닝 때 한 번 바꾸고 끝냅니다. 그 뒤로는 손댈 일이 없습니다.

바꾸는 도구는 bin/passwd.sh 하나입니다. platform · ai · studio 세 제품이 같은 이름, 같은 사용법으로 갖고 있습니다.

설정 정본은 /etc/kopens/plantpulse-ai.env 하나다

이 제품의 비밀은 /etc/kopens/plantpulse-ai.env 에 있습니다. 설치 디렉터리 안이 아니라 repo 트리 밖이고, 권한은 0600 입니다.

compose/.env 는 옛 경로입니다. 지금은 아무도 읽지 않습니다 — 여기를 고쳐도 스택은 바뀌지 않습니다.

2026-08-16 이전에는 passwd.sh 가 /etc/kopens/plantpulse-ai.env 에 쓰는데 스택을 띄우는 스크립트 10개는 compose/.env 를 읽고 있었습니다. 그래서 회전이 조용히 무효였고, passwd.sh 는 성공했다고 말하는데 서비스는 옛 키로 계속 돌았습니다. 지금은 읽는 곳과 쓰는 곳이 같은 파일 하나입니다. 옛 경로를 다시 쓰지 마세요.

애플리케이션 계정과는 다른 이야기입니다​

두 가지를 섞지 마세요.

무엇어디서 바꾸나
애플리케이션 계정사람이 로그인하는 계정각 앱의 관리자 화면에서 관리합니다
인프라 · API 키DB 계정, 서비스 간 인증 키이 문서 — bin/passwd.sh

이 문서는 아래쪽, 인프라 크리덴셜만 다룹니다.

무엇을 바꿀 수 있나​

먼저 목록부터 봅니다. 아무 인자 없이 실행해도 같습니다.

cd /opt/kopens/plantpulse-ai-docker
bin/passwd.sh --list

키 · 아이디 · 현재값(앞 3글자만) · 대상 · 그 값이 어디에 있는지가 함께 나옵니다. 전체 값을 봐야 하면 --list --show 입니다.

키무엇어떻게 바뀌나
DOCKER_NEO4J_PASSWORDNeo4j (그래프 스토리지)서버 계정이 정본 — ALTER USER (cypher-shell)
RAG_API_KEYRAG API 키 — copliot-web · lightrag · rag-api 가 함께 씁니다파일
VLLM_API_KEYvLLM API 키 — lightrag · insight-api 가 함께 씁니다파일
LITELLM_MASTER_KEYLiteLLM 마스터 키파일
LITELLM_SALT_KEYLiteLLM 솔트 키파일
PP_INBOUND_API_KEY뒷단 인바운드 키 — rag · insight · parser · vision 이 함께 씁니다파일

키 이름은 환경 변수 이름 그대로입니다. neo4j 나 rag 같은 별명은 없습니다 — 별명을 두면 이름과 변수를 잇는 표를 따로 관리해야 하고, 그 표는 반드시 실제와 어긋나기 때문입니다.

PP_INBOUND_API_KEY 를 빈 값으로 두지 마세요

뒷단 네 서비스(rag · insight · parser · vision)는 이 키가 비어 있으면 인증 없이 통과시킵니다. 값을 지우는 것은 잠금을 푸는 것과 같습니다. 바꿀 때는 반드시 새 값을 넣고, --list 로 값이 들어갔는지 확인하세요.

DOCKER_PLATFORM_* 은 여기 없습니다

플랫폼 저장소 자격증명의 사본이라 이 제품에서 바꿀 수 없습니다(서버측을 바꿀 권한이 없습니다). 목록에도 없고, 넘기면 오타와 똑같이 거부됩니다. 플랫폼 쪽 bin/passwd.sh 로 바꾼 뒤 이 제품 값을 맞춰 주세요.

바꾸기​

값을 생략하고 프롬프트로 입력하는 것이 권장 경로입니다. 비밀번호가 ps 출력이나 셸 히스토리에 남지 않습니다. 두 번 입력받아 서로 맞는지 확인합니다.

bin/passwd.sh PP_INBOUND_API_KEY

값을 인자로 직접 줄 수도 있습니다.

bin/passwd.sh RAG_API_KEY=<새값>

여러 개를 한 번에 넘기면 재시작이 1회로 묶입니다. 커미셔닝 때는 이 형태를 쓰세요.

bin/passwd.sh VLLM_API_KEY=<새값> LITELLM_MASTER_KEY=<새값>

무엇이 바뀌는지만 보고 아무것도 건드리지 않으려면 --dry-run 입니다.

bin/passwd.sh --dry-run RAG_API_KEY=<새값>

실행하면 바꿀 항목과 영향을 먼저 보여 주고 [y/N] 로 확인을 받습니다. 자동화에서 확인을 건너뛰려면 --yes 입니다.

비대화형에서는 값을 생략할 수 없습니다

스크립트·cron 처럼 터미널이 없는 환경에서 값을 빼면 프롬프트를 띄울 수 없어 오류로 끝납니다. 이때는 KEY=<값> 형식으로 넘기세요.

실행되면 무슨 일이 일어나나​

순서가 정해져 있습니다.

순서하는 일
1서버 계정이 정본인 것부터 — DOCKER_NEO4J_PASSWORD 면 Neo4j 안에서 계정을 먼저 바꿉니다
2/etc/kopens/plantpulse-ai.env 를 새 값으로 갱신합니다 (권한 0600 유지)
3docker compose up -d --wait — 서비스를 다시 만들어 새 값을 태웁니다

서버측을 먼저 바꾸고 파일을 맞추는 순서입니다. 반대로 하면 서버는 옛 값인데 파일은 새 값이라 재시작 전까지 인증이 깨진 채로 남습니다.

이 동안 AI 경로가 끊깁니다. 점검 창에서 수행하세요.

중간에 실패하면​

어디서상태할 일
1단계 (Neo4j 계정 변경)파일은 건드리지 않고 중단합니다bin/status.sh 로 neo4j 가 떠 있는지 확인 후 다시 실행
3단계 (재시작)파일은 이미 새 값입니다bin/status.sh 로 상태를 확인하고 기동 실패 원인을 처리

확인​

bin/passwd.sh --list

현재값 앞 3글자가 바뀌었으면 반영된 것입니다. 기본값이 그대로인지 한눈에 보라고 앞 3글자를 남깁니다.

관련 문서​