126 lines
3.8 KiB
Markdown
126 lines
3.8 KiB
Markdown
# GigalativBot (Telegram Counter Bot)
|
||
|
||
Ein schlanker Telegram-Bot zum Verwalten einfacher Integer-Counter. Läuft per Long Polling in einem Docker-Container.
|
||
|
||
## Features
|
||
- /add <name> – legt Counter (0) an
|
||
- /remove <name> – löscht Counter
|
||
- /increment <name> – erhöht Counter um 1 (Antwort mit neuem Wert)
|
||
- /decrement <name> – verringert Counter um 1 (Antwort mit neuem Wert)
|
||
- /list – zeigt alle Counter
|
||
- /help – Übersicht
|
||
- Counter-Namen case-insensitive (intern lowercase gespeichert)
|
||
- Persistenz als JSON unter `/data/counters.json` (Docker Volume)
|
||
- Zugriffsbeschränkung via allowed_chat_ids in `config.yaml`
|
||
- Startup-Benachrichtigung an definierte Chats via ENV `STARTUP_ANNOUNCE_CHAT_IDS`
|
||
- Begrüßung neuer Mitglieder (optional) via ENV `ANNOUNCE_ALL_JOINS=true`
|
||
- Automatische Willkommens-Nachricht, wenn der Bot einer Gruppe hinzugefügt wird
|
||
|
||
## Struktur
|
||
```
|
||
.
|
||
├─ bot.py
|
||
├─ requirements.txt
|
||
├─ Dockerfile
|
||
├─ docker-compose.yaml
|
||
├─ config.example.yaml (umbenennen zu config.yaml und anpassen)
|
||
└─ README.md
|
||
```
|
||
|
||
## Konfiguration
|
||
Passe `config.example.yaml` an und benenne sie zu `config.yaml`.
|
||
|
||
Beispiel:
|
||
```yaml
|
||
bot_token: "123456:ABCDEF..." # oder via ENV BOT_TOKEN
|
||
allowed_chat_ids: [123456789, -1001122334455]
|
||
initial_counters:
|
||
beispiel: 5
|
||
log_level: INFO
|
||
```
|
||
Wenn `allowed_chat_ids` leer oder fehlt, sind alle Chats erlaubt.
|
||
|
||
### Wichtige Environment Variablen
|
||
| Variable | Beschreibung | Beispiel |
|
||
|----------|--------------|----------|
|
||
| BOT_TOKEN | Telegram Bot Token (sensitiv, nicht committen) | 123456:ABCDEF |
|
||
| STARTUP_ANNOUNCE_CHAT_IDS | Kommagetrennte Liste von Chat IDs für Start-Meldung | -4549916385,-1001122334455 |
|
||
| ANNOUNCE_ALL_JOINS | `true` um alle neuen Mitglieder zu begrüßen | true |
|
||
| CONFIG_FILE | Pfad zur Config Datei | /app/config.yaml |
|
||
| DATA_DIR | Verzeichnis für Persistenz | /data |
|
||
|
||
## Start (Docker Compose)
|
||
Setze dein Bot Token als Environment Variable oder trage es in der config.yaml ein.
|
||
|
||
### Variante 1: Token via .env
|
||
Datei `.env` anlegen:
|
||
```
|
||
BOT_TOKEN=123456:ABCDEF...
|
||
```
|
||
Dann:
|
||
```
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### Variante 2: Token in config.yaml
|
||
Trage `bot_token:` dort ein und entferne den `BOT_TOKEN` Eintrag aus `docker-compose.yaml` oder lass die ENV leer.
|
||
|
||
### Startup Ankündigung aktivieren
|
||
Füge in `.env` hinzu (optional):
|
||
```
|
||
STARTUP_ANNOUNCE_CHAT_IDS=-4549916385
|
||
ANNOUNCE_ALL_JOINS=true
|
||
```
|
||
|
||
## Persistenz / Volume
|
||
Alle Counter werden nach jeder Änderung in `/data/counters.json` gespeichert. Das Volume `counterbot_data` stellt dauerhafte Speicherung sicher.
|
||
|
||
## Sicherheit
|
||
- Non-root User `appuser`
|
||
- Kein Port-Expose (Long Polling)
|
||
|
||
## Docker Image veröffentlichen
|
||
Zum Bauen und Pushen des Images mit `latest`-Tag und einem datierten Tag (z. B. `2025-09-30`) steht das Skript `publish.py` bereit. Stelle vorher sicher, dass du in der Registry `git.beging.de` angemeldet bist.
|
||
|
||
```bash
|
||
python publish.py --date 2025-09-30
|
||
```
|
||
|
||
Ohne `--date` wird automatisch das heutige UTC-Datum verwendet. Mit `--dry-run` kannst du die Docker-Kommandos nur anzeigen lassen:
|
||
|
||
```bash
|
||
python publish.py --dry-run
|
||
```
|
||
|
||
Falls du den `latest` Tag nicht veröffentlichen möchtest, verwende `--no-latest`.
|
||
|
||
## Logging
|
||
Standard: INFO. Anpassbar über `log_level` in der Config.
|
||
|
||
Antwort-Ausgabe nutzt jetzt HTML-Formatierung (statt MarkdownV2) um Parse-Fehler bei Sonderzeichen zu vermeiden.
|
||
|
||
## Beispiel-Interaktion
|
||
```
|
||
/add test
|
||
Counter test wurde angelegt (Wert 0).
|
||
/increment test
|
||
Counter test steht jetzt auf 1.
|
||
/list
|
||
Aktuelle Counter:
|
||
- test: 1
|
||
/remove test
|
||
Counter test wurde gelöscht.
|
||
```
|
||
|
||
## Erweiterungsideen
|
||
- /set <name> <value>
|
||
- /rename <old> <new>
|
||
- Export als CSV/JSON über /export
|
||
- Webhook-Modus + Traefik Labels
|
||
- Rate Limiting pro User
|
||
|
||
## Lizenz
|
||
Keine explizite Lizenz enthalten (privat). Ergänze bei Bedarf.
|
||
|
||
Viel Spaß!
|