596 lines
20 KiB
Markdown
596 lines
20 KiB
Markdown
# Plan: n8n Workflow → Quarkus Backend ersetzen
|
|
|
|
**Stand:** 2026-04-08
|
|
**Basis:** Avise-Tool Quarkus Backend (agent-backend/) — angepasst für SFTP → OCI Object Storage → DB-Workflow
|
|
|
|
---
|
|
|
|
## Ziel
|
|
|
|
Ersetze den n8n-Workflow (derzeit: SFTP-Poll → ZIP-Entpacken → OCI-Upload → ORDS-Trigger) durch einen nativen Quarkus-Backend-Service.
|
|
|
|
**Vorteil:**
|
|
- Keine externe Workflow-Engine-Abhängigkeit (n8n)
|
|
- Single-Responsibility: Ein Service für eine Aufgabe (Dateieingang)
|
|
- Bessere Observability (OTLP → Loki/Grafana)
|
|
- Volle Kontrolle über Fehlerbehandlung und Retry-Logik
|
|
- Einfacheres Deployment (JAR statt n8n-Instanz)
|
|
|
|
---
|
|
|
|
## Architektur-Überblick
|
|
|
|
Das Scheduling übernimmt weiterhin die APEX Automation (stündlich). Sie ruft den Quarkus-Service
|
|
per HTTP POST auf — wie bisher den n8n-Webhook. Der Service selbst hat keinen eigenen Scheduler.
|
|
|
|
```
|
|
APEX Automation (stündlich)
|
|
│
|
|
▼ HTTP POST /api/process-incoming (Header: X-Api-Key)
|
|
FileProcessingResource [Quarkus REST Endpoint]
|
|
│ gibt sofort 202 Accepted zurück (async, fire & forget)
|
|
▼
|
|
FileProcessingPipeline [Hintergrund-Thread — für jede neue ZIP]
|
|
│
|
|
├─→ SftpService [SSHJ — list, download, rename]
|
|
│
|
|
├─→ ZipExtractionService [Apache Commons Compress]
|
|
│
|
|
├─→ OciUploadService [OCI SDK — Instance Principal Auth]
|
|
│
|
|
└─→ OrdsNotificationService [MicroProfile REST Client]
|
|
│
|
|
▼
|
|
Oracle DB (eingang/, zielordner)
|
|
```
|
|
|
|
---
|
|
|
|
## Projektstruktur (Maven)
|
|
|
|
```
|
|
quarkus-automaton/
|
|
├── pom.xml (Java 25, Quarkus 3.x LTS)
|
|
│
|
|
├── src/main/java/de/galabau/
|
|
│ │
|
|
│ ├── api/
|
|
│ │ └── FileProcessingResource.java (@Path("/api/process-incoming"), @POST, API-Key-Check)
|
|
│ │
|
|
│ ├── sftp/
|
|
│ │ ├── SftpConfig.java (@ConfigMapping)
|
|
│ │ └── SftpService.java (SSHJ — list, download, rename)
|
|
│ │
|
|
│ ├── zip/
|
|
│ │ └── ZipExtractionService.java (Apache Commons Compress)
|
|
│ │
|
|
│ ├── oci/
|
|
│ │ ├── OciConfig.java
|
|
│ │ └── OciUploadService.java (OCI SDK, Instance Principal, Marker-Handling)
|
|
│ │
|
|
│ ├── ords/
|
|
│ │ ├── OrdsClient.java (MicroProfile REST Client)
|
|
│ │ └── OrdsNotificationService.java (Retry via @Retry annotation)
|
|
│ │
|
|
│ ├── pipeline/
|
|
│ │ └── FileProcessingPipeline.java (Extract → Upload → Notify → Cleanup)
|
|
│ │
|
|
│ ├── model/
|
|
│ │ ├── ProcessingContext.java (runId, Dateien, Status)
|
|
│ │ └── OrdsRequest.java (DTO)
|
|
│ │
|
|
│ ├── config/
|
|
│ │ └── ApplicationConfig.java (zentrale @ConfigMapping)
|
|
│ │
|
|
│ └── exception/
|
|
│ ├── SftpException.java
|
|
│ ├── ZipException.java
|
|
│ ├── OciException.java
|
|
│ └── OrdsException.java
|
|
│
|
|
├── src/main/resources/
|
|
│ ├── application.properties
|
|
│ └── application-dev.properties
|
|
│
|
|
└── docs/
|
|
├── SETUP.md
|
|
├── Architecture.md
|
|
├── Configuration.md
|
|
└── ErrorHandling.md
|
|
```
|
|
|
|
---
|
|
|
|
## Pipeline-Steps
|
|
|
|
| Step | Komponente | Bibliothek | Beschreibung |
|
|
|---|---|---|---|
|
|
| `api-trigger` | `FileProcessingResource` | Quarkus REST | Empfängt POST von APEX Automation, prüft API-Key, startet Pipeline async |
|
|
| `sftp-list` | `SftpService` | SSHJ | Listet `*.zip`-Dateien im Remote-Verzeichnis |
|
|
| `sftp-download` | `SftpService` | SSHJ | Lädt ZIP in lokales Arbeitsverzeichnis |
|
|
| `zip-extract` | `ZipExtractionService` | Apache Commons Compress | Entpackt ZIP, preserviert Ordnerstruktur |
|
|
| `oci-upload` | `OciUploadService` | OCI SDK | Lädt Dateien + Marker zu OCI Object Storage |
|
|
| `sftp-rename` | `SftpService` | SSHJ | Remote-Rename zu `.processed` oder `.error` |
|
|
| `ords-notify` | `OrdsNotificationService` | MicroProfile REST Client | Ruft ORDS-Endpunkt auf |
|
|
| `cleanup` | `FileProcessingPipeline` | pure Java | Löscht lokale Arbeitsdateien (ZIP + entpackte Dateien) |
|
|
|
|
---
|
|
|
|
## Konfiguration (`application.properties`)
|
|
|
|
```properties
|
|
# API-Absicherung
|
|
galabau.api.key=${GALABAU_API_KEY}
|
|
|
|
# SFTP
|
|
galabau.sftp.host=sftp.lieferant.de
|
|
galabau.sftp.port=22
|
|
galabau.sftp.username=sftp_user
|
|
galabau.sftp.password=${GALABAU_SFTP_PASSWORD}
|
|
galabau.sftp.host-key-fingerprint=SHA256:AbCdEfGh... # ssh-keyscan host | ssh-keygen -lf -
|
|
galabau.sftp.remote-path=/outgoing
|
|
galabau.sftp.local-work-dir=/tmp/sftp-work
|
|
|
|
# Alternative: Public-Key-Auth (empfohlen für Produktion)
|
|
# galabau.sftp.private-key-path=/etc/secrets/sftp-key
|
|
# galabau.sftp.private-key-passphrase=${SFTP_KEY_PASSPHRASE}
|
|
|
|
# OCI Object Storage — Auth via Credentials (Key als gemountetes Kubernetes Secret)
|
|
galabau.oci.namespace=mycompany
|
|
galabau.oci.region=eu-frankfurt-1
|
|
galabau.oci.bucket=my-bucket
|
|
galabau.oci.tenant-prefix=mandant_42/
|
|
galabau.oci.incoming-prefix=eingang/
|
|
# Scalar Credentials aus Env-Vars:
|
|
galabau.oci.tenancy-id=${OCI_TENANCY_ID}
|
|
galabau.oci.user-id=${OCI_USER_ID}
|
|
galabau.oci.fingerprint=${OCI_FINGERPRINT}
|
|
# Private Key als gemountetes Kubernetes Secret (Dateipfad, kein Env-Var-String):
|
|
galabau.oci.private-key-path=${OCI_PRIVATE_KEY_PATH} # z.B. /etc/oci/private-key.pem
|
|
|
|
# ORDS
|
|
galabau.ords.base-url=http://ords:8080
|
|
galabau.ords.process-incoming-path=/ords/.../net_storage/process_incoming_ba_data
|
|
galabau.ords.api-key=${GALABAU_ORDS_API_KEY}
|
|
|
|
# Fehlerbehandlung
|
|
galabau.retry.max-attempts=3
|
|
galabau.retry.backoff-ms=1000
|
|
```
|
|
|
|
**Credential-Strategie:**
|
|
- Alle Passwörter und API-Keys über `${ENV_VAR_NAME}` — Quarkus liest Umgebungsvariablen nativ
|
|
- OCI-Auth via **SimpleAuthenticationDetailsProvider** — Credentials aus Env-Vars, Private Key als gemountetes Kubernetes Secret (PEM-Datei); entspricht dem was `apex_web_service` mit OCI Web Credential intern tut (OCI HTTP Signature V1)
|
|
- Deployment: Kubernetes Secrets → Environment Injection für Passwörter/API-Keys
|
|
|
|
---
|
|
|
|
## REST Endpoint
|
|
|
|
```java
|
|
@Path("/api/process-incoming")
|
|
@ApplicationScoped
|
|
public class FileProcessingResource {
|
|
|
|
@Inject
|
|
ApplicationConfig config;
|
|
|
|
@Inject
|
|
FileProcessingPipeline pipeline;
|
|
|
|
@POST
|
|
@Produces(MediaType.APPLICATION_JSON)
|
|
public Response triggerProcessing(@HeaderParam("X-Api-Key") String apiKey) {
|
|
if (!config.api().key().equals(apiKey)) {
|
|
return Response.status(Response.Status.UNAUTHORIZED).build();
|
|
}
|
|
// Async: Pipeline im Hintergrund, APEX bekommt sofort 202
|
|
pipeline.processAllAsync();
|
|
return Response.accepted().build();
|
|
}
|
|
}
|
|
```
|
|
|
|
**Aufruf durch APEX Automation:**
|
|
```sql
|
|
apex_web_service.make_rest_request(
|
|
p_url => 'http://backend:8080/api/process-incoming',
|
|
p_http_method => 'POST',
|
|
p_http_headers => apex_util.string_to_table('X-Api-Key:' || <secret>)
|
|
);
|
|
```
|
|
|
|
**Concurrency Guard:** `FileProcessingPipeline` hält ein `AtomicBoolean isRunning`-Flag.
|
|
Kommt ein zweiter Trigger während eine Pipeline läuft → 409 Conflict zurückgeben, kein doppelter Lauf.
|
|
|
|
---
|
|
|
|
## Async-Verhalten
|
|
|
|
```java
|
|
@ApplicationScoped
|
|
public class FileProcessingPipeline {
|
|
|
|
private final AtomicBoolean isRunning = new AtomicBoolean(false);
|
|
|
|
@Inject
|
|
ManagedExecutor executor; // Quarkus Managed Executor
|
|
|
|
public Response processAllAsync() {
|
|
if (!isRunning.compareAndSet(false, true)) {
|
|
return Response.status(409).entity("Pipeline already running").build();
|
|
}
|
|
executor.submit(() -> {
|
|
try {
|
|
processAll();
|
|
} finally {
|
|
isRunning.set(false);
|
|
}
|
|
});
|
|
return Response.accepted().build();
|
|
}
|
|
|
|
void processAll() { ... } // eigentliche Logik
|
|
}
|
|
```
|
|
|
|
Fehler im Hintergrund-Thread landen im Log (OTLP → Grafana) — APEX bekommt sie
|
|
nicht als HTTP-Fehler, da die Antwort bereits weg ist. Das entspricht dem bisherigen
|
|
n8n fire-and-forget-Verhalten.
|
|
|
|
---
|
|
|
|
## Fehlerbehandlung & Retry
|
|
|
|
### Fehlerklassen
|
|
|
|
| Fehler | Typ | Retry | Verhalten |
|
|
|---|---|---|---|
|
|
| SFTP-Verbindung fehlgeschlagen | transient | nein | Nächster APEX-Lauf (1h) versucht es |
|
|
| ZIP beschädigt | persistent | nein | ZIP auf SFTP umbenennen zu `.error`, Log |
|
|
| OCI-Verbindung fehlgeschlagen (z.B. 503) | transient | ja (exponential backoff) | @Retry |
|
|
| OCI-Upload einer Datei schlägt fehl | persistent | nein | SFTP-Rename zu `.error`, Log — bereits hochgeladene OCI-Dateien bleiben (idempotent) |
|
|
| ORDS-Aufruf schlägt fehl | transient | ja (2-3x) | Marker liegt vor → APEX Automation schlägt beim nächsten Lauf ein |
|
|
| Allgemein technischer Fehler | fallabhängig | siehe SmallRye Fault Tolerance | Exception-Log |
|
|
|
|
### Retry-Strategie (SmallRye Fault Tolerance)
|
|
|
|
```java
|
|
@Retry(maxRetries = 3, delay = 1000, delayUnit = ChronoUnit.MILLIS)
|
|
@Timeout(value = 10, unit = ChronoUnit.SECONDS)
|
|
public void notifyOrds(ProcessingContext context) { ... }
|
|
```
|
|
|
|
---
|
|
|
|
## Datenmodelle
|
|
|
|
### `ProcessingContext`
|
|
|
|
```java
|
|
public class ProcessingContext {
|
|
public UUID runId; // eindeutige Lauf-ID
|
|
public String zipFilename; // z.B. "export_2026-04-08.zip"
|
|
public String zipNameWithoutExt; // z.B. "export_2026-04-08"
|
|
public Path localZipPath; // lokale ZIP-Datei (für Cleanup)
|
|
public Path localExtractDir; // lokales Entpack-Verzeichnis (für Cleanup)
|
|
public List<FileEntry> extractedFiles; // Verzeichnis + Datei-Namen
|
|
public boolean markerUploaded;
|
|
public LocalDateTime startTime;
|
|
public ProcessingStatus status;
|
|
}
|
|
|
|
public enum ProcessingStatus {
|
|
PENDING, PARTIALLY_UPLOADED, MARKER_UPLOADED, ORDS_NOTIFIED, FAILED
|
|
}
|
|
```
|
|
|
|
### `FileEntry`
|
|
|
|
```java
|
|
public class FileEntry {
|
|
public String relativePath; // "subdir/file.csv"
|
|
public String ociKey; // "eingang/export_2026-04-08/subdir/file.csv"
|
|
public long fileSize;
|
|
public boolean isMarker; // true nur für "_READY_FOR_DB_PROCESSING_"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## SFTP-Verarbeitung mit SSHJ
|
|
|
|
Siehe `docs/SFTP-Integration.md` für Details zur SSHJ-Integration (Host-Key-Verification,
|
|
Credentials, Fehlerbehandlung).
|
|
|
|
### Verarbeitungslogik
|
|
|
|
```
|
|
Pipeline.processAll():
|
|
1. SftpService.listZipFiles() → ["export_2026-04-08.zip", ...]
|
|
2. für jede ZIP:
|
|
a. SftpService.download(zip) → lokale Datei
|
|
b. ZipExtractionService.extract() → ProcessingContext mit FileEntry-Liste
|
|
c. OciUploadService.upload() → Dateien + Marker in OCI
|
|
d. SftpService.renameRemote(.processed oder .error)
|
|
e. OrdsNotificationService.notify()
|
|
f. cleanup: lokale ZIP + Entpack-Verzeichnis löschen ← immer, auch bei Fehler
|
|
```
|
|
|
|
**Cleanup (Schritt f) läuft immer** — in einem `finally`-Block — damit kein Disk-Vollaufen
|
|
bei Fehlern oder großen ZIPs.
|
|
|
|
---
|
|
|
|
## OCI-Authentifizierung (SimpleAuthenticationDetailsProvider)
|
|
|
|
Credentials kommen aus Umgebungsvariablen (skalare Werte) und einem gemounteten
|
|
Kubernetes Secret (Private Key als PEM-Datei).
|
|
|
|
```java
|
|
@ApplicationScoped
|
|
public class OciUploadService {
|
|
|
|
private final ObjectStorage client;
|
|
|
|
@Inject
|
|
OciConfig config;
|
|
|
|
@PostConstruct
|
|
void init() {
|
|
SimpleAuthenticationDetailsProvider auth =
|
|
SimpleAuthenticationDetailsProvider.builder()
|
|
.tenantId(config.tenancyId())
|
|
.userId(config.userId())
|
|
.fingerprint(config.fingerprint())
|
|
.region(Region.fromRegionId(config.region()))
|
|
.privateKeySupplier(new FilePrivateKeySupplier(config.privateKeyPath()))
|
|
.build();
|
|
|
|
this.client = ObjectStorageClient.builder().build(auth);
|
|
}
|
|
}
|
|
```
|
|
|
|
**Kubernetes Deployment:**
|
|
- Skalare Werte (`tenancyId`, `userId`, `fingerprint`) → Kubernetes Secret → Env-Vars
|
|
- Private Key PEM-Datei → Kubernetes Secret → Volume Mount unter `/etc/oci/private-key.pem`
|
|
- `OCI_PRIVATE_KEY_PATH=/etc/oci/private-key.pem` als Env-Var
|
|
|
|
---
|
|
|
|
## ORDS-Integration
|
|
|
|
### REST-Client
|
|
|
|
```java
|
|
@RegisterRestClient(configKey = "ords-client")
|
|
public interface OrdsClient {
|
|
|
|
@POST
|
|
@Path("${galabau.ords.process-incoming-path}")
|
|
@Consumes(MediaType.APPLICATION_JSON)
|
|
@Produces(MediaType.APPLICATION_JSON)
|
|
Response processIncoming(ProcessIncomingRequest request);
|
|
}
|
|
|
|
// application.properties:
|
|
// quarkus.rest-client.ords-client.url=${galabau.ords.base-url}
|
|
|
|
public class ProcessIncomingRequest {
|
|
public String zipName; // "export_2026-04-08"
|
|
public String runId; // für Logging-Korrelation
|
|
public LocalDateTime uploadedAt;
|
|
}
|
|
```
|
|
|
|
### Fehlerbehandlung
|
|
|
|
- Schlägt der ORDS-Aufruf fehl → Marker liegt trotzdem vor
|
|
- APEX Automation findet beim nächsten Stundenlauf den Marker und verarbeitet
|
|
- **Keine** Versuche, den Fehler lokal zu beheben
|
|
|
|
---
|
|
|
|
## Abhängigkeiten (pom.xml)
|
|
|
|
```xml
|
|
<properties>
|
|
<java.version>25</java.version>
|
|
<quarkus.platform.version><!-- aktuelle LTS auf code.quarkus.io prüfen --></quarkus.platform.version>
|
|
</properties>
|
|
|
|
<dependencyManagement>
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>io.quarkus.platform</groupId>
|
|
<artifactId>quarkus-bom</artifactId>
|
|
<version>${quarkus.platform.version}</version>
|
|
<type>pom</type>
|
|
<scope>import</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
</dependencyManagement>
|
|
|
|
<dependencies>
|
|
<!-- Quarkus Core -->
|
|
<dependency>
|
|
<groupId>io.quarkus</groupId>
|
|
<artifactId>quarkus-arc</artifactId>
|
|
</dependency>
|
|
|
|
<!-- REST Endpoint (eingehend von APEX) -->
|
|
<dependency>
|
|
<groupId>io.quarkus</groupId>
|
|
<artifactId>quarkus-rest</artifactId>
|
|
</dependency>
|
|
|
|
<!-- REST Client (ausgehend zu ORDS) -->
|
|
<dependency>
|
|
<groupId>io.quarkus</groupId>
|
|
<artifactId>quarkus-rest-client-jackson</artifactId>
|
|
</dependency>
|
|
|
|
<!-- Managed Executor (für Async-Pipeline) -->
|
|
<dependency>
|
|
<groupId>io.quarkus</groupId>
|
|
<artifactId>quarkus-smallrye-context-propagation</artifactId>
|
|
</dependency>
|
|
|
|
<!-- SFTP: SSHJ — moderner Java SFTP/SSH Client -->
|
|
<!-- Aktuelle Version prüfen: https://mvnrepository.com/artifact/com.hierynomus/sshj -->
|
|
<dependency>
|
|
<groupId>com.hierynomus</groupId>
|
|
<artifactId>sshj</artifactId>
|
|
<version>0.38.0</version>
|
|
</dependency>
|
|
|
|
<!-- OCI Object Storage SDK -->
|
|
<!-- Aktuelle Version prüfen: https://mvnrepository.com/artifact/com.oracle.oci.sdk/oci-java-sdk-objectstorage -->
|
|
<dependency>
|
|
<groupId>com.oracle.oci.sdk</groupId>
|
|
<artifactId>oci-java-sdk-objectstorage</artifactId>
|
|
<version>3.44.0</version>
|
|
</dependency>
|
|
|
|
<!-- ZIP -->
|
|
<dependency>
|
|
<groupId>org.apache.commons</groupId>
|
|
<artifactId>commons-compress</artifactId>
|
|
<version>1.26.1</version>
|
|
</dependency>
|
|
|
|
<!-- Observability -->
|
|
<dependency>
|
|
<groupId>io.quarkus</groupId>
|
|
<artifactId>quarkus-opentelemetry</artifactId>
|
|
</dependency>
|
|
|
|
<!-- Fault Tolerance -->
|
|
<dependency>
|
|
<groupId>io.quarkus</groupId>
|
|
<artifactId>quarkus-smallrye-fault-tolerance</artifactId>
|
|
</dependency>
|
|
|
|
<!-- Tests -->
|
|
<dependency>
|
|
<groupId>io.quarkus</groupId>
|
|
<artifactId>quarkus-junit5</artifactId>
|
|
<scope>test</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
```
|
|
|
|
**Hinweis:** `oci-java-sdk-objectstorage` und `sshj` liegen nicht im Quarkus BOM —
|
|
Versionen beim Projektstart auf Maven Central prüfen. Quarkus-eigene Artefakte (`quarkus-*`)
|
|
brauchen keine `<version>`, da das BOM sie bereitstellt.
|
|
|
|
---
|
|
|
|
## Observability & Logging
|
|
|
|
### MDC-Hierarchie
|
|
|
|
```
|
|
runId → ein ZIP-Verarbeitungslauf (gesetzt am Anfang jeder ZIP)
|
|
step → aktueller Pipeline-Step
|
|
fileIdx → welche Datei in diesem Schritt (optional)
|
|
```
|
|
|
|
MDC nach jeder ZIP mit `MDC.clear()` leeren — damit kein Kontext in die nächste ZIP sickert.
|
|
|
|
### Log-Level
|
|
|
|
| Schritt | Level | Beispiel |
|
|
|---|---|---|
|
|
| `api-trigger` | INFO | "Processing triggered by APEX, starting async pipeline" |
|
|
| `sftp-list` | INFO | "5 new ZIP files found on SFTP" |
|
|
| `zip-extract` | INFO | "ZIP 'export_2026-04-08.zip' extracted: 12 files, 5 directories" |
|
|
| `oci-upload` | INFO | "Uploaded 12 files + marker to OCI in 3.2s" |
|
|
| `ords-notify` | INFO | "ORDS endpoint called, HTTP 200" |
|
|
| `cleanup` | DEBUG | "Local files deleted: /tmp/sftp-work/export_2026-04-08.zip" |
|
|
| Fehler | ERROR | Mit vollem MDC-Context und Exception |
|
|
|
|
**Stack:** OTLP → Loki/Grafana (Entwicklung: Dev Services, Produktion: externer Collector)
|
|
|
|
---
|
|
|
|
## Migrations-Schritte
|
|
|
|
1. **Phase 1: Entwicklung**
|
|
- Projekt-Setup (Java 25, Quarkus 3.x, SSHJ)
|
|
- REST Endpoint (`FileProcessingResource`) mit API-Key-Auth + Concurrency Guard
|
|
- SFTP-Operationen (SSHJ: list, download, rename) mit Fingerprint-Verification
|
|
- ZIP-Entpacken (Apache Commons Compress)
|
|
- OCI-Upload (OCI SDK, Instance Principal, Marker-Handling)
|
|
- ORDS-Benachrichtigung (REST Client + Retry)
|
|
- Lokaler Cleanup (always in finally)
|
|
- Fehlerbehandlung + OTLP-Logging
|
|
- Package `pck_auto_import` mit `p_process_incoming_files` auf DB-Seite implementieren
|
|
- Unit-Tests + Integration-Tests
|
|
|
|
2. **Phase 2: Testing & Deployment**
|
|
- E2E-Tests mit echtem SFTP / OCI / ORDS
|
|
- Parallel-Run: n8n und Quarkus-Backend gleichzeitig aktiv
|
|
- **APEX Automation aktualisieren:** URL von n8n-Webhook auf `http://backend:8080/api/process-incoming` ändern, `X-Api-Key`-Header ergänzen
|
|
- Grafana Dashboards + Alerts aufsetzen
|
|
|
|
3. **Phase 3: Cutover**
|
|
- n8n deaktivieren / entfernen
|
|
- Monitoring etablieren
|
|
|
|
---
|
|
|
|
## Deployment-Constraints
|
|
|
|
- **Einzelinstanz:** Der Service läuft als Einzelinstanz. Kein Clustering.
|
|
Mehrere Instanzen würden dieselben SFTP-Dateien gleichzeitig verarbeiten.
|
|
Der `AtomicBoolean`-Guard schützt nur innerhalb einer Instanz.
|
|
Solange APEX Automation den Webhook nur einmal pro Lauf aufruft, kein Problem.
|
|
|
|
- **Idempotenz:** OCI PUT ist idempotent. Bei abgebrochenem Lauf ohne Marker:
|
|
nächster Trigger lädt ZIP erneut, Dateien werden überschrieben — kein korrupter Zustand.
|
|
|
|
- **Disk-Space:** Lokales Arbeitsverzeichnis `/tmp/sftp-work` — Cleanup läuft immer im finally.
|
|
Maximale gleichzeitige Belegung: eine ZIP + entpackte Dateien (sequenzielle Verarbeitung).
|
|
Capacity Planning erforderlich (→ offene Frage).
|
|
|
|
---
|
|
|
|
## Vorteile gegenüber n8n
|
|
|
|
| Aspekt | n8n | Quarkus Backend |
|
|
|---|---|---|
|
|
| **Abhängigkeiten** | Externe SaaS/self-hosted | Ein JAR |
|
|
| **Fehlerbehandlung** | UI-basiert konfigurieren | Java Code, testbar |
|
|
| **Observability** | n8n-Logs + externe Integrationen | OTLP → Loki/Grafana nativ |
|
|
| **Sicherheit** | Credentials in n8n-DB | Env-Variablen / Secrets |
|
|
| **Trigger** | n8n-Webhook | REST Endpoint (identisches Muster) |
|
|
| **Wartbarkeit** | Workflow-Änderungen in UI | Code-Reviews, Git-History |
|
|
| **Skalierung** | Horizontale Skalierung komplex | Standard Quarkus/Kubernetes |
|
|
|
|
---
|
|
|
|
## Architektur-Entscheidungen ✅
|
|
|
|
- [x] Trigger: **REST Endpoint** (von APEX Automation aufgerufen, identisch zu bisherigem n8n-Webhook)
|
|
- [x] Scheduling: **APEX Automation** (bleibt unverändert — kein eigener Scheduler im Service)
|
|
- [x] Async: **fire & forget** (202 Accepted sofort, Pipeline im Hintergrund — wie n8n)
|
|
- [x] Endpoint-Auth: **X-Api-Key Header** (einfach, funktioniert mit APEX Web Service Calls)
|
|
- [x] Concurrency Guard: **AtomicBoolean** (kein Doppellauf bei schnellen APEX-Retries)
|
|
- [x] SFTP-Lösung: **SSHJ** (`com.hierynomus:sshj`) — leichtgewichtiger SFTP-Client
|
|
- [x] SFTP Host-Key: **Fingerprint-basiert** via `galabau.sftp.host-key-fingerprint` in Config
|
|
- [x] OCI Auth: **SimpleAuthenticationDetailsProvider** (Credentials via Env-Vars + gemountetes Kubernetes Secret für Private Key — entspricht `apex_web_service` mit OCI Credential)
|
|
- [x] OCI SDK: **OCI Java SDK** (HTTP Signature V1 automatisch)
|
|
- [x] ZIP: **Apache Commons Compress**
|
|
- [x] REST Clients: **MicroProfile REST Client** (configKey-basiert)
|
|
- [x] Credentials: **`${ENV_VAR}`** in application.properties — Quarkus liest nativ aus Umgebungsvariablen
|
|
- [x] Java: **25**
|
|
- [x] Cleanup: **immer im finally** nach jeder ZIP
|
|
|
|
## Offene Fragen
|
|
|
|
- [ ] Disk-Space: Wie groß dürfen ZIPs maximal sein? → Capacity Planning
|
|
- [ ] SFTP-Auth: Password oder Public-Key für Produktion? → Public-Key empfohlen
|
|
- [ ] Monitoring: Welche Grafana-Alerts sind Pflicht? → TBD mit OPS-Team
|