feat: integrate Bugtracker module, UpdateService enhancements & Token hierarchy
This commit is contained in:
Deploymentcenter Bot
@@ -0,0 +1,156 @@
|
||||
# Deploymentcenter — Bugtracker, Feature-Tracker & Token Provisioning Guide
|
||||
|
||||
> **Zielgruppe**: KI-Agenten & Softwareentwickler
|
||||
> **Zweck**: Anleitung zur automatisierten Registrierung, Fehlererfassung, Feature-Einreichung und Behebung über das Deployment Center.
|
||||
|
||||
---
|
||||
|
||||
## 1. Token-Architektur & Autonome Sub-Token-Erstellung
|
||||
|
||||
Das Deployment Center nutzt eine hierarchische Token-Struktur:
|
||||
- **Master-Token**: Wird im Deployment Center Admin-Dashboard pro Identität (z. B. Entwickler-Agent, Client-Anwendung, Host-Server) erstellt.
|
||||
- **Sub-Token**: Wird von Anwendungen oder KI-Agenten autonom über die Provisioning-API angefordert und für API-Aufrufe genutzt.
|
||||
|
||||
### Sub-Token Anfordern (`POST /api/tokens/v1/provision`)
|
||||
Sendet einen HTTP POST Request mit dem Master-Token im `X-Master-Token` Header.
|
||||
|
||||
```http
|
||||
POST /api/tokens/v1/provision HTTP/1.1
|
||||
Host: dc.mhdf.de
|
||||
Content-Type: application/json
|
||||
X-Master-Token: dc_master_myapp_dev_agent_001
|
||||
|
||||
{
|
||||
"name": "Dev Workstation Agent #4",
|
||||
"instance_id": "DEV-WORKSTATION-01",
|
||||
"scopes": ["bugtracker:report", "bugtracker:manage"],
|
||||
"environment": "development"
|
||||
}
|
||||
```
|
||||
|
||||
#### JSON Antwort:
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"sub_token": "dc_sub_5f8a2c1...",
|
||||
"token_id": "tok_s_89a1b2c3",
|
||||
"name": "Dev Workstation Agent #4",
|
||||
"scopes": ["bugtracker:report", "bugtracker:manage"],
|
||||
"environment": "development"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Bug & Feature Ingest API (`POST /api/bugtracker/v1/report`)
|
||||
|
||||
Wird von Überwachungs-Agenten im laufenden Betrieb oder Entwickler-Agenten auf der Workstation genutzt.
|
||||
|
||||
### Request Schema:
|
||||
```json
|
||||
{
|
||||
"project_slug": "myapp",
|
||||
"type": "bug", // "bug" oder "feature_request"
|
||||
"environment": "development", // "production", "development", "staging", "testing"
|
||||
"severity": "high", // "low", "medium", "high", "critical"
|
||||
"title": "NullReferenceException in UserAuthService.cs line 42",
|
||||
"description": "Beim Login ohne gesetzte Session ist ein Unerwarteter Nullpointer-Fehler aufgetreten.",
|
||||
"error_message": "NullReferenceException: Object reference not set to an instance of an object.",
|
||||
"stack_trace": "at MyApp.Core.UserAuthService.ValidateToken(String token)...",
|
||||
"build_version": "v1.4.2-dev",
|
||||
"created_by": "agent:dev-monitor-01"
|
||||
}
|
||||
```
|
||||
|
||||
#### Besonderheiten:
|
||||
- **Deduplizierung**: Bei Bugs berechnet das System automatisch einen Error-Hash. Tritt derselbe Fehler in derselben Umgebung erneut auf, wird kein neuer Bug angelegt, sondern `occurrence_count` hochgezählt.
|
||||
|
||||
---
|
||||
|
||||
## 3. Geschützte Management & Resolution API (`/api/bugtracker/v1/manage`)
|
||||
|
||||
Schnittstelle für KI-Behebungs-Agenten zum Abrufen offener Bugs, Schreiben von Diagnose-Notizen und Markieren als gelöst.
|
||||
|
||||
**Header**: `Authorization: Bearer <dein_sub_token>` (Benötigt Scope `bugtracker:manage`).
|
||||
|
||||
### 3.1 Offene Items Abfragen (`GET /api/bugtracker/v1/manage/index.php`)
|
||||
Filter-Parameter: `environment` (`development`/`production`), `type` (`bug`/`feature_request`), `status` (`open`/`in_progress`/`resolved`).
|
||||
|
||||
### 3.2 Item-Details & Kommentar-Historie (`GET /api/bugtracker/v1/manage/index.php?id=123`)
|
||||
|
||||
### 3.3 Ermittlungsschritt / Kommentar Hinzufügen (`POST /api/bugtracker/v1/manage/index.php?action=comment&id=123`)
|
||||
```json
|
||||
{
|
||||
"comment": "Log-Analyse gestartet. Der Fehler tritt auf, wenn $_SESSION['dc_user_id'] nicht gesetzt ist.",
|
||||
"author": "agent:code-fixer-01",
|
||||
"action_taken": "investigated"
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 Item als Gelöst / Umgesetzt Markieren (`POST /api/bugtracker/v1/manage/index.php?action=resolve&id=123`)
|
||||
```json
|
||||
{
|
||||
"resolved_in_build": "v1.4.3",
|
||||
"resolution_notes": "Null-Check für Session-Variable hinzugefügt.",
|
||||
"author": "agent:code-fixer-01"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. C# (.NET 8) Implementierungsbeispiel für KI-Agenten
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
using System.Net.Http;
|
||||
using System.Text;
|
||||
using System.Text.Json;
|
||||
using System.Threading.Tasks;
|
||||
|
||||
public class DeploymentCenterBugtrackerClient
|
||||
{
|
||||
private static readonly HttpClient HttpClient = new HttpClient();
|
||||
private const string BaseUrl = "https://dc.mhdf.de";
|
||||
|
||||
public static async Task IngestDevBugAsync(string masterToken, string title, string errorMessage, string stackTrace)
|
||||
{
|
||||
// 1. Sub-Token anfordern
|
||||
var provisionReq = new HttpRequestMessage(HttpMethod.Post, $"{BaseUrl}/api/tokens/v1/provision")
|
||||
{
|
||||
Content = new StringContent(JsonSerializer.Serialize(new
|
||||
{
|
||||
client_name = "Dev Agent Client",
|
||||
scopes = new[] { "bugtracker:report" },
|
||||
environment = "development"
|
||||
}), Encoding.UTF8, "application/json")
|
||||
};
|
||||
provisionReq.Headers.Add("X-Master-Token", masterToken);
|
||||
|
||||
var provResponse = await HttpClient.SendAsync(provisionReq);
|
||||
var provJson = await provResponse.Content.ReadAsStringAsync();
|
||||
using var doc = JsonDocument.Parse(provJson);
|
||||
string subToken = doc.RootElement.GetProperty("sub_token").GetString();
|
||||
|
||||
// 2. Bug melden
|
||||
var reportReq = new HttpRequestMessage(HttpMethod.Post, $"{BaseUrl}/api/bugtracker/v1/report")
|
||||
{
|
||||
Content = new StringContent(JsonSerializer.Serialize(new
|
||||
{
|
||||
project_slug = "myapp",
|
||||
type = "bug",
|
||||
environment = "development",
|
||||
severity = "high",
|
||||
title = title,
|
||||
error_message = errorMessage,
|
||||
stack_trace = stackTrace,
|
||||
build_version = "v1.4.2-dev",
|
||||
created_by = "agent:dev-agent-01"
|
||||
}), Encoding.UTF8, "application/json")
|
||||
};
|
||||
reportReq.Headers.Add("Authorization", $"Bearer {subToken}");
|
||||
|
||||
var reportResponse = await HttpClient.SendAsync(reportReq);
|
||||
Console.WriteLine($"Report Response: {reportResponse.StatusCode}");
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,133 @@
|
||||
# Deploymentcenter — UpdateService Integration & Deployment Guide
|
||||
|
||||
Das **UpdateService-Modul** des Deploymentcenters bietet ein unternehmensweites, leichtgewichtiges Update-, Rollback- und Reparatur-Schema auf Basis eines LEMP-Stacks (Nginx Static Files + PHP API).
|
||||
|
||||
---
|
||||
|
||||
## 1. Übersicht & Architektur
|
||||
|
||||
- **Kein dauerhafter Background-Dienst**: Hauptanwendungen prüfen beim Start einmalig schnell und netzwerktolerant auf verfügbare Updates und Dateiintegrität.
|
||||
- **Entkoppelte Ausführung**: Bei Handlungsbedarf beendet sich die Hauptanwendung sauber und übergibt die Kontrolle an den eigenständigen Console Agent (`update-agent.exe` / `update-agent`).
|
||||
- **3-Kanal-System**: Kanäle `prod` (Produktiv), `beta` (Vorab-Test), `dev` (Entwicklung).
|
||||
- **Statische LEMP-Verteilung**: Downloads und Versionen-Manifeste (`latest.json`, `manifest.json`, `package.tar.gz`) werden über Nginx extrem performant bereitgestellt.
|
||||
|
||||
---
|
||||
|
||||
## 2. Integration in .NET Client-Anwendungen
|
||||
|
||||
### A. Referenz auf `Deploymentcenter.Client`
|
||||
|
||||
Binde das Projekt oder Paket `Deploymentcenter.Client` in deine Anwendung ein.
|
||||
|
||||
```csharp
|
||||
using Deploymentcenter.Client;
|
||||
using Deploymentcenter.Client.Models;
|
||||
|
||||
// Early Start Hook in Program.cs (oder App.xaml.cs)
|
||||
var updateClient = new UpdateClient();
|
||||
var checkResult = await updateClient.CheckForUpdateAsync(
|
||||
baseUrl: "https://dc.mhdf.de",
|
||||
projectId: "myapp",
|
||||
currentVersion: BuildInfo.Version,
|
||||
channel: "prod"
|
||||
);
|
||||
|
||||
if (checkResult.UpdateAvailable)
|
||||
{
|
||||
Console.WriteLine($"[UPDATE] Neues Release v{checkResult.LatestRelease.Version} verfügbar!");
|
||||
|
||||
// UpdateAgent starten und Hauptanwendung beenden
|
||||
UpdateClient.LaunchUpdateAgent(
|
||||
agentPath: "update-agent.exe",
|
||||
projectId: "myapp",
|
||||
channel: "prod",
|
||||
action: "update",
|
||||
version: "latest",
|
||||
exitCurrentApp: true
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### B. MSBuild BuildInfo Generierung
|
||||
|
||||
Binde das `Deploymentcenter.BuildInfo.targets` Script in deine `.csproj` ein, damit Version, UTC-Build-Datum und Git Commit-Hash automatisch zur Übersetzungszeit generiert werden:
|
||||
|
||||
```xml
|
||||
<Import Project="..\Deploymentcenter.Client\Deploymentcenter.BuildInfo.targets" />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Packaging & Deployment CLI (`pack-and-deploy`)
|
||||
|
||||
Das Packaging-Tool verpackt den `dotnet publish`-Output, berechnet Hashes, erzeugt das `manifest.json` und lädt alles per FTP auf den LEMP-Server.
|
||||
|
||||
### Aufruf-Beispiel:
|
||||
|
||||
```bash
|
||||
# Automatisierter Release-Publish via CLI
|
||||
pack-and-deploy --project myapp --version 1.4.0 --channel prod --publish-dir ./bin/Release/net8.0/publish --changelog "Fehlerbehebungen und Performance-Optimierung"
|
||||
```
|
||||
|
||||
### Konfiguration (`packager.config.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"ftpHost": "www531.your-server.de",
|
||||
"ftpPort": 21,
|
||||
"ftpUser": "bergisnu_4",
|
||||
"ftpPass": "o2#M*NN^5EsT",
|
||||
"ftpRemoteBaseDir": "/public_html/releases",
|
||||
"apiBaseUrl": "https://dc.mhdf.de",
|
||||
"excludePatterns": [
|
||||
"*.pdb",
|
||||
"*.xml",
|
||||
"appsettings.Development.json",
|
||||
"*.log",
|
||||
"logs/*"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Standalone UpdateAgent (`update-agent`)
|
||||
|
||||
Der `update-agent` kann sowohl interaktiv (Spectre.Console Terminal UI) als auch im Headless CLI-Modus betrieben werden.
|
||||
|
||||
### CLI Modus Befehle:
|
||||
|
||||
```bash
|
||||
# Nach Updates suchen
|
||||
update-agent --project myapp --channel prod --action check
|
||||
|
||||
# Auf neueste Version aktualisieren
|
||||
update-agent --project myapp --channel prod --action update --version latest --target-dir /opt/myapp
|
||||
|
||||
# Rollback auf ältere Version
|
||||
update-agent --project myapp --channel prod --action update --version 1.3.2
|
||||
|
||||
# Integritäts-Reparatur der aktuellen Installation
|
||||
update-agent --project myapp --channel prod --action repair
|
||||
|
||||
# Alle verfügbaren Versionen auflisten
|
||||
update-agent --project myapp --channel prod --action list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. LEMP Verzeichnisstruktur auf dem Server
|
||||
|
||||
```text
|
||||
/var/www/releases/ (oder /public_html/releases/)
|
||||
└── {ProjectId}/ # z.B. myapp, polytrader
|
||||
├── prod/
|
||||
│ ├── latest.json # Kanal-Übersicht & neueste Version
|
||||
│ ├── 1.4.0/
|
||||
│ │ ├── package.tar.gz # Das gezippte Release
|
||||
│ │ ├── package.tar.gz.sha256
|
||||
│ │ └── manifest.json # Einzeldateien + Hashes
|
||||
│ └── 1.3.9/
|
||||
├── beta/
|
||||
└── dev/
|
||||
```
|
||||
Reference in New Issue
Block a user