# 환경 변수

> NeuroChain의 모든 환경 변수 — 노드(네트워크, 합의, 경제, AI, IBC v2, 보안), gateway, 웹 앱, 문서 사이트, MCP 서버 — 와 그 기본값, 각 변수가 바꾸는 내용을 정리합니다.

Source: https://docs.nro.world/ko/operate/env

모든 서비스는 환경 변수에서 설정을 읽으며, 저장소의 `.env.example`에 주석과 함께 나열되어 있습니다. 아래 기본값은 변수가 설정되지 않았을 때 코드가 사용하는 값입니다.

일부 프로토콜 값(가스 예산, 스테이크, 보상, 슬래싱, AI 임계값)은 체인에 저장되는 **거버넌스 파라미터**입니다. 이 중 환경 변수가 있는 값의 경우, 환경 변수가 **해당 노드의 시작 시점에** 온체인 값을 덮어씁니다 — 테스트 네트워크용이며, 공유 네트워크에서는 모든 검증자가 같은 값을 사용해야 합니다. [거버넌스 → 파라미터](/ko/learn/governance#parameters)를 참고하십시오.

## 노드

### 네트워크와 신원

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `CHAIN_ENV` | `mainnet` | `mainnet`: 엄격한 서명, faucet 꺼짐, RPC는 localhost. `testnet`: 서명은 경고만, faucet 켜짐 |
| `NEUROCHAIN_NETWORK` | `neurochain-mainnet-1` | 네트워크 / 체인 id |
| `NEUROCHAIN_DATA_DIR` | `./data` | 데이터 디렉터리(상태, WAL, 키) |
| `NEUROCHAIN_MODELS_DIR` | `./models` | AI 모델 가중치 |
| `NEUROCHAIN_RPC_PORT` | `9933` | HTTP RPC 포트 |
| `NEUROCHAIN_RPC_HOST` | `localhost` (mainnet) / `0.0.0.0` (testnet) | RPC 바인드 주소 |
| `NEUROCHAIN_P2P_PORT` | `30333` | P2P 포트(합의도 전달) |
| `NEUROCHAIN_P2P_PORT_MIN` / `_MAX` | `1024` / `65534` | 허용되는 피어 포트 범위 |
| `NEUROCHAIN_NODE_ADDR` | `localhost:<p2p port>` | 피어가 이 노드에 접속할 때 사용하는 주소로, `0.0.0.0`이면 안 됩니다. 노드를 제네시스 검증자 항목과 대응시킵니다 |
| `NEUROCHAIN_BOOTSTRAP` | — | 시작 시 연결할 피어(쉼표로 구분) |
| `NEUROCHAIN_PEER_DISCOVERY_SECS` | `30` | 피어 탐색 주기 |
| `NEUROCHAIN_P2P_CONN_RATE_LIMIT` | `20` | IP당 초당 인바운드 P2P 연결 수 |
| `NEUROCHAIN_TLS_CERT`, `NEUROCHAIN_TLS_KEY` | — | RPC를 HTTPS로 제공 |

### 제네시스

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `NEUROCHAIN_GENESIS_VALIDATORS` | 이 노드만 | `neuro:name.node|p2p_host:port|stake_nro|trust|ml_dsa_pubkey_hex|owner.human,…` — 모든 검증자에서 동일해야 합니다. [노드 실행](./node#a-multi-validator-network) 참고 |
| `NEUROCHAIN_GENESIS_ACCOUNTS` | — | `neuro:addr.human|nro,…` — 초기 잔액 |
| `NEUROCHAIN_FAUCET_BALANCE` | 1 000 000 000 NRO | 제네시스 시 faucet 볼트의 잔액 |
| `NEUROCHAIN_INITIAL_BALANCE` | `0` | 처음 보는 계정을 처음 읽을 때 입금되는 uNRO(테스트 네트워크 전용) |
| `NEUROCHAIN_GAS_SPONSOR` | `neuro:faucet.vault` | 온보딩 가스 스폰서 |
| `NEUROCHAIN_GAS_SPONSOR_FUND` | 1 000 000 NRO | 제네시스 시 스폰서의 가스 풀 |
| `NEUROCHAIN_CHECKPOINT_URL` | — | 빈 노드를 이 노드의 상태 스냅샷에서 시작 |

### 합의와 샤딩

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `NEUROCHAIN_MIN_VALIDATORS` | `7` | 이 값보다 적으면 노드가 내결함성 저하를 경고합니다 |
| `NEUROCHAIN_BLOCK_MS` | `200` | 트랜잭션이 있는 블록을 제안하기 전 최소 대기 시간 |
| `NEUROCHAIN_EMPTY_BLOCK_MS` | `2000` | 빈 블록을 제안하기 전 최소 대기 시간 |
| `NEUROCHAIN_SYNC_HISTORY_BLOCKS` | `10000` | 따라잡는 피어에게 제공하기 위해 보관하는 결정된 블록 수 |
| `NEUROCHAIN_JAIL_BLOCKS` | `10000` | 슬래싱 후 jail 기간(거버넌스 `jail_blocks`) |
| `NEUROCHAIN_SLASH_FRACTION_DOUBLE_SIGN_BPS` | `500` | 이중 서명 슬래싱, `min_stake`의 베이시스 포인트 |
| `NEUROCHAIN_SLASH_REWARD_FRACTION_BPS` | `100` | 슬래싱 중 신고자 몫 |
| `NEUROCHAIN_SLASH_EVIDENCE_WINDOW` | `10000` | 증거로 입증할 수 있는 가장 오래된 위반(블록 단위) |
| `NEUROCHAIN_SHARD_ID` | — | 이 노드가 담당하는 샤드. 설정하지 않으면 단일 샤드 |
| `NEUROCHAIN_SHARDS` | 샤드 id가 있으면 `4`, 없으면 `1` | 샤드 수 |
| `NEUROCHAIN_SHARD_DIR_PREFIX` | `shard` | 샤드별 하위 디렉터리 이름 |

### 경제와 mempool

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `NEUROCHAIN_UNBONDING_BLOCKS` | 거버넌스(1 512 000) | 스테이킹 잠금 |
| `NEUROCHAIN_REWARD_INTERVAL_BLOCKS` | 거버넌스(216 000) | 보상 지급 간 블록 수 |
| `NEUROCHAIN_FUEL_PER_GAS_UNIT` | `20000` | 가스 단위당 컨트랙트 fuel |
| `NEUROCHAIN_MAX_SPONSORED_FEE` | `100000` uNRO | 가스 풀이 트랜잭션당 지불하는 최대 수수료 |
| `NEUROCHAIN_MAX_MEMPOOL` | `10000` | 보관하는 대기 트랜잭션 수 |
| `NEUROCHAIN_MAX_PENDING_PER_ACCOUNT` | `64` | 발신자당 대기 트랜잭션 수 |
| `NEUROCHAIN_RBF_MIN_BUMP_PCT` | `10` | 대기 트랜잭션을 교체하는 데 필요한 가스 가격 인상률 |
| `NEUROCHAIN_MIN_FEE_PER_GAS` | `0` | 추가 mempool 가격 하한 |
| `NEUROCHAIN_FAUCET_MAX_NRO` | `100` | 최대 faucet 요청(테스트 네트워크) |
| `NEUROCHAIN_FAUCET_COOLDOWN_SECS` | `86400` | 주소별 faucet 쿨다운. `0` = 없음 |

### AI

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `MONITOR_INTERVAL_SECS` | `20` | 배포된 컨트랙트의 재감사 주기 |
| `MONITOR_SCORE_THRESHOLD` | `10` | 인증서 업데이트를 일으키는 점수 변화 |
| `NEUROCHAIN_SENTINEL_POLICY_ENABLED` | 거버넌스(`0`) | Sentinel 정책 계층 켜기/끄기 |
| `NEUROCHAIN_SENTINEL_HOLD_THRESHOLD` | 거버넌스(`60`) | 이체가 보류되기 시작하는 점수 × 100 |
| `NEUROCHAIN_SENTINEL_STEPUP_THRESHOLD` | 거버넌스(`70`) | 소유자 확인이 필요해지는 점수 × 100 |
| `NEUROCHAIN_SENTINEL_HOLD_BLOCKS` | 거버넌스(`50`) | 자동 해제 지연 |
| `NEUROCHAIN_SENTINEL_CONFIRM_EXPIRY_BLOCKS` | 거버넌스(`1000`) | 환불 전 확인 대기 시간 |
| `NEUROCHAIN_SENTINEL_AGENT_CONFIRM_THRESHOLD` | 거버넌스(`60`) | 세션 키 이체의 임계값 |
| `NEUROCHAIN_TRUST_ACTIVATION_BLOCKS` | 거버넌스(`300`) | 신뢰 수신자가 효력을 갖기까지의 지연 |
| `AI_EXPORT_MAX_LIMIT` | `5000` | AI 데이터 내보내기 요청당 행 수 |

### IBC v2

[IBC v2와 샤딩 → 구성](./ibc#configuration)을 참고하십시오: `NEUROCHAIN_IBC_OPERATOR_PUBKEYS`, `NEUROCHAIN_IBC_TRUSTED_PUBKEYS`, `NEUROCHAIN_IBC_REQUIRE_HEADER`, `NEUROCHAIN_IBC_REQUIRE_PACKET_COMMITMENT`, `NEUROCHAIN_IBC_TIMEOUT_BLOCKS`, `NEUROCHAIN_IBC_MAX_PACKET_UNRO`, `NEUROCHAIN_IBC_MAX_CHANNEL_ESCROW_UNRO`, `NEUROCHAIN_IBC_NATIVE_DENOM`.

### 네이티브 자산

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `NEUROCHAIN_ASSET_ISSUERS` | — | 제네시스 시 `verified` 발행자 등급을 받는 주소 |
| `NEUROCHAIN_RESERVED_SYMBOLS` | — | 제네시스 시 예약되는 티커 |
| `NEUROCHAIN_RESERVED_NAMES` | — | 제네시스 시 모든 유료 주소와 자산 이름에 대해 예약되는 이름: `name` 또는 `name|owner1;owner2`, 쉼표로 구분. 이후에는 투표로만 변경됩니다 |
| `NEUROCHAIN_VALIDATOR_OWNER` | — | `NEUROCHAIN_GENESIS_VALIDATORS`가 설정되지 않았을 때 단일 자체 검증자의 소유자 `.human`(mainnet에서 필수) |

두 변수 모두 제네시스 시 한 번만 읽히며, 이후 레지스트리는 거버넌스를 통해서만 변경됩니다.

### 접근과 한도

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `NEUROCHAIN_RPC_RATE_LIMIT` | `100` | IP당 초당 RPC 요청 수 |
| `CORS_ALLOWED_ORIGINS` | `*` | 허용되는 브라우저 출처 |
| `NEUROCHAIN_INTERNAL_TOKEN` | — | 내부 엔드포인트에 필요한 `X-Internal-Token` |
| `NEUROCHAIN_SNAPSHOT_TOKEN` | — | `/api/v1/state/snapshot`에 필요한 bearer 토큰 |
| `NEUROCHAIN_ALLOW_SERVER_DERIVE` | `false` | 테스트 네트워크에서 `POST /api/v1/wallet/derive-address`(복구 구문을 받음)를 허용. mainnet에서는 항상 꺼짐 |
| `RUST_LOG` | `neurochain=info,warn` | 로그 수준 |

## Gateway

[Gateway](./gateway#configuration) 페이지에 설명과 함께 나열되어 있습니다: `PORT`, `NODE_RPC_URL`, `NEUROCHAIN_SHARD_NODES`, `SHARD_NODE_URLS`, `NETWORK_ID`, `CORS_ALLOWED_ORIGINS`, `TLS_CERT`, `TLS_KEY`, 요청 한도(`GLOBAL_RL_MAX_RPS`, `AI_RL_MAX_RPM`, `WS_*`), 체인 감시(`POLL_NODE_INTERVAL_MS`, `SENTINEL_*`, `ALERT_COOLDOWN_MS`), faucet(`FAUCET_AMOUNT`, `FAUCET_COOLDOWN_SECS`, `REDIS_URL`), AI 도구(`ANTHROPIC_API_KEY`, `SMARTFORGE_*`, `AI_EXPORT_TOKEN`, `ASSISTANT_*`).

## 웹 앱

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `WEB_PORT` | `8080` | 개발 서버 포트 |
| `WEB_HOST` | `localhost` | 개발 서버 바인드. 네트워크에 노출하려면 `0.0.0.0` |
| `GATEWAY_URL` | `http://localhost:3000` | 개발 서버가 `/api`와 `/ws`를 프록시하는 gateway |
| `VUE_APP_NEUROCHAIN_RPC` | —(같은 출처) | 빌드에 고정된 API 기본 URL을 강제로 넣습니다 |
| `VUE_APP_SITE_URL`, `VUE_APP_SITE_NAME`, `VUE_APP_SITE_OG_IMAGE` | — | 배포된 앱의 메타데이터 |
| `VUE_APP_DOCS_URL` | — | 이 문서로의 링크 |

## 문서 사이트

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `DOCS_SITE_URL` | `https://docs.nro.world` | 정규 URL, sitemap, `hreflang`, `llms.txt` |
| `DOCS_OG_IMAGE` | `/og-image.png` | 소셜 미리보기 이미지 |
| `DOCS_GOOGLE_SITE_VERIFICATION`, `DOCS_BING_SITE_VERIFICATION` | — | 검색 콘솔 소유권 토큰 |
| `DOCS_HOST`, `DOCS_PORT` | `localhost`, `5173` | 개발 서버 |
| `DOCS_BASE` | `/` | 기본 경로 |

## MCP 서버

| 변수 | 기본값 | 의미 |
|------|--------|------|
| `NEUROCHAIN_MCP_CONFIG` | — | JSON 구성 파일 경로 — [AI 에이전트(MCP)](/ko/build/mcp) 참고 |