비밀번호 · API 키 변경
PlantPulse AI 는 그래프 스토리지(Neo4j) 계정과 내부 서비스를 잇는 API 키 몇 개를 씁니다.
2026.09 부터 내부 API 키는 설치기가 설치마다 새로 만듭니다(자리표시자일 때만). 2026.10 에는 저장
자격증명 암호화 키 둘(PI_COPILOT_SECRET_KEY · PI_DT_SECRET_KEY)도 첫 설치 때 함께 만들어집니다. Neo4j
비밀번호는 만들어 주지 않으므로 설치할 때 채워야 합니다(자리표시자가 남으면 START=1 기동이 거부됩니다).
그 뒤로는 유출이 의심되거나 사람이 바뀔 때 이 문서대로 바꿉니다.
바꾸는 도구는 bin/passwd.sh 하나입니다. platform · ai · studio 세 제품이 같은 이름,
같은 사용법으로 갖고 있습니다.
/etc/kopens/plantpulse-ai.env 하나다이 제품의 비밀은 /etc/kopens/plantpulse-ai.env 에 있습니다. 설치 디렉터리 안이 아니라
repo 트리 밖이고, 권한은 0600 입니다.
🔴 compose/.env 를 고치지 마십시오. 아무도 읽지 않습니다 — 스택은 바뀌지 않습니다.
passwd.sh 가 쓰는 파일과 스택을 띄우는 스크립트가 읽는 파일은 같은 하나입니다.
그래서 회전한 값이 그대로 반영됩니다.
애플리케이션 계정과는 다른 이야기입니다
두 가지를 섞지 마세요.
| 무엇 | 어디서 바꾸나 | |
|---|---|---|
| 애플리케이션 계정 | 사람이 로그인하는 계정 | 각 앱의 관리자 화면에서 관리합니다 |
| 인프라 · API 키 | DB 계정, 서비스 간 인증 키 | 이 문서 — bin/passwd.sh |
이 문서는 아래쪽, 인프라 크리덴셜만 다룹니다.
무엇을 바꿀 수 있나
먼저 목록부터 봅니다. 아무 인자 없이 실행해도 같습니다.
cd /opt/kopens/plantpulse-ai-docker
bin/passwd.sh --list
키 · 아이디 · 현재값(앞 3글자만) · 대상 · 그 값이 어디에 있는지가 함께 나옵니다.
전체 값을 봐야 하면 --list --show 입니다.
| 키 | 무엇 | 어떻게 바뀌나 |
|---|---|---|
PI_NEO4J_PASSWORD | Neo4j — LightRAG 지식 그래프와 공장 그래프 거울, 두 인스턴스 | 서버 계정이 정본 — 두 인스턴스 모두에서 ALTER USER (cypher-shell) |
PI_RAG_API_KEY | RAG API 키 — copliot-web · lightrag · rag-api 가 함께 씁니다 | 파일 |
PI_VLLM_API_KEY | vLLM API 키 — lightrag · insight-api 가 함께 씁니다 | 파일 |
PI_LLM_API_KEY | LiteLLM 마스터 키 | 파일 |
PI_LITELLM_SALT_KEY | LiteLLM 솔트 키 — 🔴 회전하지 마십시오(아래) | 파일 |
PI_INBOUND_API_KEY | 뒷단 인바운드 키 — rag · insight · parser · vision · 디지털 스레드가 받고(비면 그 다섯이 기동을 거부합니다), 코파일럿 · 관리 콘솔 백엔드가 같은 값으로 부릅니다 | 파일 |
키 이름은 환경 변수 이름 그대로입니다. neo4j 나 rag 같은 별명은 없습니다 — 별명을
두면 이름과 변수를 잇는 표를 따로 관리해야 하고, 그 표는 반드시 실제와 어긋나기 때문입니다.
PI_ 로 시작합니다이름이 한 번 정리됐습니다(2026-08-27). 폴백이 없으므로 옛 이름으로 넘기면
unknown key 로 거부됩니다 — 오타와 똑같이 다룹니다(비슷한 이름이 있으면 제안해 줍니다).
| 옛 이름 | 지금 이름 |
|---|---|
DOCKER_NEO4J_PASSWORD | PI_NEO4J_PASSWORD |
RAG_API_KEY | PI_RAG_API_KEY |
VLLM_API_KEY | PI_VLLM_API_KEY |
LITELLM_MASTER_KEY | PI_LLM_API_KEY |
LITELLM_SALT_KEY | PI_LITELLM_SALT_KEY |
PP_INBOUND_API_KEY | PI_INBOUND_API_KEY |
컨테이너 안에서는 서비스마다 다른 이름(CO_INBOUND_API_KEY · TS_INBOUND_API_KEY …)으로
보이지만, 운영자가 만지는 값은 위의 여섯 개뿐입니다. compose 가 하나를 여러 이름으로
나눠 넣습니다.
비우면 두 겹으로 막힙니다. 기동 전 판정(bin/lint-env.sh)이 PI_INBOUND_API_KEY is empty … 로 스택을 올리지 않고,
뒷단 서비스(rag · insight · parser · vision · 디지털 스레드)도 자기 키가 비면 기동을 거부합니다(예전에는 인증 없이
통과시켰습니다). 인증 없이 띄우는 길은 개발용 스위치 PI_INBOUND_AUTH_DISABLED=true 를 일부러 줄 때뿐이고, 키가 있으면
그 스위치는 무시됩니다 → 환경 변수 설정
다만 CHANGE_ME_… 자리표시자는 빈 값이 아니라 그 검사를 통과하고, 그 문자열은 모든 설치에서 같습니다. 바꿀 때는
반드시 새 값을 넣고(--generate 권장), --list 로 값이 들어갔는지 확인하세요. passwd.sh 는 파일을 고친 뒤 스택
전체를 다시 올리므로, 이 키를 받는 쪽과 부르는 쪽이 한꺼번에 새 값으로 맞춰집니다.
PP_* 는 여기 없습니다PP_PG_PASSWORD · PP_CASSANDRA_PASSWORD · PP_REDIS_PASSWORD 같은 PP_* 는 플랫폼 자격증명이라 이
제품에서 바꿀 수 없습니다(서버측을 바꿀 권한이 없습니다). 목록에도 없고, 넘기면 오타와 똑같이
거부됩니다. 접두사가 주인을 말합니다 — PP_ = 플랫폼, PI_ = AI.
2026.10 부터 컨테이너는 플랫폼 계정 · 비밀번호를 기동할 때 플랫폼에서 받습니다 → 환경 변수
설정. 그래서 플랫폼 쪽 bin/passwd.sh 로 바꾼 뒤에는 AI 의 해당
컨테이너를 다시 시작하면 새 값을 받습니다(bin/restart.sh). 기동 전 DB 프로비저닝 같은 호스트 스크립트도
실행할 때마다 플랫폼에서 받으므로 AI 쪽에서 고칠 줄은 없습니다 — 호스트 env 에는 플랫폼 계정 · 비밀번호 줄이
없습니다. 옛 설치에 PP_PG_* · PP_CASSANDRA_* · PP_REDIS_PASSWORD 줄이 남아 있으면 읽지 않고, 기동 전 판정이
지우라고 알려 줍니다.
호스트 env 에 남는 플랫폼 비밀은 PP_DATALAKE_ADMIN_API_KEY(자격증명을 받을 키)와 PP_API_TOKEN(플랫폼 V5 API)
둘입니다. 플랫폼에서 이 값이 바뀌면 /etc/kopens/plantpulse-ai.env 의 그 줄을 손으로 맞추고 bin/restart.sh 로
다시 만듭니다.
관리 콘솔(PI_ADMIN_USER · PI_ADMIN_PASSWORD)과 LiteLLM 관리 화면(PI_LITELLM_UI_USERNAME ·
PI_LITELLM_UI_PASSWORD)은 passwd.sh 목록에 없습니다. 환경 파일을 고치고 bin/up.sh 로 다시
만듭니다 → 초기 비밀번호 변경
바꾸기
값을 생략하고 프롬프트로 입력하는 것이 권장 경로입니다. 비밀번호가 ps 출력이나 셸
히스토리에 남지 않습니다. 두 번 입력받아 서로 맞는지 확인합니다.
bin/passwd.sh PI_INBOUND_API_KEY
값을 인자로 직접 줄 수도 있습니다.
bin/passwd.sh PI_RAG_API_KEY=<새값>
여러 개를 한 번에 넘기면 재시작이 1회로 묶입니다. 커미셔닝 때는 이 형태를 쓰세요.
bin/passwd.sh PI_VLLM_API_KEY=<새값> PI_LLM_API_KEY=<새값>
값을 도구가 만들게 하기 — --generate
사람이 값을 정할 필요가 없는 키는 도구가 만들게 하는 것이 가장 안전합니다. 아무것도 타이핑하지
않으므로 셸 히스토리 · ps 에 남지 않고, 설치기와 같은 규칙(길이 · 계열 접두사)으로 만듭니다.
bin/passwd.sh --generate PI_INBOUND_API_KEY PI_RAG_API_KEY
만든 값은 앞머리가 어느 계열 키인지 말해 줍니다. 로그나 설정 화면에서 조각만 보여도 무엇인지 알 수 있고, 잘못된 자리에 붙여 넣은 것도 눈에 띕니다. 접두사는 비밀이 아니며, 그 뒤의 무작위 부분 길이는 줄지 않습니다.
| 키 | 접두사 |
|---|---|
PI_INBOUND_API_KEY | ppin_ |
PI_VLLM_API_KEY | ppvl_ |
PI_RAG_API_KEY | pprg_ |
PI_LLM_API_KEY | sk-pplm_ |
PI_ADMIN_SESSION_SECRET | ppss_ (설치기만 만듭니다 — passwd.sh 목록에는 없습니다) |
--generate 가 거부하는 키도 있습니다.
PI_LITELLM_SALT_KEY— 키가 아니라 솔트입니다(아래)PI_NEO4J_PASSWORD등 생성 규칙이 없는 키 — 값을 직접 주거나 프롬프트로 넣습니다PI_ADMIN_PASSWORD·PP_*— 사람이 그 값으로 로그인하거나, 플랫폼이 정한 값과 맞아야 합니다PI_COPILOT_SECRET_KEY·PI_DT_SECRET_KEY— 목록에 없습니다. 무작위 교체는 저장값을 버리는 것과 같습니다(아래 「저장 자격증명 암호화 키」)
무엇이 바뀌는지만 보고 아무것도 건드리지 않으려면 --dry-run 입니다.
bin/passwd.sh --dry-run PI_RAG_API_KEY=<새값>
실행하면 바꿀 항목과 영향을 먼저 보여 주고 [y/N] 로 확인을 받습니다. 자동화에서
확인을 건너뛰려면 --yes 입니다.
스크립트·cron 처럼 터미널이 없는 환경에서 값을 빼면 프롬프트를 띄울 수 없어 오류로
끝납니다. 이때는 KEY=<값> 형식으로 넘기세요.
PI_LITELLM_SALT_KEY 는 회전하면 «조용히» 깨집니다이 값은 관리 콘솔 모델 등록 화면에서 넣은 외부 제공자 API 키를 게이트웨이 DB 에 암호화하는
열쇠입니다. 바꿔도 이미 저장된 것을 다시 암호화해 주지 않습니다 — 컨테이너는 healthy 로 뜨고 모델
목록도 그대로인데 그 모델들의 호출만 실패합니다. passwd.sh 는 이 키를 바꾸려 하면 확인 전에
경고를 띄웁니다. 설치할 때 한 번 정하고, 백업 대상에 넣으십시오.
실행되면 무슨 일이 일어나나
순서가 정해져 있습니다.
| 순서 | 하는 일 |
|---|---|
| 1 | 서버 계정이 정본인 것부터 — PI_NEO4J_PASSWORD 면 Neo4j 두 인스턴스 모두에서 계정을 먼저 바꿉니다. 바꾸기 전에 둘 다 지금 값으로 로그인되는지 확인하고, 한쪽이라도 안 되면 아무것도 바꾸지 않고 멈춥니다 |
| 2 | /etc/kopens/plantpulse-ai.env 를 새 값으로 갱신합니다 (권한 0600 유지) |
| 3 | docker compose up -d --wait — 서비스를 다시 만들어 새 값을 태웁니다(compose 파일과 환경 파일을 명시해 부르므로 어느 디렉터리에서 실행해도 같습니다) |
서버측을 먼저 바꾸고 파일을 맞추는 순서입니다. 반대로 하면 서버는 옛 값인데 파일은 새 값이라 재시작 전까지 인증이 깨진 채로 남습니다.
이 동안 AI 경로가 끊깁니다. 점검 창에서 수행하세요.
중간에 실패하면
| 어디서 | 상태 | 할 일 |
|---|---|---|
| 1단계 (Neo4j 계정 변경) | 파일은 건드리지 않고 중단합니다. 첫 인스턴스는 바뀌고 둘째에서 실패했다면 이미 바뀐 인스턴스 이름을 찍습니다 | bin/status.sh 로 plantpulse-neo4j · plantpulse-digital-thread-neo4j 가 떠 있는지 확인합니다. 한쪽만 바뀌었다면 그쪽을 옛 값으로 되돌린 뒤(ALTER CURRENT USER) 다시 실행합니다 |
| 3단계 (재시작) | 파일은 이미 새 값입니다 | bin/status.sh 로 상태를 확인하고 기동 실패 원인을 처리 |
저장 자격증명 암호화 키 — _PREVIOUS 로 교체합니다
PI_COPILOT_SECRET_KEY(코파일럿) · PI_DT_SECRET_KEY(디지털 스레드 커넥터 등록부)는 화면에서 넣은
자격증명(외부 커넥터 인증 값 · LLM 키 · SMTP 비밀번호 · Slack 웹훅 · Web Push 개인키, 커넥터 자격증명)을
DB 에 봉하는 열쇠입니다. passwd.sh 목록에 없습니다 — 새 값만 넣으면 옛 값으로 봉한 것을 풀 수
없기 때문입니다. 교체는 옛 값을 함께 주어 «다시 봉하게» 하는 절차로 합니다.
| 순서 | 하는 일 |
|---|---|
| 1 | 옛 값을 PI_COPILOT_SECRET_KEY_PREVIOUS 에(쉼표로 여럿 가능), 새 값(openssl rand -base64 32)을 PI_COPILOT_SECRET_KEY 에 둡니다 |
| 2 | bin/restart.sh plantpulse-copilot-web — 기동이 저장값을 새 키로 다시 봉합니다. 로그의 [SECRETS] sealed at rest … 로 개수를 봅니다 |
| 3 | PI_COPILOT_SECRET_KEY_PREVIOUS 를 비우고 한 번 더 다시 만듭니다 |
PI_DT_SECRET_KEY 도 같습니다 — PI_DT_SECRET_KEY_PREVIOUS 에 옛 값을 두고 plantpulse-digital-thread-api
를 다시 만든 뒤 비웁니다.
키가 바뀌었는데 옛 값이 없으면 코파일럿은 Stored secrets cannot be decrypted 로 기동을 거부하고,
봉한 행과 그것을 비우는 SQL 을 로그에 찍습니다 — 조용히 인증 없이 부르지 않습니다. 키를 잃었다면 그
자격증명을 화면에서 다시 넣는 수밖에 없습니다. env 파일 백업에 이 두 값이 들어 있는지 확인하십시오.
확인
bin/passwd.sh --list
현재값 앞 3글자가 바뀌었으면 반영된 것입니다. 기본값이 그대로인지 한눈에 보라고 앞 3글자를 남깁니다.