비밀번호 · 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 는 성공했다고 말하는데 스택은 옛 값으로 계속 돌았습니다
(ANTHROPIC_API_KEY · AI_API_KEY 가 그 상태였습니다). 옛 경로를 다시 쓰지 마세요.
앱 로그인 계정은 여기 대상이 아닙니다
두 가지를 섞지 마세요.
| 무엇 | 어디서 바꾸나 | |
|---|---|---|
| 앱 로그인 계정 | 사람이 Studio 에 로그인하는 계정 | 앱 안의 환경설정 → 사용자 관리 |
| 인프라 · API 키 | 번들 PostgreSQL 계정, AI 키 | 이 문서 — 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 입니다.
| 키 | 무엇 | 어떻게 바뀌나 |
|---|---|---|
PG_PASSWORD | 번들 PostgreSQL | 서버 계정이 정본 — ALTER ROLE (psql) |
ANTHROPIC_API_KEY | Anthropic API 키 | 파일 — agent-server 기동 시 로드 |
AI_API_KEY | OpenAI 호환 API 키 | 파일 — agent-server 기동 시 로드 |
키 이름은 환경 변수 이름 그대로입니다. postgres 같은 별명은 없습니다 — 별명을 두면
이름과 변수를 잇는 표를 따로 관리해야 하고, 그 표는 반드시 실제와 어긋나기 때문입니다.
PG_PASSWORD 가 목록에 없다면 정상입니다PG_PASSWORD 는 번들 PostgreSQL 을 띄우는 설치에서만 이 제품 소유입니다
(COMPOSE_PROFILES 에 bundled-pg 가 있을 때). 플랫폼·공용 PG 를 쓰는 설치라면 그
비밀번호는 남의 것이라 목록에서 빠지고, 대신 그 사실을 알려 줍니다.
플랫폼의 PP_* 도 여기 없습니다. 넘기면 오타와 똑같이 거부됩니다.
바꾸기
값을 생략하고 프롬프트로 입력하는 것이 권장 경로입니다. 비밀번호가 ps 출력이나 셸
히스토리에 남지 않습니다. 두 번 입력받아 서로 맞는지 확인합니다.
bin/passwd.sh PG_PASSWORD
값을 인자로 직접 줄 수도 있습니다.
bin/passwd.sh ANTHROPIC_API_KEY=<새값>
여러 개를 한 번에 넘기면 재시작이 1회로 묶입니다. 커미셔닝 때는 이 형태를 쓰세요.
bin/passwd.sh PG_PASSWORD=<새비번> ANTHROPIC_API_KEY=<새값>
무엇이 바뀌는지만 보고 아무것도 건드리지 않으려면 --dry-run 입니다.
bin/passwd.sh --dry-run PG_PASSWORD=<새비번>
실행하면 바꿀 항목과 영향을 먼저 보여 주고 [y/N] 로 확인을 받습니다. 자동화에서
확인을 건너뛰려면 --yes 입니다.
스크립트·cron 처럼 터미널이 없는 환경에서 값을 빼면 프롬프트를 띄울 수 없어 오류로
끝납니다. 이때는 KEY=<값> 형식으로 넘기세요.
실행되면 무슨 일이 일어나나
순서가 정해져 있습니다.
| 순서 | 하는 일 |
|---|---|
| 1 | 서버 계정이 정본인 것부터 — PG_PASSWORD 면 PostgreSQL 안에서 계정을 먼저 바꿉니다 |
| 2 | /etc/kopens/plantpulse-studio.env 를 새 값으로 갱신합니다 (권한 0600 유지) |
| 3 | docker compose up -d --wait — 컨테이너를 다시 만들어 새 값을 태웁니다 |
서버측을 먼저 바꾸고 파일을 맞추는 순서입니다. 반대로 하면 서버는 옛 값인데 파일은 새 값이라 재시작 전까지 접속이 깨진 채로 남습니다.
이 동안 Studio 접속이 끊깁니다. 점검 창에서 수행하세요.
중간에 실패하면
| 어디서 | 상태 | 할 일 |
|---|---|---|
| 1단계 (PostgreSQL 계정 변경) | 파일은 건드리지 않고 중단합니다 | bin/status.sh 로 번들 PG 가 떠 있는지 확인 후 다시 실행 |
| 3단계 (재시작) | 파일은 이미 새 값입니다 | bin/status.sh 로 상태를 확인하고 기동 실패 원인을 처리 |
PG_PASSWORD 를 손으로 고치지 마세요번들 모드에서 파일의 PG_PASSWORD 만 바꾸면 기존 데이터 디렉터리의 계정과 어긋나 스택이
뜨지 않습니다. passwd.sh 가 서버 계정을 먼저 바꾸는 이유가 이것입니다.
확인
bin/passwd.sh --list
현재값 앞 3글자가 바뀌었으면 반영된 것입니다. 기본값이 그대로인지 한눈에 보라고 앞 3글자를 남깁니다.