비밀 관리

API 키와 토큰은 환경변수 파일에만 둡니다. 설정 파일(settings.json)은 평문이라 파일이 유출되면 키가 그대로 노출되기 때문입니다.

이 원칙은 2026.07 릴리즈부터 적용되며, 기존 설치도 그대로 동작합니다(아래 "기존 설치 이관" 참조).

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

환경변수 파일의 경로는 /etc/kopens/plantpulse-studio.env 입니다. 설치 디렉터리 (/opt/kopens/plantpulse-studio-docker) 안이 아니라 repo 트리 밖이고, 권한은 0600 입니다. platform · ai · studio 세 제품이 같은 규약으로 /etc/kopens/plantpulse-<제품>.env 를 씁니다.

설치 디렉터리 루트의 .env 는 옛 경로입니다. 지금은 아무도 읽지 않으므로 거기를 고쳐도 스택은 바뀌지 않습니다. 옛 파일이 남아 있어도 이행 후에는 대조용일 뿐입니다.

비밀 여섯 — 무엇을, 언제

.env 에 넣는 값입니다. 쓰지 않는 기능의 키는 비워 두면 됩니다.

환경변수	용도	언제 필요한가	없으면
`PP_API_TOKEN`	PlantPulse 플랫폼 서비스 키	실데이터(사이트·설비·태그·알람) 조회 전반	🔴 비면 기동을 거부합니다
`PI_LLM_API_KEY`	OpenAI 호환 게이트웨이 키	사내 AI 게이트웨이를 쓸 때(기본 경로)	🔴 비면 기동을 거부합니다
`PS_ANTHROPIC_API_KEY`	Anthropic 키	AI 프로바이더가 anthropic 일 때	에이전트가 실제로 동작하지 않음(스텁 응답)
`OPENAI_API_KEY`	OpenAI 키	AI 프로바이더가 openai 일 때	〃
`GIT_TOKEN`	원격 Git 접근 토큰(PAT)	앱 소스를 고객사 GitLab/GitHub 로 푸시할 때	Git 푸시 기능만 사용 불가
`APP_REGISTRY_TOKEN`	앱 이미지 레지스트리 토큰	배포된 앱을 도커 이미지로 push 할 때	이미지 push 기능만 사용 불가

컨테이너 안에서 보는 이름과 다릅니다

로그·소스에서는 PLATFORM_API_KEY · AI_API_KEY · ANTHROPIC_API_KEY 로 보이지만, .env 에 적는 이름은 위의 것입니다. 대조표는 환경변수 레퍼런스 의 「두 층의 이름」에 있습니다.

AI 키는 셋 중 하나만

환경설정 → AI 탭에서 고른 프로바이더에 맞는 키 하나면 됩니다. 사내 게이트웨이(OpenAI 호환)를 쓰는 현장이라면 PI_LLM_API_KEY 입니다.

키 넣기

sudo vi /etc/kopens/plantpulse-studio.env

# ── 비밀(키·토큰) — 환경변수 전용 ─────────────────────────
PP_API_TOKEN=...
PI_LLM_API_KEY=...
# PS_ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=
# GIT_TOKEN=
# APP_REGISTRY_TOKEN=

sudo chmod 600 /etc/kopens/plantpulse-studio.env
cd /opt/kopens/plantpulse-studio-docker && bash bin/restart.sh

docker restart 로는 키가 바뀌지 않습니다

docker restart plantpulse-studio-server 는 .env 를 다시 읽지 않습니다. 컨테이너를 만들 때 주입된 예전 환경변수를 그대로 들고 재시작할 뿐입니다. 키를 바꾼 뒤 "왜 그대로지"를 한참 찾게 되는 대표적인 함정입니다.

반드시 컨테이너를 다시 만들어야 합니다.

bash bin/restart.sh
# 또는
docker compose up -d --force-recreate

.env 에 넣었다고 컨테이너에 들어가는 것은 아닙니다

컨테이너에 전달되는 것은 docker-compose.yml 의 environment: 목록에 적힌 변수뿐입니다. 위 6종은 이미 배선돼 있지만, 표에 없는 변수를 새로 추가했다면 compose 에도 함께 추가해야 합니다. (전달 누락으로 AI 가 비활성 상태로 뜬 실제 사례가 있습니다.)

반영 확인

# 서버가 인식한 키 출처 확인 — 부팅 로그
docker logs plantpulse-studio-server 2>&1 | head -40

화면에서는 환경설정 → AI / 플랫폼 탭의 키 입력란에 환경변수 기본값 배지가 붙고, 빈 칸에 「환경변수 값을 쓰는 중 — 입력하면 덮어씁니다」 가 뜨면 정상입니다. 입력란 자체는 잠기지 않습니다 — 환경변수는 기본값이고, 화면에서 덮어쓸 수 있습니다.

우선순위와 기존 설치 이관

순위	출처	비고
1	화면에서 넣은 값(`settings.json`)	값이 있으면 이쪽이 이깁니다
2	환경변수(`/etc/kopens/plantpulse-studio.env`)	설치가 심어 주는 기본값

2026-08-23 에 이 순서가 «뒤집혔습니다»

그전에는 환경변수가 이겼습니다. 그랬더니 env 에 죽은 키가 하나 박히면 환경설정 화면에서 무엇을 입력해도 무시되는 상태가 됐고, 화면으로는 고칠 방법이 아예 없었습니다. AI 프로바이더를 언제든 갈아끼울 수 있어야 한다는 요구가 이 순서를 강제했습니다.

그래서 키가 죽었을 때 서버에 들어갈 필요가 없습니다 — 환경설정 화면에 새 값을 넣으면 즉시 덮입니다. 옛 순서를 기억하고 계셨다면 여기서 바꾸십시오.

대가는 settings.json 이 평문이라는 것입니다(서버가 0600 을 강제하고 백업 아카이브도 600/700). 비밀을 파일에 두고 싶지 않다면 화면을 비워 두고 환경변수만 쓰십시오 — 그러면 종전과 똑같이 동작합니다.

업그레이드해도 기존 설치가 갑자기 깨지지 않습니다. 다만 파일에 비밀이 남아 있으면 부팅 로그가 옮길 대상을 알려 줍니다(값은 로그에 절대 남지 않고, 어떤 항목을 어느 환경변수로 옮기면 되는지만 표시됩니다).

settings.json 에 비밀이 남아 있습니다 — … platform.apiKey → PLATFORM_API_KEY

이관 절차는 세 단계입니다.

해당 값을 /etc/kopens/plantpulse-studio.env 의 대응 환경변수로 옮긴다
bash bin/restart.sh
환경설정 화면에서 그 항목의 배지가 환경변수 기본값 으로 바뀐 것을 확인한 뒤, settings.json 에서 옛 값을 지운다 → 부팅 경고가 사라진다

settings.json 위치

<DATA_ROOT>/state/settings.json (기본 /var/lib/pp-studio/state/settings.json). 편집 전 백업을 권장하며, 편집 후에는 재기동이 필요합니다.

키 교체(로테이션)

Anthropic 키와 게이트웨이 키는 전용 도구가 있습니다. 파일 갱신과 컨테이너 재생성을 한 번에 하고, 값이 셸 히스토리에 남지 않습니다.

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh                    # ① 되돌릴 지점 확보
bin/passwd.sh PS_ANTHROPIC_API_KEY    # ② 값 생략 → 프롬프트로 입력
bash bin/status.sh                    # ③ 헬스 확인

자세한 사용법은 비밀번호 · API 키 변경 에 있습니다.

나머지 키(PP_API_TOKEN · OPENAI_API_KEY · GIT_TOKEN · APP_REGISTRY_TOKEN)는 도구 대상이 아니라 파일을 직접 고칩니다.

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh                              # ① 되돌릴 지점 확보
sudo vi /etc/kopens/plantpulse-studio.env       # ② 새 키로 교체
bash bin/restart.sh                             # ③ 컨테이너 재생성
bash bin/status.sh                              # ④ 헬스 확인

교체 후에는 채팅 질의 한 번(플랫폼 키 확인), 앱 빌드 한 번(AI 키 확인)으로 실동작을 점검하는 것이 확실합니다.

자동으로 적용되는 보호

항목	동작
파일 권한	서버가 부팅할 때마다 `settings.json` · 환경변수 파일을 `0600`, 상태 디렉터리를 `0700` 으로 강제
감사 로그	환경설정 변경 시 바뀐 필드가 기록됨 — 비밀은 값 대신 지문(해시 앞 8자)만
화면	환경변수로 관리되는 키는 입력이 비활성화되어 실수로 덮어쓸 수 없음
키 대행	플랫폼 키는 서버 안에만 있고, 로그인한 사용자의 요청에만 대신 붙습니다(익명 요청에는 붙지 않음)

예외 — MCP 외부 서버 토큰

환경설정 → MCP 탭에서 사용자가 임의 개수로 추가하는 외부 MCP 서버의 토큰은 개수가 가변이라 환경변수로 표현할 수 없어 settings.json 에 저장됩니다. (플랫폼·AI 키보다 민감도가 낮은 값입니다.)

지켜야 할 것

하지 말아야 할 것

환경변수 파일 · settings.json 을 형상관리(Git)에 커밋하지 마세요. 정본을 repo 트리 밖(/etc/kopens/)에 둔 이유가 이것입니다.
키를 채팅·이메일·티켓 본문에 붙여 넣지 마세요.
백업 아카이브를 권한 없이 공유하지 마세요 — 백업과 복구의 취급 주의 참조.

노출된 것 같으면

발급처(플랫폼 · AI 프로바이더 · Git · 레지스트리)에서 먼저 폐기하고 새 키를 발급한 뒤, 위 "키 교체" 절차를 수행하세요. 서버 재기동 전까지는 옛 키가 메모리에 남아 있습니다.

비밀 여섯 — 무엇을, 언제​

키 넣기​

반영 확인​

우선순위와 기존 설치 이관​

키 교체(로테이션)​

자동으로 적용되는 보호​

예외 — MCP 외부 서버 토큰​

지켜야 할 것​

관련 문서​