# A301 MMO Game Server - 프로젝트 보고서

---

## 1. 프로젝트 개요

| 항목 | 내용 |
|------|------|
| 프로젝트명 | A301 MMO Game Server |
| 언어 | C# (.NET 9.0) |
| 네트워크 | LiteNetLib (UDP 기반) |
| 직렬화 | Protocol Buffers (protobuf-net) |
| 데이터베이스 | MySQL (Dapper ORM) |
| 로깅 | Serilog |
| 배포 | Docker Compose |

---

## 2. 프로젝트 구현 구성

### 2.1 디렉토리 구조

```
a301_mmo_game_server/
├── MMOTestServer/
│   ├── MMOserver/                    # 게임 서버 실행 프로젝트
│   │   ├── Api/
│   │   │   └── RestApi.cs            # JWT 토큰 검증 (외부 API 호출)
│   │   ├── Game/
│   │   │   ├── GameServer.cs         # 메인 게임 서버 (ServerBase 상속)
│   │   │   ├── Player.cs             # 플레이어 엔티티 (상태 + 위치)
│   │   │   ├── Channel/
│   │   │   │   ├── Channel.cs        # 단일 게임 채널
│   │   │   │   ├── ChannelManager.cs # 채널 관리 (Singleton)
│   │   │   │   └── Maps/
│   │   │   │       └── Robby.cs      # 로비 맵
│   │   │   └── Engine/
│   │   │       └── Vector3.cs        # 3D 위치 구조체
│   │   ├── Packet/
│   │   │   ├── PacketHeader.cs       # PacketCode Enum 정의
│   │   │   └── PacketBody.cs         # 모든 패킷 클래스 (ProtoContract)
│   │   ├── RDB/                      # 데이터베이스 계층
│   │   │   ├── DbConnectionFactory.cs
│   │   │   ├── Models/
│   │   │   ├── Repositories/
│   │   │   ├── Services/
│   │   │   └── Handlers/
│   │   ├── Utils/
│   │   │   ├── Singleton.cs
│   │   │   └── UuidGeneratorManager.cs
│   │   ├── Program.cs               # 서버 진입점
│   │   └── config.json              # DB 접속 설정
│   │
│   ├── ServerLib/                    # 핵심 네트워크 라이브러리 (DLL)
│   │   ├── Service/
│   │   │   ├── ServerBase.cs         # 추상 서버 베이스 클래스
│   │   │   ├── Session.cs            # 세션 상태 관리
│   │   │   └── SessionManager.cs     # 세션 매니저
│   │   ├── Packet/
│   │   │   ├── PacketSerializer.cs   # Protobuf 직렬화 (4바이트 헤더)
│   │   │   └── PacketType.cs         # 기본 패킷 타입
│   │   ├── RDB/
│   │   │   ├── Database/
│   │   │   │   └── IDbConnectionFactory.cs
│   │   │   ├── Repositories/
│   │   │   │   └── ARepository.cs    # 제네릭 비동기 Repository 베이스
│   │   │   └── Handlers/
│   │   │       ├── HelperHandler.cs
│   │   │       └── Response.cs
│   │   └── Utils/
│   │       └── CrashDumpHandler.cs   # 크래시 덤프 핸들러
│   │
│   └── MMOserver.sln
│
├── ClientTester/                     # 클라이언트 테스트 도구
│   └── EchoClientTester/
│       ├── DummyService/             # 더미 플레이어 시뮬레이션
│       │   ├── DummyClientService.cs
│       │   ├── DummyClients.cs
│       │   └── MapBounds.cs
│       ├── EchoDummyService/         # Echo/Ping 테스트
│       │   ├── EchoDummyClientService.cs
│       │   └── EchoDummyClients.cs
│       └── Packet/
│
├── compose.yaml                      # Docker Compose (MySQL + Server)
└── ReadMe.md                         # DB 아키텍처 문서
```

### 2.2 핵심 모듈 구성

#### ServerLib (네트워크 코어 라이브러리)

| 모듈 | 파일 | 역할 |
|------|------|------|
| ServerBase | `ServerBase.cs` | 추상 서버 - 연결/해제/패킷 수신 이벤트 처리 |
| Session | `Session.cs` | 인증 상태 + Peer 매핑 (hashKey, token) |
| PacketSerializer | `PacketSerializer.cs` | 4바이트 헤더(type 2B + size 2B) + Protobuf 페이로드 |
| ARepository | `ARepository.cs` | 제네릭 비동기 CRUD (Dapper.Contrib 기반) |
| CrashDumpHandler | `CrashDumpHandler.cs` | 예외 로깅 + 메모리 힙 덤프 생성 |

#### MMOserver (게임 로직)

| 모듈 | 파일 | 역할 |
|------|------|------|
| GameServer | `GameServer.cs` | 패킷 라우팅 + 게임 로직 처리 (ServerBase 상속) |
| Player | `Player.cs` | 플레이어 데이터 (위치, HP/MP, 닉네임 등) |
| Channel | `Channel.cs` | 채널 단위 플레이어 그룹 관리 |
| ChannelManager | `ChannelManager.cs` | 전역 채널 관리 (Singleton) |
| RestApi | `RestApi.cs` | JWT 토큰 검증 (외부 인증 API 연동) |
| UuidGeneratorManager | `UuidGeneratorManager.cs` | Lock-free 고유 ID 생성기 |

### 2.3 패킷 프로토콜 정의

| 코드 | 패킷명 | 전송 방식 | 설명 |
|------|--------|-----------|------|
| 1 | `ACC_TOKEN` | Reliable | 실제 JWT 토큰 인증 |
| 1001 | `DUMMY_ACC_TOKEN` | Reliable | 더미 클라이언트 인증 |
| 1000 | `ECHO` | Reliable | 네트워크 테스트 (Ping) |
| 2 | `LOAD_CHANNEL` | Reliable | 채널 목록 응답 |
| 3 | `INTO_CHANNEL` | Reliable | 채널 입장 |
| 5 | `UPDATE_CHANNEL_USER` | Reliable | 유저 입장/퇴장 알림 |
| 6 | `TRANSFORM_PLAYER` | **Unreliable** | 이동/회전 동기화 |
| 7 | `ACTION_PLAYER` | Reliable | 공격/스킬/회피 액션 |
| 8 | `STATE_PLAYER` | Reliable | HP/MP 상태 동기화 |

### 2.4 데이터베이스 계층 (RDB)

**아키텍처 패턴**: `Handler → Service → Repository → DB`

```
[Handler]  API 요청 수신 / JSON 응답 반환
    ↓
[Service]  비즈니스 로직 (검증, 변환)
    ↓
[Repository]  데이터 접근 (Dapper CRUD)
    ↓
[MySQL]  커넥션 풀 (Min: 5, Max: 100)
```

### 2.5 스레드 모델

| 구분 | 방식 | 설명 |
|------|------|------|
| 네트워크 루프 | **싱글 스레드** | `netManager.PollEvents()` 1ms 주기 호출 |
| 패킷 처리 | 동기 처리 | Poll 루프 내에서 순차적 처리 |
| JWT 검증 | async/await | `HttpClient` 비동기 호출 |
| DB 연산 | async/await | Dapper 비동기 쿼리 |
| UUID 생성 | lock 기반 | 스레드 안전 ID 할당 |

---

## 3. 파이프라인

### 3.1 클라이언트 접속 ~ 게임 플레이 전체 흐름

```
[1] 클라이언트 접속 (UDP)
 │
 ├─ LiteNetLib ConnectionRequest
 │   └─ ServerBase.OnConnectionRequest() → 연결 키 검증
 │
 ▼
[2] 인증 (Authentication)
 │
 ├─ 클라이언트 → 서버: ACC_TOKEN 또는 DUMMY_ACC_TOKEN 패킷 전송
 │
 ├─ [실제 인증] JWT 토큰 → RestApi.VerifyTokenAsync()
 │   └─ POST https://a301.api.tolelom.xyz/api/auth/verify
 │       ├─ 성공 → username 반환, hashKey 생성
 │       ├─ 401 → 즉시 실패 (토큰 무효)
 │       └─ 기타 오류 → 3회 재시도 (1초 간격)
 │
 ├─ [더미 인증] hashKey 직접 수신 (≤1000 범위)
 │
 ├─ Session 객체 생성 (hashKey, token, peer)
 │   └─ peer.Tag에 Session 저장
 │
 ▼
[3] 채널 선택
 │
 ├─ 서버 → 클라이언트: LOAD_CHANNEL (채널 목록)
 ├─ 클라이언트 → 서버: INTO_CHANNEL (채널 선택)
 │
 ├─ 서버 처리:
 │   ├─ 채널에 플레이어 추가
 │   ├─ 기존 플레이어 목록 조회
 │   └─ 서버 → 클라이언트: INTO_CHANNEL 응답 (기존 플레이어 리스트)
 │
 ├─ 서버 → 채널 전체: UPDATE_CHANNEL_USER (새 플레이어 입장 알림)
 │
 ▼
[4] 게임 루프 (실시간 동기화)
 │
 ├─ TRANSFORM_PLAYER [Unreliable]
 │   └─ 위치(X,Y,Z) + 회전(RotY) → 채널 내 브로드캐스트
 │
 ├─ ACTION_PLAYER [ReliableOrdered]
 │   └─ 공격/스킬/회피 → 채널 내 브로드캐스트
 │
 ├─ STATE_PLAYER [ReliableOrdered]
 │   └─ HP/MP 상태 변경 → 채널 내 브로드캐스트
 │
 ▼
[5] 연결 종료
 │
 ├─ 클라이언트 → 서버: EXIT_CHANNEL
 ├─ 서버: 채널에서 플레이어 제거
 ├─ 서버 → 채널 전체: UPDATE_CHANNEL_USER (퇴장 알림)
 └─ 세션 정리 및 Peer 해제
```

### 3.2 패킷 처리 파이프라인

```
수신 (OnNetworkReceive)
   ↓
┌─────────────────────────────────────┐
│  4바이트 헤더 파싱                    │
│  ├─ type: ushort (2B) → 패킷 종류   │
│  └─ size: ushort (2B) → 페이로드 크기 │
└─────────────────────────────────────┘
   ↓
┌─────────────────────────────────────┐
│  Protobuf 역직렬화                    │
│  └─ byte[] → 패킷 객체              │
└─────────────────────────────────────┘
   ↓
┌─────────────────────────────────────┐
│  타입별 분기                          │
│  ├─ ECHO (1000) → HandleEcho()     │
│  ├─ AUTH (1/1001) → HandleAuth()   │
│  └─ GAME (2~8) → HandlePacket()   │
└─────────────────────────────────────┘
   ↓
┌─────────────────────────────────────┐
│  게임 로직 처리                       │
│  └─ 채널 내 브로드캐스트               │
└─────────────────────────────────────┘
   ↓
송신 (SendTo / BroadcastToChannel)
```

### 3.3 세션 관리 파이프라인

```
PendingPeers (미인증)           Sessions (인증 완료)
Dictionary<int, NetPeer>       Dictionary<long, NetPeer>

  접속 시 등록 ──────────────→  인증 성공 시 이동
  (peerId 기반)                 (hashKey 기반)

                               TokenHash (토큰 매핑)
                               Dictionary<string, long>
                               token → hashKey 조회
```

- **재접속 처리**: 동일 hashKey로 재접속 시 기존 Peer 강제 해제 → 새 Peer로 교체
- **채널 유지**: 재접속 시 기존 채널 멤버십 유지 (채널 선택 스킵)

### 3.4 빌드 및 배포 파이프라인

```
소스 코드
   ↓
dotnet build (MMOserver.sln)
   ├─ ServerLib.csproj → ServerLib.dll
   └─ MMOserver.csproj → MMOserver.exe
   ↓
Docker Build (Dockerfile)
   ↓
Docker Compose (compose.yaml)
   ├─ MySQL 컨테이너
   └─ MMOServer 컨테이너
       └─ UDP 포트: 9050, 9500
```

---

## 4. 문제점 - 해결

### 4.1 해결된 문제

#### [P1] 이동 패킷 재전송 문제
- **문제**: 이동(Transform) 패킷이 `ReliableOrdered`로 전송되어 패킷 손실 시 재전송 발생 → 위치 동기화 지연, Head-of-Line 블로킹
- **해결**: 이동 패킷을 `Unreliable` 전송으로 변경 (`commit: 42f0ef1`)
- **효과**: 실시간성 향상, 네트워크 지연 최소화 (오래된 위치 데이터는 폐기)

#### [P2] 로그인 인증 실패 시 재시도 부재
- **문제**: JWT 토큰 검증 API 호출이 일시적 네트워크 오류로 실패 시 즉시 인증 실패 처리
- **해결**: 3회 재시도 로직 추가 (1초 간격), 401 응답은 즉시 실패 (`commit: c8ce36a`)
- **효과**: 일시적 API 장애에 대한 내결함성 확보

#### [P3] 토큰 → HashKey 매핑 구조
- **문제**: 토큰과 hashKey 간의 매핑이 명확하지 않아 재접속/중복 접속 처리 어려움
- **해결**: `TokenHash` 딕셔너리 도입, 토큰 관리 로직 구조화 (`commit: bfa3394`)
- **효과**: 동일 토큰 재접속 시 기존 세션 정리 및 hashKey 재활용

#### [P4] 에코 클라이언트 수신 버그
- **문제**: 에코 테스트 클라이언트에서 수신 패킷 처리 오류
- **해결**: 수신 로직 버그 수정 (`commit: 18fd8a0`)

#### [P5] 서버 크래시 시 디버깅 정보 부족
- **문제**: 서버 비정상 종료 시 원인 파악 불가
- **해결**: `CrashDumpHandler` 구현 (`commit: 2be1302`)
  - Debug 빌드: `.log` 파일 (스택 트레이스)
  - Release 빌드: `.log` + `.dmp` 파일 (힙 덤프)
  - UnhandledException, UnobservedTaskException 모두 캡처
- **효과**: 프로덕션 환경 크래시 사후 분석 가능

#### [P6] 패킷 레이트 리미팅 부재
- **문제**: 클라이언트의 패킷 전송 빈도 제한 없음 → 패킷 플러딩 공격에 취약
- **해결**: `Session` 클래스에 슬라이딩 윈도우 방식 레이트 리미터 구현
  - 초당 최대 120 패킷 허용 (`MaxPacketsPerSecond`)
  - 초과 시 해당 패킷 드롭 + 경고 로그
  - 3회 연속 초과 시 강제 연결 해제
  - `ServerBase.OnNetworkReceive()`에서 인증된 패킷 처리 전 체크
- **적용 파일**: `Session.cs`, `ServerBase.cs`
- **효과**: 악의적 패킷 플러딩 방어, 서버 안정성 향상

#### [P7] 부하 테스트 도구 부재
- **문제**: 대규모 동시접속 시나리오 검증 도구 없음, 기존 더미 클라이언트는 10명 고정
- **해결**: `StressTest` 모듈 신규 구현 (`ClientTester/EchoClientTester/StressTest/`)
  - `StressTestClient.cs`: 이동 + Echo RTT 동시 측정 클라이언트
  - `StressTestService.cs`: 점진적 Ramp-up, 퍼센타일 레이턴시(P50/P95/P99), CSV 내보내기
  - `Program.cs`: CLI 인자 지원 (`stress -c 100 -d 60 --ip ...`) + 대화형 모드 3번 메뉴
- **효과**: N명 동시접속 시나리오 자동 검증, 성능 병목 지점 파악

### 4.2 현재 남아 있는 문제

#### [I1] 서버 사이드 위치 검증 미구현
- **현상**: 클라이언트가 전송하는 위치를 서버에서 검증하지 않음
- **영향**: 스피드핵, 텔레포트 등 치트 방어 불가
- **권장**: `MapBounds` 로직을 서버 사이드에 적용, 비정상 이동 감지 시 보정

#### [I2] 플레이어 데이터 DB 연동 미완성
- **현상**: 플레이어 데이터가 하드코딩된 기본값 사용 (TODO 주석 존재)
- **영향**: 캐릭터 정보 저장/불러오기 불가
- **권장**: Player 모델 DB 테이블 생성, 로그인 시 DB 조회

#### [I3] NPC / 파티 시스템 미구현
- **현상**: 패킷 코드(TRANSFORM_NPC, ACTION_NPC, UPDATE_PARTY 등)는 정의되어 있으나 처리 로직 없음
- **영향**: 게임 콘텐츠 부족
- **권장**: NPC AI 시스템, 파티 매칭 로직 순차 구현

---

## 5. 정리

### 5.1 아키텍처 요약

```
┌──────────────────────────────────────────────────────┐
│                    클라이언트 (Unity)                   │
└──────────────┬───────────────────────────┬────────────┘
               │ UDP (LiteNetLib)          │
┌──────────────▼───────────────────────────▼────────────┐
│                  ServerBase (네트워크 코어)              │
│  ┌────────────┐  ┌────────────┐  ┌─────────────────┐ │
│  │ 연결 관리    │  │ 패킷 직렬화  │  │   세션 관리      │ │
│  └────────────┘  └────────────┘  └─────────────────┘ │
└──────────────┬───────────────────────────┬────────────┘
               │                           │
┌──────────────▼───────────────┐  ┌────────▼────────────┐
│      GameServer (게임 로직)    │  │   RestApi (인증)     │
│  ┌─────────┐  ┌────────────┐ │  │  JWT 토큰 검증       │
│  │ Channel  │  │  Player    │ │  │  (외부 API 호출)     │
│  │ Manager  │  │  State     │ │  └─────────────────────┘
│  └─────────┘  └────────────┘ │
└──────────────┬───────────────┘
               │
┌──────────────▼───────────────┐
│     RDB Layer (데이터베이스)    │
│  Handler → Service → Repo    │
│         → MySQL              │
└──────────────────────────────┘
```

### 5.2 기술적 강점

| 항목 | 내용 |
|------|------|
| UDP 기반 통신 | LiteNetLib으로 TCP 오버헤드 없이 실시간 통신 |
| Protobuf 직렬화 | 컴팩트 바이너리 인코딩으로 대역폭 절약 |
| 이동 패킷 Unreliable | HOL 블로킹 방지, 최신 위치만 유효 |
| 싱글 스레드 이벤트 루프 | Lock 불필요, 동시성 이슈 최소화 |
| 비동기 DB/API | async/await로 네트워크 루프 블로킹 방지 |
| 크래시 덤프 | 프로덕션 환경 사후 분석 지원 |
| 계층화된 DB 구조 | Handler-Service-Repository 패턴 |
| Docker 배포 | 컨테이너화된 일관된 배포 환경 |

### 5.3 향후 작업 (Roadmap)

| 우선순위 | 작업 | 설명 |
|---------|------|------|
| **높음** | 플레이어 DB 연동 | 캐릭터 정보 저장/불러오기 완성 |
| **높음** | 서버 사이드 위치 검증 | 치트 방어를 위한 이동 유효성 검사 |
| **중간** | NPC 시스템 | AI 기반 NPC 이동/전투 로직 |
| **낮음** | 파티 시스템 | 파티 생성/참여/매칭 |
| **낮음** | 모니터링 대시보드 | 서버 상태/접속자 수 실시간 모니터링 |

> **완료된 항목**: 토큰 캐시 정리 (기 구현 확인), 패킷 레이트 리미팅 (적용 완료), 부하 테스트 도구 (구현 완료)

### 5.4 부하 테스트 도구 (StressTest)

`ClientTester/EchoClientTester/StressTest/` 에 구현됨.

#### 구성 파일

| 파일 | 역할 |
|------|------|
| `StressTestClient.cs` | 개별 스트레스 클라이언트 (이동 + Echo RTT 동시 측정) |
| `StressTestService.cs` | 테스트 오케스트레이터 (Ramp-up, 통계, CSV 내보내기) |

#### 기능

| 기능 | 설명 |
|------|------|
| 점진적 Ramp-up | N초 간격으로 클라이언트 추가 (서버 부하 단계적 증가) |
| 지속시간 제한 | 테스트 자동 종료 (초 단위, 0 = 무제한) |
| 실시간 통계 | 10초마다 접속수, 전송/수신 rate, AvgRTT 출력 |
| 퍼센타일 레이턴시 | P50, P95, P99, Min, Max, Avg RTT 계산 |
| 최악 클라이언트 분석 | RTT 상위 5명 상세 리포트 |
| CSV 내보내기 | `results/stress_{N}clients_{timestamp}.csv` 자동 저장 |

#### 사용법

**CLI 모드:**
```bash
# 기본 (50명, 60초)
dotnet run -- stress

# 커스텀
dotnet run -- stress -c 100 -d 120 --ip 192.168.0.10 --port 9500

# 전체 옵션
dotnet run -- stress \
  -c 200          # 클라이언트 수
  -d 60           # 테스트 시간 (초, 0=무제한)
  -i 100          # 전송 주기 (ms)
  -r 1000         # Ramp-up 간격 (ms)
  -b 20           # Ramp-up 당 추가 수
  --ip localhost  # 서버 IP
  --port 9500     # 서버 포트
```

**대화형 모드:**
```
메뉴에서 3번 선택 → 클라이언트 수, 테스트 시간 입력
```

#### 출력 예시

```
╔═══════════════════════════════════════════════╗
║           STRESS TEST 최종 리포트              ║
╠═══════════════════════════════════════════════╣
║ 테스트 시간 : 60.0초
║ 클라이언트  : 98/100 접속 유지
╠═══════════════════════════════════════════════╣
║ [처리량]
║   총 전송    : 118,200 패킷
║   총 수신    : 117,850 패킷
║   처리량     : 1,970.0 패킷/초
╠═══════════════════════════════════════════════╣
║ [레이턴시] (RTT 샘플: 59,100개)
║   Min        : 0.15 ms
║   Avg        : 1.23 ms
║   P50        : 0.89 ms
║   P95        : 3.45 ms
║   P99        : 8.12 ms
║   Max        : 25.67 ms
╚═══════════════════════════════════════════════╝
```

### 5.5 최근 개발 이력

| 커밋 | 내용 |
|------|------|
| `2be1302` | 크래시 덤프 기능 추가 (Release: 힙 덤프) |
| `42f0ef1` | 이동 패킷 Unreliable 전송으로 변경 |
| `bfa3394` | 토큰 → HashKey 생성 로직 구조 변경 |
| `c8ce36a` | 로그인 실패 시 재시도 로직 추가 |
| `18fd8a0` | 에코 클라이언트 수신 버그 수정 |

---

> **작성일**: 2026-03-05
> **프로젝트 상태**: 핵심 네트워크 인프라 완성, 게임 콘텐츠 확장 단계