MIJI DApp Server Docs

Redis 설정 및 복구 가이드

1. 기본 설정

• Docker Compose에서 redis 서비스는 redis:7-alpine 이미지를 사용하며 /data에 redis-data 볼륨을 마운트합니다.
• 실행 옵션: --appendonly yes --appendfsync everysec
  → 재기동 시 데이터 손실을 최대 1초 이내로 제한.
• 운영 환경에서도 동일한 AOF 설정 + 주기적 RDB 스냅샷을 권장합니다.

2. Bull 큐/Nonce 복구 절차

1. API 서버 재기동
   • JanitorService가 MongoDB의 status: DEPLOYING 컨트랙트와 PENDING/PROCESSING 민팅 주문을 Bull 큐에 다시 등록합니다.
2. Nonce 동기화
   • 서버 기동 시 NonceBootstrapService가 ALLOWED_CHAIN_IDS × 서비스 지갑 조합을 순회하면서 RPC의 getTransactionCount(..., 'pending') 결과를 기준으로 Redis를 자동 동기화합니다. (Redis에는 “최근 사용한 nonce”가 저장되므로, 펜딩 값에서 1을 뺀 값이 들어가고 다음 트랜잭션부터 올바른 nonce가 부여됩니다.)
   • 추가로 수동 리커버리가 필요하면 pnpm --filter server redis:sync-nonce <chainId> <address> 명령을 호스트에서 실행하세요. (예: pnpm --filter server redis:sync-nonce 43114 0x1234...)
3. 재큐잉 조건
   • Janitor는 txHash가 비어 있는 주문만 재삽입합니다. 이미 브로드캐스트된 주문은 status=SENT로 남아 자동 재삽입되지 않습니다.

3. 운영 체크리스트

• Redis 인스턴스가 AOF를 켜고 있는지, 디스크 용량이 충분한지 정기적으로 확인하세요.
• 재부팅/장애 이후에는 위 복구 절차(1~2)를 수행하고 로그로 완료 여부를 기록합니다.
• 필요 시 scripts/sync-nonce.ts를 여러 주소에 대해 반복 실행할 수 있도록 쉘 스크립트/문서를 준비해 두는 것을 권장합니다.

4. Redis에 적재되는 주요 데이터 흐름

| 영역 | Redis Key / Queue | 쓰기 시점 | 이후 플로우 | | — | — | — | — | | 배포 큐 | Bull deployment-queue (job data: {contractId, chainId, ...}) | ContractsService.orderDeployment()에서 Mongo 문서 생성 후 Queue.add() 호출 | ContractsProcessor가 job을 active → completed/failed로 이동. 성공 시 Mongo DeployedContract 갱신, deployment.success 이벤트 발생. 실패 시 status=FAILED, deployment.failed 이벤트. | | 민팅 큐 | Bull minting-queue (job data: {orderId}) | MintingService.createOrder()에서 Mongo MintingOrder 생성 후 큐 적재 | MintingProcessor가 민팅 트랜잭션 전송 → status=SENT + txHash 기록 → 확정 시 status=CONFIRMED, 실패 시 status=FAILED. 이벤트(mint.confirmed/mint.failed)가 Webhook/Bull에 전달됨. | | Webhook 큐 | Bull webhook-queue (job data: {eventType, payload, relatedIds}) | WebhookService.sendWebhook()가 이벤트 리스너에서 호출 | WebhookProcessor가 HTTP POST 수행, 응답 상태에 따라 WebhookLog에 SUCCESS/FAILED 기록, 실패 시 Bull 재시도. | | Nonce 관리 | String key nonce:<chainId>:<address> | NonceManagerService.getNextNonce() 호출 시 INCR로 증가, setNonce/resetNonce로 재설정 가능 | 컨트랙트/민팅 Processor가 동일 주소 nonce를 공유. Redis 초기화 시 sync-nonce.ts로 RPC 값 복원. | | Janitor 재큐 로직 | 위 큐와 동일 | Redis가 초기화되거나 job이 stuck일 때 Mongo 상태 기준으로 재적재 | deployment-queue: status=DEPLOYING & deploymentTxHash 미존재 건만 재큐. minting-queue: status∈{PENDING,PROCESSING} & txHash 미존재 건만 재큐. |

Bull의 상태 전이는 waiting → active → completed/failed로 Redis에 저장되며, removeOnComplete/removeOnFail 옵션 덕분에 일정 개수 이후 자동 삭제됩니다. 장애 조사 시에는 Redis CLI로 bull:deployment-queue:* 키를 조회해 현재 job 상태를 확인할 수 있습니다.