GitMa/README.md

# Git Manager

A web-based management platform for Gitea server mirrors and SSH keys, providing centralized control over Git server synchronization and key management.

## Features

- **SSH Key Management**
  - Create, read, update, and delete SSH keys
  - AES-256 encryption for stored private keys
  - Secure key storage and retrieval

- **Server Management**
  - Add and manage Gitea server configurations
  - Server health monitoring
  - Automatic synchronization support

- **Repository Synchronization**
  - Mirror repositories from Gitea servers
  - Sync history and logging
  - Scheduled sync operations

- **Web Interface**
  - Modern Vue.js-based frontend
  - Element Plus UI components
  - Real-time status monitoring

- **REST API**
  - Full-featured REST API
  - Token-based authentication
  - OpenAPI documentation

## Quick Start

### Prerequisites

- Python 3.8+
- Node.js 16+
- Git

### Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd git
```

2. Install backend dependencies:
```bash
cd backend
pip install -r requirements.txt
```

3. Install frontend dependencies:
```bash
cd ../frontend
npm install
```

### Initialization

1. Create environment configuration:
```bash
cp .env.example .env
```

2. Edit `.env` with your configuration:
```bash
# Generate a secure encryption key (32 bytes, base64 encoded)
python -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"

# Generate a secure API token
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

3. Initialize the database:
```bash
cd backend
python init_db.py
```

### Build and Run

#### Option 1: Using the start script (Linux/Mac)
```bash
./start.sh
```

#### Option 2: Manual startup

1. Build the frontend:
```bash
cd frontend
npm run build
```

2. Start the backend server:
```bash
cd ../backend
python -m app.main
```

Or using uvicorn directly:
```bash
cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

3. Access the application:
   - Web UI: http://localhost:8000
   - API Documentation: http://localhost:8000/api/docs
   - ReDoc: http://localhost:8000/api/redoc

## API Documentation

### Authentication

All API endpoints require authentication via the `X-API-Token` header:

```bash
curl -H "X-API-Token: your-api-token" http://localhost:8000/api/servers
```

### Main Endpoints

#### Status
- `GET /api/status` - Get system status

#### SSH Keys
- `GET /api/ssh-keys` - List all SSH keys
- `POST /api/ssh-keys` - Create a new SSH key
- `GET /api/ssh-keys/{key_id}` - Get SSH key details
- `PUT /api/ssh-keys/{key_id}` - Update SSH key
- `DELETE /api/ssh-keys/{key_id}` - Delete SSH key

#### Servers
- `GET /api/servers` - List all servers
- `POST /api/servers` - Add a new server
- `GET /api/servers/{server_id}` - Get server details
- `PUT /api/servers/{server_id}` - Update server
- `DELETE /api/servers/{server_id}` - Delete server
- `POST /api/servers/{server_id}/sync` - Trigger server sync

For detailed API documentation, visit `/api/docs` when the server is running.

## Development Setup

### Backend Development

1. Install development dependencies:
```bash
cd backend
pip install -r requirements.txt
```

2. Run tests:
```bash
pytest
```

3. Run with auto-reload:
```bash
uvicorn app.main:app --reload
```

### Frontend Development

1. Start development server:
```bash
cd frontend
npm run dev
```

2. Build for production:
```bash
npm run build
```

3. Preview production build:
```bash
npm run preview
```

## Project Structure

```
git/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── api/            # API route handlers
│   │   ├── models/         # SQLAlchemy ORM models
│   │   ├── schemas/        # Pydantic schemas
│   │   ├── services/       # Business logic
│   │   ├── config.py       # Configuration management
│   │   ├── database.py     # Database connection
│   │   ├── security.py     # Encryption & auth
│   │   └── main.py         # FastAPI application
│   ├── tests/              # Backend tests
│   ├── init_db.py          # Database initialization script
│   └── requirements.txt    # Python dependencies
├── frontend/               # Vue.js frontend
│   ├── src/
│   │   ├── api/           # API client
│   │   ├── components/    # Vue components
│   │   ├── router/        # Vue Router config
│   │   ├── stores/        # Pinia stores
│   │   └── main.js        # App entry point
│   ├── package.json       # Node dependencies
│   └── vite.config.js     # Vite config
├── data/                  # Application data
│   ├── database.db        # SQLite database
│   ├── ssh-keys/          # Stored SSH keys
│   └── repos/             # Mirrored repositories
├── docs/                  # Documentation
├── tests/                 # Integration tests
├── .env.example           # Environment template
├── start.sh               # Startup script
└── README.md              # This file
```

## Configuration

Configuration is managed through environment variables in the `.env` file:

| Variable | Description | Default |
|----------|-------------|---------|
| `GM_ENCRYPT_KEY` | AES-256 encryption key (base64) | Required |
| `GM_API_TOKEN` | API authentication token | Required |
| `GM_DATA_DIR` | Data directory path | `./data` |
| `GM_HOST` | Server host | `0.0.0.0` |
| `GM_PORT` | Server port | `8000` |

## Tech Stack

### Backend
- **FastAPI** - Modern, fast web framework
- **SQLAlchemy** - ORM for database operations
- **Pydantic** - Data validation using Python type annotations
- **Uvicorn** - ASGI server
- **APScheduler** - Task scheduling
- **Paramiko** - SSH/SCP operations
- **GitPython** - Git operations
- **Cryptography** - AES-256 encryption

### Frontend
- **Vue.js 3** - Progressive JavaScript framework
- **Vite** - Build tool and dev server
- **Vue Router** - Official router
- **Pinia** - State management
- **Element Plus** - Vue 3 UI library
- **Axios** - HTTP client

### Database
- **SQLite** - Lightweight database (easily replaceable with PostgreSQL/MySQL)

## Security

- SSH private keys are encrypted using AES-256-GCM
- API authentication via secure tokens
- CORS support for cross-origin requests
- Input validation and sanitization

## License

[Your License Here]

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.