본문으로 건너뛰기

비밀 관리

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 는 옛 경로입니다. 지금은 아무도 읽지 않으므로 거기를 고쳐도 스택은 바뀌지 않습니다. 옛 파일이 남아 있어도 이행 후에는 대조용일 뿐입니다.

비밀 6종 — 무엇을, 언제​

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

환경변수용도언제 필요한가없으면
PLATFORM_API_KEYPlantPulse 플랫폼 서비스 키실데이터(사이트·설비·태그·알람) 조회 전반채팅 질의·배포앱에서 실데이터가 조회되지 않음
ANTHROPIC_API_KEYAnthropic 키AI 프로바이더가 anthropic 일 때에이전트가 실제로 동작하지 않음(스텁 응답)
OPENAI_API_KEYOpenAI 키AI 프로바이더가 openai 일 때〃
AI_API_KEYOpenAI 호환 게이트웨이 키사내 AI 게이트웨이를 쓸 때〃
GIT_TOKEN원격 Git 접근 토큰(PAT)앱 소스를 고객사 GitLab/GitHub 로 푸시할 때Git 푸시 기능만 사용 불가
APP_REGISTRY_TOKEN앱 이미지 레지스트리 토큰배포된 앱을 도커 이미지로 push 할 때이미지 push 기능만 사용 불가
AI 키는 셋 중 하나만

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

키 넣기​

sudo vi /etc/kopens/plantpulse-studio.env
# ── 비밀(키·토큰) — 환경변수 전용 ─────────────────────────
PLATFORM_API_KEY=...
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=
# AI_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 pp-studio-server 는 .env 를 다시 읽지 않습니다. 컨테이너를 만들 때 주입된 예전 환경변수를 그대로 들고 재시작할 뿐입니다. 키를 바꾼 뒤 "왜 그대로지"를 한참 찾게 되는 대표적인 함정입니다.

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

bash bin/restart.sh
# 또는
docker compose up -d --force-recreate
.env 에 넣었다고 컨테이너에 들어가는 것은 아닙니다

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

반영 확인​

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

화면에서는 환경설정 → AI / 플랫폼 탭의 키 입력란이 비활성화되고 "환경변수로 관리 중" 으로 표시되면 정상입니다.

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

순위출처비고
1환경변수(/etc/kopens/plantpulse-studio.env)값이 있으면 이쪽이 무조건 이깁니다
2settings.json레거시 폴백 — 예전 설치 호환용

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

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

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

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

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

키 교체(로테이션)​

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

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

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

나머지 키(PLATFORM_API_KEY · 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 · 레지스트리)에서 먼저 폐기하고 새 키를 발급한 뒤, 위 "키 교체" 절차를 수행하세요. 서버 재기동 전까지는 옛 키가 메모리에 남아 있습니다.

관련 문서​