비밀번호 · API 키 변경
Studio 가 쓰는 DB 계정과 AI 키는 초기값이 모든 설치에서 같습니다. 커미셔닝 때 한 번 바꾸고 끝냅니다. 그 뒤로는 손댈 일이 없습니다.
바꾸는 도구는 bin/passwd.sh 하나입니다. platform · ai · studio 세 제품이 같은 이름,
같은 사용법으로 갖고 있습니다.
/etc/kopens/plantpulse-studio.env 하나다이 제품의 비밀은 /etc/kopens/plantpulse-studio.env 에 있습니다. 설치 디렉터리
(/opt/kopens/plantpulse-studio-docker) 안이 아니라 repo 트리 밖이고, 권한은 0600
입니다.
설치 디렉터리 루트의 .env 는 옛 경로입니다. 지금은 아무도 읽지 않습니다 — 여기를
고쳐도 스택은 바뀌지 않습니다.
2026-08-16 이전에는 passwd.sh 가 /etc/kopens/plantpulse-studio.env 에 쓰는데
compose 와 나머지 스크립트는 repo 루트 .env 를 읽고 있었습니다. 그래서 회전이 조용히
무효였고, passwd.sh 는 성공했다고 말하는데 스택은 옛 값으로 계속 돌았습니다
(PS_ANTHROPIC_API_KEY · PI_LLM_API_KEY 가 그 상태였습니다). 옛 경로를 다시 쓰지 마세요.
앱 로그인 계정은 여기 대상이 아닙니다
두 가지를 섞지 마세요.
| 무엇 | 어디서 바꾸나 | |
|---|---|---|
| 앱 로그인 계정 | 사람이 Studio 에 로그인하는 계정 | 앱 안의 환경설정 → 사용자 관리 |
| AI 키 | Anthropic · OpenAI 호환 게이트웨이 키 | 이 문서 — bin/passwd.sh |
.env 로 앱 계정을 바꾸려 하지 마세요 — 죽은 값이 됩니다Studio 서버는 로그인할 때 ①DB → ②환경변수 순으로 봅니다. DB 에 계정이 잡히면 거기서
끝내므로, 그 뒤에 env 의 STUDIO_LOCAL_USERS 를 고쳐 봐야 아무 효과가 없습니다.
앱 계정은 환경설정 → 사용자 관리에서 만들고, 역할을 주고, 비밀번호를 재설정합니다.
자세한 내용은 환경설정(관리자) 의 사용자 관리 절에
있습니다. 출처가 환경변수 인 계정은 화면에서 수정·삭제할 수 없습니다.
부트스트랩 계정(STUDIO_LOCAL_USERS)은 첫 진입용 임시 수단입니다. 운영 계정이 준비되면
비우고 재기동하세요.
무엇을 바꿀 수 있나
먼저 목록부터 봅니다. 아무 인자 없이 실행해도 같습니다.
cd /opt/kopens/plantpulse-studio-docker
bin/passwd.sh --list
키 · 아이디 · 현재값(앞 3글자만) · 대상 · 그 값이 어디에 있는지가 함께 나옵니다.
전체 값을 봐야 하면 --list --show 입니다.
| 키 | 무엇 | 어떻게 바뀌나 |
|---|---|---|
PS_ANTHROPIC_API_KEY | Anthropic API 키 | 파일 — agent-server 기동 시 로드 |
PI_LLM_API_KEY | OpenAI 호환 게이트웨이 키 | 파일 — agent-server 기동 시 로드 |
둘뿐입니다. 키 이름은 .env 의 변수 이름 그대로이고, anthropic 같은 별명은
없습니다 — 별명을 두면 이름과 변수를 잇는 표를 따로 관리해야 하고, 그 표는 반드시 실제와
어긋나기 때문입니다.
🔴 PG_PASSWORD 라는 키는 없습니다. 스튜디오는 외부 PostgreSQL 만 쓰고
(번들 컨테이너는 2026-08-28 에 없앴습니다), 접속 정보는 .env 의 DATABASE_URL 한 줄
안에 들어 있습니다. 그 계정의 정본은 PG 안에 있으므로 DB 쪽에서 먼저 바꾸고
DATABASE_URL 을 맞춘 뒤 bin/restart.sh 입니다.
플랫폼의 PP_* 도 여기 없습니다. 넘기면 오타와 똑같이 거부됩니다.
로그나 소스에서는 ANTHROPIC_API_KEY · AI_API_KEY 로 보입니다. .env 와
passwd.sh 에 쓰는 이름은 위의 둘입니다 →
환경변수 레퍼런스
바꾸기
값을 생략하고 프롬프트로 입력하는 것이 권장 경로입니다. 비밀번호가 ps 출력이나 셸
히스토리에 남지 않습니다. 두 번 입력받아 서로 맞는지 확인합니다.
bin/passwd.sh PI_LLM_API_KEY
값을 인자로 직접 줄 수도 있습니다.
bin/passwd.sh PS_ANTHROPIC_API_KEY=<새값>
여러 개를 한 번에 넘기면 재시작이 1회로 묶입니다. 커미셔닝 때는 이 형태를 쓰세요.
bin/passwd.sh PI_LLM_API_KEY=<새값> PS_ANTHROPIC_API_KEY=<새값>
무엇이 바뀌는지만 보고 아무것도 건드리지 않으려면 --dry-run 입니다.
bin/passwd.sh --dry-run PI_LLM_API_KEY=<새값>
실행하면 바꿀 항목과 영향을 먼저 보여 주고 [y/N] 로 확인을 받습니다. 자동화에서
확인을 건너뛰려면 --yes 입니다.
스크립트·cron 처럼 터미널이 없는 환경에서 값을 빼면 프롬프트를 띄울 수 없어 오류로
끝납니다. 이때는 KEY=<값> 형식으로 넘기세요.
실행되면 무슨 일이 일어나나
순서가 정해져 있습니다.
| 순서 | 하는 일 |
|---|---|
| 1 | /etc/kopens/plantpulse-studio.env 를 새 값으로 갱신합니다 (권한 0600 유지) |
| 2 | docker compose up -d --wait — 컨테이너를 다시 만들어 새 값을 태웁니다 |
두 키 모두 파일이 정본입니다. 바깥 서비스의 계정을 함께 바꿔야 하는 종류가 아니라, 파일을 고치고 다시 태우면 끝입니다.
이 동안 Studio 접속이 끊깁니다. 점검 창에서 수행하세요.
중간에 실패하면
| 어디서 | 상태 | 할 일 |
|---|---|---|
| 2단계 (재시작) | 파일은 이미 새 값입니다 | bin/status.sh 로 상태를 확인하고 기동 실패 원인을 처리 |
PI_LLM_API_KEY 는 비어 있으면 스택이 기동을 거부합니다. 바꿀 때는 반드시 새 값을
넣고 --list 로 들어갔는지 확인하십시오.
확인
bin/passwd.sh --list
현재값 앞 3글자가 바뀌었으면 반영된 것입니다. 기본값이 그대로인지 한눈에 보라고 앞 3글자를 남깁니다.