docs: README mit Logo, Installation, API-Übersicht und Projektstruktur
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
229
README.md
Normal file
229
README.md
Normal file
@@ -0,0 +1,229 @@
|
||||
<p align="center">
|
||||
<img src="mcm_logo.png" alt="MCM Logo" width="200"/>
|
||||
</p>
|
||||
|
||||
<h1 align="center">MCM – MultiCustomerMessenger</h1>
|
||||
|
||||
<p align="center">
|
||||
Unified Messaging Gateway für Telegram, WhatsApp und SMS auf dem Raspberry Pi
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
## Überblick
|
||||
|
||||
MCM ist ein selbst gehostetes Messaging-Gateway, das eingehende und ausgehende Nachrichten über mehrere Kanäle zentral verwaltet. Die Bedienung erfolgt über eine REST-API oder eine interaktive Terminal-Oberfläche (TUI), die auch im Browser läuft.
|
||||
|
||||
**Unterstützte Kanäle**
|
||||
|
||||
| Kanal | Backend |
|
||||
|---|---|
|
||||
| Telegram | python-telegram-bot (Bot, Long-Polling) |
|
||||
| WhatsApp | Green API (green-api.com) |
|
||||
| SMS | python-gsmmodem-new (USB-Modem) |
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
- REST-API (FastAPI) mit OpenAPI-Dokumentation (`/docs`)
|
||||
- Terminal-UI (Textual) – im Browser via `textual serve`
|
||||
- Multi-User-Authentifizierung mit JWT-Tokens
|
||||
- Benutzerverwaltung (Admin-Rollen, Passwort ändern)
|
||||
- Konversations- und Kontaktverwaltung in der Datenbank
|
||||
- MariaDB als Produktions-Backend, SQLite für lokale Entwicklung
|
||||
- SMS optional – läuft auch ohne angeschlossenes USB-Modem
|
||||
- systemd-Dienst für den Dauerbetrieb
|
||||
|
||||
---
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
- Python 3.11+
|
||||
- MariaDB (optional, SQLite ist Standard)
|
||||
- USB-GSM-Modem (optional, für SMS)
|
||||
- Green API Account (optional, für WhatsApp)
|
||||
- Telegram Bot Token (optional)
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# 1. Repository klonen
|
||||
git clone https://gitea.it-drui.de/viewit/MCM.git
|
||||
cd MCM
|
||||
|
||||
# 2. Virtuelle Umgebung anlegen und Pakete installieren
|
||||
python3 -m venv .venv
|
||||
.venv/bin/pip install -r requirements.txt
|
||||
|
||||
# 3. Konfiguration anlegen
|
||||
cp .env.example .env
|
||||
# .env mit den eigenen Werten befüllen (Tokens, DB-URL, Secret Key)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Konfiguration (`.env`)
|
||||
|
||||
```env
|
||||
# API
|
||||
API_KEY=mein-sicherer-api-key
|
||||
HOST=0.0.0.0
|
||||
PORT=8000
|
||||
|
||||
# Datenbank
|
||||
DATABASE_URL=sqlite:///./mcm.db
|
||||
# Für MariaDB:
|
||||
# DATABASE_URL=mysql+pymysql://user:pass@localhost:3306/mcm
|
||||
|
||||
# Telegram
|
||||
TELEGRAM_TOKEN=123456:ABC-...
|
||||
|
||||
# WhatsApp (Green API)
|
||||
WHATSAPP_ID_INSTANCE=1234567890
|
||||
WHATSAPP_API_TOKEN=abcdef...
|
||||
|
||||
# SMS (USB-Modem)
|
||||
SMS_ENABLED=false
|
||||
SMS_PORT=/dev/ttyUSB0
|
||||
|
||||
# Authentifizierung
|
||||
SECRET_KEY=change-this-secret-key-min-32-chars!!
|
||||
TOKEN_EXPIRE_HOURS=24
|
||||
|
||||
# Standard-Admin (wird beim ersten Start angelegt)
|
||||
DEFAULT_ADMIN_USER=admin
|
||||
DEFAULT_ADMIN_PASSWORD=admin
|
||||
```
|
||||
|
||||
> **Wichtig:** `SECRET_KEY` sollte ein langer zufälliger String sein:
|
||||
> ```bash
|
||||
> openssl rand -hex 32
|
||||
> ```
|
||||
|
||||
---
|
||||
|
||||
## Starten
|
||||
|
||||
### Mit Terminal-UI (lokal)
|
||||
|
||||
```bash
|
||||
.venv/bin/python main.py
|
||||
```
|
||||
|
||||
### Nur API (kein Terminal)
|
||||
|
||||
```bash
|
||||
.venv/bin/python main.py --no-tui
|
||||
# oder
|
||||
.venv/bin/python main_api_only.py
|
||||
```
|
||||
|
||||
### TUI im Browser
|
||||
|
||||
```bash
|
||||
# API separat starten (Terminal 1)
|
||||
.venv/bin/python main_api_only.py
|
||||
|
||||
# TUI als Browser-App (Terminal 2)
|
||||
.venv/bin/python -m textual serve --host 0.0.0.0 --port 8001 tui_standalone.py
|
||||
```
|
||||
|
||||
Dann im Browser öffnen: `http://<raspberry-ip>:8001`
|
||||
|
||||
---
|
||||
|
||||
## Benutzerverwaltung
|
||||
|
||||
Beim ersten Start wird automatisch ein Admin-Benutzer angelegt (`admin` / `admin`).
|
||||
Das Passwort sollte direkt danach geändert werden.
|
||||
|
||||
### API-Endpoints
|
||||
|
||||
| Methode | Pfad | Beschreibung |
|
||||
|---|---|---|
|
||||
| `POST` | `/api/v1/auth/login` | Anmeldung → JWT-Token |
|
||||
| `GET` | `/api/v1/auth/me` | Aktueller Benutzer |
|
||||
| `GET` | `/api/v1/users/` | Benutzerliste (Admin) |
|
||||
| `POST` | `/api/v1/users/` | Benutzer anlegen (Admin) |
|
||||
| `PUT` | `/api/v1/users/{id}` | Benutzer bearbeiten |
|
||||
| `DELETE` | `/api/v1/users/{id}` | Benutzer löschen (Admin) |
|
||||
|
||||
### Beispiel – Login per curl
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username": "admin", "password": "admin"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API-Übersicht
|
||||
|
||||
Vollständige Dokumentation unter `http://localhost:8000/docs`
|
||||
|
||||
| Methode | Pfad | Beschreibung |
|
||||
|---|---|---|
|
||||
| `POST` | `/api/v1/messages` | Nachricht senden |
|
||||
| `GET` | `/api/v1/conversations/` | Konversationen auflisten |
|
||||
| `GET` | `/api/v1/conversations/{id}/messages` | Nachrichten einer Konversation |
|
||||
| `GET` | `/api/v1/contacts/` | Kontakte auflisten |
|
||||
| `POST` | `/api/v1/contacts/` | Kontakt anlegen |
|
||||
| `GET` | `/api/v1/channels/status` | Kanal-Status |
|
||||
| `GET` | `/health` | Health-Check |
|
||||
|
||||
---
|
||||
|
||||
## systemd-Dienst
|
||||
|
||||
```bash
|
||||
# Dienst installieren
|
||||
sudo cp install/mcm.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable mcm
|
||||
sudo systemctl start mcm
|
||||
|
||||
# Status prüfen
|
||||
sudo systemctl status mcm
|
||||
journalctl -u mcm -f
|
||||
```
|
||||
|
||||
Weitere Details: [install/README_install.md](install/README_install.md)
|
||||
|
||||
---
|
||||
|
||||
## Projektstruktur
|
||||
|
||||
```
|
||||
MCM/
|
||||
├── main.py # Einstiegspunkt (TUI + API)
|
||||
├── main_api_only.py # Nur API (für systemd)
|
||||
├── tui_standalone.py # Einstiegspunkt für textual serve
|
||||
├── config.py # Einstellungen (pydantic-settings)
|
||||
├── schemas.py # Pydantic-Modelle
|
||||
├── api/
|
||||
│ ├── app.py # FastAPI-Anwendung
|
||||
│ ├── auth.py # JWT + API-Key Authentifizierung
|
||||
│ └── routes/ # REST-Routen
|
||||
├── channels/ # Kanal-Implementierungen
|
||||
├── services/ # Business-Logik
|
||||
├── tasks/ # APScheduler (WhatsApp-Polling)
|
||||
├── tui/
|
||||
│ ├── api_client.py # HTTP-Client für TUI → API
|
||||
│ ├── app.py # Textual App
|
||||
│ ├── screens/ # Login- und Hauptbildschirm
|
||||
│ └── styles.tcss # TUI-Stylesheet
|
||||
├── db/
|
||||
│ ├── models.py # SQLAlchemy-Modelle
|
||||
│ └── database.py # Engine + Session
|
||||
└── install/ # systemd-Dienst + Installationsanleitung
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Lizenz
|
||||
|
||||
Privates Projekt – alle Rechte vorbehalten.
|
||||
Reference in New Issue
Block a user