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:
2026-03-25 09:39:38 +00:00
parent 67c85ff8a0
commit 94e1af0e6f

279
README.md Normal file
View 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!** 🎨✨