Add README and CONFIG in RU and EN

2026-02-08 01:08:17 +03:00
parent d0c40b9e50
commit ab2bc5de33
4 changed files with 322 additions and 0 deletions
--- a/CONFIG.en.md
+++ b/CONFIG.en.md
@@ -0,0 +1,96 @@
+# Configuration
+
+This project uses `config.yaml`. Start from `config.example.yaml`.
+
+## telegram
+
+- `token` (string, required): Telegram bot token.
+- `admin_id` (int, required): Telegram user id with admin access.
+
+## paths
+
+- `artifact_state` (string): JSON file for artifact state.
+- `restic_env` (string): Path to a file with RESTIC_* environment variables.
+
+## thresholds
+
+- `disk_warn` (int, percent): Disk usage warning threshold.
+- `load_warn` (float): System load warning threshold.
+
+## alerts
+
+- `enabled` (bool): Enable resource alerts.
+- `interval_sec` (int): Poll interval.
+- `cooldown_sec` (int): Cooldown between alerts.
+- `notify_recovery` (bool): Send recovery notifications.
+- `smart_enabled` (bool): Enable SMART health polling.
+- `smart_interval_sec` (int): SMART poll interval.
+- `smart_cooldown_sec` (int): SMART alert cooldown.
+- `smart_temp_warn` (int): SMART temperature warning (C).
+
+## audit
+
+- `enabled` (bool): Enable audit logging.
+- `path` (string): Log file path. Default `/var/server-bot/audit.log`.
+- `rotate_when` (string): Rotation schedule for `TimedRotatingFileHandler`. Example `W0` for weekly on Monday.
+- `backup_count` (int): How many rotated files to keep.
+
+## arcane
+
+- `base_url` (string): Arcane API base url.
+- `api_key` (string): Arcane API key.
+- `env_id` (int): Arcane environment id.
+
+## npmplus
+
+Used for SSL certificate status.
+
+- `base_url` (string): NPMplus API base url, for example `https://10.10.10.10:81/api`.
+- `identity` (string): Login email.
+- `secret` (string): Login password.
+- `token` (string): Optional static token (not recommended if it expires).
+- `verify_tls` (bool): Set to `false` for self-signed TLS.
+
+Token flow:
+
+- First token: `POST /api/tokens` with `identity` and `secret`.
+- Refresh: `GET /api/tokens` using the cached token.
+
+## security
+
+- `reboot_password` (string): Password required before reboot.
+
+## docker
+
+- `autodiscovery` (bool): Discover containers by name/label.
+- `watchdog` (bool): Enable container watchdog notifications.
+- `label` (string): Optional label filter `key=value`.
+- `match` (list): Name substrings used for discovery.
+- `aliases` (map): Alias -> real container name.
+- `containers` (map): Explicit container list (legacy modules). Each item can define:
+  - `name` (string): Container name.
+  - `url` (string): Health URL for the URLs check.
+
+Example:
+
+```yaml
+telegram:
+  token: "YOUR_TELEGRAM_BOT_TOKEN"
+  admin_id: 123456789
+
+paths:
+  artifact_state: "/opt/tg-bot/state.json"
+  restic_env: "/etc/restic/restic.env"
+
+audit:
+  enabled: true
+  path: "/var/server-bot/audit.log"
+  rotate_when: "W0"
+  backup_count: 8
+
+npmplus:
+  base_url: "https://10.10.10.10:81/api"
+  identity: "your@email.com"
+  secret: "yourPassword"
+  verify_tls: false
+```
--- a/CONFIG.md
+++ b/CONFIG.md
@@ -0,0 +1,96 @@
+# Конфигурация
+
+Проект использует `config.yaml`. Начни с `config.example.yaml`.
+
+## telegram
+
+- `token` (string, обяз.): токен бота.
+- `admin_id` (int, обяз.): Telegram user id администратора.
+
+## paths
+
+- `artifact_state` (string): JSON файл состояния артефактов.
+- `restic_env` (string): путь к файлу с RESTIC_* переменными.
+
+## thresholds
+
+- `disk_warn` (int, %): порог предупреждения по диску.
+- `load_warn` (float): порог предупреждения по нагрузке.
+
+## alerts
+
+- `enabled` (bool): включить алерты.
+- `interval_sec` (int): интервал опроса.
+- `cooldown_sec` (int): кулдаун между алертами.
+- `notify_recovery` (bool): уведомлять о восстановлении.
+- `smart_enabled` (bool): SMART проверки.
+- `smart_interval_sec` (int): интервал SMART.
+- `smart_cooldown_sec` (int): кулдаун SMART.
+- `smart_temp_warn` (int): порог температуры (C).
+
+## audit
+
+- `enabled` (bool): включить аудит.
+- `path` (string): путь к лог-файлу. По умолчанию `/var/server-bot/audit.log`.
+- `rotate_when` (string): режим ротации (`TimedRotatingFileHandler`), например `W0`.
+- `backup_count` (int): сколько файлов хранить.
+
+## arcane
+
+- `base_url` (string): base url API Arcane.
+- `api_key` (string): ключ API Arcane.
+- `env_id` (int): ID окружения Arcane.
+
+## npmplus
+
+Используется для статуса SSL сертификатов.
+
+- `base_url` (string): base url API, например `https://10.10.10.10:81/api`.
+- `identity` (string): email логин.
+- `secret` (string): пароль.
+- `token` (string): опционально статический токен (не рекомендуется при истечении).
+- `verify_tls` (bool): `false` для self-signed TLS.
+
+Логика токена:
+
+- первый токен: `POST /api/tokens` с `identity` и `secret`.
+- refresh: `GET /api/tokens` с текущим токеном.
+
+## security
+
+- `reboot_password` (string): пароль для подтверждения reboot.
+
+## docker
+
+- `autodiscovery` (bool): автодискавери по имени/label.
+- `watchdog` (bool): уведомления о контейнерах.
+- `label` (string): фильтр label `key=value`.
+- `match` (list): подстроки для поиска контейнеров.
+- `aliases` (map): alias -> реальное имя.
+- `containers` (map): явный список (legacy). Можно задавать:
+  - `name` (string)
+  - `url` (string) для URLs проверки
+
+Пример:
+
+```yaml
+telegram:
+  token: "YOUR_TELEGRAM_BOT_TOKEN"
+  admin_id: 123456789
+
+paths:
+  artifact_state: "/opt/tg-bot/state.json"
+  restic_env: "/etc/restic/restic.env"
+
+audit:
+  enabled: true
+  path: "/var/server-bot/audit.log"
+  rotate_when: "W0"
+  backup_count: 8
+
+npmplus:
+  base_url: "https://10.10.10.10:81/api"
+  identity: "your@email.com"
+  secret: "yourPassword"
+  verify_tls: false
+```
--- a/README.en.md
+++ b/README.en.md
@@ -0,0 +1,65 @@
+# tg-admin-bot
+
+Telegram admin bot for Linux servers. Provides quick status checks, backup controls, and ops actions from a chat.
+
+## Features
+
+- Docker: status, restart, logs (tail, since, filter).
+- Arcane: list projects, refresh, up/down, restart.
+- Backups (restic): snapshots, repo stats, run backup, queue, restic check, weekly report.
+- System: disks, security, URLs health, metrics, package updates, upgrade, reboot, hardware info, SSL cert status (NPMplus).
+- Alerts: disk/load and SMART monitoring with cooldown.
+- Audit log: all button presses and messages (weekly rotation).
+
+## Requirements
+
+- Linux host.
+- Python 3.11+ (tested with 3.13).
+- System tools as needed:
+  - docker
+  - restic
+  - smartctl (smartmontools)
+  - sudo access for reboot/upgrade/backup scripts
+  - systemd (for timers/status, optional but recommended)
+
+## Install
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r req.txt
+```
+
+## Configure
+
+1. Copy the example config:
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+2. Edit `config.yaml` and set at least:
+
+- `telegram.token`
+- `telegram.admin_id`
+
+3. Optional:
+
+- Restic env file path (`paths.restic_env`).
+- Docker autodiscovery or explicit `docker.containers`.
+- Arcane and NPMplus API settings.
+- Audit log path and rotation.
+
+See `CONFIG.en.md` for full details.
+
+## Run
+
+```bash
+python bot.py
+```
+
+## Notes
+
+- For NPMplus with self-signed TLS, set `npmplus.verify_tls: false`.
+- The bot uses `sudo` for certain actions (reboot, upgrade, backup scripts). Ensure the service user has the required permissions.
+- Audit log default path is `/var/server-bot/audit.log`.
--- a/README.md
+++ b/README.md
@@ -0,0 +1,65 @@
+# tg-admin-bot
+
+Telegram-бот администратора для Linux-серверов. Даёт быстрый доступ к статусам, бэкапам и операциям через чат.
+
+## Возможности
+
+- Docker: статус, рестарт, логи (tail, since, фильтр).
+- Arcane: список проектов, refresh, up/down, restart.
+- Бэкапы (restic): снапшоты, статистика репозитория, запуск бэкапа, очередь, restic check, weekly report.
+- Система: диски, безопасность, проверка URL, метрики, обновления, upgrade, reboot, железо, SSL (NPMplus).
+- Алерты: диск/нагрузка и SMART с cooldown.
+- Аудит: все нажатия и сообщения (ротация раз в неделю).
+
+## Требования
+
+- Linux-хост.
+- Python 3.11+ (проверено на 3.13).
+- Системные утилиты по необходимости:
+  - docker
+  - restic
+  - smartctl (smartmontools)
+  - sudo для reboot/upgrade/backup скриптов
+  - systemd (для таймеров/статуса, желательно)
+
+## Установка
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r req.txt
+```
+
+## Настройка
+
+1. Скопировать пример:
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+2. Заполнить минимум:
+
+- `telegram.token`
+- `telegram.admin_id`
+
+3. Опционально:
+
+- путь к restic env (`paths.restic_env`)
+- docker autodiscovery или явный список `docker.containers`
+- Arcane и NPMplus API
+- аудит логов
+
+Подробности в `CONFIG.md`.
+
+## Запуск
+
+```bash
+python bot.py
+```
+
+## Примечания
+
+- Для NPMplus с self-signed TLS установи `npmplus.verify_tls: false`.
+- Бот использует `sudo` для части операций — настрой права.
+- Аудит по умолчанию пишется в `/var/server-bot/audit.log`.