Lineage II High Five Fun Server

Descripción General

Este proyecto es una implementación completa del Servidor Lineage II High Five Fun que me apasiona desarrollar y aprender a desplegar en clústeres de Kubernetes. Como fan del juego clásico Lineage II, este proyecto representa tanto mi amor por el juego como mi viaje en el dominio de las tecnologías modernas nativas de la nube.

Motivación del Proyecto

Lineage II ocupa un lugar especial en mi corazón como uno de los MMORPGs más icónicos jamás creados. La crónica High Five representa la era dorada del juego, y quería recrear esa experiencia mientras aprendía estrategias modernas de DevOps y despliegue en Kubernetes. Este proyecto combina nostalgia con tecnología de vanguardia.

Descripción General de la Arquitectura

El sistema está construido usando una arquitectura de microservicios desplegada en Kubernetes (K3s), con las siguientes características:

  • Servidor de Juego: Implementación del servidor Lineage II basada en Java
  • Servidor de Inicio de Sesión: Autenticación y gestión de personajes
  • Servidor Web: API REST basada en Go y servidor WebSocket
  • Aplicación Web: Frontend React Next.js
  • Proveedor de Recursos: Gestión de activos del juego y parches
  • API OAuth: Servicio centralizado de autenticación y autorización
  • Aplicación de Correo: Servicio de correo electrónico dedicado para notificaciones
  • Stack de Monitoreo: Prometheus, Grafana, Loki para observabilidad
  • Bases de Datos: MySQL para datos del juego, MongoDB para datos de la aplicación

Infraestructura

  • Orquestación de Contenedores: Kubernetes (K3s)
  • Ingress: Traefik con SSL de Let’s Encrypt
  • Monitoreo: Stack Prometheus + Grafana + Loki
  • CI/CD: GitHub Actions con GHCR

Microservicios Externos

El Servidor Lineage II Fun se integra con dos microservicios externos críticos que proporcionan funcionalidad esencial:

Servicio API OAuth

Un servidor de autorización OAuth 2.0 robusto que proporciona autenticación y autorización centralizadas para todo el ecosistema:

  • Gestión de Tokens JWT: Genera y valida tokens de acceso seguros con expiración configurable
  • Control de Acceso Basado en Roles (RBAC): Soporta tipos de usuario y cuenta de servicio con permisos granulares
  • Permisos Basados en Alcance: Alcances personalizados para diferentes niveles de acceso de servicio
  • Soporte Multi-Aplicación: Gestiona acceso en múltiples aplicaciones objetivo
  • Integración MongoDB: Almacenamiento persistente para datos de autorización con índices optimizados
  • Características de Seguridad: Firma de clave privada RSA, validación completa de tokens

Integración con Servidor Lineage:

  • WebServer utiliza API OAuth para autenticación de servicio a servicio
  • Valida tokens JWT para acceso seguro a API
  • Gestiona autorización para operaciones de administrador y permisos de usuario
  • Cachea tokens de autorización para optimización de rendimiento

Servicio Aplicación de Correo

Un servicio de correo electrónico dedicado que maneja todas las notificaciones de correo electrónico para la plataforma de juegos:

  • Integración API de Correo: Servicio de correo para entrega de correos electrónicos
  • API Asegurada con OAuth: Endpoints protegidos que requieren tokens JWT válidos con alcance de permiso de correo enviado
  • Plantillas de Correo: Soporte para plantillas de correo HTML y formato enriquecido
  • Tipos de Notificación: Activación de cuenta, restablecimiento de contraseña, confirmaciones de donación, alertas de estado del servidor
  • Confiabilidad de Entrega: Mecanismos de reintento incorporados y manejo de errores

Integración con Servidor Lineage:

  • WebServer llama a API de Correo para correos de registro de usuario
  • Notificaciones de estado del servidor enviadas a administradores
  • Notificaciones de confirmación y reembolso de pago
  • Correos de activación de cuenta y restablecimiento de contraseña
  • Utiliza API OAuth para autenticación al enviar correos electrónicos

Flujo de Comunicación de Servicios:

Loading diagram...
View PlantUML Source
@startuml Service Communication Flow

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title External Services Communication Flow

participant "WebServer" as WebServer #blue
participant "OAuth API" as OAuthAPI #purple
participant "Mailer App" as MailerApp #lightblue
actor "User Email" as UserEmail #lightgreen

WebServer -> OAuthAPI : Request JWT token\n(service authentication)
OAuthAPI -> WebServer : Return JWT token

WebServer -> MailerApp : Send email request\n(with JWT token)
MailerApp -> OAuthAPI : Validate JWT token\n& check scope permissions
OAuthAPI -> MailerApp : Token valid ✅

MailerApp -> MailerApp : Process email\n(templates, formatting)
MailerApp -> UserEmail : Email delivered 📧
MailerApp -> WebServer : Delivery confirmation

@enduml

Estos servicios externos siguen los mismos patrones de despliegue que la aplicación principal, ejecutándose en espacios de nombres de Kubernetes separados (oauth y resource) con sus propias instancias de MongoDB, certificados SSL y configuraciones de monitoreo.

Características Principales

Características del Juego

  • Experiencia Clásica Lineage II High Five: Mecánicas de juego auténticas
  • Soporte de Múltiples Servidores: Sieghardt, Lionna con diferentes tasas
  • Estado del Servidor en Tiempo Real: Monitoreo en vivo de disponibilidad del servidor de juego
  • Gestión de Personajes: Creación de cuenta, visualización de personajes

Características Web Modernas

  • Sistema de Donación: Procesamiento de pagos integrado con PIX y tarjeta de crédito impulsado por Mercado Pago
  • Actualizaciones en Tiempo Real: Transmisión de datos en vivo basada en WebSocket
  • Diseño Responsivo: Interfaz compatible con dispositivos móviles
  • Soporte Multiidioma: Portugués e Inglés
  • Panel de Administración: Gestión y monitoreo del servidor

Características DevOps

  • Despliegue Nativo en la Nube: Manifiestos completos de Kubernetes
  • Observabilidad: Monitoreo y registro integral
  • Seguridad: SSL/TLS, validación de webhook, limitación de velocidad
  • Escalabilidad: Listo para autoescalado horizontal de pods
  • Alta Disponibilidad: Verificaciones de salud y reinicios automáticos

Flujo de Comunicación

El sistema utiliza un patrón de comunicación sofisticado:

  1. Cliente ↔ WebApp: HTTPS/WSS
  2. WebApp ↔ WebServer: WebSocket para comunicación en tiempo real
  3. WebServer ↔ Servidor de Juego: Socket TCP para operaciones del juego
  4. WebServer ↔ Bases de Datos: Agrupación de conexiones para persistencia de datos
  5. Webhooks de Pago: Validación segura de webhook para actualizaciones de pago
  6. Monitoreo: Recopilación de trazas y métricas de OpenTelemetry

Entorno de Desarrollo

El proyecto soporta tanto desarrollo local como despliegue en producción:

  • Local: Docker Compose para desarrollo rápido
  • Producción: Despliegue completo de Kubernetes con monitoreo
  • CI/CD: Compilaciones y despliegues automatizados

Diagramas de Arquitectura del Sistema

Los siguientes diagramas PlantUML proporcionan vistas detalladas de la arquitectura del sistema y patrones de comunicación. Cada diagrama se enfoca en un flujo único y específico:

1. Arquitectura General del Sistema

Loading diagram...
View PlantUML Source
@startuml
!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam defaultFontSize 11
skinparam componentStyle uml2

title Lineage II High Five Fun Server - Communication Architecture

' External actors
actor "Game Client\n(Lineage II)" as GameClient #lightblue
actor "Web User\n(Browser)" as WebUser #lightgreen
cloud "Internet" as Internet #gray

' External services
cloud "Mercado Pago\nAPI" as MercadoPago #orange
cloud "GitHub Container\nRegistry" as GHCR #gray
cloud "Let's Encrypt\nCA" as LetsEncrypt #green

cloud "Cloud" as CloudDATA {
database "MySQL Database" as MySQL #brown
database "MongoDB" as MongoDB #brown
}

' External Microservices (separate deployments)
package "External Services" as ExternalServices {
component "OAuth API" as OAuthAPI #purple
component "Mailer App" as MailerApp #lightblue
}

' Kubernetes Cluster boundary
rectangle "K3s Kubernetes Cluster" as K8sCluster {

    ' Ingress Layer
    component "Traefik Ingress" as Traefik #red

    ' Application Namespace
    package "Game server" as AppNamespace {
        ' Frontend
        component "WebApp\n(Next.js)" as WebApp #lightgreen
        ' Backend API
        component "WebServer\n(Go + WebSocket)" as WebServer #blue
        ' Game Services
        component "Login Server\n(Java)" as LoginServer #yellow
        component "Sieghardt\nGame Server\n(Java L2J)" as GameServer #yellow
        component "Lionna(1000x)\nGame Server\n(Java L2J)" as LionaGameServer #yellow
        ' Support Services
        component "Resources Provider" as ResourcesProvider #cyan
        ' Databases
    }

    ' Monitoring Namespace
    package "Monitoring" as MonitoringNamespace {
        component "Prometheus" as Prometheus #orange
        component "Grafana" as Grafana #orange
        component "Loki" as Loki #orange
        component "OpenTelemetry\nCollector" as OTelCollector #orange
    }

}

' External connections
Internet --> Traefik
WebUser --> Internet
GameClient --> Internet

' Ingress routing
Traefik --> WebApp
Traefik --> WebServer

' Game client connections (external LoadBalancer)
GameClient --> LoginServer
GameClient --> GameServer
GameClient --> LionaGameServer

' Internal service communication
WebApp --> WebServer
WebServer --> LoginServer
WebServer --> GameServer
WebServer --> LionaGameServer
LoginServer --> GameServer
LoginServer --> LionaGameServer

' Database connections
WebServer --> MySQL
WebServer --> MongoDB
WebServer --> ResourcesProvider
LoginServer --> MySQL
GameServer --> MySQL
LionaGameServer --> MySQL
LionaGameServer --> WebServer
GameServer --> WebServer

' External API calls
WebServer --> MercadoPago
MercadoPago --> WebServer

' External microservices integration
WebServer --> OAuthAPI
WebServer --> MailerApp
OAuthAPI --> MongoDB
MailerApp --> OAuthAPI

' Resource management
WebApp --> ResourcesProvider

' Monitoring and observability
WebServer --> OTelCollector
WebApp --> Prometheus
WebServer --> Prometheus
GameServer --> Prometheus
LoginServer --> Prometheus
OTelCollector --> Prometheus
Prometheus --> Grafana
Loki --> Grafana

' SSL/TLS
LetsEncrypt --> Traefik

' Container registry
GHCR --> K8sCluster

note right of WebServer
**WebSocket Processors:**
• donation_payment_flow
• donation_history_flow
• server_status_flow
• account_flow
• character_flow

**Real-time Features:**
• Live server status
• Payment processing
• Character updates
• Donation history

**External Integrations:**
• OAuth API for authentication
• Mailer App for notifications
• Mercado Pago for payments
end note
@enduml

Muestra la descripción general completa del sistema incluyendo todos los servicios, bases de datos, integraciones externas y flujos de comunicación dentro del clúster de Kubernetes.

2. Flujo de Pago

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Payment Flow

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Donation Payment Flow

actor "Player" as Player #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Database" as DB #brown
participant "Mercado Pago" as MercadoPago #orange
participant "Game Server" as GameServer #yellow

== Payment Process ==

Player -> WebApp : Select donation package
WebApp -> WebApp : Show payment options\n(PIX, Credit/Debit Card)
Player -> WebApp : Choose payment method & confirm

WebApp -> WebServer : Create payment request
WebServer -> DB : Store payment record
WebServer -> MercadoPago : Create payment\n(PIX or Card)

MercadoPago -> WebServer : Payment created\n(QR code or card form)
WebServer -> WebApp : Return payment details
WebApp -> Player : Display payment interface

Player -> MercadoPago : Complete payment\n(PIX scan or card details)
MercadoPago -> WebServer : Payment webhook\n(approved/rejected)

@enduml

2.1 Flujo de Pago con Estado Actualizado

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Payment Flow Status Updated

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Donation Payment Flow

actor "Player" as Player #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Database" as DB #brown
participant "Mercado Pago" as MercadoPago #orange
participant "Game Server" as GameServer #yellow

alt Payment Approved
WebServer -> DB : Update payment status
WebServer -> GameServer : Add coins to account
GameServer -> WebServer : Coins added successfully
WebServer -> WebApp : Payment success notification
WebApp -> Player : Show success message
else Payment Failed
WebServer -> DB : Update payment status
WebServer -> WebApp : Payment failed notification
WebApp -> Player : Show error & retry options
end

@enduml

Características del Flujo de Pago:

  • 💳 Múltiples Métodos de Pago: Soporte para PIX (instantáneo), Tarjeta de Crédito, Tarjeta de Débito
  • 🔐 Procesamiento Seguro: Tokenización de tarjeta compatible con PCI y encriptación
  • ⚡ Actualizaciones en Tiempo Real: Notificaciones WebSocket para retroalimentación instantánea
  • 🛡️ Validación de Seguridad: Verificación de firma de webhook HMAC SHA256
  • 🔄 Monitoreo en Segundo Plano: Verificación automática de estado cada 5 minutos
  • 💰 Recompensas Instantáneas: Monedas agregadas al inventario del juego inmediatamente
  • 📱 Integración PIX: Sistema de pago instantáneo de Brasil con códigos QR
  • 💳 Procesamiento de Tarjetas: Soporte para todas las marcas principales de tarjetas de crédito/débito

Detalla el proceso de pago de donación de extremo a extremo utilizando tanto métodos PIX como de Tarjeta de Crédito/Débito con integración de Mercado Pago.

3. Flujo de Registro de Cuenta

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Account Registration

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Account Registration Process

actor "User" as User #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Database" as DB #brown
participant "Mailer App" as MailerApp #lightblue
participant "Game Server" as GameServer #yellow

User -> WebApp : Fill registration form\n(username, email, password)
WebApp -> WebApp : Validate form data
WebApp -> WebServer : Submit registration request

WebServer -> WebServer : Validate user data\n& check duplicates
WebServer -> DB : Store user account
DB -> WebServer : Account created successfully

WebServer -> MailerApp : Send welcome email
MailerApp -> User : Welcome email sent

WebServer -> GameServer : Create game account
GameServer -> GameServer : Initialize player data\n(starting items, stats)
GameServer -> WebServer : Game account ready

WebServer -> WebApp : Registration successful
WebApp -> User : Show success message\n& check email for activation

@enduml

4. Flujo de Activación de Cuenta

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Account Activation

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Account Activation Process

actor "User" as User #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Database" as DB #brown

User -> User : Check email & click activation link
User -> WebApp : Access activation URL
WebApp -> WebServer : Activate account request

WebServer -> WebServer : Validate activation token
WebServer -> DB : Update account status\n(active = true)
DB -> WebServer : Account activated

WebServer -> WebApp : Account activated successfully
WebApp -> User : Account ready!\nYou can now login

@enduml

5. Flujo de Conexión WebSocket

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - WebSocket Connection

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title WebSocket Connection & Real-time Updates

actor "User" as User #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Game Server" as GameServer #yellow

User -> WebApp : Open application
WebApp -> WebServer : WebSocket connection request
WebServer -> WebServer : Authenticate & register client
WebServer -> WebApp : Connection established

loop Every 30 seconds
WebServer -> GameServer : Check server status
GameServer -> WebServer : Server data (players, status)
WebServer -> WebApp : Broadcast server status
WebApp -> User : Update live server info
end

@enduml

6. Flujo de Datos de Cuenta

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Account Data

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Account Information Request

actor "User" as User #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Database" as DB #brown

User -> WebApp : Request account info
WebApp -> WebServer : Get account data (WebSocket)
WebServer -> DB : Query user account
DB -> WebServer : Account & character data
WebServer -> WebApp : Send account info
WebApp -> User : Display account details

@enduml

7. Flujo de Notificación de Pago

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Payment Notification

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Payment Success Notification

participant "WebServer" as WebServer #blue
participant "WebApp" as WebApp #lightgreen
participant "Game Server" as GameServer #yellow
actor "User" as User #lightgreen

note over WebServer : Payment webhook received\nfrom Mercado Pago

WebServer -> GameServer : Add coins to account
GameServer -> WebServer : Coins added successfully
WebServer -> WebApp : Payment success notification\n(WebSocket broadcast)
WebApp -> User : Show success message\n"Coins added! 🎉"

@enduml

8. Flujo de Reconexión WebSocket

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - WebSocket Reconnection

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title WebSocket Auto-reconnection

actor "User" as User #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue

WebServer -> WebApp : Connection lost ❌
WebApp -> WebApp : Detect disconnection
WebApp -> WebApp : Wait (exponential backoff)
WebApp -> WebServer : Attempt reconnection
WebServer -> WebApp : Reconnection successful ✅
WebApp -> WebApp : Restore application state
WebApp -> User : Connection restored

@enduml

Características de WebSocket:

  • 🔄 Actualizaciones en Tiempo Real: Estado del servidor en vivo, notificaciones de pago, actualizaciones de personajes
  • 🔗 Patrón de Vinculación: Separación limpia entre lógica de UI y WebSocket
  • 🛡️ Auto-reconexión: Estrategia de retroceso exponencial para recuperación de conexión
  • 📊 Procesadores de Mensajes: Controladores dedicados para cada tipo de mensaje
  • 🎯 Transmisión Dirigida: Enrutamiento eficiente de mensajes a clientes específicos
  • ⚡ Baja Latencia: Comunicación directa de WebSocket para actualizaciones instantáneas

Ilustra los patrones de comunicación en tiempo real entre el frontend React y el backend Go utilizando conexiones WebSocket.

9. Integración de Servicios Externos

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - External Services

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title External Services Integration

participant "WebServer" as WebServer #blue
participant "OAuth API" as OAuthAPI #purple
participant "Mailer App" as MailerApp #lightblue
participant "Database" as DB #brown
actor "User Email" as UserEmail #lightgreen

== Authentication & Email Flow ==

WebServer -> OAuthAPI : Request authentication token
OAuthAPI -> DB : Validate credentials
DB -> OAuthAPI : User authorized
OAuthAPI -> WebServer : JWT token

WebServer -> WebServer : User registration/donation event
WebServer -> MailerApp : Send email request\n(with JWT token)
MailerApp -> OAuthAPI : Validate token & scope
OAuthAPI -> MailerApp : Token valid

MailerApp -> MailerApp : Send email
MailerApp -> UserEmail : Email delivered
MailerApp -> WebServer : Email sent successfully

@enduml

Detalla la integración con microservicios externos (API OAuth y Aplicación de Correo), mostrando flujos de autenticación, notificaciones de correo electrónico y patrones de comunicación de servicio a servicio.