viewit/MCM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4c5f6a16a72d116001f83e444b3e690a311f57a7
MCM/README.md

5.7 KiB
Raw Blame History

MCM Logo

MCM – MultiCustomerMessenger

Unified Messaging Gateway für Telegram, WhatsApp und SMS auf dem Raspberry Pi

Ü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

# 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)

# 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:

openssl rand -hex 32

Starten

Mit Terminal-UI (lokal)

.venv/bin/python main.py

Nur API (kein Terminal)

.venv/bin/python main.py --no-tui
# oder
.venv/bin/python main_api_only.py

TUI im Browser

# 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

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

# 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

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.