Servidor Lineage II High Five Fun

Visão Geral

Este projeto é uma implementação abrangente de um Servidor Lineage II High Five Fun que desenvolvo com paixão e aprendo a implantar em clusters Kubernetes. Como fã do clássico jogo Lineage II, este projeto representa tanto meu amor pelo jogo quanto minha jornada em dominar tecnologias modernas nativas da nuvem.

Motivação do Projeto

Lineage II ocupa um lugar especial no meu coração como um dos MMORPGs mais icônicos já criados. A crônica High Five representa a era dourada do jogo, e eu quis recriar essa experiência enquanto aprendo estratégias modernas de DevOps e implantação no Kubernetes. Este projeto combina nostalgia com tecnologia de ponta.

Visão Geral da Arquitetura

O sistema é construído usando uma arquitetura de microsserviços implantada no Kubernetes (K3s), incluindo:

  • Game Server: Implementação do servidor Lineage II baseada em Java
  • Login Server: Autenticação e gerenciamento de personagens
  • Web Server: API REST e servidor WebSocket baseados em Go
  • Web Application: Frontend React com Next.js
  • Resources Provider: Gerenciamento de assets do jogo e patches
  • OAuth API: Serviço centralizado de autenticação e autorização
  • Mailer App: Serviço dedicado de email para notificações
  • Stack de Monitoramento: Prometheus, Grafana, Loki para observabilidade
  • Bancos de Dados: MySQL para dados do jogo, MongoDB para dados da aplicação

Infraestrutura

  • Orquestração de Contêineres: Kubernetes (K3s)
  • Ingress: Traefik com SSL Let’s Encrypt
  • Monitoramento: Stack Prometheus + Grafana + Loki
  • CI/CD: GitHub Actions com GHCR

Microsserviços Externos

O Servidor Lineage II Fun integra-se com dois microsserviços externos críticos que fornecem funcionalidades essenciais:

Serviço OAuth API

Um servidor de autorização OAuth 2.0 robusto que fornece autenticação e autorização centralizadas para todo o ecossistema:

  • Gerenciamento de Tokens JWT: Gera e valida tokens de acesso seguros com expiração configurável
  • Controle de Acesso Baseado em Funções (RBAC): Suporta tipos de usuários e contas de serviço com permissões detalhadas
  • Permissões Baseadas em Escopo: Escopos personalizados para diferentes níveis de acesso ao serviço
  • Suporte Multi-Aplicação: Gerencia acesso em múltiplas aplicações alvo
  • Integração MongoDB: Armazenamento persistente para dados de autorização com índices otimizados
  • Recursos de Segurança: Assinatura com chave privada RSA, validação abrangente de tokens

Integração com o Servidor Lineage:

  • WebServer usa OAuth API para autenticação serviço-a-serviço
  • Valida tokens JWT para acesso seguro à API
  • Gerencia autorização para operações administrativas e permissões de usuário
  • Armazena tokens de autorização em cache para otimização de desempenho

Serviço Mailer App

Um serviço de email dedicado que gerencia todas as notificações por email da plataforma de jogos:

  • Integração com API de Email: Serviço de email para entrega de mensagens
  • API Protegida por OAuth: Endpoints protegidos que requerem tokens JWT válidos com escopo de permissão de envio de email
  • Templates de Email: Suporte para templates HTML e formatação rica
  • Tipos de Notificação: Ativação de conta, redefinição de senha, confirmações de doação, alertas de status do servidor
  • Confiabilidade de Entrega: Mecanismos integrados de retry e tratamento de erros

Integração com o Servidor Lineage:

  • WebServer chama a API Mailer para emails de registro de usuário
  • Notificações de status do servidor enviadas para administradores
  • Notificações de confirmação de pagamento e reembolso
  • Emails de ativação de conta e redefinição de senha
  • Usa OAuth API para autenticação ao enviar emails

Fluxo de Comunicação de Serviços:

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

Esses serviços externos seguem os mesmos padrões de implantação da aplicação principal, executando em namespaces Kubernetes separados (oauth e resource) com suas próprias instâncias MongoDB, certificados SSL e configurações de monitoramento.

Principais Recursos

Recursos do Jogo

  • Experiência Clássica do Lineage II High Five: Mecânicas de jogo autênticas
  • Suporte a Múltiplos Servidores: Sieghardt, Lionna com diferentes taxas
  • Status do Servidor em Tempo Real: Monitoramento ao vivo da disponibilidade do servidor de jogo
  • Gerenciamento de Personagens: Criação de contas, visualização de personagens

Recursos Web Modernos

  • Sistema de Doação: Processamento de pagamentos integrado com PIX e cartão de crédito fornecido pelo Mercado Pago
  • Atualizações em Tempo Real: Streaming de dados ao vivo baseado em WebSocket
  • Design Responsivo: Interface amigável para dispositivos móveis
  • Suporte Multilíngue: Português e Inglês
  • Painel Administrativo: Gerenciamento e monitoramento do servidor

Recursos de DevOps

  • Implantação Nativa da Nuvem: Manifestos Kubernetes completos
  • Observabilidade: Monitoramento e registro abrangentes
  • Segurança: SSL/TLS, validação de webhook, limitação de taxa
  • Escalabilidade: Pronto para auto-escalonamento horizontal de pods
  • Alta Disponibilidade: Verificações de saúde e reinicializações automáticas

Fluxo de Comunicação

O sistema usa um padrão de comunicação sofisticado:

  1. Cliente ↔ WebApp: HTTPS/WSS
  2. WebApp ↔ WebServer: WebSocket para comunicação em tempo real
  3. WebServer ↔ Game Server: Socket TCP para operações do jogo
  4. WebServer ↔ Bancos de Dados: Pool de conexões para persistência de dados
  5. Webhooks de Pagamento: Validação segura de webhook para atualizações de pagamento
  6. Monitoramento: Coleta de traces e métricas OpenTelemetry

Ambiente de Desenvolvimento

O projeto suporta desenvolvimento local e implantação em produção:

  • Local: Docker Compose para desenvolvimento rápido
  • Produção: Implantação completa no Kubernetes com monitoramento
  • CI/CD: Builds e implantações automatizados

Diagramas de Arquitetura do Sistema

Os seguintes diagramas PlantUML fornecem visões detalhadas da arquitetura do sistema e padrões de comunicação. Cada diagrama foca em um fluxo único e específico:

1. Arquitetura Geral do 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

Mostra a visão geral completa do sistema incluindo todos os serviços, bancos de dados, integrações externas e fluxos de comunicação dentro do cluster Kubernetes.

2. Fluxo de Pagamento

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 Atualização de Status do Fluxo de Pagamento

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

Recursos do Fluxo de Pagamento:

  • 💳 Múltiplos Métodos de Pagamento: Suporte a PIX (instantâneo), Cartão de Crédito e Débito
  • 🔐 Processamento Seguro: Tokenização e criptografia de cartões compatível com PCI
  • ⚡ Atualizações em Tempo Real: Notificações WebSocket para feedback instantâneo
  • 🛡️ Validação de Segurança: Verificação de assinatura webhook com HMAC SHA256
  • 🔄 Monitoramento em Background: Verificação automática de status a cada 5 minutos
  • 💰 Recompensas Instantâneas: Moedas adicionadas ao inventário do jogo imediatamente
  • 📱 Integração PIX: Sistema de pagamento instantâneo do Brasil com códigos QR
  • 💳 Processamento de Cartões: Suporte a todas as principais bandeiras de cartão de crédito/débito

Detalha o processo completo de pagamento de doações usando tanto métodos PIX quanto Cartão de Crédito/Débito com integração Mercado Pago.

3. Fluxo de Registro de Conta

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. Fluxo de Ativação de Conta

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. Fluxo de Conexão 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. Fluxo de Dados da Conta

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. Fluxo de Notificação de Pagamento

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. Fluxo de Reconexão 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

Recursos do WebSocket:

  • 🔄 Atualizações em Tempo Real: Status ao vivo do servidor, notificações de pagamento, atualizações de personagens
  • 🔗 Padrão de Binding: Separação limpa entre a interface do usuário e a lógica WebSocket
  • 🛡️ Auto-reconexão: Estratégia de exponential backoff para recuperação de conexão
  • 📊 Processadores de Mensagens: Handlers dedicados para cada tipo de mensagem
  • 🎯 Broadcasting Direcionado: Roteamento eficiente de mensagens para clientes específicos
  • ⚡ Baixa Latência: Comunicação WebSocket direta para atualizações instantâneas

Ilustra os padrões de comunicação em tempo real entre o frontend React e o backend Go usando conexões WebSocket.

9. Integração de Serviços 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

Detalha a integração com microsserviços externos (OAuth API e Mailer App), mostrando fluxos de autenticação, notificações por email e padrões de comunicação serviço-a-serviço.