Coolify 배포 환경변수 인벤토리 · 이전 체크리스트
Coolify에 설정된 환경변수를 코드와 대조해, 서버 이전·재설치 때 무엇을 그대로 옮기고 무엇을 바꾸거나 버려야 하는지 남긴다. 변수의 전체 명세(필수·기본값·설명)는 docs/ENVIRONMENT_VARIABLES.md를 기준표로 본다.
- 대조 커밋:
5b6d920(main HEAD) - 기록 시점: 2026-10-11
- 방법: Coolify 환경변수 목록과 코드의
process.env.*/env.*읽기 지점을 1:1 대조.
대조 결과 요약
Coolify에 설정된 20개 중:
| 판정 | 개수 | 의미 |
|---|---|---|
| ✅ 사용 | 17 | 코드가 실제로 읽는다. |
| ⚠️ 사용(레거시 이름) | 2 | 지금은 동작하지만 server/envAliases.ts가 표준 이름으로 복사해 준 것. 그 파일이 제거되면 못 읽는다. |
| ❌ 서버 코드 미사용 | 1 | docker-compose.onprem.yml 볼륨 매핑 전용. 서버는 읽지 않는다. |
| ⛔ 완전 미사용(죽은 변수) | 0 | — |
결론: 당장 깨지는 값은 없다. 다만 레거시 이름 2개는 표준 이름으로 바꾸고, compose 전용 1개는 정리 대상이며, 빠진 값 1개(
PORTAL_CONSOLE_FILESTORE_MAPPING_ID)를 채워야 FileStore 소비 기능이 완결된다.
Coolify 원본 목록 (대조 대상)
DATABASE_URL
DATABASE_DIALECT
PORTAL_JWT_SECRET
DIRECTORY_ADMIN_BOOTSTRAP_TOKEN
DIRECTORY_ENVELOPE_MASTER_KEY
PORTAL_CONSOLE_LIBRARY_PUBLISH_TOKEN
PORTAL_CONSOLE_DOC_LIBRARY_PROVIDER
PORTAL_CONSOLE_DOC_LIBRARY_HOST_PATH
FILE_STORE_ADMIN_TOKEN
FILE_STORE_BASE_URL
FILE_STORE_SERVICE_TOKEN
MODEL_GATEWAY_URL
MODEL_GATEWAY_ADMIN_TOKEN
PORTAL_ALLOW_INSECURE_PLATFORM_URL
PORTAL_EXPLORE_CATALOG_JSON
FILE_STORE_SYNC_TOKEN
PORTAL_CONSOLE_FILESTORE_CONSUMER_ID
MODEL_GATEWAY_SERVICE_TOKEN
PORTAL_CONSOLE_REGISTRATION_TOKEN
PORTAL_CONSOLE_TOKEN_CONSUMERS_JSON변수별 판정
| 변수 | 판정 | 코드가 읽는 위치 | 조치 |
|---|---|---|---|
DATABASE_URL | ✅ 사용 | server/db.ts:6 · server/setupBootstrap.ts:60,245 | 그대로 이전 |
DATABASE_DIALECT | ✅ 사용 | server/db/provider.ts:10 | 그대로 이전 |
PORTAL_JWT_SECRET | ✅ 사용 | server/portalConfig.ts:5 · server/uiDelivery.ts:27 · server/index.ts:100 | 같은 값 유지 필수 |
DIRECTORY_ADMIN_BOOTSTRAP_TOKEN | ⚠️ 레거시 | server/envAliases.ts:23 → PORTAL_CONSOLE_ADMIN_BOOTSTRAP_TOKEN (adminBootstrap.ts:20) | 표준 이름으로 키 이름 변경 |
DIRECTORY_ENVELOPE_MASTER_KEY | ⚠️ 레거시 | server/envAliases.ts:28 → PORTAL_CONSOLE_ENVELOPE_MASTER_KEY (envelopeEncryption.ts:17) | 표준 이름으로 키 이름 변경 (값은 32바이트 Base64 유지) |
PORTAL_CONSOLE_LIBRARY_PUBLISH_TOKEN | ✅ 사용 | server/libraryRoutes.ts:9 | 그대로 이전(CI와 공유) |
PORTAL_CONSOLE_DOC_LIBRARY_PROVIDER | ✅ 사용(선택) | server/docLibrary.ts:29 | 값이 r2면 예외. 파일시스템만 쓰면 비우거나 삭제 |
PORTAL_CONSOLE_DOC_LIBRARY_HOST_PATH | ❌ 서버 미사용 | docker-compose.onprem.yml:32(볼륨 소스) 전용 | compose 배포가 아니면 삭제 가능 |
FILE_STORE_ADMIN_TOKEN | ✅ 사용 | server/fileStore.ts:134 | FileStore의 같은 값과 일치 |
FILE_STORE_BASE_URL | ✅ 사용 | server/fileStoreClient.ts:13 | 주소(환경별로 바뀔 수 있음) |
FILE_STORE_SERVICE_TOKEN | ✅ 사용 | server/fileStoreClient.ts:14 | FileStore의 같은 값과 일치 |
MODEL_GATEWAY_URL | ✅ 사용 | server/modelGateway.ts:10 · modelGatewayInference.ts:11 | 주소(환경별) |
MODEL_GATEWAY_ADMIN_TOKEN | ✅ 사용 | server/modelGateway.ts:11 | 게이트웨이의 같은 값과 일치 |
PORTAL_ALLOW_INSECURE_PLATFORM_URL | ✅ 사용 | server/platformLinks.ts:16 | 내부망 http 배포에서만 true |
PORTAL_EXPLORE_CATALOG_JSON | ✅ 사용 | server/controlPlaneCatalog.ts:38 | 설정값(그대로 이전) |
FILE_STORE_SYNC_TOKEN | ✅ 사용 | server/fileStoreRoutes.ts:27 | FileStore의 같은 값과 일치 |
PORTAL_CONSOLE_FILESTORE_CONSUMER_ID | ✅ 사용 | server/fileStoreClient.ts:15 | FileStore 등록과 일치 |
MODEL_GATEWAY_SERVICE_TOKEN | ✅ 사용 | server/modelGatewayInference.ts:12 | 게이트웨이의 같은 값과 일치 |
PORTAL_CONSOLE_REGISTRATION_TOKEN | ✅ 사용 | server/portalRegistrationRoute.ts:15 | 자기등록 포털과 공유 |
PORTAL_CONSOLE_TOKEN_CONSUMERS_JSON | ✅ 사용 | server/serviceTokenConsumers.ts:46 | 소비자 시크릿과 일치 |
이전(마이그레이션) 체크리스트
1. 값이 반드시 "같아야" 하는 것 — 복사해서 그대로 옮긴다
바꾸면 세션·암호문·연동이 깨진다. 반드시 기존 값을 그대로 복사한다.
| 변수 | 왜 같은 값이어야 하나 |
|---|---|
PORTAL_JWT_SECRET | 소비 포털 앱이 같은 비밀로 세션을 검증한다. 다르면 로그인에 성공해도 포털이 세션을 인정하지 않는다. |
PORTAL_CONSOLE_ENVELOPE_MASTER_KEY (Coolify: DIRECTORY_ENVELOPE_MASTER_KEY) | 이 키로 암호화된 기존 값(감사 로그·자격증명·R2 비밀)을 복호화한다. 다르면 복호화가 실패한다(키 회전은 PORTAL_CONSOLE_ENVELOPE_LEGACY_MASTER_KEYS 사용). |
FILE_STORE_SERVICE_TOKEN · FILE_STORE_ADMIN_TOKEN · FILE_STORE_SYNC_TOKEN | FileStore의 같은 이름 값과 일치해야 인증된다. |
MODEL_GATEWAY_ADMIN_TOKEN · MODEL_GATEWAY_SERVICE_TOKEN | 게이트웨이의 같은 이름 값과 일치해야 한다. |
PORTAL_CONSOLE_REGISTRATION_TOKEN | 자기등록 포털과 공유하는 토큰. |
PORTAL_CONSOLE_TOKEN_CONSUMERS_JSON | 소비자 clientSecret이 소비자 쪽 설정과 같아야 위임 토큰이 발급된다. |
PORTAL_CONSOLE_FILESTORE_CONSUMER_ID | FileStore에 등록된 consumerId와 일치해야 한다. |
2. 환경에 따라 "바뀔 수 있는" 것 — 새 주소/경로로 재설정
| 변수 | 이전 시 확인 |
|---|---|
DATABASE_URL · DATABASE_DIALECT | 새 DB를 쓰면 주소·방언 변경. 기존 DB를 옮기면 데이터도 함께 이전. |
FILE_STORE_BASE_URL · MODEL_GATEWAY_URL | 서비스 주소가 바뀌면 갱신. |
PORTAL_ALLOW_INSECURE_PLATFORM_URL | 내부망 http(예: http://model-gateway:8080)를 쓸 때만 true. 공인 https면 비워둔다. |
PORTAL_CONSOLE_DOC_LIBRARY_PATH | 문서 라이브러리 로컬 경로(기본 <cwd>/var/doc-library). 컨테이너 배포면 볼륨에 연결해야 재기동 후에도 남는다. |
PORTAL_CONSOLE_DOC_LIBRARY_HOST_PATH | compose 볼륨 소스. (서버 코드는 읽지 않음) |
3. 이름을 바꿔야 하는 것 — 레거시 접두 제거
server/envAliases.ts는 "1릴리스 후 제거 예정"이다. 그때 값을 못 읽게 되므로 지금 바꿔 둔다. 서버 기동 로그의 [env-aliases] 이전 이름 환경변수를 새 이름으로 매핑했습니다: … 경고로 레거시 사용 여부를 확인할 수 있다.
| 현재(Coolify) | 바꿀 이름(표준) |
|---|---|
DIRECTORY_ADMIN_BOOTSTRAP_TOKEN | PORTAL_CONSOLE_ADMIN_BOOTSTRAP_TOKEN |
DIRECTORY_ENVELOPE_MASTER_KEY | PORTAL_CONSOLE_ENVELOPE_MASTER_KEY |
4. 서버가 읽지 않는 것 — 정리 대상
| 변수 | 처리 |
|---|---|
PORTAL_CONSOLE_DOC_LIBRARY_HOST_PATH | 서버 코드 미사용. docker-compose.onprem.yml로 배포할 때만 볼륨 소스로 쓰인다. Coolify가 자체 볼륨을 쓰면 삭제 가능. |
PORTAL_CONSOLE_DOC_LIBRARY_PROVIDER | 값이 r2면 오류. 파일시스템을 쓰면 비우거나 삭제. |
5. 목록에 없지만 채워야 하는 것
| 변수 | 필요성 |
|---|---|
PORTAL_CONSOLE_FILESTORE_MAPPING_ID | 필수 점검. server/fileStoreClient.ts:16 — 이 값이 없으면 FileStore 소비자 상태가 configured=false가 되어 프로필 사진 업로드가 동작하지 않는다. FileStore 관리자 화면에서 매핑을 등록해 값을 채운다. |
JWT_SECRET | 선택(폴백). PORTAL_JWT_SECRET가 있으면 없어도 동작한다(server/adminIdentity.ts:65). 설치 마법사가 생성한다. |
PORTAL_CONSOLE_SETUP_TOKEN | DB가 아직 안 붙은 초기 설치 때만 필요. DB가 연결돼 있으면 불필요. |
PORTAL_CONSOLE_ADMIN_API_KEYS_JSON | 선택. 콘솔 로그인(JWT)이 아니라 API 키로 관리자 인증할 때만. |
DB_POOL_MAX | 선택(기본 10, PostgreSQL만). |
PORTAL_CONSOLE_FILESTORE_ORGANIZATION_ID | 선택(기본 00000000-0000-0000-0000-000000000000). |
PORTAL_CONSOLE_FILESTORE_ENABLED | 선택(기본 true). |
이전 후 검증
- 레거시 별칭 경고 확인 — 서버 로그에
[env-aliases]경고가 없어야 한다(있으면 3번의 이름 변경이 덜 된 것). - 포털 세션 — 소비 포털에서 로그인 후 세션이 유지되는지(
PORTAL_JWT_SECRET동일 여부). - 암호문 복호화 — 기존 자격증명/감사 로그의 비밀값이 정상 표시되는지(마스터 키 동일 여부). 키 회전 절차는
docs/envelope-key-rotation.md. - FileStore 소비자 상태 — 콘솔 화면에서 FileStore 연결이
configured인지(누락 이름이 안내된다).CONSUMER_ID+MAPPING_ID쌍이 필요. - 모델 게이트웨이 — 운영 화면(프로바이더·사용량)이 열리고, 번역/AI 호출이 503이 아닌지.
관련 문서
docs/ENVIRONMENT_VARIABLES.md— 전체 환경변수 명세(필수·기본값·설명·사용 위치)docs/deployment-and-reset.md— 배포·리셋 절차docs/envelope-key-rotation.md— 봉투 암호화 키 회전docs/FILE_STORE_DESK.md— FileStore 소비자 등록(consumerId·mappingId)docker-compose.onprem.yml— 온프렘 compose 변수(MYSQL_*·PORTAL_CONSOLE_PORT·PORTAL_CONSOLE_DOC_LIBRARY_HOST_PATH)