Schnellstart

Quelldateien

Diese Seite wurde aus den folgenden Quelldateien erstellt:

• Deploy.md
• Dockerfile
• Genie_start.sh
• start_genie.sh
• check_dep_port.sh
• genie-client/main.py
• genie-tool/server.py
• genie-client/server.py
• ui/src/hooks/index.ts
• ui/src/utils/index.ts

JoyAgent-JDGenIE ist eine Multi-Service-Architektur, die aus einem Frontend (UI), einem Java-Backend, einem Python-basierten Tool-Service und einem MCP-Client besteht. Das System ermöglicht die Integration von LLM-Modellen für verschiedene KI-gestützte Aufgaben.

Voraussetzungen und Umgebungsprüfung

Systemanforderungen

Das Projekt benötigt folgende Abhängigkeiten mit spezifischen Mindestversionen:

Die detaillierte Installationsanleitung für macOS umfasst die Installation von Java via Homebrew (brew install maven) mit dem Pfad /opt/homebrew/Cellar/openjdk/24.0.1/libexec/openjdk.jdk/Contents/Home sowie alternative manuelle Installation über Oracle-Downloads (Deploy.md:3-31).

Automatische Abhängigkeitsprüfung

Das Projekt enthält ein automatisiertes Prüfskript, das alle Systemanforderungen validiert:

bash
1chmod +x check_dep_port.sh
2./check_dep_port.sh

Das Skript check_dep_port.sh prüft automatisch die installierten Versionen von Java, Maven und Node.js. Es extrahiert die Versionsnummern und vergleicht sie mit den Mindestanforderungen (Java >= 17, Node.js >= 18). Bei erfolgreicher Prüfung erscheint eine grüne Bestätigungsmeldung, bei Fehlern eine rote Warnung (check_dep_port.sh:13-61).

Installation von uv für Python

Für die Python-basierten Services wird der Paketmanager uv benötigt:

bash
1pip install uv

Dieser Manager wird für die Verwaltung virtueller Umgebungen und Abhängigkeiten der Tool- und MCP-Services verwendet.

Schnellstart mit Ein-Skript-Installation

Übersicht des automatisierten Starts

Das Projekt bietet ein umfassendes Startskript Genie_start.sh, das alle Komponenten automatisch konfiguriert und startet. Dieses Skript führt folgende Schritte aus:

1. Konfigurationsprüfung und -validierung
2. Initialisierung aller Komponenten
3. Sequenzieller Start aller Dienste

正在加载图表渲染器...

Automatische Konfigurationsprüfung

Das Startskript validiert automatisch die Konfigurationsdateien vor dem Start. Es prüft, ob die Datei genie-backend/src/main/resources/application.yml existiert und ob Platzhalter wie <input llm server here> oder <input llm key here> ersetzt wurden. Ebenso wird die .env-Datei im genie-tool-Verzeichnis auf Platzhalter wie <your api key> geprüft (Genie_start.sh:55-95).

Falls die .env-Datei nicht existiert, wird automatisch die Vorlage .env_template kopiert:

bash
1# Automatische Kopie durch das Skript
2cp genie-tool/.env_template genie-tool/.env

Initialisierung aller Komponenten

Die Initialisierung umfasst drei Hauptphasen:

1. Backend-Build: Wechselt in genie-backend und führt build.sh aus
2. Datenbank-Initialisierung: Führt python -m genie_tool.db.db_engine im Tool-Verzeichnis aus
3. Virtuelle Umgebungen: Erstellt Python-virtual-environments für Tool- und MCP-Services

(Genie_start.sh:97-149)

bash
1# Start des vollständigen Systems
2chmod +x Genie_start.sh
3./Genie_start.sh

Manueller Start der einzelnen Dienste

Frontend-Service

Der Frontend-Service wird im Verzeichnis ui gestartet:

bash
1cd joyagent-jdgenie/ui && sh start.sh

Bei erfolgreicher Start erscheint die Meldung Local: http://localhost:3000/. Das Frontend ist dann unter dieser URL erreichbar (Deploy.md:32-52).

Backend-Service

Der Backend-Service erfordert einen Build-Schritt vor dem Start:

bash
1cd joyagent-jdgenie/genie-backend && sh build.sh

Nach erfolgreichem Build erscheint [INFO] BUILD SUCCESS. Anschließend wird der Service gestartet:

bash
1sh start.sh

Die Logs können über tail -f genie-backend_startup.log überwacht werden (Deploy.md:32-52).

Tool-Service und MCP-Service

Die Python-basierten Services werden mit uv verwaltet:

bash
1# Tool-Service
2cd joyagent-jdgenie/genie-tool
3pip install uv
4uv sync
5source .venv/bin/activate
6python -m genie_tool.db.db_engine  # Nur beim ersten Start
7cp .env_template .env
8uv run python server.py

bash
1# MCP-Client-Service
2cd joyagent-jdgenie/genie-client
3uv venv
4source .venv/bin/activate
5sh start.sh

(Deploy.md:71-100)

Docker-Deployment

Multi-Stage Docker-Build

Das Projekt enthält ein umfassendes Dockerfile mit Multi-Stage-Build für alle Komponenten:

Der Build-Prozess installiert zunächst pnpm global, konfiguriert npm mit einem chinesischen Mirror und führt den Frontend-Build durch. Anschließend wird das Java-Backend mit Maven kompiliert (Dockerfile:1-19).

Container-Konfiguration

Das finale Image konfiguriert:

• Volumes: /data/genie-tool für persistente Daten
• Ports: 3000 (Frontend), 8080 (Backend), 1601 (MCP)
• Healthcheck: Prüft alle 30 Sekunden http://localhost:3000

(Dockerfile:105-120)

bash
1# Docker-Image bauen
2docker build -t joyagent-jdgenie .
3
4# Container starten
5docker run -d \
6  -p 3000:3000 \
7  -p 8080:8080 \
8  -p 1601:1601 \
9  -e OPENAI_API_KEY=your_key \
10  -e OPENAI_BASE_URL=your_url \
11  joyagent-jdgenie

Container-Startskript

Das Container-Startskript start_genie.sh orchestriert alle Services innerhalb des Containers. Es startet das Frontend mit pnpm preview --host 0.0.0.0 --port 3000, führt das Backend-Startskript aus und initialisiert die Python-Services (start_genie.sh:1-61).

Konfiguration der LLM-API

Backend-Konfiguration

Die LLM-Konfiguration erfolgt in genie-backend/src/main/resources/application.yml. Die Konfiguration unterstützt mehrere Modelle mit folgenden Parametern:

yaml
1settings: '{"claude-3-7-sonnet-v1": {
2    "model": "claude-3-7-sonnet-v1",
3    "max_tokens": 8192,
4    "temperature": 0,
5    "base_url": "<input llm server here>",
6    "apikey": "<input llm key here>",
7    "max_input_tokens": 128000
8}}'

Die Platzhalter <input llm server here> und <input llm key here> müssen durch die tatsächliche LLM-Server-URL und den API-Schlüssel ersetzt werden (Deploy.md:53-67).

Umgebungsvariablen

Die Tool-Services verwenden eine .env-Datei im Verzeichnis genie-tool:

(Genie_start.sh:72-86)

Nach Änderungen an der Konfiguration ist ein erneuter Build und Neustart erforderlich:

bash
1cd genie-backend && sh build.sh && sh start.sh

Laufzeitüberprüfung und Validierung

Dienst-Status prüfen

Nach dem Start sollten folgende Endpunkte erreichbar sein:

Log-Überwachung

Das Backend schreibt Logs in genie-backend_startup.log. Die Überwachung erfolgt mit:

bash
1tail -f genie-backend_startup.log

(Deploy.md:54)

Docker-Healthcheck

Im Docker-Deployment prüft der integrierte Healthcheck die Frontend-Verfügbarkeit:

bash
1# Healthcheck-Status anzeigen
2docker inspect --format='{{.State.Health.Status}}' <container_id>

(Dockerfile:116-117)

Häufige Probleme und Lösungen

Problem 1: Java-Version nicht kompatibel

Symptom: Build schlägt fehl mit Java-Versionsfehler

Lösung: Java-Version prüfen und ggf. aktualisieren:

bash
1java -version
2# Sollte >= 17 anzeigen
3
4# macOS mit Homebrew
5brew install openjdk

(Deploy.md:5-14)

Problem 2: pnpm nicht gefunden

Symptom: Fehlermeldung beim Frontend-Start

Lösung: pnpm global installieren:

bash
1npm install -g pnpm
2# oder
3curl -fsSL https://get.pnpm.io/install.sh | sh -

(Deploy.md:24-26)

Problem 3: Konfigurationsplatzhalter nicht ersetzt

Symptom: Startskript bricht mit Fehlermeldung zu Platzhaltern ab

Lösung: Konfigurationsdateien manuell prüfen:

bash
1# Backend-Konfiguration
2grep -n "input llm" genie-backend/src/main/resources/application.yml
3
4# Tool-Umgebungsvariablen
5grep -n "your api key" genie-tool/.env

Beide Befehle sollten keine Ergebnisse liefern, wenn die Konfiguration korrekt ist (Genie_start.sh:34-50).

Problem 4: Port bereits belegt

Symptom: Dienst startet nicht, Port-Konflikt

Lösung: Belegte Ports prüfen:

bash
1# Ports 3000, 8080, 1601 prüfen
2lsof -i :3000
3lsof -i :8080
4lsof -i :1601

Problem 5: Virtuelle Python-Umgebung fehlerhaft

Symptom: Python-Module nicht gefunden

Lösung: Virtuelle Umgebung neu erstellen:

bash
1cd genie-tool
2rm -rf .venv
3uv sync
4source .venv/bin/activate

(Genie_start.sh:119-122)

Nächste Schritte

Nach erfolgreichem Start des Systems empfiehlt sich die Konsultation folgender Themenbereiche:

1. API-Dokumentation: Detaillierte Beschreibung der verfügbaren Endpunkte und deren Parameter
2. Modell-Konfiguration: Erweiterte Einstellungen für verschiedene LLM-Provider
3. Tool-Entwicklung: Erstellung eigener Tools für das System
4. Produktions-Deployment: Sicherheitshinweise und Skalierungsoptionen für den produktiven Einsatz

Die Konfiguration zusätzlicher Modelle in der application.yml ermöglicht die Nutzung verschiedener LLM-Provider parallel. Dabei können unterschiedliche Modelle für verschiedene Betriebsmodi (z.B. React-Modus) spezifiziert werden (Deploy.md:56-64).