에붕쿤들의 즐거운 에덴 생활 보장을 위한 구조선
에버소울 오프라인 프로젝트의 전체 가상 서버 시스템 및 네트워크 흐름도입니다. 안드로이드 기기나 에뮬레이터에서 발생하는 모든 네트워크 요청을 로컬 PC 서버로 유도하여 가상으로 응답을 리플레이하고 영속성을 처리합니다.
%%{init: {'theme': 'base', 'themeVariables': { 'background': '#1e1e1e', 'primaryColor': '#2d2d2d', 'primaryTextColor': '#ffffff', 'textColor': '#ffffff', 'primaryBorderColor': '#007acc', 'lineColor': '#007acc', 'clusterBkg': '#252526', 'clusterBorder': '#007acc' } }}%%
flowchart TB
classDef default fill:#333333,stroke:#007acc,stroke-width:2px,color:#ffffff,rx:8,ry:8;
classDef active fill:#094771,stroke:#50fa7b,stroke-width:3px,color:#ffffff,rx:8,ry:8,stroke-dasharray: 5 5;
classDef database fill:#4b3621,stroke:#f57c00,stroke-width:2px,color:#ffffff,rx:8,ry:8;
linkStyle default stroke:#007acc,stroke-width:2px,stroke-dasharray: 5 5;
subgraph ClientZone ["안드로이드 기기 / 에뮬레이터 환경"]
direction TB
Client["에버소울 게임 앱 (com.kakaogames.eversoul)"]
PortForward["ADB 역방향 터널링 (localhost:9991)"]
Client <-->|루프백 소켓 통신| PortForward
end
subgraph ServerZone ["Eversoul 오프라인 가상 서버 (Port: 9991)"]
direction TB
TCP["TCP 소켓 리스너"]
Parser["프로토콜 파서 & 라우터"]
TCP --> Parser
subgraph CoreEngines ["가상 서버 도메인"]
direction LR
Auth["인증 & IDP 모듈"]
Game["게임 콘텐츠 엔진"]
WS["실시간 세션 & 채팅"]
end
Parser -->|인증/로그인| Auth
Parser -->|게임 트랜잭션| Game
Parser -->|웹소켓 프레임| WS
subgraph ToolEngines ["관리 및 보조 모듈"]
direction LR
WebUI["웹 UI 대시보드 API"]
Proxy["리버스 프록시 하베스터"]
end
Parser -->|웹 어드민 경로| WebUI
Parser -->|미구현/외부 경로| Proxy
subgraph DataLayer ["데이터 저장소 레이어"]
direction LR
DB[("SQLite DB (account.db)")]
Fixtures[("JSON 픽스쳐 (responses/)")]
Tables[("메타 TBL 데이터 (tbl_json/)")]
end
Game <-->|sqlite_orm 제어| DB
Game -->|기본 데이터 적재| Fixtures
Game -->|사양 검증 및 대조| Tables
ADBRunner["ADB 및 Logcat 엔진"]
WebUI <-->|원격 명령 및 로그 리포트| ADBRunner
end
subgraph CloudZone ["카카오 게임즈 상용망"]
RealServer["에버소울 상용 API 서버"]
end
PortForward <-->|TCP 루프백 접속| TCP
Proxy <-->|libcurl API 포워딩| RealServer
ADBRunner <.->|ADB Shell & Logcat 모니터링| Client
에버소울 오프라인 서버의 세부 구성 요소 및 모듈별 심층 마크다운 기술 문서입니다.
- 종합 아키텍처 개요 명세서 (architecture.md): 시스템 전반의 디렉터리 구성 및 라이프사이클 흐름.
- Zinny / Kakao IDP 인증 서버 명세 (auth_server.md): 앱 인포데스크, 기기 로그인 및 가짜 세션 발행 원리.
- Mock 게임 프로토콜 및 데이터베이스 명세 (game_server.md): Protobuf 암복호화, SQLite ORM 기반 계정 상태 관리 및 동적 상태 변이 규칙.
- 리버스 프록시 및 API 하베스터 명세 (proxy_server.md): libcurl 포워딩 및 report_API 자동 수집 프레임워크.
- 실시간 웹소켓 & socket.io Replay 명세 (websocket_server.md): 실시간 세션 푸시 및 웹소켓 프레임 처리 흐름.
- 웹 UI 대시보드 및 REST API 명세 (web_ui_server.md): 웹 UI 대시보드 리소스 서빙 및 로그 스트리밍(SSE) API.
- ADB 인젝터 & Logcat 진단 모듈 명세 (adb_injector.md): reverse 포트 포워딩 자동화 및 실시간 원격 앱 진단 제어.
현재 프로젝트는 기존의 단순 정적 JSON 픽스쳐 의존성에서 완벽히 탈피하여, 359개의 TBL JSON 메타데이터와 SQLite AccountDB를 실시간 룩업하여 Protobuf를 서버단에서 동적 조립(Dynamic Assembly)하는 100% C++ 네이티브 백엔드 라우팅 시스템으로 전면 재설계되어 진행 중입니다.
docs/plan/ 디렉터리에 정의된 엄격한 개발 원칙(가짜 구현 금지, 데이터 기반 전수 검증) 하에 다음과 같은 세션(Session) 단위 작업이 진행되고 있습니다.
| 영역 / 도메인 | 상태 | 설명 (구현 근거 및 아키텍처) |
|---|---|---|
| 서버 인입 및 인증 | 완료 | TCP/HTTP 라우팅, offline-zat- 세션 관리, Kakao SDK 우회 처리 완벽 제어 |
| 핵심 스키마 통신 | 완료 | Google Protobuf 커스텀 런타임 인코딩/디코딩, 64비트 정밀도 자체 JSON 파서 탑재 |
| Foundation (세션 1) | 완료 | TblStore 로드 방식 최적화, Enum.json 및 Item.json 기반 재화 분류 로직 확립 |
| Ark / Domain (세션 2~5) | 완료 | 방주 오버클럭/레벨업, 영지(Domain) 전체 제어, 미궁(Labyrinth) 동적 상태 관리 구현 완료 |
| Reward Economy (세션 6~7) | 완료 | 우편함, 상점, 이벤트 보상 등 재화 보상 경제 시스템 전반의 SQLite 영속성 및 트랜잭션 구현 완료 |
| Hero, Town & Social (세션 8~9) | 완료 | 정령 장비/성장/유물, 영지(Town) 건물 및 배치, 소셜(친구/길드) 시스템 전면 상태 통합 및 동적 처리 |
| Runtime Hook & Diagnostics | 완료 | ADB Logcat을 이용한 런타임 Trace 훅 배포 및 웹 대시보드 실시간 분석 통합 |
절대 원칙 (Critical Rule): 향후 프로젝트 기여 시, 픽스쳐를 단순히 덮어씌우거나 문자열을 조립해 가짜 응답을 내리는 방식(
prefer_fixtures)을 강력히 금지합니다.
- 반드시
ProtocolBuffers/Global원본을 대조할 것.tbl_json에서 실제 데이터(확률, 가격, 보상 등)를 검증하고,account.db상태를 연동하는 완전한 C++ 엔드포인트를 구현할 것.
현재 모바일 환경(순정 안드로이드 기기)은 패킷 가로채기 및 후킹 패치 처리가 어렵기 때문에, 윈도우 PC 가상 서버와 안드로이드 에뮬레이터 조합을 통해서만 원활한 플레이가 가능합니다.
- 패치 완료된 에버소울 APK: 구글 드라이브 다운로드 폴더
- 권장 에뮬레이터 (MuMu Player V5.28.0): 뮤뮤 플레이어 직링크 다운로드 (기타 LDPlayer 9 등 안드로이드 64비트 가상화 에뮬레이터도 지원합니다.)
- 루팅 권한 활성화: 에뮬레이터의
기기 세부 설정또는시스템 설정에 진입하여 루팅(Root) 권한을 반드시 활성화하십시오. - ADB 원격 접속 활성화: 에뮬레이터 설정의 개발자 옵션 또는 기본 디바이스 설정에서 ADB 원격 접속(USB 디버깅)을 활성화 상태로 변경하십시오.
- ADB 연결 포트 확인:
- MuMu Player의 경우, 우측 상단 메뉴(
...) ➡️ [기기 정보] 또는 [진단 정보] ➡️ [네트워크 정보] 탭에 가시면 기기별 ADB 내부 포트 및 외부 포트가 명시되어 있습니다. (예:127.0.0.1:16384또는127.0.0.1:5555)
- MuMu Player의 경우, 우측 상단 메뉴(
- 오프라인 서버(
eversoul_console.exe)를 실행합니다. - 브라우저를 열어 가상 서버 웹 UI 대시보드
http://localhost:9991/web/에 접속합니다. - 최초 설정 페이지의 ADB 포트 설정 단계에서 에뮬레이터 진단 정보의 포트(예:
5555,5557,16384)를 입력하고 연결 및 목록 갱신을 클릭합니다. - 입력한 포트가
127.0.0.1:<port>형식으로 연결되면 연결 가능 기기 목록에 추가됩니다. 여러 포트를 반복 입력해 후보 기기를 모두 수집할 수 있습니다. - 목록에서 실제 사용할 기기를 최종 선택한 뒤 선택 기기 루트/리버스 검증을 실행합니다. 이 단계에서만
eversoul.ini에 선택 기기, ADB 포트, 루팅 상태,adb reverse tcp:9991 tcp:9991검증 결과가 저장됩니다. - 서버 재시작 시 저장된 INI 값을 기준으로 동일한 단일 기기를 재연결하고 reverse 상태를 재검증합니다. 중간 후보 수집 단계에서는
adb disconnect를 실행하지 않으므로 실행 중인 에뮬레이터 연결을 끊지 않습니다.
웹 UI의 분석 탭은 HAR, fixture, TBL, 런타임 ADB 상태를 같은 기준으로 점검하기 위한 진단 도구입니다.
tools/adb_runtime_response_probe.py:eversoul.ini와 웹 UI에서 선택한 ADB 정보를 읽어 패키지, 프로세스, reverse, logcat 상태를 수집합니다.tools/analyze_har_runtime_evidence.py:logs/har/*.har,responses/,responses_newbie/,tbl_json/을 대조하여 요청-바디-응답-TBL 근거를 리서치 출력으로 정리합니다.tools/har_to_json.py: 선택된 HAR 입력을 fixture 분석용 JSON으로 변환합니다.
본 PC Fixture 서버 작업은 Git Bash 기준으로 수행합니다. Android SO 빌드는 이 저장소의 현재 백엔드 구현 범위가 아닙니다.
cmake -S . -B build/cmd -DCMAKE_BUILD_TYPE=Release
cmake --build build/cmd --target eversoul_console encoder_validate offline_data_test orm_seed_check -j"$(nproc)"웹 UI와 실시간 분석 도구까지 포함한 배포 패키지는 아래 명령으로 생성합니다.
./bs.ps1 -a분석 패키지 빌드는 build/a/에서 수행되며 build/release/에 eversoul_console.exe, eversoul_runtime_debugger.exe, web/, tools/, responses/, responses_newbie/, tbl_json/, schema/, ProtocolBuffers/, docs/, research/, adb.exe와 ADB DLL을 덮어씁니다.
컴파일 완료 후, 아래의 단위 테스트 바이너리를 실행하여 무결성 검증을 완료할 수 있습니다.
# 프로토콜 인코더 무결성 검증
./build/cmd/encoder_validate
# 오프라인 데이터 및 프로필 구조 로드 테스트
./build/cmd/offline_data_test build/cmd/offline_data/libofflinedata.so UserInfo