설정 참조

서비스

Private Channels 인스턴스를 실행한다는 것은 다음 Docker Compose 서비스들을 직접 관리한다는 의미입니다:

컨테이너	역할
`private-channel-postgres-primary`	쓰기 노드 상태 데이터베이스 (PostgreSQL 16)
`private-channel-postgres-replica`	읽기 노드 상태 데이터베이스 (스트리밍 복제본)
`private-channel-postgres-indexer`	인덱서 및 운영자 데이터베이스
`private-channel-write-node`	트랜잭션 수신 및 실행 (포트 8900, 루프백 전용)
`private-channel-read-node`	RPC 읽기 쿼리 처리 (포트 8901, 루프백 전용)
`private-channel-gateway`	쓰기 노드와 읽기 노드 간 요청 라우팅; RBAC 적용 (포트 8899)
`private-channel-indexer-solana`	Yellowstone gRPC를 통해 Solana의 `Deposit` 이벤트 모니터링
`private-channel-indexer-private-channel`	RPC 폴링을 통해 채널의 `Burn` 이벤트 모니터링
`private-channel-operator-solana`	입금 확인 시 채널 토큰 발행
`private-channel-operator-private-channel`	출금 확인 시 메인넷에서 `ReleaseFunds` 호출
`private-channel-auth`	선택적 JWT/RBAC 서비스 (Docker 프로필: `auth`)

관측성 컨테이너(prometheus, grafana, cadvisor)도 함께 포함되어 있습니다.

게이트웨이

devnet Docker Compose 설정에는 합리적인 기본값이 적용되어 있습니다. Docker 외부에서 게이트웨이를 실행하거나 프로덕션 환경에 배포할 경우에만 재정의하세요.

환경 변수	기본값	필수 여부	설명
`GATEWAY_PORT`	`8899` (devnet)	아니요	수신 포트
`GATEWAY_WRITE_URL`	`http://write-node:8900` (devnet 환경 파일 값; 바이너리 기본값 없음)	예	쓰기 노드 URL - `sendTransaction` 요청이 라우팅되는 곳
`GATEWAY_READ_URL`	`http://read-node:8901` (devnet 환경 파일 값; 바이너리 기본값 없음)	예	읽기 노드 URL - 그 외 모든 RPC 메서드가 라우팅되는 곳
`GATEWAY_CORS_ALLOWED_ORIGIN`	`*`	아니요	`Access-Control-Allow-Origin` 헤더 값
`JWT_SECRET`	-	아니요	RBAC 활성화; 인증 서비스의 `JWT_SECRET`과 일치해야 함
`AUTH_DATABASE_URL`	-	`JWT_SECRET` 설정 시	지갑 소유권 확인용 인증 DB
`AUTH_DATABASE_MAX_CONNECTIONS`	`10`	아니요	인증 DB 연결 풀 크기
`METRICS_PORT`	`9101`	아니요	Prometheus 메트릭 포트
`RUST_LOG`	`info`	아니요	로그 수준

GATEWAY_WRITE_URL과 GATEWAY_READ_URL은 Docker 내에서 실행 시 Docker Compose 서비스 호스트명(write-node, read-node)을 사용합니다. localhost 동등값은 Docker 외부에서 게이트웨이 바이너리를 직접 실행할 때만 사용하세요.

게이트웨이 바이너리 자체의 내장 기본값은 GATEWAY_PORT가 8898입니다. .env.example과 .env.devnet은 모두 이를 8899로 설정하며, 이것이 Docker Compose 설정에서 실제로 사용되는 값입니다(versions.env는 툴체인 및 이미지 버전 고정값만 보유하며 서비스 포트는 포함하지 않음). 8898 기본값은 환경 파일 없이 바이너리를 직접 실행할 때만 적용됩니다.

GATEWAY_CORS_ALLOWED_ORIGIN의 기본값은 *로, 브라우저에서 모든 출처가 게이트웨이를 호출할 수 있도록 허용합니다. 프로덕션 배포 전에 애플리케이션의 실제 출처로 제한하세요.

쓰기 노드 및 읽기 노드

전체 쓰기 노드 및 읽기 노드 설정 참조는 저장소 내 docs/CONFIG.md 에 있습니다.

인증 서비스

환경 변수	필수 여부	설명
`JWT_SECRET`	예	HS256 서명 시크릿; 게이트웨이의 `JWT_SECRET`과 일치해야 함
`AUTH_PORT`	아니요 (기본값 `8903`)	수신 포트
`AUTH_DATABASE_URL`	예	인증 데이터베이스용 PostgreSQL 연결 문자열
`CORS_ALLOWED_ORIGIN`	아니요 (기본값 `*`)	이 서비스의 `Access-Control-Allow-Origin` 헤더 값 (게이트웨이의 `GATEWAY_CORS_ALLOWED_ORIGIN`과 독립적)
`AUTH_DATABASE_MAX_CONNECTIONS`	아니요 (기본값 `10`)	인증 DB 연결 풀 크기

서비스 포트 참조

서비스	호스트 포트	바인딩
게이트웨이	8899	모든 인터페이스
쓰기 노드	8900	루프백 전용
읽기 노드	8901	루프백 전용
스트리머	8902	내부 전용 (`expose`, 호스트에 미게시); devnet 스택에 포함되지 않음
인증 서비스	8903	모든 인터페이스
운영자 메트릭	9102, 9103	모든 인터페이스
Grafana	37429	모든 인터페이스
Prometheus	9090	모든 인터페이스
cAdvisor	8080	모든 인터페이스

보안 참고: 쓰기 노드 및 읽기 노드 포트는 루프백 (127.0.0.1)에만 바인딩됩니다. 게이트웨이, 인증 서비스, 운영자 메트릭, Grafana, Prometheus, cAdvisor는 모두 devnet Docker Compose 설정에서 모든 네트워크 인터페이스에 게시됩니다. 로컬 개발 이상의 환경에서는 호스트 또는 네트워크 수준에서 방화벽을 설정하세요; RBAC는 게이트웨이 자체의 JSON-RPC 메서드만 보호하며, 다른 서비스는 보호하지 않습니다. 스트리머는 예외로, Docker가 호스트에 게시하지 않는 비인증 내부 피드입니다.

네트워크 요구 사항

방화벽 규칙 및 대역폭 요구 사항은 저장소 내 docs/TECHNICAL_REQUIREMENTS.md 를 참조하세요.