Lewati ke konten utama

Ikhtisar

Pendahuluan​

Dokumen ini memberikan ikhtisar komprehensif tentang layanan backend Ravenxcope.Backend ASP.NET Core. Layanan ini adalah API pusat untuk platform pusat pertahanan RavenXcope, yang bertanggung jawab atas autentikasi, manajemen organisasi dan pengguna, kontrol akses berbasis peran (RBAC), orkestrasi siklus hidup sensor, dan integrasi analitik. Layanan ini mengikuti arsitektur berlapis dengan pemisahan kekhawatiran yang jelas di seluruh lapisan API, Aplikasi, Domain, dan Infrastruktur.

Pola Arsitektur​

Backend mengikuti Arsitektur Berlapis dengan controller tipis yang menangani transport API, kelas layanan khusus yang menangani logika bisnis, entitas yang mewakili model data, dan repositori di bawah infrastruktur yang menangani persistensi. Integrasi layanan eksternal (Redis, InfluxDB, OpenSearch, Ansible) dibungkus dalam kelas layanan infrastruktur. Kekhawatiran lintas-potong (cross-cutting) seperti pemutus sirkuit (circuit breaker), pembatasan laju (rate limiting), dan penanganan pengecualian global diimplementasikan melalui middleware dan layanan bersama.

API LayerControllersApplication LayerDTOs & LogicDomain LayerEntitiesInfrastructureServices & Repos

Struktur Proyek​

ravenxcope-backend
Program.cs# Titik masuk aplikasi dan bootstrap
Ravenxcope.Backend.csproj# Referensi NuGet dan pengaturan proyek
appsettings.json# Templat konfigurasi produksi
appsettings.Development.json# Konfigurasi pengembangan (gitignored)
Dockerfile# Build Docker multi-tahap
.gitlab-ci.yml# Definisi pipa CI/CD
API# Lapisan Presentasi (controller tipis)
Controllers
Analytics
Assets
Auth
Locations
Organizations
Permissions
Roles
Sensors
Users
Application# DTO dan Model Permintaan/Respons
DTOs
Domain# Entitas Bisnis Inti
Entities# Namespace: Ravenxcope.Backend.Domain.Entities
Infrastructure# Akses Data & Layanan Eksternal
Data
Services
Repositories
Extensions# Komposisi Startup
Common# Utilitas Bersama
Protos# gRPC Protocol Buffers
Migrations# Migrasi EF Core
Scripts# Skrip utilitas
Seed# File data benih (seed)
Knowledge# Dokumentasi (ini)

Tumpukan Teknologi​

KategoriTeknologiVersiTujuan
Runtime.NET10.0Runtime aplikasi
FrameworkASP.NET Core10.0Framework Web API
ORMEntity Framework Core9.0.1Akses database dan migrasi
DatabasePostgreSQL (Npgsql)9.0.4Database relasional utama
CachingRedis (StackExchange.Redis)2.10.1Blacklist token & penyimpanan sesi
Pencarian/AnalitikOpenSearch1.8.0Pengambilan log dan analitik
Deret WaktuInfluxDB4.18.0Data metrik dan heartbeat
Hashing Kata SandiBCrypt.Net-Next4.0.3Hashing kata sandi yang aman
LoggingSerilog9.0.0Logging terstruktur
JWTMicrosoft.AspNetCore.Authentication.JwtBearer10.0.0Autentikasi token
Dokumentasi APISwashbuckle (Swagger)6.9.0Dokumentasi OpenAPI
gRPCGrpc.AspNetCore2.70.0Titik akhir pemeriksaan kesehatan sensor

Prinsip Desain Utama​

  1. Fail-Fast pada Konfigurasi: Layanan memvalidasi semua kunci konfigurasi yang diperlukan saat startup dan langsung melempar pengecualian jika ada yang hilang atau berisi nilai placeholder.

  2. Fail-Fast pada Dependensi: Sebelum melayani lalu lintas apa pun, layanan memverifikasi konektivitas ke PostgreSQL, Redis, InfluxDB, dan OpenSearch menggunakan pemeriksaan kesehatan berbasis percobaan ulang (retry).

  3. Komposisi Startup melalui Ekstensi: Semua tanggung jawab startup (registrasi layanan, pipa middleware, pemeriksaan kesehatan, migrasi) diisolasi dalam metode ekstensi khusus di direktori Extensions/, menjaga Program.cs tetap bersih dan deklaratif.

  4. Pola Typed Options: Semua bagian konfigurasi diikat ke kelas opsi ber-tipe kuat (misalnya, PostgresqlSettingsOptions, JwtSettingsOptions, InfluxDbOptions) menggunakan IOptions<T>, menghindari pembacaan konfigurasi berbasis string yang tersebar.

  5. Manajemen Stempel Waktu Otomatis: ApplicationDbContext mengesampingkan SaveChanges dan SaveChangesAsync untuk secara otomatis mengatur stempel waktu CreatedAt dan UpdatedAt pada semua entitas yang dilacak.

  6. Izin Benih melalui Migrasi: Izin inti (CRUD untuk Pengguna, Sensor, Peran, Aset, dan edit Organisasi) ditanamkan melalui EF Core HasData di OnModelCreating, memastikan izin tersebut ada di setiap lingkungan.

  7. JWT dengan Blacklisting Token dan Refresh Token: Autentikasi menggunakan token JWT simetris dengan acara OnTokenValidated yang memeriksa Redis untuk pencabutan token. Refresh token dikeluarkan saat login/register dan disimpan di Redis dengan TTL 30 hari.

  8. Akses Cakupan Organisasi: Pengguna, sensor, aset, dan peran dicakup ke organisasi. Controller mengekstrak ID organisasi dari klaim JWT untuk memfilter akses data.

  9. Controller Tipis dengan Lapisan Layanan: Semua controller mendelegasikan logika bisnis ke kelas layanan khusus (misalnya, IAuthService, ISensorsService, IAssetService). Controller hanya menangani masalah transport HTTP.

  10. Amplop Respons Standar: Semua titik akhir mengembalikan respons melalui ApiEnvelope.Success() / ApiEnvelope.Error(), menyediakan kontrak { success, data, errors, traceId } yang konsisten.

  11. Penanganan Pengecualian Global: Middleware penangan pengecualian global (GlobalExceptionHandlingExtensions) menangkap pengecualian yang tidak tertangani dan memetakannya ke kode status HTTP yang sesuai melalui ApiExceptionMapper, menghilangkan blok try-catch di controller.

  12. Pembatasan Laju (Rate Limiting): Titik akhir autentikasi (login, register) dilindungi oleh pembatas laju jendela tetap (fixed-window) untuk mencegah serangan brute-force.

  13. Panggilan Eksternal yang Resilien: ResilientHttpService menyediakan pola pemutus sirkuit (circuit breaker) dan percobaan ulang (retry) untuk panggilan HTTP eksternal (misalnya, Ansible), mencegah kegagalan beruntun.

Jaminan Startup​

Saat startup, layanan melakukan langkah-langkah berikut dalam urutan yang ketat:

  1. Menginisialisasi logging terstruktur Serilog dari appsettings
  2. Memvalidasi semua kunci konfigurasi yang diperlukan (melempar pengecualian jika ada nilai yang hilang/placeholder)
  3. Mengeluarkan peringatan jika rahasia JWT lebih pendek dari 32 karakter
  4. Mendaftarkan semua layanan DI, opsi ber-tipe, dan dependensi middleware
  5. Membangun koneksi Redis (terhubung secara aktif selama registrasi DI)
  6. Mengeksekusi pemeriksaan kesehatan dependensi dengan logika retry untuk PostgreSQL, Redis, InfluxDB, dan OpenSearch
  7. Menerapkan migrasi database EF Core secara otomatis ketika Database:AutoMigrate bernilai true
  8. Mengonfigurasi pipa middleware HTTP dan memetakan controller + titik akhir gRPC
  9. Mulai menerima lalu lintas HTTP dan gRPC

Model Penyebaran​

Backend dirancang untuk berjalan dalam tumpukan kemasan kontainer (containerized stacks) sebagai bagian dari penyebaran Docker Compose pusat pertahanan. Ia mengharapkan variabel lingkungan (menggunakan konvensi garis bawah ganda ASP.NET Core) untuk mengisi placeholder appsettings.json saat runtime.

  • Port yang diekspos Docker: 5144
  • Titik masuk: dotnet Ravenxcope.Backend.dll
  • Gambar basis: mcr.microsoft.com/dotnet/aspnet:10.0
  • Gambar build: mcr.microsoft.com/dotnet/sdk:10.0