환경변수 명세 (Environment Variables)
ProcessCenter(process-center) 서버가 읽는 환경변수를 한 곳에 정리한다. 각 변수의 필수 여부·기본값·설명·코드 사용 위치를 밝혀, 배포 Secret 구성과 진단의 기준으로 삼는다.
읽는 방법
- 표시 —
필수(없으면 기동/기능 실패) ·조건부(해당 기능을 쓸 때만 필요) ·선택(없으면 기본값) ·개발(로컬 전용) ·compose(온프렘 compose 전용). - 기본값 — 코드가 명시한 폴백.
—는 기본값 없음(미설정 시 빈 값/미동작). - 사용 위치 — 값을 실제로 읽는 파일:줄. 여러 모듈이
env = process.env를 주입받아 호출 시점에 읽는 곳도 있다. - 로딩 규칙 — 서버 엔트리가
import "dotenv/config"를 하므로.env를 자동 로드한다(server/_core/index.ts:1). PortalConsole과 달리 별도--env-file없이pnpm dev로 반영된다..env는 gitignore 대상이다. - 프론트엔드 —
client/는 런타임 환경변수를 쓰지 않는다(import.meta.env·VITE_*미사용). 필요한 값은 서버가 API로 내려보낸다.
요약
- 코드에서 읽는 변수는 80여 개(개발·테스트·compose 전용 포함). 아래 9계열로 나눈다.
- Coolify에 설정된 22개는 전부 실제로 읽힌다 — 죽은 변수 0개(대조는 §10).
- 다만 목록에 없는 필수 변수 2개(
FILE_STORE_CONSUMER_ID·FILE_STORE_MAPPING_ID)가 첨부 업로드에 필요하다. - 레거시 접두(
DIRECTORY_*등)는server/envAliases.ts가 새 이름으로 복사한다(§9).
1. 애플리케이션 · 런타임
| 변수 | 필수 | 기본값 | 설명 | 사용 위치 |
|---|---|---|---|---|
NODE_ENV | 선택 | development | production이면 Secure 쿠키·HTTPS 강제·정적 서빙. 그 외는 dev 취급. | server/_core/env.ts:8 · server/_core/index.ts:54 · server/app.ts:109 |
PORT | 선택 | 3000 | HTTP 리슨 포트. | server/_core/index.ts:60 |
APP_ORIGIN | 조건부(권장) | — | 브라우저 공개 origin. 원장 콜백 URL 생성·RAG 수집 origin 폴백·CORS 폴백에 쓰인다. | server/directory-gateway.ts:27 · server/ragPublicationService.ts:111 · server/app.ts:35 |
CORS_ORIGINS | 선택 | APP_ORIGIN | 쉼표 구분 교차 출처 허용 목록. 비우면 APP_ORIGIN으로 대체. | server/app.ts:35 |
DEPLOYMENT_PROFILE | 선택 | CLOUD | CLOUD | ON_PREM. 미설정도 CLOUD. | server/runtimeSettings.ts:40,45 |
HOST_PORT | compose | 3000 | 온프렘 compose 호스트 포트 매핑. | docker-compose.onprem.yml |
2. 데이터베이스
| 변수 | 필수 | 기본값 | 설명 | 사용 위치 |
|---|---|---|---|---|
DATABASE_URL | 조건부 | — | DB 접속 문자열(mysql://·postgresql://). 비면 DB 기능 비활성. | server/db-connection.ts:7 · server/_core/env.ts:6 · drizzle.config*.ts |
DATABASE_DIALECT | 선택 | mysql | 드라이버 선택. | server/db/provider.ts:14 · server/_core/env.ts:11 |
DB_POOL_MAX | 선택 | 10 | 커넥션 풀 최대 연결 수. | server/db/provider.ts:29 |
DB_POOL_IDLE_TIMEOUT_MS | 선택 | 10000 | 유휴 연결 회수 시간. | server/db/provider.ts:31 |
DB_POOL_CONNECT_TIMEOUT_MS | 선택 | 5000 | 연결 타임아웃. | server/db/provider.ts:33 |
DB_POOL_STATEMENT_TIMEOUT_MS | 선택 | 30000 | 문장 타임아웃. | server/db/provider.ts:36 |
DB_POOL_QUERY_TIMEOUT_MS | 선택 | 30000 | 쿼리 타임아웃. | server/db/provider.ts:37 |
RAG_DATABASE_URL | 선택 | DATABASE_URL | RAG 전용 DB(별도 스키마 마이그레이션용). | drizzle.config.rag.ts:5 |
MYSQL_* · POSTGRES_* | compose | MYSQL_*=processcenter | 온프렘 compose DB 자격증명(MYSQL_DATABASE/USER/PASSWORD/ROOT_PASSWORD, POSTGRES_DB/USER/PASSWORD). | docker-compose.onprem.yml |
3. 원장(DirectoryService) 연동 · 인증
PORTAL_CONSOLE_ORIGIN이 있으면 DIRECTORY 모드(중앙 정체성·조직 동기화), 없으면 STANDALONE(포털 자체 데이터)로 동작한다.
| 변수 | 필수 | 기본값 | 설명 | 사용 위치 |
|---|---|---|---|---|
PORTAL_CONSOLE_ORIGIN | 조건부 | — | 원장 주소. 설정 시 DIRECTORY 모드. 운영에서는 HTTPS여야 한다. | server/runtimeSettings.ts:35,49 · server/directory-gateway.ts:14 |
PORTAL_CONSOLE_API_KEY | 조건부 | — | 원장 API 키(조직·사용자 동기화, 용어 링크). DIRECTORY 모드에서 필요. AI 번역의 용어집 우선 적용에는 glossary:read scope 가 필요하다(없으면 403 insufficient_scope — 번역은 용어집 없이 계속되고 미리보기에 경고가 뜬다). | server/directory-gateway.ts:74 · server/runtimeSettings.ts:55,95 |
PORTAL_CONSOLE_PORTAL_ID | 선택 | process-center | 포털 식별자. | server/runtimeSettings.ts:54 · server/directorySyncService.ts:15 |
PORTAL_CONSOLE_CLIENT_ID | 선택 | PORTAL_CONSOLE_PORTAL_ID | OAuth 콜백의 client_id. | server/directory-gateway.ts:16 |
PORTAL_CONSOLE_CALLBACK_PATH | 선택 | /auth/callback | 로그인 콜백 경로. | server/directory-gateway.ts:17 |
PORTAL_JWT_SECRET | 조건부 | PORTAL_CONSOLE_SESSION_SECRET → dev 폴백 | 원장 세션 검증 비밀. 원장(PortalConsole)과 같은 값이어야 세션이 통한다. | server/_core/directory-auth.ts:7 · server/_core/env.ts:3 |
PORTAL_CONSOLE_SESSION_SECRET | 선택 | — | PORTAL_JWT_SECRET 미설정 시 서명 비밀 폴백. | server/_core/directory-auth.ts:7 |
PORTAL_CONSOLE_LOCAL_OPEN_ID | 선택 | local-admin | 로컬(비원장) 사용자 기본 open id. | server/_core/env.ts:7 |
PORTAL_CONSOLE_LOCAL_SECRET | 선택 | — | 로컬 사용자 시크릿 폴백. | server/_core/env.ts:4 |
PORTAL_CONSOLE_PORTAL_API_KEY | 선택(레거시 폴백) | — | PORTAL_CONSOLE_API_KEY의 구 이름 폴백. | server/directorySyncService.ts:13 · server/termLinkSync.ts:279 |
PORTAL_CONSOLE_TENANT_ID | 선택 | — | RAG 테넌트 식별자. | server/rag/ragIdentity.ts:65 |
PROCESS_CENTER_SERVICE_CLIENT_SECRET | 조건부 | — | 원장 위임 토큰 소비자 시크릿. 콘솔 PORTAL_CONSOLE_TOKEN_CONSUMERS_JSON의 process-center.clientSecret과 같은 값. | server/directoryDelegation.ts:40 · server/themePolicyGateway.ts:23 |
PORTAL_CONSOLE_SYNC_INTERVAL_MS | 선택 | 3600000 | 조직·사용자 동기화 주기(최소 15분). | server/directorySyncService.ts:455 |
PORTAL_CONSOLE_SYNC_LEASE_TTL_MS | 선택 | 600000 | 동기화 리스 TTL(최소 60초). | server/directorySyncService.ts:17 |
PORTAL_CONSOLE_SYNC_ALLOW_EMPTY_SNAPSHOT | 선택 | false | true면 빈 스냅샷도 반영. | server/directorySyncService.ts:18 |
PORTAL_CONSOLE_SYNC_FAILURE_ALERT_THRESHOLD | 선택 | 3 | 연속 실패 경보 임계. | server/directorySyncService.ts:19 |
PORTAL_CONSOLE_SYNC_ALERT_WEBHOOK_URL | 선택 | — | 실패 경보 웹훅. | server/directorySyncService.ts:20 |
PORTAL_CONSOLE_SYNC_ALERT_REPEAT_INTERVAL_MS | 선택 | 86400000 | 경보 반복 간격(최소 1시간). | server/directorySyncService.ts:25 |
PORTAL_CONSOLE_SYNC_AUTH_RETRY_INTERVAL_MS | 선택 | 21600000 | 인증 실패 재시도 간격(최소 15분). | server/directorySyncService.ts:30 |
DISABLE_DIRECTORY_SYNC | 선택 | false | true면 동기화 스케줄러 비활성. | server/directorySyncService.ts:450 |
4. 로컬 로그인 (선택)
| 변수 | 필수 | 기본값 | 설명 | 사용 위치 |
|---|---|---|---|---|
LOCAL_AUTH_USERS | 선택 | "" | loginId:비밀번호[:admin|user] 목록. 있으면 아이디/비밀번호 로그인 폼 제공. | server/localAuth.ts:82 |
LOCAL_AUTH_ENABLED | 선택 | true | false면 이 로그인 방식만 끈다. | server/localAuth.ts:126 |
LOCAL_AUTH_SESSION_HOURS | 선택 | 8 | 로컬 세션 유효 시간. | server/localAuth.ts:136 |
LOCAL_AUTH_PASSWORD | 스크립트 | — | 자격증명 해시 생성 스크립트 입력(런타임 아님). | scripts/localAuthCredential.mjs:38 |
5. 파일 · 첨부 (FileStore)
첨부·에디터 이미지·공지 첨부의 저장소는 FileStore가 소유한다(docs/FILESTORE_ATTACHMENT_INTEGRATION.md). ProcessCenter는 FileStore 소비자로 업로드/조회/삭제한다.
| 변수 | 필수 | 기본값 | 설명 | 사용 위치 |
|---|---|---|---|---|
FILE_STORE_ENABLED | 선택 | true | "false"면 FileStore 호출을 끈다. | server/fileStoreClient.ts:9 |
FILE_STORE_BASE_URL | 조건부 | — | FileStore base URL. | server/fileStoreClient.ts:4 |
FILE_STORE_SERVICE_TOKEN | 조건부 | — | 서비스 토큰. FileStore의 FILE_STORE_SERVICE_TOKEN과 같은 값(소비자 공용). | server/fileStoreClient.ts:5 |
FILE_STORE_CONSUMER_ID | 조건부 | — (예: process-center) | 소비자 식별자. 없으면 업로드 실패. | server/fileStoreClient.ts:6 |
FILE_STORE_MAPPING_ID | 조건부 | — (정책 UUID) | FileStore에 등록한 정책 id(UUID). consumerId 문자열이 아니다. 없으면 업로드 실패. | server/fileStoreClient.ts:7 |
FILE_STORE_ORGANIZATION_ID | 선택 | 00000000-0000-0000-0000-000000000000 | 업로드에 실을 조직 식별자. | server/fileStoreClient.ts:8 |
ATTACHMENT_DOWNLOAD_MODE | 선택 | relay | 첨부 다운로드 경로. relay(기본)=ProcessCenter 서버가 FileStore 원본을 받아 same-origin 으로 흘려보낸다. direct=FileStore 서명 URL을 브라우저에 그대로 넘긴다 — FileStore 에 FILE_STORE_ALLOWED_ORIGINS 를 켠 배포에서만 동작한다. | server/attachmentDelivery.ts:12 |
FILE_STORE_ALLOWED_ORIGINS | 선택(기본 꺼짐) | — | FileStore 가 브라우저 직접 다운로드에 허용할 소비 포탈 origin(FILE_STORE_ALLOWED_ORIGINS, FileStore 환경변수). ATTACHMENT_DOWNLOAD_MODE=direct 일 때만 필요하다. | FileStore/src/corsHeaders.ts |
PROFILE_STORAGE_PROVIDER | 선택 | r2 (BUILT_IN_FORGE_API_URL 있으면 managed) | 프로필 저장소 표기. | server/runtimeSettings.ts:57 |
ORPHAN_ASSET_RETRY_INTERVAL_MS | 선택 | 300000 | 고아 자산 정리 재시도 주기(최소 15초). | server/services/orphanAssetRetryQueue.ts:35 |
ORPHAN_ASSET_RETRY_BASE_BACKOFF_MS | 선택 | 30000 | 백오프 기준(최소 1초). | server/services/orphanAssetRetryQueue.ts:36 |
ORPHAN_ASSET_RETRY_MAX_ATTEMPTS | 선택 | 10 | 최대 시도 횟수. | server/services/orphanAssetRetryQueue.ts:37 |
ORPHAN_ASSET_RETRY_BATCH_SIZE | 선택 | 25 | 배치 크기(최대 100). | server/services/orphanAssetRetryQueue.ts:38 |
ORPHAN_ASSET_RETRY_LEASE_MS | 선택 | 300000 | 리스 TTL(최소 30초). | server/services/orphanAssetRetryQueue.ts:39 |
DISABLE_ORPHAN_ASSET_RETRY | 선택 | false | true면 정리 스케줄러 비활성. | server/services/orphanAssetRetryQueue.ts:169 |
6. AI · ModelGateway · 임베딩
MODEL_GATEWAY_URL+MODEL_GATEWAY_SERVICE_TOKEN이 있으면 게이트웨이를 쓰고, 없으면 PRIVATE_LLM_URL로 직접 호출한다.
| 변수 | 필수 | 기본값 | 설명 | 사용 위치 |
|---|---|---|---|---|
MODEL_GATEWAY_URL | 조건부 | — | 게이트웨이 base URL. | server/ai/aiClient.ts:5,90 |
MODEL_GATEWAY_SERVICE_TOKEN | 조건부 | — | 게이트웨이 서비스 토큰. | server/ai/aiClient.ts:5,93 |
MODEL_GATEWAY_MODEL | 선택 | AUTO(PRIVATE_LLM_MODEL 폴백) | 사용 모델. | server/ai/aiClient.ts:73 |
PRIVATE_LLM_URL | 조건부 | — | 게이트웨이 미사용 시 직접 LLM 주소. | server/ai/aiClient.ts:99,103 |
PRIVATE_LLM_MODEL | 선택 | local-model | 직접 LLM 모델명. | server/ai/aiClient.ts:104 |
PRIVATE_LLM_API_KEY | 선택 | — | 직접 LLM 키. | server/ai/aiClient.ts:105 |
PRIVATE_LLM_TIMEOUT_MS | 선택 | 20000 | LLM 호출 타임아웃. | server/ai/aiClient.ts:33 |
RAG_ENABLED | 선택 | false | "true"면 로컬 임베딩(RAG) 기능 활성. | server/_core/env.ts:12 · server/ai/aiClient.ts:28 |
PRIVATE_EMBEDDING_URL | 조건부 | — | 임베딩 서버 주소. | server/_core/env.ts:13 · server/rag/privateAi.ts:18 |
PRIVATE_EMBEDDING_MODEL | 선택 | bge-m3 | 임베딩 모델. | server/_core/env.ts:14 |
PRIVATE_EMBEDDING_DIMENSIONS | 선택 | 1024 | 임베딩 차원. | server/_core/env.ts:16 |
BUILT_IN_FORGE_API_URL | 선택(레거시) | — | 관리형 저장/스토리지 URL(있으면 PROFILE_STORAGE_PROVIDER 기본이 managed). | server/_core/env.ts:9 |
BUILT_IN_FORGE_API_KEY | 선택(레거시) | — | 위 관리형 서비스 키. | server/_core/env.ts:10 |
7. RAG 서비스 발행
문서/첨부를 RagService(RAGCenter)로 발행할 때 쓴다. RAG_SERVICE_ENABLED=true + URL + 위임 토큰이 모두 있어야 동작한다.
| 변수 | 필수 | 기본값 | 설명 | 사용 위치 |
|---|---|---|---|---|
RAG_SERVICE_ENABLED | 선택 | false | "true"일 때만 발행 활성. | server/ragCenterClient.ts:31 · server/ragPublicationService.ts:120 |
RAG_SERVICE_URL | 조건부 | — | RagService 주소. | server/ragCenterClient.ts:35 |
RAG_SERVICE_TOKEN | 조건부 | — | RagService 서비스 토큰. | server/ragPublicationService.ts:95 |
RAG_SERVICE_CONTENT_ORIGIN | 선택 | APP_ORIGIN | 수집 대상 콘텐츠 origin. | server/ragPublicationService.ts:111 |
RAG_SERVICE_SUBJECT | 선택 | system | 발행 주체. | server/ragPublicationService.ts:126 |
RAG_RETENTION_DAYS | 선택 | — | 발행 문서 보존 일수. | server/ragPublicationService.ts:81,321 |
8. 탐색 · 연계
| 변수 | 필수 | 기본값 | 설명 | 사용 위치 |
|---|---|---|---|---|
EXPLORE_GATEWAY_URL | 조건부 | — | 탐색(Explore) 게이트웨이 주소. 위임 설정과 함께 있어야 활성. | server/exploreGatewaySearch.ts:12,29 |
EXPLORE_GATEWAY_AUDIENCE | 선택 | explore-gateway | 위임 토큰 audience. | server/directoryDelegation.ts:21 |
EXPLORE_GATEWAY_API_KEY | 선택 | — | 게이트웨이가 이 포털 검색 API를 호출할 때 쓰는 키. | server/remoteExplore.ts:11 |
EXPLORE_ADAPTER_TIMEOUT_MS | 선택 | 1500 (100~10000) | 탐색 어댑터 타임아웃. | server/explore/registry.ts:23,26 |
PROCESS_NODE_CONSUMERS_JSON | 선택 | AGENT_CENTER_API_KEY 폴백 | 참조정보 계약 v2 소비자 목록([{consumerId,secret,scopes}]). | server/remoteProcessNodesV2.ts:310 |
AGENT_CENTER_API_KEY | 선택(레거시) | — | v2 소비자 자동 승격용 레거시 키. | server/remoteProcessNodesV2.ts:310 |
TERM_LINK_SYNC_INTERVAL_MS | 선택 | 300000 | 용어 링크 동기화 주기(최소 30초). | server/termLinkSync.ts:283 |
DISABLE_TERM_LINK_SYNC | 선택 | false | true면 용어 링크 동기화 비활성. | server/termLinkSync.ts:278 |
THEME_CACHE_TTL_MS | 선택 | 60000 | 공통 테마 정책 캐시 TTL(최소 5초). | server/themePolicyGateway.ts:5 |
UI_PLATFORM_ORIGIN | 선택 | — | UI Platform 주소(공통 UI 연계). | server/themePolicyGateway.ts:10 |
9. 레거시 별칭
server/envAliases.ts가 이전 접두 이름을 표준 이름으로 복사한다(표준 이름에 값이 있으면 그 값을 우선). 각 서비스 엔트리 최상단에서 import되어 다른 모듈보다 먼저 실행된다. 1릴리스 후 제거 예정이다. 표준 접두: PORTAL_CONSOLE_* · FILE_STORE_* · UI_PLATFORM_* · RAG_SERVICE_*.
| 이전 이름(접두) | 표준 이름 | 비고 |
|---|---|---|
DIRECTORY_SERVICE_* · DIRECTORY_* | PORTAL_CONSOLE_* | 원장 연동 값(예: DIRECTORY_SERVICE_ORIGIN → PORTAL_CONSOLE_ORIGIN) |
RAG_CENTER_* · RAGCENTER_* | RAG_SERVICE_* | RagService 값 |
UI_CENTER_* · UICENTER_BASE_URL | UI_PLATFORM_* | UiPlatform 값 |
기동 로그에 [env-aliases] 이전 이름 환경변수를 새 이름으로 매핑했습니다: … 경고가 뜨면 레거시 이름을 쓰고 있다는 신호다(표준 이름으로 교체 권장).
10. Coolify 설정 대조
Coolify에 설정된 22개는 전부 코드에서 읽힌다(죽은 변수 0개). 다만 필수 2개가 빠져 있다.
설정됨 · 사용 중 (22/22)
DATABASE_URL · DATABASE_DIALECT · PORTAL_CONSOLE_API_KEY · PORTAL_CONSOLE_ORIGIN · APP_ORIGIN · PORTAL_CONSOLE_PORTAL_ID · PORTAL_JWT_SECRET · DEPLOYMENT_PROFILE · FILE_STORE_SERVICE_TOKEN · MODEL_GATEWAY_URL · MODEL_GATEWAY_MODEL · PRIVATE_LLM_TIMEOUT_MS · MODEL_GATEWAY_SERVICE_TOKEN · FILE_STORE_BASE_URL · PROCESS_CENTER_SERVICE_CLIENT_SECRET · RAG_SERVICE_ENABLED · RAG_SERVICE_URL · RAG_SERVICE_CONTENT_ORIGIN · RAG_SERVICE_TOKEN · EXPLORE_GATEWAY_URL · EXPLORE_GATEWAY_AUDIENCE · EXPLORE_GATEWAY_API_KEY
목록에 빠진 필수 (첨부 업로드에 필요)
| 변수 | 값 |
|---|---|
FILE_STORE_CONSUMER_ID | process-center |
FILE_STORE_MAPPING_ID | FileStore에 등록한 process-center 정책의 UUID (consumerId가 아님) |
값 정합 (다른 서비스와 일치해야)
PORTAL_JWT_SECRET= PortalConsole과 동일PROCESS_CENTER_SERVICE_CLIENT_SECRET= PortalConsolePORTAL_CONSOLE_TOKEN_CONSUMERS_JSON의process-center.clientSecret과 동일FILE_STORE_SERVICE_TOKEN= FileStore와 동일FILE_STORE_MAPPING_ID= FileStore의process-center정책 UUID
11. 개발 · 테스트 전용
| 변수 | 필수 | 기본값 | 설명 | 사용 위치 |
|---|---|---|---|---|
DEV_AUTO_LOGIN | 개발 | false | "true"면 개발 자동 로그인. 운영(NODE_ENV=production)에서는 무효. | server/devLogin.ts:41,42 |
DEV_AUTO_LOGIN_OPEN_ID | 개발 | — | 자동 로그인 사용자 open id. | server/devLogin.ts:52 |
DEV_AUTO_LOGIN_SESSION_HOURS | 개발 | — | 자동 로그인 세션 시간. | server/devLogin.ts:36 |
WORKFLOW_ROUTE_DEBUG | 개발 | NaN | 워크플로 라우팅 디버그 스위치. | client/src/features/workflow-map/ui/workflowLayout.ts:938 |
NPM_TOKEN | 빌드 | — | 사설 패키지 레지스트리 토큰(빌드 시). | .npmrc / Dockerfile |
폐기:
.env.onprem.example의PORTAL_IDENTITY_MODE는 코드에서 읽지 않는다. 정체성 모드는PORTAL_CONSOLE_ORIGIN존재 여부로 결정된다(server/runtimeSettings.ts:49).
관련 문서
docs/FILESTORE_ATTACHMENT_INTEGRATION.md— 첨부(FileStore) 연동docs/DIRECTORY_AUTHORIZATION_INTEGRATION.md— 원장 인가 연동docs/THEME-AUTH-CONTRACT.md— 공통 UI/테마·인증 계약docs/PROCESS_REFERENCE_CONTRACT.md— 참조정보 계약 v2(소비자)docs/EXPLORE_ADAPTER_CONTRACT.md— 탐색 어댑터docs/RAGCENTER_INTEGRATION_PLAN.md— RagService 발행docs/ONPREM_DEPLOYMENT.md·docs/deployment-platforms.md— 배포.env.example·.env.onprem.example·.env.r2.integration.example— 예시server/envAliases.ts— 레거시 접두 별칭(제거 예정)