feat: add one-click installers and Windows launcher

2026-07-22 21:50:12 +03:00 · 2026-05-24 23:07:03 +03:00
parent 186139f796
commit a70439194e
18 changed files with 870 additions and 720 deletions
@@ -2,186 +2,195 @@

 Русский | [English](README_EN.md)

-Личный Telegram-бот для данных Xiaomi Fitness / Mi Band.
+Личный self-hosted Telegram-бот для данных Xiaomi Fitness / Mi Band.

-Он сам забирает шаги, сон, пульс и SpO2 из Xiaomi Fitness, складывает их в локальную SQLite-базу и показывает понятное меню в Telegram. Идея простая: данные с браслета остаются у вас на сервере, а Telegram становится удобной кнопкой «посмотреть здоровье за сегодня», «обновить вручную» или «выгрузить CSV».
+Забирает шаги, сон, пульс и SpO2 из облака Xiaomi Fitness, хранит их
+в локальной SQLite-базе и даёт доступ к ним прямо из Telegram —
+без сторонних сервисов и без передачи данных третьим лицам.

-Проект рассчитан на одного владельца. Это не публичный бот для многих пользователей и не медицинский сервис.
+> **Проект рассчитан на одного владельца.**
+> Это не публичный бот и не медицинский сервис.

-## Что умеет
+## Возможности

- Показывает последние шаги, сон, пульс и SpO2 в Telegram.
- Запускает ручную синхронизацию кнопкой в меню.
- Автоматически синхронизирует данные по расписанию.
- Хранит историю в SQLite в папке `data/`.
- Экспортирует накопленные таблицы в ZIP с CSV-файлами.
- Работает через Docker Compose.
- Пишет Xiaomi token атомарно с правами `0600`.
-
-## Кому подходит
-
-Проект подойдет, если вы:
-
- пользуетесь Xiaomi Fitness / Mi Band;
- хотите видеть свои данные в Telegram;
- готовы запустить маленький self-hosted сервис;
- понимаете, что неофициальные API могут сломаться после изменений Xiaomi.
-
-Проект не подойдет, если нужен многопользовательский SaaS, медицинская точность, гарантия совместимости со всеми браслетами или официальный Xiaomi API.
-
-## Важно про reverse engineering
-
-`miband-bot` - неофициальный проект. Он не связан с Xiaomi, Zepp, Huami, Telegram или их партнерами.
-
-Доступ к данным Xiaomi Fitness сделан через reverse engineering неофициальных API. Это значит:
-
- Xiaomi может изменить API без предупреждения;
- вход или синхронизация могут временно перестать работать;
- используйте проект только для своих аккаунтов и своих данных;
- соблюдайте применимые законы и условия сервисов в вашей стране;
- данные браслета не являются медицинским заключением.
+- Просмотр последних шагов, сна, пульса и SpO2 в Telegram.
+- Ручная и автоматическая синхронизация по расписанию.
+- Хранение истории в SQLite (`data/`).
+- Экспорт всех таблиц в ZIP с CSV-файлами прямо в чат.
+- Развёртывание через Docker Compose.
+- Атомарная запись Xiaomi-токена с правами `0600`.
+- Умная автопривязка к первому пользователю (whitelist).

 ## Как это работает

 ```text
-Mi Band -> Xiaomi Fitness cloud -> miband-bot -> SQLite -> Telegram menu / CSV export
+Mi Band → Xiaomi Fitness cloud → miband-bot → SQLite → Telegram / CSV
 ```

-В Docker Compose запускаются два процесса:
+Docker Compose запускает два процесса:

- `tracker` - периодически синхронизирует данные из Xiaomi Fitness;
- `fitness-bot` - отвечает в Telegram, показывает меню, запускает ручной sync и экспорт.
+- `tracker` — периодически синхронизирует данные из Xiaomi Fitness;
+- `fitness-bot` — обслуживает Telegram-меню, ручной sync и экспорт.

-Оба процесса используют одну папку `./data`. Запись защищена файловым lock, поэтому фоновая и ручная синхронизация не пишут в SQLite/token одновременно.
+Оба процесса работают с одной папкой `./data`. Конкурентная запись
+исключена файловым lock-ом.

-## Что понадобится
+## Требования

- Сервер или домашняя машина с Docker и Docker Compose.
+- Docker и Docker Compose (или установленный Python 3.10+).
 - Telegram bot token от [@BotFather](https://t.me/BotFather).
- Ваш Telegram user id.
- Xiaomi аккаунт, в котором видны данные Xiaomi Fitness.
+- Аккаунт Xiaomi с данными Xiaomi Fitness.

 ## Быстрый запуск

-1. Скопируйте пример секретов:
+### Способ 1: Бесшовная установка в один клик (Рекомендуется)

-```sh
-cp secrets.env.example secrets.env
-```
+Если у вас еще нет проекта на компьютере, вы можете автоматически скачать и настроить его одной командой в терминале:

-2. Заполните минимум эти переменные:
+- **macOS / Linux:**
+  ```sh
+  curl -fsSL https://raw.githubusercontent.com/iAlexeyRu/miband-bot/main/install.sh | bash
+  ```
+- **Windows (PowerShell):**
+  ```powershell
+  powershell -c "irm https://raw.githubusercontent.com/iAlexeyRu/miband-bot/main/install.ps1 | iex"
+  ```

-```env
-TELEGRAM_BOT_TOKEN=123456:replace-me
-TELEGRAM_ALLOWED_USER_ID=123456789
-```
+Установщик сам создаст папку `miband-bot`, загрузит и распакует файлы проекта, проверит окружение и запустит интерактивную настройку!
+Повторный запуск этой же PowerShell-команды в уже настроенной установке обновит файлы и сразу запустит бота без повторного ввода токена.

-3. Запустите сервис:
+---

-```sh
-docker compose up -d --build
-docker compose logs -f fitness-bot
-```
+### Способ 2: Запуск из скачанной папки

-4. Откройте своего Telegram-бота и отправьте `/start`.
+Если вы уже склонировали репозиторий через `git clone` или скачали архив вручную:

-5. Бот покажет кнопку входа в Xiaomi. Подтвердите вход по ссылке/QR. После этого бот сохранит `data/token_<telegram_user_id>.json`, запустит первую синхронизацию и откроет главное меню.
+- **macOS / Linux:**
+  ```sh
+  ./setup.sh
+  ```
+- **Windows:**
+  Запустите двойным кликом файл `setup.bat` или выполните в консоли:
+  ```cmd
+  setup.bat
+  ```
+
+Скрипт сам проверит окружение, пошагово поможет получить токен, создаст конфигурацию `secrets.env`, развернет окружение Python (если выбран запуск без Docker) и предложит запустить бота одной кнопкой.
+После настройки бот можно запускать повторно через `run_local.bat` из папки `miband-bot`.
+
+---
+
+### Способ 3: Полностью ручная настройка (manual setup):
+
+1. Скопируйте шаблон конфигурации:
+   ```sh
+   cp secrets.env.example secrets.env
+   ```
+2. Укажите ваш `TELEGRAM_BOT_TOKEN` в файле `secrets.env`. Переменную `TELEGRAM_ALLOWED_USER_ID` **оставьте пустой** — бот автоматически привяжется к вам при первом старте.
+3. Запустите Docker контейнеры:
+   ```sh
+   docker compose up -d --build
+   ```
+4. Откройте вашего созданного бота в Telegram и отправьте ему команду `/start` — бот распознает ваш аккаунт, привяжет его как единственного владельца и начнет синхронизацию!

 ## Настройки

-Основные переменные лежат в `secrets.env`:
+Все переменные — в `secrets.env`:

-```env
-TELEGRAM_BOT_TOKEN=123456:replace-me
-TELEGRAM_ALLOWED_USER_ID=123456789
-SYNC_INTERVAL=900
-QUERY_DURATION=2
-ENABLE_FDS_SLEEP_DETAILS=true
-```
+| Переменная                 | По умолчанию | Описание                                |
+| -------------------------- | ------------ | --------------------------------------- |
+| `TELEGRAM_BOT_TOKEN`       | —            | Token Telegram-бота                     |
+| `TELEGRAM_ALLOWED_USER_ID` | —            | Разрешённый user id (оставьте пустым для автопривязки) |
+| `SYNC_INTERVAL`            | `900`        | Интервал фоновой синхронизации, секунды |
+| `QUERY_DURATION`           | `2`          | Глубина запроса при sync, дней          |
+| `ENABLE_FDS_SLEEP_DETAILS` | `true`       | Загружать детальные ночные данные FDS   |

- `TELEGRAM_BOT_TOKEN` - token вашего Telegram-бота.
- `TELEGRAM_ALLOWED_USER_ID` - единственный Telegram user id, которому разрешен доступ.
- `SYNC_INTERVAL` - интервал фоновой синхронизации в секундах. `900` = 15 минут.
- `QUERY_DURATION` - сколько последних дней запрашивать при sync.
- `ENABLE_FDS_SLEEP_DETAILS` - пробовать ли загружать детальные ночные данные FDS.
+Пути к базе и статусу заданы в `compose.yaml`. При запуске без Docker
+смотрите `secrets.env.example`.

-Пути к базе и статусу уже заданы в `compose.yaml`. Если запускаете без Docker, смотрите `secrets.env.example`.
-
-## Где лежат данные
+## Файлы данных

 Runtime-файлы создаются в `./data`:

- `token_<telegram_user_id>.json` - Xiaomi auth token, секретный файл;
- `miband_<telegram_user_id>.db` - SQLite-база с health-данными;
- `status_<telegram_user_id>.json` - последний статус синхронизации;
- `fitness_bot_state.db` - служебное состояние Telegram-меню;
- `sync_<telegram_user_id>.lock` - lock-файл синхронизации.
+| Файл                   | Содержимое                        |
+| ---------------------- | --------------------------------- |
+| `token_<id>.json`      | Xiaomi auth token (**секретный**) |
+| `miband_<id>.db`       | SQLite-база с health-данными      |
+| `status_<id>.json`     | Последний статус синхронизации    |
+| `allowed_user.id`      | ID привязанного владельца         |
+| `fitness_bot_state.db` | Служебное состояние Telegram-меню |
+| `sync_<id>.lock`       | Lock-файл синхронизации           |

-Не коммитьте `secrets.env`, `data/`, `*.db`, `token*.json` и `status*.json`. Эти файлы уже добавлены в `.gitignore`.
+`secrets.env`, `data/`, `*.db`, `token*.json` и `status*.json`
+добавлены в `.gitignore` — не коммитьте их.

-## Команды бота
+## Команды

- `/start` - открыть меню или начать вход в Xiaomi.
- `/sync` - запустить ручную синхронизацию.
- `/status` - показать состояние локальной базы.
-
-Основное управление происходит кнопками в Telegram-меню.
-
-## Экспорт CSV
-
-В меню есть экспорт данных. Бот собирает ZIP с CSV-таблицами и отправляет его в Telegram.
-
-Помните: ZIP с health-данными уходит через инфраструктуру Telegram. Не отправляйте экспорт в чужие чаты и не храните его там, где доступ есть у других людей.
+| Команда   | Действие                              |
+| --------- | ------------------------------------- |
+| `/start`  | Открыть меню или начать вход в Xiaomi |
+| `/sync`   | Запустить ручную синхронизацию        |
+| `/status` | Показать состояние локальной базы     |

 ## Локальная разработка

 ```sh
 python3 -m venv .venv
 .venv/bin/pip install -r requirements-dev.txt -e mi-fitness-python
-.venv/bin/python -m py_compile fitness_bot.py miband_sync.py $(find miband_tracker -name '*.py' | sort)
+.venv/bin/python -m py_compile fitness_bot.py miband_sync.py \
+    $(find miband_tracker -name '*.py' | sort)
 .venv/bin/python -m pytest
 .venv/bin/python -m pytest mi-fitness-python/tests/unit
 .venv/bin/ruff check .
 .venv/bin/python -m pip check
 ```

-Entrypoints сохранены для Docker и локального запуска:
+Точки входа:

 ```sh
-python -u miband_sync.py
-python -u fitness_bot.py
-```
-
-Если проект установлен как Python package, доступны console scripts:
-
-```sh
-miband-sync
-miband-fitness-bot
+python -u miband_sync.py      # или: miband-sync
+python -u fitness_bot.py      # или: miband-fitness-bot
 ```

 ## Troubleshooting

-**Бот не отвечает.**
-Проверьте `TELEGRAM_BOT_TOKEN`, `TELEGRAM_ALLOWED_USER_ID` и логи:
+**Бот не отвечает** — проверьте `TELEGRAM_BOT_TOKEN`, логи, а также убедитесь, что вы первыми отправили `/start` боту для привязки. При необходимости сбросить привязанного владельца просто удалите файл `data/allowed_user.id` и отправьте `/start` снова.

 ```sh
 docker compose logs -f fitness-bot
 ```

-**Синхронизация пишет, что token не найден.**
-Откройте бота в Telegram, отправьте `/start` и пройдите Xiaomi login flow.
+**Token не найден** — отправьте `/start` и пройдите Xiaomi login flow.

-**Token истек.**
-В меню запустите повторный вход в Xiaomi. Старый token можно удалить из `data/`.
+**Token истёк** — запустите повторный вход из меню; старый файл
+можно удалить из `data/`.

-**Данных мало или нет SpO2/деталей сна.**
-Проверьте, что Xiaomi Fitness реально показывает эти данные. Часть данных зависит от модели браслета, настроек шаринга и доступности неофициального API.
+**Нет SpO2 или деталей сна** — убедитесь, что эти данные отображаются
+в самом приложении Xiaomi Fitness. Доступность зависит от модели
+браслета и настроек шаринга.

-**После обновления Xiaomi все сломалось.**
-Это ожидаемый риск reverse-engineering проекта. Проверьте issues/README и логи, затем обновите код или временно отключите проблемную часть.
+**После обновления Xiaomi всё сломалось** — это ожидаемый риск
+при работе с неофициальным API. Проверьте issues и логи, затем
+обновите код или временно отключите проблемный модуль.

-## Лицензия и vendored SDK
+## Важно: reverse engineering и ограничения

-Проект распространяется под GNU GPL v3.0 or later. Полный текст лицензии лежит в [LICENSE](LICENSE).
+`miband-bot` — неофициальный проект, не связанный с Xiaomi, Zepp,
+Huami или Telegram.

-SDK `mi-fitness-python` хранится в репозитории как vendored source copy и остается под своей GNU GPL v3.0 лицензией: [mi-fitness-python/LICENSE](mi-fitness-python/LICENSE). Подробности о происхождении и политике обновления описаны в [VENDORED.md](VENDORED.md).
+Доступ к данным реализован через reverse engineering закрытых API,
+поэтому:
+
+- Xiaomi может изменить API без предупреждения;
+- авторизация или синхронизация могут временно не работать;
+- используйте проект только со своими аккаунтами и данными;
+- соблюдайте законодательство и условия использования сервисов;
+- данные браслета не являются медицинским заключением.
+
+## Лицензия
+
+Проект распространяется под [GNU GPL v3.0 or later](LICENSE).
+
+SDK `mi-fitness-python` включён как vendored source copy под
+[GNU GPL v3.0](mi-fitness-python/LICENSE). Подробности — в
+[VENDORED.md](VENDORED.md).