backend structure build

2025-12-23 18:38:44 +00:00
parent 861e0f65c3
commit e7f55839eb
8 changed files with 702 additions and 27 deletions
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -0,0 +1,186 @@
+# BAMS Architecture
+
+## Overview
+
+BAMS (Backup Appliance Management System) is a comprehensive management platform for backup appliances, providing unified control over storage, tape libraries, iSCSI targets, and Bacula integration.
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Cockpit Web UI                        │
+│                  (Cockpit Plugin)                        │
+└──────────────────────┬──────────────────────────────────┘
+                       │ HTTP/REST API
+                       │
+┌──────────────────────▼──────────────────────────────────┐
+│              BAMS Backend Service (Go)                   │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐│
+│  │   Disk   │  │   Tape   │  │   iSCSI   │  │ Bacula  ││
+│  │ Service  │  │ Service  │  │  Service │  │ Service ││
+│  └────┬─────┘  └────┬─────┘  └────┬──────┘  └────┬────┘│
+└───────┼─────────────┼──────────────┼──────────────┼─────┘
+        │             │              │              │
+┌───────▼─────┐ ┌─────▼─────┐ ┌─────▼──────┐ ┌─────▼─────┐
+│    LVM      │ │   mtx     │ │    SCST    │ │  systemd  │
+│    ZFS      │ │  sg_lib   │ │   iSCSI    │ │  bacula-sd│
+└─────────────┘ └───────────┘ └────────────┘ └───────────┘
+```
+
+## Components
+
+### 1. Backend Service (Go)
+
+**Location**: `backend/`
+
+**Structure**:
+- `main.go` - Entry point, HTTP server setup
+- `internal/api/` - REST API handlers and routing
+- `internal/services/` - Business logic services
+  - `disk/` - Disk repository management (LVM/ZFS)
+  - `tape/` - Tape library management
+  - `iscsi/` - iSCSI target management (SCST)
+  - `bacula/` - Bacula integration
+  - `logs/` - Logging and diagnostics
+  - `audit/` - Audit logging
+- `internal/config/` - Configuration management
+- `internal/logger/` - Logging utilities
+- `internal/utils/` - Helper functions
+
+**Key Features**:
+- RESTful API with JSON responses
+- Graceful shutdown handling
+- Request validation
+- Error recovery middleware
+- CORS support
+
+### 2. Cockpit Plugin (Frontend)
+
+**Location**: `cockpit/`
+
+**Files**:
+- `manifest.json` - Plugin metadata
+- `index.html` - Main UI structure
+- `bams.js` - JavaScript application logic
+
+**Features**:
+- Dashboard with real-time monitoring
+- Storage repository management
+- Tape library operations
+- iSCSI target configuration
+- Bacula status and control
+- Log viewer
+
+### 3. Configuration
+
+**Location**: `configs/`
+
+**Files**:
+- `bams.service` - Systemd service file
+- `config.yaml.example` - Configuration template
+- `polkit.rules` - Polkit authorization rules
+
+## Data Flow
+
+### Disk Repository Creation
+
+1. User creates repository via UI
+2. Frontend sends POST to `/api/v1/disk/repositories`
+3. Backend validates input
+4. Disk service creates LVM volume or ZFS zvol
+5. Repository metadata stored
+6. Response returned to UI
+
+### Tape Operations
+
+1. User triggers inventory/load/unload
+2. Frontend sends request to API
+3. Tape service executes `mtx` commands
+4. Results parsed and returned
+5. UI updates display
+
+### iSCSI Target Management
+
+1. User creates/updates target
+2. Backend validates IQN, portals, initiators
+3. SCST configuration generated
+4. Configuration applied via `scstadmin`
+5. Status returned to UI
+
+## Security
+
+- **Authentication**: PAM/system users via Cockpit
+- **Authorization**: Polkit rules for privileged operations
+- **Audit Logging**: All configuration changes logged
+- **Input Validation**: All user input validated
+- **Error Handling**: Panic recovery middleware
+
+## API Endpoints
+
+### Dashboard
+- `GET /api/v1/dashboard` - System overview
+
+### Disk Repositories
+- `GET /api/v1/disk/repositories` - List repositories
+- `POST /api/v1/disk/repositories` - Create repository
+- `GET /api/v1/disk/repositories/{id}` - Get repository
+- `DELETE /api/v1/disk/repositories/{id}` - Delete repository
+
+### Tape Library
+- `GET /api/v1/tape/library` - Library status
+- `POST /api/v1/tape/inventory` - Run inventory
+- `GET /api/v1/tape/drives` - List drives
+- `POST /api/v1/tape/drives/{id}/load` - Load tape
+- `POST /api/v1/tape/drives/{id}/unload` - Unload tape
+- `GET /api/v1/tape/slots` - List slots
+
+### iSCSI Targets
+- `GET /api/v1/iscsi/targets` - List targets
+- `POST /api/v1/iscsi/targets` - Create target
+- `GET /api/v1/iscsi/targets/{id}` - Get target
+- `PUT /api/v1/iscsi/targets/{id}` - Update target
+- `DELETE /api/v1/iscsi/targets/{id}` - Delete target
+- `POST /api/v1/iscsi/targets/{id}/apply` - Apply configuration
+- `POST /api/v1/iscsi/targets/{id}/luns` - Add LUN
+- `DELETE /api/v1/iscsi/targets/{id}/luns/{lun}` - Remove LUN
+- `GET /api/v1/iscsi/sessions` - List sessions
+
+### Bacula
+- `GET /api/v1/bacula/status` - SD status
+- `GET /api/v1/bacula/config` - Get config
+- `POST /api/v1/bacula/config` - Generate config
+- `POST /api/v1/bacula/inventory` - Run inventory
+- `POST /api/v1/bacula/restart` - Restart SD
+
+### Logs & Diagnostics
+- `GET /api/v1/logs/{service}` - Get logs
+- `GET /api/v1/logs/{service}/stream` - Stream logs (WebSocket)
+- `GET /api/v1/diagnostics/bundle` - Download support bundle
+
+## Deployment
+
+1. Build backend: `make build`
+2. Install service: `make install`
+3. Configure: Edit `/etc/bams/config.yaml`
+4. Start service: `systemctl start bams`
+5. Access via Cockpit web interface
+
+## Dependencies
+
+- **Go 1.21+**
+- **Cockpit 300+**
+- **SCST** (iSCSI target framework)
+- **mtx** (tape library control)
+- **LVM tools** (for LVM repositories)
+- **ZFS tools** (for ZFS repositories, optional)
+- **Bacula** (for backup integration)
+
+## Future Enhancements
+
+- WebSocket support for real-time log streaming
+- Multi-tenant support
+- High Availability
+- Tape encryption management
+- Cloud tiering
+- Policy-based tape lifecycle
+