coding
94e1af0e6f
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
280 lines
7.4 KiB
Markdown
280 lines
7.4 KiB
Markdown
# 🎨 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!** 🎨✨
|