Initial commit: Werkzeuge-Sammlung

Enthält: - rdp_client.py: RDP Client mit GUI und Monitor-Auswahl - rdp.sh: Bash-basierter RDP Client - teamleader_test/: Network Scanner Fullstack-App - teamleader_test2/: Network Mapper CLI Subdirectories mit eigenem Repo wurden ausgeschlossen. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-28 09:39:24 +01:00
commit cb073786b3
112 changed files with 23543 additions and 0 deletions
--- a/teamleader_test/docs/guides/troubleshooting.md
+++ b/teamleader_test/docs/guides/troubleshooting.md
@@ -0,0 +1,478 @@
+# Troubleshooting Guide
+
+Common errors, solutions, and debugging procedures for the Network Scanner Tool.
+
+---
+
+## Quick Diagnostics
+
+### Health Check
+```bash
+# Check if services are running
+docker compose ps
+
+# Test backend health
+curl http://localhost/health
+
+# Check logs
+docker compose logs backend --tail=50
+docker compose logs frontend --tail=50
+```
+
+---
+
+## Common Errors & Solutions
+
+### Backend Errors
+
+#### ❌ `500 Internal Server Error` on API calls
+
+**Symptoms**: API returns 500 error, backend logs show exceptions
+
+**Common Causes**:
+1. **Schema mismatch** between backend (Pydantic) and frontend (TypeScript)
+2. **Database constraint violation** (NOT NULL, UNIQUE, etc.)
+3. **SQLAlchemy DetachedInstanceError** in background tasks
+
+**Solutions**:
+
+**Schema Mismatch**:
+```bash
+# Check if frontend/src/types/api.ts matches app/schemas.py
+# Example: Backend returns "network_range" but frontend expects "target"
+
+# Fix: Update TypeScript interface
+# frontend/src/types/api.ts
+export interface Scan {
+  network_range: string;  // ← Must match backend exactly
+  // not: target: string;
+}
+```
+
+**Database Constraint**:
+```python
+# Error: NOT NULL constraint failed: services.host_id
+# Cause: Services added before host committed
+
+# Fix: Commit and refresh host BEFORE adding services
+host = self._get_or_create_host(ip)
+self.db.commit()      # ← CRITICAL: Ensure host.id is set
+self.db.refresh(host)
+
+# NOW safe to add services
+service = Service(host_id=host.id, port=80)
+self.db.add(service)
+```
+
+**DetachedInstanceError**:
+```python
+# Error: Instance is not bound to a Session
+# Cause: Using request session in background task
+
+# Fix: Create new session in background task
+def scan_wrapper(scan_id: int):
+    db = SessionLocal()  # ← New session
+    try:
+        scan_service.execute_scan(scan_id, db)
+    finally:
+        db.close()
+
+background_tasks.add_task(scan_wrapper, scan_id)
+```
+
+#### ❌ `TopologyNode object has no field "position"`
+
+**Symptoms**: `/api/topology` returns 500, logs show Pydantic validation error
+
+**Cause**: Code trying to set field that doesn't exist in schema
+
+**Solution**:
+```python
+# Check app/schemas.py - ensure TopologyNode has required fields
+class TopologyNode(BaseModel):
+    id: str
+    ip: str
+    hostname: Optional[str]
+    type: str
+    status: str
+    service_count: int
+    connections: int
+    # NOTE: No "position" field in simplified schema
+
+# Remove any code that sets node.position
+# Don't use _calculate_layout() if it sets positions
+```
+
+#### ❌ `Database is locked`
+
+**Symptoms**: SQLite database errors, operations timeout
+
+**Cause**: SQLite only allows one writer at a time
+
+**Solutions**:
+1. Close other database connections
+2. Wait for running scans to complete
+3. Restart backend: `docker compose restart backend`
+4. For production with high concurrency, use PostgreSQL
+
+---
+
+### Frontend Errors
+
+#### ❌ Blank page / White screen
+
+**Symptoms**: Frontend loads but shows nothing
+
+**Debugging**:
+```bash
+# 1. Open browser console (F12)
+# 2. Check for JavaScript errors
+
+# Common errors:
+# - "Cannot read property 'X' of undefined" → API returned unexpected structure
+# - "Network Error" → Backend not running or wrong URL
+# - "TypeError: X is not a function" → Missing dependency or wrong import
+```
+
+**Solutions**:
+```bash
+# Check VITE_API_URL environment variable
+# frontend/.env
+VITE_API_URL=http://localhost:8000
+
+# Verify backend is running
+curl http://localhost:8000/health
+
+# Rebuild frontend
+docker compose up -d --build frontend
+```
+
+#### ❌ TypeScript build errors
+
+**Symptoms**: `docker compose up --build` fails with TS errors
+
+**Common Errors**:
+```typescript
+// Error: Type X is not assignable to type Y
+// Fix: Check frontend/src/types/api.ts matches backend response
+
+// Error: Property 'X' does not exist on type 'Y'
+// Fix: Add missing property to interface or use optional chaining
+
+// Error: 'X' is declared but its value is never read
+// Fix: Remove unused variable or use underscore: _unused
+```
+
+#### ❌ Network map crashes or doesn't display
+
+**Symptoms**: Network page loads but map is blank or crashes
+
+**Debugging**:
+```bash
+# Check topology API response structure
+curl -s http://localhost:8000/api/topology | jq .
+
+# Should return:
+{
+  "nodes": [{"id": "1", "ip": "...", ...}],
+  "edges": [{"source": "1", "target": "2", ...}],
+  "statistics": {...}
+}
+```
+
+**Solutions**:
+- Verify `topology.nodes` is an array
+- Check node objects have required fields: `id`, `ip`, `type`, `status`
+- Ensure edge objects have: `source`, `target`, `type`
+- Run a scan first to populate data
+
+---
+
+### Docker & Deployment Errors
+
+#### ❌ `Cannot start service backend: Ports are not available`
+
+**Symptoms**: Docker Compose fails to start, port 8000 or 80 in use
+
+**Solution**:
+```bash
+# Find process using port
+lsof -ti:8000
+lsof -ti:80
+
+# Kill process or stop conflicting container
+docker stop $(docker ps -q)
+
+# Or change ports in docker-compose.yml
+services:
+  backend:
+    ports:
+      - "8001:8000"  # Use different host port
+```
+
+#### ❌ `no such file or directory: ./data/network_scanner.db`
+
+**Symptoms**: Backend can't access database
+
+**Solution**:
+```bash
+# Create data directory
+mkdir -p /home/rwiegand/Nextcloud/entwicklung/Werkzeuge/teamleader_test/data
+
+# Check volume mounting in docker-compose.yml
+volumes:
+  - ./data:/app/data
+
+# Restart containers
+docker compose down && docker compose up -d
+```
+
+#### ❌ Container keeps restarting
+
+**Symptoms**: `docker compose ps` shows container constantly restarting
+
+**Debugging**:
+```bash
+# Check container logs
+docker compose logs backend --tail=100
+
+# Common issues:
+# - Missing environment variables
+# - Failed database initialization
+# - Port conflicts
+# - Import errors (missing dependencies)
+```
+
+---
+
+### Scanning Errors
+
+#### ❌ Scan starts but nothing is discovered
+
+**Symptoms**: Scan completes but finds 0 hosts
+
+**Causes**:
+1. Network range is wrong or unreachable
+2. Firewall blocking outgoing connections
+3. Hosts are actually offline
+
+**Solutions**:
+```bash
+# Test network connectivity manually
+ping 192.168.1.1
+
+# Verify network range syntax
+# Correct: "192.168.1.0/24"
+# Wrong: "192.168.1.0-255", "192.168.1.*"
+
+# Check if you're on the correct network
+ip addr show
+
+# Try scanning your own machine
+curl -X POST http://localhost:8000/api/scans/start \
+  -H "Content-Type: application/json" \
+  -d '{"network_range":"127.0.0.1/32","scan_type":"quick"}'
+```
+
+#### ❌ Scan never completes / hangs
+
+**Symptoms**: Scan status stays "running" indefinitely
+
+**Debugging**:
+```bash
+# Check backend logs for errors
+docker compose logs backend --tail=100 | grep -i error
+
+# Check if scan is actually running
+curl http://localhost:8000/api/scans/1/status
+
+# Look for exceptions in logs
+docker compose logs backend | grep -i "exception\|traceback"
+```
+
+**Solutions**:
+```bash
+# Cancel stuck scan
+curl -X DELETE http://localhost:8000/api/scans/1/cancel
+
+# Restart backend
+docker compose restart backend
+
+# If persists, check for:
+# - Deadlocks (check cancel_requested flag)
+# - Infinite loops in scan logic
+# - Background task not properly yielding
+```
+
+#### ❌ Progress bar doesn't update
+
+**Symptoms**: Scan starts but progress stays at 0%
+
+**Cause**: WebSocket not connected or not receiving updates
+
+**Solutions**:
+```bash
+# Check WebSocket connection in browser console (F12)
+# Should see: "WebSocket connected. Total connections: 1"
+
+# Verify WebSocket endpoint
+curl --include \
+     --no-buffer \
+     --header "Connection: Upgrade" \
+     --header "Upgrade: websocket" \
+     --header "Sec-WebSocket-Version: 13" \
+     --header "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
+     http://localhost:8000/api/ws
+
+# Check backend WebSocket handler
+# app/api/endpoints/websocket.py should broadcast progress
+```
+
+---
+
+### Database Errors
+
+#### ❌ `PendingRollbackError`
+
+**Symptoms**: Operations fail with "can't reconnect until invalid transaction is rolled back"
+
+**Cause**: Exception occurred but transaction wasn't rolled back
+
+**Solution**:
+```python
+# Wrap operations in try/except with rollback
+try:
+    # Database operations
+    self.db.commit()
+except Exception as e:
+    self.db.rollback()  # ← CRITICAL
+    logger.error(f"Error: {e}")
+    raise
+```
+
+#### ❌ Column doesn't exist after schema change
+
+**Symptoms**: `no such column: connections.extra_data`
+
+**Cause**: Database schema doesn't match models
+
+**Solution**:
+```bash
+# For development: Delete and recreate database
+rm data/network_scanner.db
+docker compose restart backend
+
+# For production: Create migration
+# (Requires alembic setup - TODO)
+```
+
+---
+
+## Debugging Procedures
+
+### Backend Debugging
+
+```bash
+# 1. Enable debug logging
+# Edit .env
+DEBUG=True
+LOG_LEVEL=DEBUG
+
+# 2. Restart backend
+docker compose restart backend
+
+# 3. Watch logs in real-time
+docker compose logs -f backend
+
+# 4. Test specific endpoint
+curl -v http://localhost:8000/api/hosts
+
+# 5. Check database state
+docker compose exec backend python -c "
+from app.database import SessionLocal
+from app.models import Host
+db = SessionLocal()
+print('Hosts:', db.query(Host).count())
+"
+```
+
+### Frontend Debugging
+
+```bash
+# 1. Open browser DevTools (F12)
+# 2. Check Console tab for errors
+# 3. Check Network tab for failed API calls
+# 4. Use React DevTools extension
+
+# Test API directly
+curl http://localhost:8000/api/topology
+
+# Check if response matches TypeScript types
+# Compare with frontend/src/types/api.ts
+```
+
+### Network Issues
+
+```bash
+# Test backend API from host
+curl http://localhost:8000/health
+
+# Test from inside frontend container
+docker compose exec frontend wget -O- http://backend:8000/health
+
+# Check DNS resolution
+docker compose exec frontend nslookup backend
+
+# Verify network connectivity
+docker network inspect teamleader_test_scanner-network
+```
+
+---
+
+## Performance Issues
+
+### Slow Scans
+
+**Symptoms**: Scans take much longer than expected
+
+**Solutions**:
+1. **Reduce concurrency**: Edit `app/config.py`, set `MAX_CONCURRENT_SCANS = 25`
+2. **Increase timeout**: Set `DEFAULT_SCAN_TIMEOUT = 5`
+3. **Use quick scan**: Only scan common ports
+4. **Reduce network range**: Scan /28 instead of /24
+
+### High Memory Usage
+
+**Symptoms**: Docker containers using excessive memory
+
+**Solutions**:
+```bash
+# Limit container memory
+# docker-compose.yml
+services:
+  backend:
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+
+# Reduce concurrent scans
+# app/config.py
+MAX_CONCURRENT_SCANS = 25
+```
+
+---
+
+## Getting Help
+
+If issues persist:
+
+1. **Check logs**: `docker compose logs backend --tail=100`
+2. **Review this guide**: Common solutions above
+3. **Check copilot instructions**: [.github/copilot-instructions.md](../.github/copilot-instructions.md)
+4. **Review code review archive**: [archive/review-2025-12-04/](../archive/review-2025-12-04/)
+5. **Verify project status**: [docs/project-status.md](project-status.md)
+
+---
+
+**Last Updated**: December 4, 2025