diff --git a/README.md b/README.md index 90e176d..9fe1d23 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,20 @@ -# Бот техподдерки пользователя +# Бот техподдержки пользователя + + Пользователи пишут свои вопросы боту компании, бот пересылает эти сообщения в чат поддержки, сотрудники поддержки отвечают на эти сообщения через reply. Основной плюс - анонимизация сотрудников поддержки. -Бот работает в режиме webhook, но может работать и в режиме polling +Бот работает в режиме webhook, но может работать и в режиме polling. -Для обхода запрета на пересылку сообщения у пользователя, бот копирует содержимое и уже затем отправляет его в чат поддержки. +Для обхода запрета на пересылку сообщений у пользователя, бот копирует содержимое и уже затем отправляет его в чат поддержки. -По умолчанию бот отправляет сообщения в один чат поддержки с id, указанным в переменных окружения .env +По умолчанию бот отправляет сообщения в один чат поддержки с id, указанным в переменных окружения .env. ## Бот умеет - Пересылать сообщения, документы, аудио и видео от пользователя в группу к администраторам и обратно -- Выдавать информацию о пользователе из телеграма -- Выдавать месячный отчет и за указанный интервал даты по количеству обращений и общему числу сообщений и ответов +- Выдавать информацию о пользователе из Telegram +- Выдавать месячный отчет и отчет за указанный интервал дат по количеству обращений и общему числу сообщений и ответов - Банить и разбанивать пользователей ## Типы контента, которые может пересылать бот @@ -28,18 +30,23 @@ ### Настройка Nignx -Предполагается, что есть готовый настроенный vps сервер с установленным nginx. +Предполагается, что у вас есть готовый настроенный VPS сервер с установленным nginx. -1.Перейти в каталог nginx sites-available -``` +1. Перейти в каталог nginx `sites-available`: + +``` sh cd /etc/nginx/sites-available/ ``` -2.Создать файл с именем вашего домена -``` + +2. Создайте файл с именем вашего домена: + +``` sh nano domain.example.com ``` -3.Внутри написать -``` + +3. Внутри файла напишите: + +``` sh server { listen 80; @@ -54,34 +61,45 @@ server { } } ``` -server_name - ваш домен с подключенным ssl сертификатом (например, Let's Encrypt) -Вместо /telegram/ можно написать любой путь, на который должны приниматься данные. Этот же путь нужно указать в .env файле. 4. Создать ярлык в каталоге sites-enabled +`server_name` - ваш домен с подключенным SSL сертификатом (например, Let's Encrypt). Вместо `/telegram/` можно написать любой путь, на который должны приниматься данные. Этот же путь нужно указать в `.env` файле. +4. Создайте символическую ссылку в каталоге `sites-enabled` + +```sh +sudo ln -s /etc/nginx/sites-available/domain.example.com /etc/nginx/sites-enabled/ ``` -sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/ -``` -5.Проверить что нет ошибок в конфигурации nginx -``` +5. Проверьте конфигурацию nginx на ошибки: +```sh sudo nginx -t ``` -6. Перезапустить службу nginx + +6. Перезапустить службу nginx: ```sh sudo systemctl restart nginx ``` -7. Установить certbot - ```sudo apt install -y certbot python3-certbot-nginx``` -8. Установить https соединение, выпустив ssl сертификат с помощью certbot для вашего домена + +7. Установить certbot: +``` sh +sudo apt install -y certbot python3-certbot-nginx +``` + +8. Установите HTTPS соединение, выпустив SSL сертификат с помощью certbot для вашего домена: ```sh sudo certbot --nginx ``` -9 Добавить автоматическое обновление сертификата ```sudo certbot renew --dry-run ``` +9. Добавить автоматическое обновление сертификата: +```sh +sudo certbot renew --dry-run +``` -Можно на всякий случай еще раз перезапустить nginx +Можно на всякий случай еще раз перезапустить nginx. ### Запуск бота -1. Создать бота через botfather (см. ниже), добавить бота в группу с сотрудниками поддержки, дать боту права администратора, узнать id группы (см. ниже) -2. Cкопировать этот гит на сервер любым удобным способом -3. Создать .env файл в корне со следующим содержанием: + +1. Создайте бота через BotFather (см. ниже), добавьте бота в группу с сотрудниками поддержки, дайте боту права администратора, узнайте id группы (см. ниже). +2. Скопируйте этот репозиторий на сервер любым удобным способом. +3. Создайте .env файл в корне со следующим содержанием: ```sh TELEGRAM_TOKEN=<телеграм_токен_вашего_бота> GROUP_ID= @@ -97,55 +115,46 @@ POSTGRES_PASSWORD= START_MESSAGE=<Приветственное сообщение бота, когда клиент нажимает кнопку start> ``` В качестве теста логин пользователя БД, пароль и название БД можно указать postgres. Только для теста, не для продакшена! -4. Запустить сборку docker-образа и его запуск из файла docker-compose. + +4. Запустить сборку docker-образа и его запуск из файла `docker-compose`: ```sh sudo docker-compose up -d --build ``` -Ключ -d для того чтобы контейнер запустился в фоне. -5. Зайти в контейнер c базой данных, создать базу данных, выдать права на нее пользователю (в данном случае postgres) -``` +Ключ `-d` для того чтобы контейнер запустился в фоне. + +5. Зайдите в контейнер с базой данных, создайте базу данных, выдайте права на нее пользователю (в данном случае postgres): +```sh docker exec -it support-bot-db psql -U postgres -\l #убеждаемся что базы данных нет +\l #убеждаемся, что базы данных нет create database support_bot_db; grant all privileges on database support_bot_db to postgres; \q #выходим из psql ``` -6. Применить миграции -```docker exec -it support-bot alembic upgrade head``` + +6. Применить миграции: +```sh +docker exec -it support-bot alembic upgrade head +``` ### Где что брать -1. WEBHOOK_DOMAIN - домен с подключенным ssl сертификатом - -2. WEBHOOK_PATH - URL путь после домена. - -В данном случае WEBHOOK_DOMAIN + WEBHOOK_PATH будет domain.example.com/telegram/ - -3. Token получаем при создании бота через отца ботов (https://t.me/BotFather) - -4. Свой личный id или id группы узнать можно через этого бота. - https://t.me/myidbot . Узнать свой id - написать боту в личку, узнать id - группы - добавить бота в чат группы (например группы поддержки), затем - ввести команду ```/getgroupid``` . - -5. APP_HOST - IP на котором будет работать приложение (по умолчанию на хосте -127.0.0.1, localhost или можно указать 0.0.0.0) - -6. APP_PORT - порт, который приложение будет использовать. Порт должен быть -уникальным и не дублировать порты других приложений, работающих на сервере -или в Docker. - +1. `WEBHOOK_DOMAIN` - домен с подключенным ssl сертификатом +2. `WEBHOOK_PATH` - URL путь после домена. В данном случае `WEBHOOK_DOMAIN` + `WEBHOOK_PATH` будет `domain.example.com/telegram/`. +3. Token получаем при создании бота через BotFather [BotFather](https://t.me/BotFather). +4. Свой личный id или id группы можно узнать через бота [myidbot](https://t.me/myidbot). Узнать свой id - написать боту в личку, узнать id группы - добавить бота в чат группы (например группы поддержки), затем ввести команду `/getgroupid`. +5. `APP_HOST` - IP, на котором будет работать приложение (по умолчанию на хосте `127.0.0.1`, `localhost` или можно указать `0.0.0.0`). +6. `APP_PORT` - порт, который приложение будет использовать. Порт должен быть уникальным и не дублировать порты других приложений, работающих на сервере или в Docker. ## Запуск в режиме polling (на локальном компьютере) -1. Скопировать гит на локальный компьютер -2. Создать файл .env (см. выше) -3. В файле .env удалить (закомментировать) WEBHOOK_DOMAIN. Прописать свои переменные окружения. Так же прописать переменные окружения в файле docker-compose-postgres-localhost.yaml +1. Скопируйте репозиторий на локальный компьютер. +2. Создайте файл `.env` (см. выше). +3. В файле `.env` удалить (закомментировать) `WEBHOOK_DOMAIN`. Пропишите свои переменные окружения. Так же пропишите переменные окружения в файле `docker-compose-postgres-localhost.yaml` 4. Установить виртуальное окружение, активировать его, - установить зависимости из requirements.txt + установить зависимости из `requirements.txt`: ```sh python -m venv venv pip install -r requirements.txt ``` -5. В докере запустить контейнер с базой данных из файла [docker-compose-postgres-localhost.yaml](docker-compose-postgres-localhost.yaml). +5. В докере запустить контейнер с базой данных из файла `docker-compose-postgres-localhost.yaml`: ```sh docker-compose -f docker-compose-postgres-localhost up -d ``` @@ -153,43 +162,46 @@ docker-compose -f docker-compose-postgres-localhost up -d ```sh alembic upgrade head ``` -7. Если алембик ругается что база данных не существует, создать ее вручную и выйти из psql. Затем попытаться сделать миграцию повторно. +7. Если alembic ругается, что базы данных не существует, создайте ее вручную и выйдите из psql. Затем попробуйте выполнить миграцию повторно: ```sh docker exec -it postgres psql -U postgres -#далее sql +# далее в psql create database support_bot_db; grant all privileges on database support_bot_db to postgres; ``` -5. Запустить main.py ```python main.py```. По умолчанию бот должен подключиться базе данных postgres с именем пользователя postgres и паролем postgres -PS: Для запуска необходим python 3.9 или выше +8. Запустить `main.py`: +```sh +python main.py +``` +Для запуска необходим python 3.9 или выше. ## Команды бота В **чате поддержки** доступны следующие команды: -```/info``` - Команда вводится через reply на вопрос пользователя и выдает информацию о нем (Имя, -фамилия, id, никнейм, а также количество сообщений от пользователя и ответов пользователю. Последие 2 - берутся из созданной базы данных. +`/info` - Команда вводится через reply на вопрос пользователя и выдает информацию о нем (имя, фамилия, id, никнейм, а также количество сообщений от пользователя и ответов пользователю. Последние два берутся из созданной базы данных). -```/report``` - отчет по количеству клиентов за месяц, сообщений от них и количество ответов администраторов. +`/report` - Отчет по количеству клиентов за месяц, сообщений от них и количество ответов администраторов. -```/report 01.01.2020 15.02.2021``` - отчет за выбранный период. Две любые даты через пробел, по шаблону. +`/report 01.01.2020 15.06.2024` - Отчет за выбранный период. Две любые даты через пробел, по шаблону. -```/ban``` - Команда вводится через reply на вопрос пользователя. Банит пользователя. Сообщения от него будут игнорироваться ботом +`/ban` - Команда вводится через reply на вопрос пользователя. Банит пользователя. Сообщения от него будут игнорироваться ботом. +`/unban` - Команда вводится через reply на вопрос пользователя. Разбанивает пользователя. -```/unban``` - Команда вводится через reply на вопрос пользователя. Разбанивает пользователя. +`/banlist` - Список забаненных пользователей. Выводит список пользователей в формате `id - имя_фамилия`. -```/banlist``` - Список забаненных пользователей. Выводит список пользователей в формате id - имя_фамилия +`/registeradmin` - Регистрирует нового администратора в чате поддержки. Также администратор регистрируется автоматически, если ответит на сообщение клиента через reply. Это сделано на случай, если забыли зарегистрировать администратора, а он уже отвечает на сообщения. -```/registeradmin``` - Регистрирует нового администратора в **чате поддержки**. Также, адинистратор регистриуется автоматически, если ответит на сообщение клиента через reply. Это сделано на случай если забыли зарегистрировать администратора, а он уже отвечает на сообщения. - -```/deleteadmin``` - Удаляет права администратора у пользователя в **чате поддержки**. После удаления прав администратора нужно вручную удалить пользователя из группы телеграм. +`/deleteadmin` - Удаляет права администратора у пользователя в чате поддержки. После удаления прав администратора нужно вручную удалить пользователя из группы Telegram. ## Автозапуск бота -1.Создание службы:Создайте файл службы для вашего бота. Например, my_bot.service -``` +1. Создание службы: +Создайте файл службы для вашего бота, например `my_bot.service`: +```sh sudo nano /etc/systemd/system/my_bot.service ``` -2.Редактирование службы:Внесите следующие настройки в файл службы: -``` +2. Редактирование службы: +Внесите следующие настройки в файл службы: +```sh [Unit] Description=My Python Telegram Bot After=network.target @@ -204,18 +216,20 @@ Restart=always [Install] WantedBy=multi-user.target ``` -Замените your_username, your_groupname, /path/to/your/bot, и /path/to/your/python на соответствующие значения для вашей среды. Убедитесь, что ExecStart указывает на правильный путь к вашему скрипту Python бота. +Замените `your_username`, `your_groupname`, `/path/to/your/bot`, и `/path/to/your/python` на соответствующие значения для вашей среды. Убедитесь, что `ExecStart` указывает на правильный путь к вашему скрипту Python бота. -3.Перезагрузка systemd:После того как вы сохранили изменения, перезагрузите systemd для применения новой службы: -``` +3. Перезагрузка systemd: +После того как вы сохранили изменения, перезагрузите systemd для применения новой службы: +```sh sudo systemctl daemon-reload ``` -4.Управление службой:Теперь вы можете управлять вашим ботом как службой. Например, чтобы запустить его и настроить автозапуск при загрузке системы, выполните следующие команды: -``` +4. Управление службой: +Теперь вы можете управлять вашим ботом как службой. Например, чтобы запустить его и настроить автозапуск при загрузке системы, выполните следующие команды: +```sh sudo systemctl start my_bot sudo systemctl enable my_bot ``` Чтобы проверить статус вашей службы, выполните: -``` +```sh sudo systemctl status my_bot ``` \ No newline at end of file