Add comprehensive README.md with installation and usage guide
Features documented: - Quick start guide with Docker - Complete feature list with emojis - Step-by-step usage instructions - Command reference table - Environment variables configuration - Remove.bg API setup - Docker management commands - Troubleshooting section - System requirements - Security notes - CI/CD information - Project structure overview - Support information
This commit is contained in:
279
README.md
Normal file
279
README.md
Normal file
@@ -0,0 +1,279 @@
|
|||||||
|
# 🎨 Telegram Sticker Bot Manager
|
||||||
|
|
||||||
|
Ein Telegram Bot zum Verwalten und Organisieren von Sticker-Paketen. Erstellt mit Python und der python-telegram-bot Bibliothek.
|
||||||
|
|
||||||
|
## ✨ Features
|
||||||
|
|
||||||
|
- **🆕 Neue Stickerpakete erstellen** - Einfacher 4-Schritte-Assistent
|
||||||
|
- **📥 Existierende Pakete importieren** - Bereits vorhandene Pakete hinzufügen
|
||||||
|
- **➕ Sticker hinzufügen** - Unterstützt Bilder (PNG, JPG, WebP) und GIFs
|
||||||
|
- **🎨 Automatische Bildoptimierung** - Konvertiert zu 512px WebP mit Transparenz
|
||||||
|
- **🎬 GIF zu Video-Sticker** - Automatische Konvertierung zu WebM (VP9)
|
||||||
|
- **✨ Hintergrundentfernung** - Optional mit lokalen oder API-basierten Tools
|
||||||
|
- **🏷 Emoji verwalten** - Emojis von Stickern ändern
|
||||||
|
- **✏️ Pakete umbenennen** - Titel einfach ändern
|
||||||
|
- **🗑 Sticker/Pakete löschen** - Mit Bestätigungsdialog
|
||||||
|
- **💎 Premium-Status** - Erkennt Telegram Premium Nutzer
|
||||||
|
|
||||||
|
## 🚀 Schnellstart
|
||||||
|
|
||||||
|
### Voraussetzungen
|
||||||
|
|
||||||
|
- Docker und Docker Compose
|
||||||
|
- Einen Telegram Bot Token (von @BotFather)
|
||||||
|
- Deine Telegram User ID
|
||||||
|
|
||||||
|
### Installation
|
||||||
|
|
||||||
|
1. **Repository klonen:**
|
||||||
|
```bash
|
||||||
|
git clone http://192.168.88.201:3000/sarah/stickerbot.git
|
||||||
|
cd stickerbot
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Umgebungsvariablen konfigurieren:**
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **`.env` Datei bearbeiten:**
|
||||||
|
```bash
|
||||||
|
# Required
|
||||||
|
BOT_TOKEN=dein_bot_token_hier
|
||||||
|
OWNER_ID=deine_telegram_user_id
|
||||||
|
|
||||||
|
# Optional: Für Hintergrundentfernung über API (50 Aufrufe/Monat kostenlos)
|
||||||
|
REMOVE_BG_API_KEY=dein_remove_bg_api_key
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Docker Container starten:**
|
||||||
|
```bash
|
||||||
|
sudo docker-compose up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Überprüfen, ob der Bot läuft:**
|
||||||
|
```bash
|
||||||
|
sudo docker-compose logs -f
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📖 Verwendung
|
||||||
|
|
||||||
|
### Bot starten
|
||||||
|
|
||||||
|
Schreibe dem Bot in Telegram:
|
||||||
|
```
|
||||||
|
/start
|
||||||
|
```
|
||||||
|
|
||||||
|
Das Hauptmenü erscheint mit folgenden Optionen:
|
||||||
|
|
||||||
|
- **➕ Neues Stickerpaket** - Erstellt ein neues Paket
|
||||||
|
- **📥 Existierendes hinzufügen** - Fügt bereits existierende Pakete hinzu
|
||||||
|
- **📦 Meine Stickerpakete** - Zeigt alle deine Pakete an
|
||||||
|
- **❓ Hilfe** - Zeigt Hilfeinformationen
|
||||||
|
|
||||||
|
### Stickerpaket erstellen
|
||||||
|
|
||||||
|
1. Auf "➕ Neues Stickerpaket" klicken
|
||||||
|
2. Kurzen Namen eingeben (z.B. `meine_sticker`)
|
||||||
|
3. Titel eingeben (z.B. "Meine coolen Sticker")
|
||||||
|
4. Emoji eingeben (z.B. 😎)
|
||||||
|
5. Bild senden (PNG, JPG oder GIF)
|
||||||
|
6. Optional: Hintergrund entfernen auswählen
|
||||||
|
|
||||||
|
### Existierendes Paket hinzufügen
|
||||||
|
|
||||||
|
1. Auf "📥 Existierendes hinzufügen" klicken
|
||||||
|
2. Den Namen des Pakets eingeben (z.B. `meine_alten_sticker`)
|
||||||
|
3. Der Bot fügt es automatisch zu deiner Liste hinzu
|
||||||
|
|
||||||
|
### Sticker zu Paket hinzufügen
|
||||||
|
|
||||||
|
1. Auf "📦 Meine Stickerpakete" klicken
|
||||||
|
2. Das gewünschte Paket auswählen
|
||||||
|
3. Auf "➕ Sticker hinzufügen" klicken
|
||||||
|
4. Bild oder GIF senden
|
||||||
|
5. Emoji eingeben
|
||||||
|
|
||||||
|
**Bilder:** Werden automatisch zu 512px WebP konvertiert
|
||||||
|
**GIFs:** Werden zu animierten Video-Stickern (max. 3 Sekunden)
|
||||||
|
|
||||||
|
### Hintergrundentfernung
|
||||||
|
|
||||||
|
Wenn du ein Bild sendest, fragt der Bot:
|
||||||
|
|
||||||
|
- **🤖 Lokal entfernen** - Kostenlos, läuft auf dem Server (etwas langsamer)
|
||||||
|
- **☁️ Remove.bg API** - Schneller, 50 Aufrufe/Monat kostenlos (falls API-Key gesetzt)
|
||||||
|
- **⏭️ Ohne Entfernung** - Bild wird so verwendet
|
||||||
|
|
||||||
|
### Sticker löschen
|
||||||
|
|
||||||
|
1. Den Sticker an den Bot weiterleiten
|
||||||
|
2. Bot zeigt Optionen zum Löschen
|
||||||
|
|
||||||
|
### Paket löschen
|
||||||
|
|
||||||
|
1. "📦 Meine Stickerpakete" wählen
|
||||||
|
2. Paket auswählen
|
||||||
|
3. "🗑 Paket löschen" wählen
|
||||||
|
4. Bestätigen
|
||||||
|
|
||||||
|
⚠️ **Achtung:** Das Löschen kann nicht rückgängig gemacht werden!
|
||||||
|
|
||||||
|
## 🛠️ Befehle
|
||||||
|
|
||||||
|
| Befehl | Beschreibung |
|
||||||
|
|--------|--------------|
|
||||||
|
| `/start` | Bot starten und Hauptmenü anzeigen |
|
||||||
|
| `/hilfe` | Detaillierte Hilfe anzeigen |
|
||||||
|
| `/cancel` | Aktuelle Aktion abbrechen |
|
||||||
|
|
||||||
|
## ⚙️ Konfiguration
|
||||||
|
|
||||||
|
### Umgebungsvariablen
|
||||||
|
|
||||||
|
| Variable | Beschreibung | Optional |
|
||||||
|
|----------|--------------|----------|
|
||||||
|
| `BOT_TOKEN` | Telegram Bot Token von @BotFather | Nein |
|
||||||
|
| `OWNER_ID` | Deine Telegram User ID | Nein |
|
||||||
|
| `REMOVE_BG_API_KEY` | API Key für remove.bg | Ja |
|
||||||
|
| `DATABASE_PATH` | Pfad zur SQLite DB (Standard: `sticker_bot.db`) | Ja |
|
||||||
|
| `PREMIUM_CHECK_INTERVAL` | Interval für Premium-Check in Stunden (Standard: 24) | Ja |
|
||||||
|
|
||||||
|
### Remove.bg API Key (Optional)
|
||||||
|
|
||||||
|
Um die Hintergrundentfernung über API zu nutzen:
|
||||||
|
|
||||||
|
1. Bei [remove.bg](https://www.remove.bg/) registrieren
|
||||||
|
2. API Key generieren
|
||||||
|
3. In `.env` Datei eintragen: `REMOVE_BG_API_KEY=dein_key`
|
||||||
|
|
||||||
|
**Hinweis:** 50 Aufrufe pro Monat sind kostenlos.
|
||||||
|
|
||||||
|
## 🐳 Docker Verwaltung
|
||||||
|
|
||||||
|
### Container starten
|
||||||
|
```bash
|
||||||
|
sudo docker-compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
### Container stoppen
|
||||||
|
```bash
|
||||||
|
sudo docker-compose down
|
||||||
|
```
|
||||||
|
|
||||||
|
### Logs anzeigen
|
||||||
|
```bash
|
||||||
|
sudo docker-compose logs -f
|
||||||
|
```
|
||||||
|
|
||||||
|
### Neu bauen (nach Änderungen)
|
||||||
|
```bash
|
||||||
|
sudo docker-compose up -d --build --force-recreate
|
||||||
|
```
|
||||||
|
|
||||||
|
### Container-Status prüfen
|
||||||
|
```bash
|
||||||
|
sudo docker ps | grep stickerbot
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📁 Projektstruktur
|
||||||
|
|
||||||
|
```
|
||||||
|
stickerbot/
|
||||||
|
├── bot.py # Hauptbot mit allen Handlern
|
||||||
|
├── sticker_manager.py # Sticker-Verwaltungsfunktionen
|
||||||
|
├── image_processor.py # Bildverarbeitung (WebP, Resize)
|
||||||
|
├── gif_processor.py # GIF zu WebM Konvertierung
|
||||||
|
├── background_remover.py # Hintergrundentfernung
|
||||||
|
├── database.py # SQLite Datenbank
|
||||||
|
├── config.py # Konfigurationsmanagement
|
||||||
|
├── Dockerfile # Docker Konfiguration
|
||||||
|
├── docker-compose.yml # Docker Compose Setup
|
||||||
|
├── requirements.txt # Python Dependencies
|
||||||
|
├── .env.example # Beispiel-Umgebungsvariablen
|
||||||
|
└── data/ # Persistente Daten
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🔄 Automatische Builds (CI/CD)
|
||||||
|
|
||||||
|
Das Projekt enthält Gitea Actions Workflows für automatische Docker-Builds:
|
||||||
|
|
||||||
|
### Auto-Build (bei jedem Push)
|
||||||
|
- **Trigger:** Push auf `main` oder `master` Branch
|
||||||
|
- **Ergebnis:** Docker Image wird gebaut und in die Registry gepusht
|
||||||
|
- **Tags:** `latest` und `v{nummer}-autobuild`
|
||||||
|
|
||||||
|
### Manueller Build
|
||||||
|
- **Trigger:** Manuell über Gitea Web-Interface
|
||||||
|
- **Optionen:**
|
||||||
|
- Benutzerdefinierte Version (z.B. `1.0.0`)
|
||||||
|
- Zusätzliche Tags (z.B. `stable,production`)
|
||||||
|
- `latest` Tag optional
|
||||||
|
|
||||||
|
### Registry
|
||||||
|
Standardmäßig wird das Image zu `192.168.88.201:5000` gepusht.
|
||||||
|
|
||||||
|
## 🐛 Fehlerbehebung
|
||||||
|
|
||||||
|
### Bot reagiert nicht
|
||||||
|
```bash
|
||||||
|
# Prüfen ob Container läuft
|
||||||
|
sudo docker ps | grep stickerbot
|
||||||
|
|
||||||
|
# Logs anzeigen
|
||||||
|
sudo docker-compose logs -f
|
||||||
|
```
|
||||||
|
|
||||||
|
### Build fehlschlägt
|
||||||
|
```bash
|
||||||
|
# Mit force-recreate neu bauen
|
||||||
|
sudo docker-compose up -d --build --force-recreate
|
||||||
|
```
|
||||||
|
|
||||||
|
### Datenbank zurücksetzen
|
||||||
|
```bash
|
||||||
|
# ACHTUNG: Löscht alle Daten!
|
||||||
|
rm data/sticker_bot.db
|
||||||
|
sudo docker-compose restart
|
||||||
|
```
|
||||||
|
|
||||||
|
### Hintergrundentfernung langsam
|
||||||
|
Beim ersten Start lädt rembg das ML-Modell (~180MB). Dies dauert einmalig etwas länger.
|
||||||
|
|
||||||
|
## 📋 Systemanforderungen
|
||||||
|
|
||||||
|
- **RAM:** Mindestens 512MB (für rembg Modell empfohlen: 1GB+)
|
||||||
|
- **Speicherplatz:** ~500MB für Container + Datenbank
|
||||||
|
- **Netzwerk:** Internetverbindung für Telegram API
|
||||||
|
- **Betriebssystem:** Linux mit Docker Unterstützung
|
||||||
|
|
||||||
|
## 📝 Technische Details
|
||||||
|
|
||||||
|
- **Python:** 3.11
|
||||||
|
- **Basis-Image:** python:3.11-slim (Debian)
|
||||||
|
- **Bot API:** python-telegram-bot 22.7
|
||||||
|
- **Datenbank:** SQLite
|
||||||
|
- **Bildverarbeitung:** Pillow, rembg, FFmpeg
|
||||||
|
|
||||||
|
## 🔒 Sicherheit
|
||||||
|
|
||||||
|
- Der Bot ist nur für den `OWNER_ID` zugänglich
|
||||||
|
- Keine Gruppen-Unterstützung (nur private Chats)
|
||||||
|
- API-Keys werden in Umgebungsvariablen gespeichert
|
||||||
|
- Docker Container läuft als non-root User
|
||||||
|
|
||||||
|
## 📄 Lizenz
|
||||||
|
|
||||||
|
Dieses Projekt ist für private Nutzung bestimmt.
|
||||||
|
|
||||||
|
## 🤝 Support
|
||||||
|
|
||||||
|
Bei Fragen oder Problemen:
|
||||||
|
1. `/hilfe` in Telegram eingeben
|
||||||
|
2. Die `OPENCODE.md` konsultieren (technische Dokumentation)
|
||||||
|
3. Logs überprüfen: `sudo docker-compose logs -f`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Viel Spaß mit deinem Sticker Bot!** 🎨✨
|
||||||
Reference in New Issue
Block a user