환경변수

이 문서는 비공개 호스트 환경에 이미 접근 권한이 있는 Nexia 유지관리자를 위한 참고 자료입니다. Core는 외부 개발자에게 배포하지 않습니다. 아래 호스트 명령은 공개 CLI·클라우드 샌드박스의 선행 조건이 아닙니다. 외부 개발자는 빠른 시작을 따라주세요.

설정할 기능과 값을 받는 서비스를 먼저 찾으세요. 일반 App 개발은 App 개발 환경 준비에서 시작하고, 선택 서비스는 해당 가이드에 따라 활성화합니다. 이 목록은 Core와 실행 서비스의 환경변수를 다룹니다. App의 업무 설정은 설정의 소유권에서 구분합니다.

설정 찾기

로컬 runtime과 PHP
DB·파일·메일·실시간
Worktree port와 테스트
신원·테넌시·Signature
Search·analytics
Agent Edge·Gateway
Tracing·선택 서비스
호환 이름·내부 값

세 파일은 이 계약을 서로 다른 관점에서 게시하며 서로 바꾸어 쓸 수 없습니다.

파일	소유 권한	사용 방법
`.env.example`	Local Docker Compose	`task setup`이 ignored `.env`로 복사하고 Compose가 선택한 값을 각 service에 주입
`.env.testing.example`	자동화 PHP 테스트	Test bootstrap이 안전 fixture로 읽음. Worktree마다 고유한 database와 tenant prefix 사용
`deploy/production/.env.example`	Production owner 카탈로그	Section에 명시된 owner에만 각 값을 등록하며 어떤 process도 이 파일 전체를 읽지 않음

Production 카탈로그에 Laravel Cloud가 관리하는 framework 값도 포함하는 이유는 scripts/validate-prod-env.sh가 파일을 검증하기 때문입니다. 관리로 표시된 값은 수동 등록하지 마세요. 빈값은 production credential을 비우라는 뜻이 아니라 해당 capability를 켤 때 secret 또는 endpoint를 제공하라는 뜻입니다.

이 페이지는 Nexia가 지원하는 운영자 계약 전체를 다룹니다. 세 카탈로그의 모든 assignment, 의도적으로 제외한 source-level override, 운영 설정으로 오해하기 쉬운 호환 이름과 container 내부 이름을 모두 포함합니다. Laravel과 설치 package가 추가 upstream env() hook을 제공하더라도 이 페이지에 없으면 Nexia가 지원하는 배포 입력이 아닙니다.

최소 예시

빠른 시작을 마쳤다면 비밀값을 출력하지 않고 현재 환경·데이터베이스·검색 엔진 선택을 확인할 수 있습니다.

코드 예시

Shell

rg '^(APP_ENV|DB_DATABASE|SCOUT_DRIVER)=' .env1

첫 실행은 .env와 .env.testing을 만들고 core profile을 시작한 뒤 database를 migrate·seed합니다. Agent profile은 선택 사항이므로 AGENT_SERVICE_TOKEN은 빈값으로 둡니다. 해당 runtime은 Agent Gateway 켜기에 따라 별도로 활성화하세요. 격리된 분석 설정은 Agent 요청 실행 방식에서 확인하세요.

여러 worktree가 테스트를 실행할 때는 각 worktree의 .env.testing에서 두 격리 값을 모두 바꿉니다.

DB_DATABASE=nexia_test_agent_sse
TEST_TENANCY_DB_PREFIX=test_nexia_agent_sse_12

파라미터

범위와 표기

아래 표는 Local·Test·Production 카탈로그의 assignment를 용도별로 묶었습니다. 빈값은 파일에 key가 있고 값이 없다는 뜻이며, —는 해당 파일에 assignment가 없다는 뜻입니다. 등급은 값을 받는 runtime별로 판정합니다. 필수는 해당 runtime에 반드시 있어야 하고, 조건부는 명시된 capability를 켤 때만 필요하며, 선택은 표시된 기본값이나 비활성 상태를 유지합니다. 관리는 platform 또는 tracked configuration이 제공합니다.

Framework와 process runtime

변수	수신자	등급	비밀	Local	Test	Production	효과
`APP_NAME`	Laravel	필수	아니요	`Nexia`	`Nexia`	`Nexia-Cloud-OS`	Application 표시 이름과 기본 mail 발신자 이름
`APP_ENV`	Laravel	관리	아니요	`local`	`testing`	`production`	환경별 안전 동작 선택
`APP_KEY`	Laravel	필수, production에서 관리	예	빈값	빈값	`base64:CHANGE_ME`	Laravel application 암호화와 암호화된 framework payload의 root key
`APP_DEBUG`	Laravel	관리	아니요	`true`	`true`	`false`	예외 상세 정보 제어. Production은 반드시 false 유지
`APP_URL`	Laravel	관리	아니요	`http://localhost`	`http://localhost`	`https://nexia.to`	Canonical application URL과 Agent JWT issuer
`APP_LOCALE`	Laravel	선택	아니요	`en`	`ko`	`en`	기본 locale
`APP_FALLBACK_LOCALE`	Laravel	선택	아니요	`en`	`en`	`en`	번역 fallback locale
`APP_FAKER_LOCALE`	Laravel	선택	아니요	`ko_KR`	`ko_KR`	`ko_KR`	Seeder와 factory locale
`APP_MAINTENANCE_DRIVER`	Laravel	선택	아니요	`file`	`file`	`file`	Maintenance mode storage
`BCRYPT_ROUNDS`	Laravel	선택	아니요	`12`	`4`	`12`	Password hash work factor
`LOG_CHANNEL`	Laravel	선택	아니요	`stack`	`null`	`stack`	기본 log channel
`LOG_STACK`	Laravel	선택	아니요	`single`	—	`single`	Stack logger에 포함할 channel
`LOG_DEPRECATIONS_CHANNEL`	Laravel	선택	아니요	`null`	—	`null`	Deprecation log 대상
`LOG_LEVEL`	Laravel	선택	아니요	`debug`	`debug`	`info`	Laravel 최소 log severity. Gateway는 `AGENT_GATEWAY_LOG_LEVEL` 사용
`OCTANE_SERVER`	Laravel	선택	아니요	`frankenphp`	—	—	Octane server 구현
`OCTANE_WORKERS`	Compose	선택	아니요	`1`	—	—	Local Octane worker 수
`OCTANE_MAX_REQUESTS`	Compose	선택	아니요	`500`	—	—	Local worker recycle 전 처리할 요청 수
`OCTANE_MAX_EXECUTION_TIME`	Laravel	선택	아니요	`600`	—	—	Octane task 최대 실행 시간(초)

Data·session·storage·delivery

변수	수신자	등급	비밀	Local	Test	Production	효과
`DB_CONNECTION`	Laravel	관리	아니요	`pgsql`	`pgsql`	관리	Database driver
`DB_HOST`	Laravel	관리	아니요	`postgres`	`postgres`	관리	Database host
`DB_PORT`	Laravel	관리	아니요	`5432`	`5432`	관리	Database port
`DB_DATABASE`	Laravel	관리	아니요	`nexia`	`nexia_test`	관리	Central database 이름
`DB_USERNAME`	Laravel	관리	아니요	`postgres`	`postgres`	관리	Database login 이름
`DB_PASSWORD`	Laravel, Langfuse Compose	필수, 연결된 production DB가 관리	예	`secret`	`secret`	빈값	Database credential. Self-hosted Langfuse도 여기서 DSN을 파생
`TEST_TENANCY_DB_PREFIX`	Test bootstrap	Test에서 필수	아니요	—	`test_nexia_`	—	폐기 가능한 병렬 tenant database prefix. Worktree마다 고유해야 함
`REDIS_CLIENT`	Laravel	관리	아니요	`phpredis`	`phpredis`	관리	Redis client 구현
`REDIS_HOST`	Laravel	관리	아니요	`redis`	`redis`	관리	Redis host
`REDIS_PASSWORD`	Laravel	관리	예	`null`	`null`	관리	Redis credential
`REDIS_PORT`	Laravel	관리	아니요	`6379`	`6379`	관리	Redis port
`SESSION_DRIVER`	Laravel	관리	아니요	`redis`	`array`	관리	Session persistence. Test는 memory에 보관
`SESSION_STORE`	Laravel	Production에서 필수	아니요	`session`	—	`session`	Tenant prefix가 없는 전용 Redis store에 session 보관
`SESSION_LIFETIME`	Laravel	선택	아니요	`120`	—	`120`	유휴 session 수명(분)
`SESSION_ENCRYPT`	Laravel	선택	아니요	`false`	—	—	직렬화된 session payload 암호화
`SESSION_PATH`	Laravel	선택	아니요	`/`	—	—	Session cookie path
`SESSION_DOMAIN`	Laravel	선택	아니요	`null`	—	—	Session cookie domain
`CACHE_STORE`	Laravel	관리	아니요	`redis`	`file`	관리	기본 application cache. Agent 일부 계약은 명시적 store 사용
`QUEUE_CONNECTION`	Laravel	관리	아니요	`redis`	`sync`	관리	Queue backend. Test는 동기 실행
`FILESYSTEM_DISK`	Laravel	선택	아니요	`local`	`local`	`local`	Product storage 소유권과 구분되는 framework 기본 disk

Product storage, realtime, mail, billing, frontend

변수	수신자	등급	비밀	Local	Test	Production	효과
`PRODUCT_STORAGE_DRIVER`	Laravel	필수	아니요	`local`	—	`s3`	소유권을 인식하는 Local 또는 S3-compatible product disk 선택
`AWS_ACCESS_KEY_ID`	Laravel storage	조건부	예	빈값	—	빈값	S3/R2 credential identifier
`AWS_SECRET_ACCESS_KEY`	Laravel storage	조건부	예	빈값	—	빈값	S3/R2 secret credential
`AWS_DEFAULT_REGION`	Laravel storage	조건부	아니요	`auto`	—	`auto`	S3-compatible region
`AWS_BUCKET`	Laravel storage	조건부	아니요	빈값	—	`nexia-cloud-os-private`	Private product bucket
`AWS_PUBLIC_BUCKET`	Laravel storage	조건부	아니요	빈값	—	`nexia-cloud-os`	Public product bucket
`AWS_URL`	Laravel storage	조건부	아니요	빈값	—	`https://cdn.nexia.to`	Public object URL base
`AWS_ENDPOINT`	Laravel storage	조건부	아니요	빈값	—	R2 endpoint	S3-compatible API endpoint
`AWS_USE_PATH_STYLE_ENDPOINT`	Laravel storage	선택	아니요	`false`	—	`false`	Virtual host 대신 path-style request 선택
`BROADCAST_CONNECTION`	Laravel, local runtime-mode script	Local 선택, production 관리	아니요	`log`	`null`	`reverb`	Broadcast transport. Local에서 `reverb`를 선택하면 모든 runtime profile에 `reverb` service 포함
`REVERB_APP_ID`	Laravel, Reverb	Local 조건부, production 관리	아니요	빈값	—	빈값	Reverb application identifier
`REVERB_APP_KEY`	Laravel, Reverb, Vite, local runtime-mode script	Local 조건부, production 관리	아니요	빈값	—	빈값	Reverb public application key. Local nonblank 값이면 모든 runtime profile에 `reverb` service 포함
`REVERB_APP_SECRET`	Laravel, Reverb	Local 조건부, production 관리	예	빈값	—	빈값	Reverb signing secret
`REVERB_HOST`	Laravel, Vite	Local 조건부, production 관리	아니요	`reverb`	—	`reverb`	Reverb host
`REVERB_PORT`	Laravel, Vite	Local 조건부, production 관리	아니요	`6001`	—	`443`	Reverb port
`REVERB_SCHEME`	Laravel, Vite	Local 조건부, production 관리	아니요	`http`	—	`https`	Reverb transport scheme
`REVERB_SERVER_HOST`	Laravel	선택 Local override	아니요	주석 처리	—	—	Browser-facing host가 app container에서 닿지 않을 때 쓰는 backend 전용 Reverb host
`REVERB_SERVER_PORT`	Laravel	선택 Local override	아니요	주석 처리	—	—	Backend 전용 Reverb port. `REVERB_PORT`로 fallback
`REVERB_SERVER_SCHEME`	Laravel	선택 Local override	아니요	주석 처리	—	—	Backend 전용 Reverb scheme. `REVERB_SCHEME`으로 fallback
`SANCTUM_STATEFUL_DOMAINS`	Laravel Cloud	필수	아니요	—	—	`nexia.to,*.nexia.to`	Stateful Sanctum client로 취급할 browser origin
`MAIL_MAILER`	Laravel	조건부	아니요	`smtp`	`array`	`log`	Outbound mail transport. Production `log`는 외부 발송 없음
`MAIL_HOST`	Laravel	조건부	아니요	`mailpit`	—	빈값	SMTP host
`MAIL_PORT`	Laravel	조건부	아니요	`1025`	—	`587`	SMTP port
`MAIL_USERNAME`	Laravel	조건부	아니요	`null`	—	빈값	SMTP login 이름
`MAIL_PASSWORD`	Laravel	조건부	예	`null`	—	빈값	SMTP credential
`MAIL_SCHEME`	Laravel	선택	아니요	`null`	—	`smtp`	명시적 SMTP URL scheme
`MAIL_FROM_ADDRESS`	Laravel	조건부	아니요	`noreply@nexia.localhost`	—	`noreply@nexia.to`	기본 발신자 주소
`MAIL_FROM_NAME`	Laravel	조건부	아니요	`${APP_NAME}`	—	`${APP_NAME}`	기본 발신자 이름
`STRIPE_KEY`	Laravel	조건부	아니요	빈값	—	빈값	공개 Billing key
`STRIPE_SECRET`	Laravel	조건부	예	빈값	—	빈값	Stripe API secret
`VITE_PUBLIC_HOST`	Vite/browser	Local에서 필수	아니요	`localhost`	`localhost`	—	Frontend endpoint가 쓰는 browser-visible Local host
`VITE_REVERB_APP_KEY`	Vite/browser, local runtime-mode script	Local 조건부, production 관리	아니요	`${REVERB_APP_KEY}`	—	`${REVERB_APP_KEY}`	Browser Reverb key. Local nonblank 값이면 모든 runtime profile에 `reverb` service 포함
`VITE_REVERB_HOST`	Vite/browser	Local 조건부, production 관리	아니요	`${VITE_PUBLIC_HOST}`	—	`${REVERB_HOST}`	Browser Reverb host
`VITE_REVERB_PORT`	Vite/browser	Local 조건부, production 관리	아니요	—	—	`${REVERB_PORT}`	Browser Reverb port. Local frontend config는 `FORWARD_REVERB_PORT`로 fallback
`VITE_REVERB_SCHEME`	Vite/browser	Local 조건부, production 관리	아니요	`${REVERB_SCHEME}`	—	`${REVERB_SCHEME}`	Browser Reverb scheme
`VITE_USE_POLLING`	Vite	선택	아니요	`true`	`true`	—	Mount된 Local source의 filesystem polling 활성화
`VITE_POLL_INTERVAL`	Vite	선택	아니요	`3000`	—	—	Local polling 간격(ms)
`VITE_SHOW_UI_SANDBOX`	Vite/browser	선택	아니요	`false`	—	`false`	true일 때 개발 UI sandbox 노출

로컬 task dev:up:* 수렴에서는 명시적으로 export한 process 값을 빈값이어도 .env보다 먼저 읽고, 그다음 key fallback을 적용합니다. BROADCAST_CONNECTION의 fallback은 log, 두 app key의 fallback은 빈값입니다. 해석된 broadcast connection이 reverb이거나 두 app key 중 하나가 비어 있지 않으면 reverb를 필수 서비스로 포함합니다. .env의 리터럴 alias VITE_REVERB_APP_KEY=${REVERB_APP_KEY}는 REVERB_APP_KEY를 통해 해석하므로 원본 key가 비어 있으면 Reverb를 활성화하지 않습니다.

Local Docker port와 testing

이 값은 개발자 machine의 Docker Compose에만 속하며 Laravel Cloud나 container secret store에 등록하지 않습니다.

변수	수신자	등급	비밀	Local	Test	Production	효과
`FORWARD_WEB_BIND`	Compose	선택	아니요	`127.0.0.1`	—	—	Application port의 host interface
`FORWARD_WEB_PORT`	Compose	선택	아니요	`8080`	—	—	Host application port
`FORWARD_VITE_PORT`	Compose	선택	아니요	`5173`	—	—	Host Vite port
`FORWARD_DB_PORT`	Compose	선택	아니요	`54320`	—	—	Host PostgreSQL port
`FORWARD_REDIS_PORT`	Compose	선택	아니요	`63790`	—	—	Host Redis port
`FORWARD_MAILPIT_PORT`	Compose	선택	아니요	`8025`	—	—	Host Mailpit UI port
`FORWARD_MAILPIT_SMTP_PORT`	Compose	선택	아니요	`1025`	—	—	Host Mailpit SMTP port
`FORWARD_REVERB_PORT`	Compose	선택	아니요	`6001`	—	—	Host Reverb port
`FORWARD_TYPESENSE_PORT`	Compose	선택	아니요	`8108`	—	—	Host Typesense port

Test fixture는 선택 관측 service도 꺼서 test 동작에 영향을 주지 못하게 합니다.

변수	수신자	등급	비밀	Local	Test	Production	효과
`PULSE_ENABLED`	Laravel tests	관리 test fixture	아니요	—	`false`	—	Test에서 Pulse 비활성화
`TELESCOPE_ENABLED`	Laravel tests	관리 test fixture	아니요	—	`false`	—	Test에서 Telescope 비활성화
`NIGHTWATCH_ENABLED`	Laravel tests	관리 test fixture	아니요	—	`false`	—	Test에서 Nightwatch 비활성화
`NEXIA_TEST_PROCESSES`	Test runner	선택	아니요	—	commented (`8`)	—	병렬 Pest worker 수 제한. 기본값은 container CPU 수

Nexia identity·tenancy·file·signature

변수	수신자	등급	비밀	Local	Test	Production	효과
`ADMIN_SEEDER_EMAIL`	Laravel seeder	조건부	아니요	`admin@nexia.dev`	—	빈값	첫 administrator identity
`ADMIN_SEEDER_PASSWORD`	Laravel seeder	조건부	예	`password`	—	빈값	첫 administrator password. Seed 후 회전하거나 제거
`NEXIA_ADMIN_PATH`	Laravel	선택	아니요	`admin`	`admin`	`admin`	Central administration route prefix
`NEXIA_OIDC_ID_TOKEN_LEEWAY`	Laravel	선택	아니요	`60`	—	`60`	허용 OIDC clock skew(초)
`TENANCY_DB_PREFIX`	Laravel	선택	아니요	`nexia_`	—	`nexia_`	Tenant database 이름 prefix. 변경해도 기존 database 이름은 바뀌지 않음
`TENANCY_PENDING_COUNT`	Laravel	선택	아니요	`0`	—	`0`	미리 준비할 tenant database 수. 0이면 pool 비활성화
`TENANCY_DOMAIN_RESOLVER_CACHE`	Laravel	선택	아니요	`false`	—	`true`	Tenant domain resolution cache
`TENANCY_DOMAIN_RESOLVER_CACHE_TTL`	Laravel	선택	아니요	`3600`	—	`3600`	Domain cache 수명(초)
`MALWARE_SCANNER`	Laravel	보호 intake에 필수	아니요	`passthrough`	—	`clamd`	ClamD 또는 명시적인 Local waiver 선택
`CLAMD_HOST`	Laravel	조건부	아니요	`clamav`	—	빈값	Canonical reachable ClamD host
`CLAMD_PORT`	Laravel	조건부	아니요	`3310`	—	`3310`	Canonical ClamD TCP port
`CLAMD_CONNECT_TIMEOUT_SECONDS`	Laravel	선택	아니요	`2`	—	`2`	ClamD 연결 timeout
`CLAMD_SCAN_TIMEOUT_SECONDS`	Laravel	선택	아니요	`30`	—	`30`	ClamD scan timeout
`SIGNATURE_PDF_PROCESSOR_EXPECTED_VERSION`	Laravel health	선택	아니요	`8.71.2`	—	—	예상 PDF processor package version
`SIGNATURE_PDF_PROCESSOR_HEALTH_REQUIRED`	Laravel health	선택	아니요	`false`	—	code 기본값 `true`	PDF runtime health를 readiness 필수 조건으로 지정
`NEXIA_SIGNATURE_DISPLAY_TIMEZONE`	Laravel	선택	아니요	`UTC`	—	`UTC`	Signature evidence 표시 timezone
`APPROVAL_SESSION_EVIDENCE_FRESHNESS_MINUTES`	Laravel	선택	아니요	`720`	—	`720`	Approval이 쓰는 session evidence 최대 나이
`SIGNATURE_ENABLED`	Laravel	선택	아니요	—	—	`false`	Production Signature master rollout switch
`SIGNATURE_TENANT_ALLOWLIST`	Laravel	선택	아니요	—	—	빈값	Signature를 지정 tenant로 제한
`SIGNATURE_LEGAL_ENTITY_ALLOWLIST`	Laravel	선택	아니요	—	—	빈값	Signature를 지정 Legal Entity로 제한
`SIGNATURE_PILOT_LEGAL_ENTITY_ALLOWLIST`	Laravel	선택	아니요	—	—	빈값	Pilot cohort를 더 좁게 제한
`SIGNATURE_EXECUTION_ENGINE`	Laravel	선택	아니요	—	—	`native`	Signature execution engine 선택
`SIGNATURE_BULK_REQUEST_ENABLED`	Laravel	선택	아니요	—	—	`false`	Bulk Signature request 활성화
`SIGNATURE_BULK_REQUEST_TENANT_ALLOWLIST`	Laravel	선택	아니요	—	—	빈값	Bulk request를 tenant로 제한
`SIGNATURE_BULK_REQUEST_LEGAL_ENTITY_ALLOWLIST`	Laravel	선택	아니요	—	—	빈값	Bulk request를 Legal Entity로 제한
`DOCUMENT_BINARY_MAX_FILE_KIB`	Laravel	선택	아니요	`51200`	—	`51200`	파일당 upload 한도
`DOCUMENT_BINARY_MAX_ACTIVE_FILES`	Laravel	선택	아니요	`20`	—	`20`	Owner당 최대 active file 수
`DOCUMENT_BINARY_MAX_TOTAL_KIB`	Laravel	선택	아니요	`256000`	—	`256000`	Active file 합산 한도
`DOCUMENT_BINARY_MAX_EXTRACTED_CHARACTERS`	Laravel	선택	아니요	`2000000`	—	`2000000`	Text extraction 상한
`DOCUMENT_BINARY_STAGE_TTL_HOURS`	Laravel	선택	아니요	`48`	—	`48`	Bind되지 않은 staged file 수명
`DOCUMENT_BINARY_QUARANTINE_RETENTION_DAYS`	Laravel	선택	아니요	`30`	—	`30`	Quarantined file 보존 기간
`DOCUMENT_BINARY_DEFAULT_BOUND_RETENTION_DAYS`	Laravel	선택	아니요	`2555`	—	`2555`	기본 bound document 보존 기간
`DOCUMENT_BINARY_EXTRACTION_TIMEOUT_SECONDS`	Laravel	선택	아니요	`30`	—	`30`	외부 text extraction timeout
`DOCUMENT_BINARY_PDFTOTEXT_BINARY`	Laravel	선택	아니요	`pdftotext`	—	`pdftotext`	PDF text extraction executable

Search·analytics·embedding

변수	수신자	등급	비밀	Local	Test	Production	효과
`SCOUT_DRIVER`	Laravel Scout	선택	아니요	`database`	`database`	`database`	Index 동기화 engine
`SCOUT_QUEUE`	Laravel Scout	선택	아니요	`false`	`false`	`true`	Index 동기화를 queue에서 실행
`SCOUT_AFTER_COMMIT`	Laravel Scout	선택	아니요	`true`	`true`	`true`	Transaction commit까지 index write 지연
`TYPESENSE_HOST`	Laravel Scout	조건부	아니요	`typesense`	—	빈값	Typesense host
`TYPESENSE_PORT`	Laravel Scout	조건부	아니요	`8108`	—	`443`	Typesense port
`TYPESENSE_PROTOCOL`	Laravel Scout	조건부	아니요	`http`	—	`https`	Typesense protocol
`TYPESENSE_API_KEY`	Laravel Scout, local Typesense	조건부	예	개발용 admin key	—	빈값	Server 전용 administrative key
`TYPESENSE_SCOPED_KEY_PARENT`	Laravel Search	조건부	예	개발용 search-only key	—	빈값	Tenant-scoped key 서명에 쓰는 기존 search-only parent
`KNOWLEDGE_SEARCH_SEMANTIC_ENABLED`	Laravel Knowledge	선택	아니요	`false`	`false`	`false`	선택한 immutable profile의 semantic read 활성화
`KNOWLEDGE_SEARCH_EMBEDDING_PROFILE`	Laravel Knowledge	선택	아니요	`none`	`none`	`none`	Provider/model/version/dimension/storage generation. 현재 Production profile 없음
`RESOURCE_IMPORT_HEADER_EMBEDDING_PROVIDER`	Laravel Resource Import	선택	아니요	`none`	`none`	`none`	선택적인 header-only semantic matching 활성화
`RESOURCE_IMPORT_HEADER_EMBEDDING_BASE_URL`	Laravel Resource Import	조건부	아니요	local Ollama URL	—	빈값	도달 가능한 Ollama `/api/embed` base URL
`RESOURCE_IMPORT_HEADER_EMBEDDING_MODEL`	Laravel Resource Import	조건부	아니요	`embeddinggemma`	—	`embeddinggemma`	Header embedding model

Candidate retrieval은 예제에서 SEARCH_CANDIDATE_GATEWAY를 의도적으로 제외했으므로 SCOUT_DRIVER를 따릅니다. Indexing과 candidate retrieval을 나누는 단계적 cutover에서만 이 고급 override를 설정하세요. 전체 절차는 Search 설정 프로필을 참고합니다. Production validator는 SCOUT_DRIVER=typesense 또는 SEARCH_CANDIDATE_GATEWAY=typesense가 해당 service를 선택하면 전체 Typesense 연결을 요구합니다.

Analytics

변수	수신자	등급	비밀	Local	Test	Production	효과
`GOOGLE_ANALYTICS_ENABLED`	Laravel/browser	선택	아니요	`false`	—	`true`	Consent 기반 GA4 collection 활성화
`GOOGLE_ANALYTICS_MEASUREMENT_ID`	Browser	조건부	아니요	`G-QQR7R8D9QS`	—	`G-QQR7R8D9QS`	Public GA4 stream identifier
`GOOGLE_ANALYTICS_COLLECT_SUBDOMAINS`	Laravel/browser	선택	아니요	`developers`	—	`developers`	수집을 허용할 Central subdomain
`GOOGLE_ANALYTICS_COLLECT_TENANT_FIXTURES`	Laravel/browser	선택	아니요	`demo`	—	`demo`	수집을 허용할 fixture tenant
`ANALYTICS_PROPERTY_ID`	Laravel admin	조건부	아니요	`546439209`	—	`546439209`	Server-side report가 조회할 GA4 property
`ANALYTICS_CREDENTIALS_PATH`	Laravel admin	Local 조건부	아니요	Private storage path	—	—	Local service-account JSON path
`ANALYTICS_CREDENTIALS_BASE64`	Laravel admin	Production 조건부	예	빈값	—	빈값	Filesystem이 없는 환경의 service-account JSON
`ANALYTICS_CACHE_STORE`	Laravel admin	선택	아니요	`file`	—	`redis`	Reporting cache store
`ANALYTICS_CACHE_MINUTES`	Laravel admin	선택	아니요	`60`	—	`60`	Fresh report cache 수명
`ANALYTICS_STALE_CACHE_MINUTES`	Laravel admin	선택	아니요	`10080`	—	`10080`	Provider failure 시 stale cache 수명
`ANALYTICS_CLICK_DIMENSIONS_ENABLED`	Laravel/browser	선택	아니요	`false`	—	`false`	Click dimension reporting 활성화
`ANALYTICS_REQUEST_TIMEOUT_MILLISECONDS`	Laravel admin	선택	아니요	`12000`	—	`12000`	GA4 request timeout

Agent Edge·Gateway·web search

변수	수신자	등급	비밀	Local	Test	Production	효과
`AGENT_JWT_PRIVATE_KEY_PATH`	Laravel	Local 조건부	아니요	Private PEM path	빈값	—	Local delegation-signing key path
`AGENT_JWT_PUBLIC_KEY_PATH`	Laravel	Local 조건부	아니요	Public PEM path	빈값	—	Local delegation-verification key path
`AGENT_JWT_PRIVATE_KEY_BASE64`	Laravel Cloud	Production Agent에 필수	예	빈값	—	빈값	Filesystem이 없는 환경의 private PEM content
`AGENT_JWT_PUBLIC_KEY_BASE64`	Laravel Cloud	Production Agent에 필수	아니요	빈값	—	빈값	대응하는 public PEM content
`AGENT_SERVICE_TOKEN`	Laravel, Edge, Gateway	Agent에 필수	예	빈값	빈값	빈값	내부 callback을 인증하고 ticket prefilter HMAC 파생
`AGENT_EDGE_TOKEN`	Laravel, Edge	Agent에 필수	예	개발용 token	빈값	빈값	Laravel→Worker `/agent/*` 요청 보호
`NEXIA_CENTRAL_BASE_URL`	Edge, Gateway	Agent에 필수	아니요	`http://app:8000`	—	Wrangler-managed	Laravel bootstrap, ticket exchange, heartbeat, callback base URL
`AGENT_GATEWAY_URL`	Laravel	Agent에 필수	아니요	Local Edge URL	Test Gateway URL	Worker URL	Server-side protected Edge endpoint
`AGENT_PUBLIC_STREAM_URL`	Laravel/browser	Production Agent에 필수	아니요	Local browser endpoint	빈값	Worker `/browser/agent/stream`	정확한 no-redirect public ticket stream URL. 적용 대상은 DB rollout 정책이 결정
`AGENT_GATEWAY_PORT`	Compose	선택 Local	아니요	`8100`	—	—	Direct Gateway 진단용 host port
`AGENT_CHECKPOINT_DSN_TEMPLATE`	Gateway	Production Agent에 필수	예	Tenant DSN template	—	빈값	`{tenant_id}`를 치환하는 tenant별 LangGraph checkpoint 및 영속 usage journal DSN
`AGENT_GATEWAY_LOG_LEVEL`	Gateway	선택	아니요	`INFO`	—	Wrangler-managed	Gateway log severity
`AGENT_GATEWAY_DEBUG_ERRORS`	Gateway	선택 진단	아니요	`false`	—	code 기본값 `false`, 선택 Wrangler override	true이면 provider/tool 예외 상세를 SSE client에 노출
`AGENT_SCREEN_SEARCH_EMBEDDING_PROVIDER`	Gateway	선택	아니요	`none`	—	Wrangler-managed	`none`, `ollama`, `gemini`, `zai` semantic reranker
`AGENT_SCREEN_SEARCH_EMBEDDING_BASE_URL`	Gateway	선택 provider override	아니요	빈값/code 기본값	—	code 기본값, 선택 Wrangler override	Gemini와 Z.ai에는 hosted 기본값이 있고 Production Ollama는 Container-reachable URL 필요
`AGENT_SCREEN_SEARCH_EMBEDDING_API_KEY`	Gateway	Hosted provider 조건부	예	빈값	—	빈값	Chat key와 분리된 Gemini 또는 Z.ai screen-search key
`AGENT_SEARCH_PROVIDER`	Laravel	선택	아니요	`none`	—	`none`	Self-hosted `agent_search` web-search bridge 활성화
`AGENT_SEARCH_BASE_URL`	Laravel	조건부	아니요	`http://agent-search:8000`	—	빈값	도달 가능한 agent-search service URL
`AGENT_SEARCH_TOKEN`	Laravel, agent-search	조건부	예	빈값	—	빈값	Shared internal agent-search token
`SEARXNG_SECRET`	SearXNG host	조건부	예	빈값	—	빈값	선택 self-hosted metasearch service용 생성 secret

Cloudflare는 Production .env 파일을 읽지 않습니다. wrangler.jsonc가 비밀이 아닌 Worker 값과 Container/rate-limit binding을 commit합니다. AGENT_EDGE_TOKEN, AGENT_SERVICE_TOKEN, AGENT_CHECKPOINT_DSN_TEMPLATE과 필요할 때 AGENT_SCREEN_SEARCH_EMBEDDING_API_KEY를 wrangler secret put으로 등록합니다. 그 뒤 services/agent-gateway-edge/src/index.ts가 명시적인 nonblank allowlist만 Python Container에 전달합니다. 그 allowlist에 없는 dashboard 변수를 설정해도 Gateway는 구성되지 않습니다.

Langfuse·observability·선택 서비스

변수	수신자	등급	비밀	Local	Test	Production	효과
`LANGFUSE_ENABLED`	Gateway	선택	아니요	`false`	—	`false`	선택적 masked trace export 활성화. Failure는 fail-open 유지
`LANGFUSE_HOST`	Gateway	조건부	아니요	Internal Langfuse URL	—	빈값	Gateway exporter가 사용하는 Langfuse API base URL
`LANGFUSE_PUBLIC_KEY`	Gateway, bootstrap	조건부	아니요	개발용 key	—	빈값	Langfuse project public key
`LANGFUSE_SECRET_KEY`	Gateway, bootstrap	조건부	예	개발용 key	—	빈값	Langfuse project secret key
`LANGFUSE_MASK_CONTENT`	Gateway	선택	아니요	`true`	—	`true`	Export 전 prompt와 completion content masking
`LANGFUSE_PORT`	Local Compose	선택	아니요	`3300`	—	—	Browser에 publish한 Local Langfuse UI port
`LANGFUSE_SALT`	Langfuse host	Local 외 필수	예	빈값/개발 기본값	—	빈값	Server hashing salt
`LANGFUSE_ENCRYPTION_KEY`	Langfuse host	Local 외 필수	예	빈값/개발 기본값	—	빈값	Server data-encryption key
`LANGFUSE_NEXTAUTH_SECRET`	Langfuse host	Local 외 필수	예	빈값/개발 기본값	—	빈값	Langfuse login/session secret
`LANGFUSE_REDIS_DB`	Langfuse host	선택	아니요	`3`	—	`3`	Laravel cache/queue data와 격리한 Redis database
`LANGFUSE_INIT_ORG_ID`	Langfuse bootstrap	선택	아니요	`nexia`	—	`nexia`	Initial organization id
`LANGFUSE_INIT_PROJECT_ID`	Langfuse bootstrap	선택	아니요	`nexia-agent`	—	`nexia-agent`	Initial project id
`LANGFUSE_INIT_USER_EMAIL`	Langfuse bootstrap	Local 외 필수	아니요	`${ADMIN_SEEDER_EMAIL}`	—	빈값	Initial owner login
`LANGFUSE_INIT_USER_NAME`	Langfuse bootstrap	선택	아니요	`Nexia Dev`	—	`Nexia Admin`	Initial owner 표시 이름
`LANGFUSE_INIT_USER_PASSWORD`	Langfuse bootstrap	Local 외 필수	예	`${ADMIN_SEEDER_PASSWORD}`	—	빈값	Initial owner password
`LANGFUSE_NEXTAUTH_URL`	Self-hosted Langfuse	조건부	아니요	—	—	빈값	Browser-facing authentication callback URL
`FORWARD_LANGFUSE_PORT`	Self-hosted Compose	선택	아니요	—	—	`127.0.0.1:3300`	Loopback-only Langfuse UI binding

Sentry는 별도의 선택 Laravel error·trace export입니다.

변수	수신자	등급	비밀	Local	Test	Production	효과
`SENTRY_LARAVEL_DSN`	Laravel	선택	예	빈값	—	—	Nonblank이면 Sentry error delivery 활성화
`SENTRY_TRACES_SAMPLE_RATE`	Laravel	선택	아니요	`0`	—	—	Performance trace sampling rate

LANGFUSE_ENABLED=true이면 Gateway runtime에 완전한 host와 project keypair가 있어야 합니다. Self-hosted bootstrap을 사용한다면 bootstrap이 생성한 project keypair와 Gateway exporter의 값이 일치해야 합니다. Production validator는 host와 keypair를 요구합니다. tenant: trace-tag prefix는 Gateway가 소유하며 환경 override가 없습니다. Product usage metering은 Langfuse와 독립적입니다.

호환 alias와 내부 값

새 환경에는 아래 이름을 일반 key로 추가하지 마세요.

이름	상태	대체 이름 또는 owner
`APPROVAL_FILE_SCANNER`, `APPROVAL_CLAMD_HOST`, `APPROVAL_CLAMD_PORT`, `APPROVAL_CLAMD_CONNECT_TIMEOUT_SECONDS`, `APPROVAL_CLAMD_SCAN_TIMEOUT_SECONDS`	Read-only 호환 alias. 현재 카탈로그에는 없음	`MALWARE_SCANNER`와 `CLAMD_*`
`MAIL_ENCRYPTION`	Local 값이 `null`인 호환 assignment	`MAIL_SCHEME`이 우선. Production에 이전 이름을 추가하지 않음
`RESOURCE_IMPORT_EMBEDDING_PROVIDER`, `RESOURCE_IMPORT_EMBEDDING_BASE_URL`, `RESOURCE_IMPORT_EMBEDDING_MODEL`	한 release 동안 읽기 fallback	`RESOURCE_IMPORT_HEADER_EMBEDDING_*`
`SEARCH_SEMANTIC_ENABLED`, `SEARCH_SEMANTIC_PROVIDER`	한 release 동안 읽기 fallback	`KNOWLEDGE_SEARCH_SEMANTIC_ENABLED`, `KNOWLEDGE_SEARCH_EMBEDDING_PROFILE`
`AGENT_OLLAMA_EMBEDDING_MODEL`, `AGENT_GEMINI_EMBEDDING_MODEL`, `AGENT_ZAI_EMBEDDING_MODEL`	제거된 운영 설정	Gateway code가 provider model constant를 소유
`AGENT_GATEWAY_SSE_KEEPALIVE_SECONDS`, `AGENT_GATEWAY_SSE_BUFFER_MAX_BYTES`, `AGENT_GATEWAY_SSE_BUFFER_MAX_FRAMES`, `AGENT_MANIFEST_FETCH_MAX_ATTEMPTS`	제거된 운영 설정	Cross-runtime protocol과 safety constant는 code 소유
`AGENT_EDGE_LOCAL_HOST`, `AGENT_EDGE_LOCAL_PORT`, `AGENT_GATEWAY_UPSTREAM_URL`	Compose가 고정한 Local adapter 내부값	운영 등록 대상 아님
`QUERY_LOG_RETENTION_DAYS`, `FETCH_LOG_RETENTION_DAYS`, `SEARXNG_BASE_URL`	Search container 내부값	Compose와 tracked patch가 소유
`LANGFUSE_TENANT_TAG_PREFIX`	제거된 운영 설정	Gateway가 code-defined `tenant:` trace-tag prefix 소유
`PLAYWRIGHT_BROWSERS_PATH`, `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD`, `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`, `DATA_DIR`	agent-search image 내부값	Dockerfile 소유
`HOSTNAME`, `DATABASE_URL`, `SALT`, `ENCRYPTION_KEY`, `CLICKHOUSE_`, `LANGFUSE_S3_EVENT_UPLOAD_`, `REDIS_CONNECTION_STRING`, `TELEMETRY_ENABLED`, `NEXTAUTH_`, `LANGFUSE_INIT_PROJECT_PUBLIC_KEY`, `LANGFUSE_INIT_PROJECT_SECRET_KEY`, `MINIO_ROOT_`	파생되거나 고정된 Langfuse container 환경. 일부는 비밀	Compose가 운영자 소유 `LANGFUSE_*`, database, bootstrap 값을 이 process 이름으로 mapping. `LANGFUSE_INIT_PROJECT_ID`는 운영자 설정 유지
`VITE_APP_NAME`	현재 코드에서 읽지 않는 이름	`APP_NAME` 사용. 중복 Vite assignment를 복구하지 않음
`POSTMARK_MESSAGE_STREAM_ID`, `TYPESENSE_MAX_TOTAL_RESULTS`, `SEARXNG_SEARCH_FORMATS`	비활성, comment-only 또는 선택 image에서 미지원	운영 등록 대상 아님
`AGENT_GATEWAY_CONTAINER`, `AGENT_BROWSER_STREAM_RATE_LIMITER`	환경변수가 아닌 Cloudflare binding	`wrangler.jsonc` 소유
`PYTHONDONTWRITEBYTECODE`, `PYTHONUNBUFFERED`, `PIP_DISABLE_PIP_VERSION_CHECK`, `UV_LINK_MODE`, `UV_PROJECT_ENVIRONMENT`	Gateway image constant	Dockerfile 소유
`WWWGROUP`, `WWWUSER`, `AGENT_SEARCH_REF`	Local build argument	Compose/Docker build 소유. Search ref는 보안을 위해 고정
`LANGFUSE_TEST_HOST`	Integration test 전용 endpoint	운영 등록 대상 아님
`NEXIA_CONTRIBUTION_MANIFEST_PATH`	생성된 contribution cache path override	정상 path는 code 소유. 배포 등록 대상 아님
`NEXIA_SIGNATURE_LIVE_FIXTURE_PASSWORD`, `DEMO_ADMIN_PASSWORD`	Local fixture command/seeder 입력이며 비밀	개발 전용이며 Production 카탈로그 값이 아님
`GOOGLE_OIDC_CLIENT_ID`, `GOOGLE_OIDC_CLIENT_SECRET`, `ENTRA_OIDC_CLIENT_ID`, `ENTRA_OIDC_CLIENT_SECRET`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_ISSUER`	Development SSO seeder 입력. Secret 이름은 비밀	Production identity provider 설정은 환경이 아닌 DB 소유
`NO_COLOR`, `TERM`, `PATH`	Ambient shell/process 환경	운영체제 소유
`NEXIA_APP_IMAGE`, `NEXIA_AGENT_GATEWAY_IMAGE`	선택적 self-hosted Compose 이미지 입력	`docker-compose.prod.yml` 전용이며 관리형 Production 카탈로그에 없음

옵션

공식 카탈로그 밖 source 지원 override

현재 source는 아래 이름을 읽지만 Nexia는 지원되는 Local·Production assignment 카탈로그에서 의도적으로 제외합니다. 대부분 upstream framework escape hatch, 진단값 또는 code 기본값을 맞춰야 하는 safety constant입니다. 모든 배포가 복사할 값이 아니라 고급 override로 취급하세요. Runtime owner, validator rule, Production 필요성이 명확할 때만 공식 카탈로그로 승격합니다.

변수	수신자	등급	비밀	기본값	효과 / 제외 이유
`APP_PREVIOUS_KEYS`	Laravel	선택 rotation	예	빈값	계획된 key rotation 중 허용할 이전 application key의 쉼표 구분 목록
`CLAMD_EXPECTED_VERSION`	Laravel health	선택	아니요	`1.4`	Image/readiness 계약. 고정 scanner release와 함께만 변경
`MAIL_URL`	Laravel mail	선택	예	빈값	Upstream 전체 SMTP DSN override
`MAIL_EHLO_DOMAIN`	Laravel mail	선택	아니요	`APP_URL`의 host	Upstream SMTP EHLO domain override
`MAIL_SENDMAIL_PATH`	Laravel mail	조건부	아니요	`/usr/sbin/sendmail -bs -i`	`MAIL_MAILER=sendmail`일 때 쓰는 command
`MAIL_LOG_CHANNEL`	Laravel mail	선택	아니요	기본 log channel	`MAIL_MAILER=log`일 때 쓰는 전용 channel
`POSTMARK_API_KEY`	Laravel mail	조건부	예	빈값	`MAIL_MAILER=postmark`일 때 필수
`RESEND_API_KEY`	Laravel mail	조건부	예	빈값	`MAIL_MAILER=resend`일 때 필수
`SEARCH_CANDIDATE_GATEWAY`	Laravel Search	단계적 전환 시 선택	아니요	Scout가 Typesense이면 `typesense`, 그 외 `database`	색인 동기화와 조회 엔진을 따로 전환할 때만 지정. 일반 프로필에서는 생략
`SCOUT_PREFIX`	Laravel Scout	선택	아니요	빈값	External index 이름 prefix
`SCOUT_IDENTIFY`	Laravel Scout	선택	아니요	`false`	지원 engine의 user identification 활성화
`TYPESENSE_PATH`	Laravel Scout	선택	아니요	빈값	Hosted Typesense URL path
`TYPESENSE_CONNECTION_TIMEOUT_SECONDS`	Laravel Scout	선택	아니요	`2`	연결 timeout
`TYPESENSE_HEALTHCHECK_INTERVAL_SECONDS`	Laravel Scout	선택	아니요	`30`	Node health-check 주기
`TYPESENSE_NUM_RETRIES`	Laravel Scout	선택	아니요	`3`	Client retry 횟수
`TYPESENSE_RETRY_INTERVAL_SECONDS`	Laravel Scout	선택	아니요	`1`	Retry 지연
`TYPESENSE_IMPORT_ACTION`	Laravel Scout	선택	아니요	`upsert`	Bulk import action
`AGENT_VISION_MODELS`	Local/self-hosted Gateway 전용	선택	아니요	빈값	Image-capable local model prefix allowlist. model capability가 catalog 소유가 되기 전까지 Cloudflare는 의도적으로 전달하지 않음
`SIGNATURE_TEMPLATE_MAXIMUM_SIGNERS`	Laravel Signature	선택	아니요	`8`	최대 signer 수의 boot 기본값
`SIGNATURE_LOCAL_FIXTURE_PROFILE`	Laravel Signature	선택 Local/Test	아니요	빈값	명시적인 deterministic fixture profile 선택
`SIGNATURE_BULK_REQUEST_STUCK_AFTER_SECONDS`	Laravel Signature	선택	아니요	`900`	Bulk readiness metadata의 age 기준
`SIGNATURE_BULK_REQUEST_RECOVERY_SCAN_LIMIT`	Laravel Signature	선택	아니요	`100`	한 recovery scan에서 검사할 bulk row 최대 수
`SIGNATURE_STUCK_AFTER_SECONDS`	Laravel Signature	선택	아니요	`900`	Stuck operation query의 age 기준
`SIGNATURE_STUCK_QUERY_LIMIT`	Laravel Signature	선택	아니요	`100`	Query당 반환할 stuck operation 최대 수
`SIGNATURE_ARTIFACT_RETENTION_YEARS`	Laravel Signature	선택	아니요	`7`	Immutable artifact/evidence 기본 보존 기간
`SIGNATURE_DOMPDF_EXPECTED_VERSION`	Laravel health	선택	아니요	`3.1.6`	예상 Dompdf runtime version
`SIGNATURE_FPDI_EXPECTED_VERSION`	Laravel health	선택	아니요	`2.6.8`	예상 FPDI runtime version
`SIGNATURE_TCPDF_EXPECTED_VERSION`	Laravel health	선택	아니요	`6.11.3`	예상 TCPDF runtime version

Production은 이제 canonical MALWARE_SCANNER=clamd와 CLAMD_* 이름을 게시합니다. 도달 가능한 private CLAMD_HOST를 제공하세요. Production validator는 canonical 이름을 먼저 읽고 호환 기간에만 이전 alias를 허용합니다.

변경 적용

Laravel은 config/*.php에서 환경값을 읽습니다. VITE_* 값은 브라우저 코드에 노출되므로 비밀을 넣지 마세요. Compose는 서비스 설정을 치환하고 Gateway는 시작할 때 프로세스 설정을 읽습니다.

Laravel 설정을 바꾸면 cached configuration을 지우고 영향을 받는 long-lived process를 재시작하세요. Cloudflare secret 또는 Wrangler 변수를 바꾸면 새 Worker/Container version을 배포해야 합니다. Laravel Cloud를 바꿔도 Cloudflare에 그 값이 주입되지 않습니다. 표에 여러 runtime이 수신자로 적힌 shared secret은 모든 owner가 같은 값을 가져야 Production 등록이 완료됩니다.

Laravel Cloud variables      Laravel config와 PHP worker
Wrangler vars/bindings       공개 Worker topology와 Container 설정
Cloudflare secrets           Edge trust, checkpoint, Gateway credential
External service host env    ClamAV, Typesense, Langfuse, SearXNG 등 service1234

오류

오류 또는 관측 상태	원인	해결
`Production environment file not found: ...`	Validator에 존재하지 않는 export path 전달	실제 export 파일로 다시 실행
`APP_KEY must be a generated base64 key and must not contain CHANGE_ME.`	Production 카탈로그 placeholder 검증	Target secret store에서 Laravel key 생성
`<KEY> is missing or contains a placeholder.`	필수 Production 값이 비었거나 예시값 유지	이 페이지의 owner에 등록한 뒤 `scripts/validate-prod-env.sh` 재실행
`AGENT_EDGE_TOKEN must not use the known local development token.`	Production에 공개 Local 예시 token 유지	새 token을 생성해 Laravel Cloud와 Cloudflare에 같은 값 등록
`<KEY> must be an absolute HTTPS URL without userinfo, query, fragment, or whitespace.`	Production endpoint 형식이 잘못되었거나 안전하지 않음	Credential·query가 없는 canonical HTTPS origin/URL 등록
`AGENT_PUBLIC_STREAM_URL must use the exact /browser/agent/stream path.`	Browser stream URL이 redirect, relay 또는 잘못된 route를 가리킴	Worker의 정확한 public Direct SSE endpoint 등록
`MALWARE_SCANNER must be clamd in production.`	Production이 Local `passthrough` waiver 또는 다른 driver 선택	도달 가능한 ClamD를 배포하고 canonical scanner 설정 사용
`<KEY> must be a deployment-reachable host name or address without a scheme, path, credentials, or whitespace.`	Service host에 URL 또는 credential 포함	Host 변수에는 도달 가능한 host 이름만 저장
`<KEY> must be an integer between 1 and 65535.`	Service port가 잘못됐거나 TCP 범위를 벗어남	수신 service의 올바른 port 등록
`TYPESENSE_PROTOCOL must be one of: http https.`	Typesense에 지원하지 않는 scheme 선택	Hosted production은 `https`, 의도적인 internal endpoint는 `http` 사용
`PRODUCT_STORAGE_DRIVER must be one of: local s3.`	Product disk family가 비었거나 미지원	Self-contained Local profile 또는 전체 S3-compatible block 구성
`AGENT_SCREEN_SEARCH_EMBEDDING_PROVIDER must be one of: none ollama gemini zai.`	알 수 없는 Gateway reranker provider	지원 provider 또는 `none` 선택
`AGENT_SCREEN_SEARCH_EMBEDDING_BASE_URL for a hosted provider must be an absolute HTTPS URL without userinfo, query, fragment, or whitespace.`	Custom Gemini/Z.ai endpoint 형식이 잘못됐거나 안전하지 않음	Override 제거로 code 기본값 사용 또는 깨끗한 HTTPS base URL 등록
`RESOURCE_IMPORT_HEADER_EMBEDDING_PROVIDER must be one of: none ollama.`	Resource Import가 미지원 embedding provider 선택	도달 가능한 Ollama 또는 비활성 header embedding 사용
`KNOWLEDGE_SEARCH_SEMANTIC_ENABLED must be a boolean value.`	Feature flag가 인식 가능한 boolean 아님	`true` 또는 `false` 사용
`KNOWLEDGE_SEARCH_EMBEDDING_PROFILE must select a production-approved profile when Knowledge semantic search is enabled.`	Semantic read를 켰지만 profile이 `none` 또는 빈값	승인된 immutable profile이 생길 때까지 semantic read 비활성화
`KNOWLEDGE_SEARCH_EMBEDDING_PROFILE deterministic-local-test-vector-16-v1 is not allowed in production.`	Deterministic test profile이 Production에 유입	`none`으로 복귀. Local/Test fixture 전용
`LANGFUSE_ENABLED must be a boolean value.`	선택적 tracing switch가 인식 가능한 boolean 아님	`true` 또는 `false` 사용
`VITE_REVERB_APP_KEY must equal REVERB_APP_KEY.`	Server와 browser Reverb application key 불일치	Platform-managed public key를 양쪽에 동일하게 사용
`AGENT_JWT_PRIVATE_KEY_BASE64 must be the Base64 of a PEM key.`	Decode한 private key가 PEM material이 아님	`base64 -i private.pem`의 한 줄 출력을 Laravel Cloud에 등록
`Agent gateway environment variable '<KEY>' is not set. The request cannot proceed until it is populated.`	Edge가 필수 Container 값을 전달하지 않았거나 secret 누락	Cloudflare에 등록하고 `src/index.ts`가 canonical 이름을 전달하는지 확인
`ticket_service_unavailable`	Edge에 `NEXIA_CENTRAL_BASE_URL`, `AGENT_SERVICE_TOKEN` 또는 rate-limit binding 누락	Worker variable, secret, binding 복구 후 재시도
Gateway health가 `configured: false`	`NEXIA_CENTRAL_BASE_URL` 또는 `AGENT_SERVICE_TOKEN`이 비어 있음	Gateway runtime에 두 값 구성
Screen-search health가 `misconfigured`	Hosted provider API key 누락	Canonical screen-search key를 채우거나 `none` 선택. Readiness는 형식만 검증하며 provider reachability는 검증하지 않음
`ANALYTICS_CREDENTIALS_BASE64 must contain valid Base64.`	Service-account JSON encoding 손상	JSON을 한 줄 Base64로 다시 등록
`KNOWLEDGE_SEARCH_EMBEDDING_PROFILE '<PROFILE>' is not implemented by this release.`	Production이 미지원 semantic generation 선택	`none`으로 복귀하고 semantic retrieval 비활성화 유지
Langfuse가 활성화됐지만 trace가 비어 있음	Gateway의 host/keypair가 불완전하거나 Gateway가 trace 미전송	Gateway에 Langfuse project의 host/keypair를 설정하고 export health 확인. Product usage는 Langfuse와 독립적임
Candidate search가 indexing과 다른 engine 사용	운영자가 `SEARCH_CANDIDATE_GATEWAY`를 명시적으로 설정	Override 제거로 Scout를 따르거나 의도적인 split profile 완성
Agent web search health는 성공하지만 실제 search는 502 반환	SearXNG pair, JSON format 설정 또는 secret 누락	`search` profile의 두 container를 구성하고 `SEARXNG_SECRET` 설정
보호 upload가 계속 비활성화	Production `CLAMD_HOST`가 비었거나 도달 불가	Canonical `CLAMD_HOST`에 도달 가능한 private scanner hostname 등록
Tenant 전환 시 419 또는 logout	Session이 tenant-prefixed cache store 또는 domain-wide cookie 사용	`SESSION_STORE=session` 유지, Production `SESSION_DOMAIN`은 설정하지 않음

실제 사용

Local Agent 주입은 docker-compose.yml에서 확인할 수 있습니다. 같은 AGENT_SERVICE_TOKEN이 Local Edge와 Gateway에 전달되고 Edge adapter는 고정된 internal URL을 사용합니다. Cloudflare Production은 다른 방식을 사용합니다.

코드 예시

Shell

(
cd services/agent-gateway-edge
pnpm exec wrangler secret put AGENT_EDGE_TOKEN
pnpm exec wrangler secret put AGENT_SERVICE_TOKEN
pnpm exec wrangler secret put AGENT_CHECKPOINT_DSN_TEMPLATE
# Gemini 또는 Z.ai 화면 검색을 사용할 때만:
pnpm exec wrangler secret put AGENT_SCREEN_SEARCH_EMBEDDING_API_KEY
# Langfuse 추적을 사용할 때만:
pnpm exec wrangler secret put LANGFUSE_ENABLED
pnpm exec wrangler secret put LANGFUSE_HOST
pnpm exec wrangler secret put LANGFUSE_PUBLIC_KEY
pnpm exec wrangler secret put LANGFUSE_SECRET_KEY
)12345678910111213

Screen-search embedding secret command는 Gemini 또는 Z.ai에서만 필요합니다. Langfuse 네 command는 선택적 tracing을 켤 때만 필요하며 Langfuse project가 소유한 값을 사용합니다. Self-hosted profile이라면 bootstrap 값과도 일치해야 합니다. 비밀이 아닌 screen-search 설정은 wrangler.jsonc에, 비밀은 Wrangler에 둡니다. services/agent-gateway-edge/wrangler.jsonc가 NEXIA_CENTRAL_BASE_URL, screen-search provider, Gateway log level, Container binding, rate limiter를 소유합니다. Gateway 기본값을 override할 때만 선택 screen-search base URL을 추가하세요. services/agent-gateway-edge/src/index.ts가 Container에 들어갈 값의 최종 권한입니다.

Core 루트에서 운영 설정을 모은 파일을 무시되는 tmp/production-env-export.env에 저장한 뒤 배포 전에 검사합니다. 비밀이 들어 있는 파일이므로 커밋하지 마세요. 로컬 개발용 .env를 대신 넣으면 운영 설정 검사가 되지 않습니다.

코드 예시

Shell

bash scripts/validate-prod-env.sh tmp/production-env-export.env1

이 검사는 framework safety, Agent trust/endpoint/JWT/checkpoint 설정, 세 embedding capability 계약, 조건부 Typesense credential, canonical ClamAV, 활성화된 Langfuse의 전체 host/keypair를 다룹니다. 설정 형식을 검증할 뿐 외부 service가 수신 runtime에서 도달 가능한지는 증명하지 않습니다.

함께 읽기

설정의 소유권 — deployment, platform, tenant, App state 중 값이 속할 위치를 결정합니다.
Search 설정 프로필 — Database, Typesense, Knowledge semantic generation을 안전하게 구성합니다.
Agent Gateway 켜기 — Shared secret을 등록하고 두 Agent runtime 경계를 검증합니다.
Google Analytics 운영 — Consent 기반 browser collection과 server-side reporting을 구성합니다.
Octane·FrankenPHP 런타임 — Laravel 값 변경 뒤 worker를 재시작할 시점을 이해합니다.