230 lines
5.7 KiB
Markdown
230 lines
5.7 KiB
Markdown
<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.
|