# 🖥️ Полное руководство по деплою и управлению TelegramHelper на VPS

## 📋 Содержание

1. [Быстрый старт](#-быстрый-старт)
2. [Информация о сервере](#-информация-о-сервере)
3. [Настройка нового VPS с нуля](#-настройка-нового-vps-с-нуля)
4. [Первоначальная установка](#-первоначальная-установка)
5. [Ежедневное управление](#-ежедневное-управление)
6. [Обновление кода](#-обновление-кода)
7. [Переустановка с нуля](#-переустановка-с-нуля)
8. [Решение проблем](#-решение-проблем)

---

## 🚀 Быстрый старт

### Если бот уже установлен — обновить код:
```bash
# 1. Локально (macOS) - отправить код на сервер
rsync -av --delete \
--exclude 'venv/' --exclude '__pycache__/' --exclude '.git/' --exclude 'bot.log' \
--exclude '.env' --exclude 'app_keys.json' --exclude 'users.json' -e 'ssh -p 22542' \
/Users/olgazaharova/Project/ProjectPython/TelegramHelper/ \
root@138.124.19.67:/opt/TelegramHelper/

# 2. На сервере - перезапустить с обновлением
ssh -p 22542 root@138.124.19.67
cd /opt/TelegramHelper
./scripts/change_token.sh
# Выбрать: r - перезапустить с текущим токеном (код обновится)
```

### Если Windows — обновить код:
```bash
# Git Bash (рекомендуется) — копировать: Ctrl+Insert, вставить: Shift+Insert

# 1. Локально — отправить код на сервер (одной командой)
cd /c/Project/TelegramHelper && \
tar --exclude='venv' --exclude='__pycache__' --exclude='.git' --exclude='bot.log' --exclude='.env' --exclude='app_keys.json' --exclude='users.json' -cvf ../telegramhelper.tar . && \
scp -P 22542 ../telegramhelper.tar root@138.124.19.67:/opt/TelegramHelper/ && \
ssh -p 22542 root@138.124.19.67 "cd /opt/TelegramHelper && tar -xvf telegramhelper.tar && rm telegramhelper.tar" && \
rm ../telegramhelper.tar

# 2. На сервере — перезапустить с обновлением
ssh -p 22542 root@138.124.19.67
cd /opt/TelegramHelper
./scripts/change_token.sh
# Выбрать: r - перезапустить с текущим токеном (код обновится)
```

### Через PowerShell (без Git Bash):
```powershell
# 1. Локально — отправить код на сервер
cd C:\Project\TelegramHelper
tar -cvf ..\telegramhelper.tar --exclude='venv' --exclude='__pycache__' --exclude='.git' --exclude='bot.log' --exclude='.env' --exclude='app_keys.json' --exclude='users.json' .
scp -P 22542 ..\telegramhelper.tar root@138.124.19.67:/opt/TelegramHelper/
ssh -p 22542 root@138.124.19.67 "cd /opt/TelegramHelper && tar -xvf telegramhelper.tar && rm telegramhelper.tar"
del ..\telegramhelper.tar

# 2. На сервере — перезапустить с обновлением
ssh -p 22542 root@138.124.19.67
cd /opt/TelegramHelper
./scripts/change_token.sh
# Выбрать: r - перезапустить с текущим токеном (код обновится)
```

### Проверить что всё скопировалось:
```bash
# На сервере
ssh -p 22542 root@138.124.19.67
cd /opt/TelegramHelper

# Посмотреть последние изменённые файлы (должны быть свежие даты)
ls -lt | head -15

# Проверить размер основных файлов
ls -la api.py security.py handlers.py
```

### Если архив не распаковался (даты файлов старые):
```bash
# Распаковать вручную
cd /opt/TelegramHelper
tar -xvf telegramhelper.tar
rm telegramhelper.tar

# Проверить снова — даты должны быть сегодняшние
ls -lt | head -10
```

### Если скрипты не запускаются (bad interpreter ^M):
```bash
# Проблема: Windows-переносы строк (CRLF вместо LF)
# Решение: конвертировать в Unix формат

apt-get install -y dos2unix
dos2unix scripts/*.sh

# Теперь запустить
./scripts/change_token.sh
```

### Если нужна полная переустановка — [перейти к разделу](#-переустановка-с-нуля)

---

## 📋 Информация о сервере

| Параметр | Значение |
|----------|----------|
| **Локальная машина** | macOS |
| **Путь проекта локально** | `/Users/olgazaharova/Project/ProjectPython/TelegramHelper` |
| **Сервер** | VPS (Linux) |
| **SSH** | `root@138.124.19.67 -p 22542` |
| **Каталог на сервере** | `/opt/TelegramHelper` |
| **Файл окружения** | `/etc/telegramhelper.env` |

### SSH подключение
```bash
ssh -p 22542 -o ServerAliveInterval=60 -o ServerAliveCountMax=2 root@138.124.19.67
```

### tmux для устойчивых сессий (рекомендуется)
```bash
# Новая сессия
tmux new -s ops

# Отсоединиться: Ctrl+b, затем d
# Подключиться: tmux attach -t ops
# Список: tmux ls
```

---

## 🛡️ Настройка нового VPS с нуля

Этот раздел описывает полную настройку нового VPS перед установкой проекта: безопасность, firewall и Docker.

### Шаг 1: Подключение к новому серверу

```bash
# Первое подключение (стандартный порт 22)
ssh root@IP_АДРЕС_СЕРВЕРА
```

### Шаг 2: Обновление системы

```bash
apt update && apt upgrade -y
```

### Шаг 3: Смена порта SSH

⚠️ **Важно:** Не закрывайте текущую сессию до проверки нового порта!

```bash
# Редактируем конфиг SSH
nano /etc/ssh/sshd_config
```

Найдите и измените/добавьте строки:
```
Port 22542
PermitRootLogin yes
PasswordAuthentication yes
PubkeyAuthentication no
```

Или одной командой:
```bash
# Меняем порт SSH
sed -i 's/^#Port 22/Port 22542/' /etc/ssh/sshd_config
sed -i 's/^Port 22$/Port 22542/' /etc/ssh/sshd_config

# Проверяем
grep "^Port" /etc/ssh/sshd_config
```

### Шаг 4: Настройка UFW (firewall)

```bash
# Установка UFW
apt install -y ufw

# Базовые правила
ufw default deny incoming
ufw default allow outgoing

# ВАЖНО: Разрешаем новый SSH порт ДО включения firewall!
ufw allow 22542/tcp

# Порты для веб-сервисов
ufw allow 80/tcp
ufw allow 443/tcp

# Дополнительные порты (по необходимости)
ufw allow 2053/tcp    # панель 3x-ui
ufw allow 8081/tcp    # дополнительный веб-сервис
ufw allow 8443/tcp    # альтернативный HTTPS
ufw allow 53/tcp      # DNS
ufw allow 53/udp      # DNS
ufw allow 8888/udp    # другие сервисы

# Включаем firewall
ufw enable
# Ответить: y

# Проверяем статус
ufw status verbose
```

### Шаг 5: Перезапуск SSH и проверка

```bash
# Перезапускаем SSH
systemctl restart sshd
```

⚠️ **НЕ закрывайте текущую сессию!** Откройте новый терминал и проверьте:

```bash
# В новом терминале
ssh root@IP_АДРЕС_СЕРВЕРА -p 22542
```

Если подключение работает — можно закрыть старую сессию.

### Шаг 6: Установка Docker (Debian)

```bash
# Зависимости
apt install -y ca-certificates curl gnupg

# Ключ репозитория Docker
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

# Добавляем репозиторий (для Debian)
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

# Устанавливаем Docker
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Проверяем
docker --version
docker compose version
```

### Шаг 6 (альтернатива): Установка Docker (Ubuntu)

```bash
# Зависимости
apt install -y ca-certificates curl gnupg

# Ключ репозитория Docker
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

# Добавляем репозиторий (для Ubuntu)
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

# Устанавливаем Docker
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Проверяем
docker --version
docker compose version
```

### Шаг 7: Клонирование проекта

```bash
# Создаём директорию и клонируем
cd /opt
git clone https://github.com/kureinmaxim/TelegramHelper.git
cd TelegramHelper

# Если нужна определённая ветка
git checkout feature/simplified-vless-bot

# Проверяем
ls -la
git branch
```

### Итоговая проверка

```bash
# Проверяем все компоненты
echo "=== SSH порт ==="
grep "^Port" /etc/ssh/sshd_config

echo "=== UFW статус ==="
ufw status

echo "=== Docker ==="
docker --version

echo "=== Проект ==="
ls -la /opt/TelegramHelper
```

После этого переходите к разделу [Первоначальная установка](#-первоначальная-установка).

---

## 🔧 Первоначальная установка

### Шаг 1: Установка Docker на сервере

```bash
# Подключиться к серверу
ssh -p 22542 root@138.124.19.67

# Установить зависимости
sudo apt-get update -y
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Добавить Docker репозиторий
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(. /etc/os-release; echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Установить Docker
sudo apt-get update -y
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Запустить Docker
sudo systemctl enable --now docker

# Проверка
sudo docker info | cat
```

### Шаг 2: Доставка кода на сервер

```bash
# Локально (macOS)
rsync -av --delete \
  --exclude 'venv/' --exclude '__pycache__/' --exclude '.git/' --exclude 'bot.log' \
  --exclude '.env' --exclude 'app_keys.json' --exclude 'users.json' -e 'ssh -p 22542' \
  /Users/olgazaharova/Project/ProjectPython/TelegramHelper/ \
  root@138.124.19.67:/opt/TelegramHelper/
```

### Шаг 3: Настройка окружения

```bash
# На сервере
ssh -p 22542 root@138.124.19.67
cd /opt/TelegramHelper

# Скопировать шаблон в .env
cp example.env .env

# Отредактировать .env — заполнить обязательные поля:
nano .env
```

**Обязательные переменные в `.env`:**

| Переменная | Описание | Как получить |
|------------|----------|--------------|
| `BOT_TOKEN` | Токен бота | @BotFather в Telegram |
| `ANTHROPIC_API_KEY` | Ключ Claude | console.anthropic.com |
| `API_SECRET_KEY` | Ключ для BOMCategorizer | Уже сгенерирован в example.env |
| `API_URL` | URL API | Уже указан: `http://138.124.19.67:8000/ai_query` |

```bash
# Проверить что всё заполнено
cat .env | grep -E "(BOT_TOKEN|ANTHROPIC|API_SECRET|API_URL)" | head -5

# Установить права доступа
chmod 600 .env
```

### Шаг 4: Первый запуск

```bash
cd /opt/TelegramHelper

# Запустить скрипт настройки
./scripts/change_token.sh
# Выбрать: y - заменить токен + настроить ИИ + перезапустить
```

---

## 📊 Ежедневное управление

### Проверка статуса бота
```bash
# Контейнер запущен?
sudo docker ps | grep telegram-helper

# Последние логи
sudo docker logs --tail 100 telegram-helper | cat

# Логи в реальном времени
sudo docker logs -f telegram-helper | cat
```

### Перезапуск бота
```bash
sudo docker restart telegram-helper
```

### Остановка бота
```bash
sudo docker stop telegram-helper
```

### Проверка переменных окружения
```bash
sudo docker exec telegram-helper env | grep -E "(BOT_TOKEN|AI|ANTHROPIC|OPENAI)" | cat
```

### Удалённый просмотр логов (без входа на сервер)
```bash
# С локальной машины
ssh -p 22542 root@138.124.19.67 'sudo docker logs --tail 100 telegram-helper' | cat
```

---

## 🔄 Обновление кода

### Автоматический способ (рекомендуется)

```bash
# 1. Локально - отправить код
rsync -av --delete \
  --exclude 'venv/' --exclude '__pycache__/' --exclude '.git/' --exclude 'bot.log' \
  --exclude '.env' --exclude 'app_keys.json' --exclude 'users.json' -e 'ssh -p 22542' \
  /Users/olgazaharova/Project/ProjectPython/TelegramHelper/ \
  root@138.124.19.67:/opt/TelegramHelper/

# 2. На сервере - перезапустить
ssh -p 22542 root@138.124.19.67
cd /opt/TelegramHelper
./scripts/change_token.sh
# Выбрать: r - перезапустить с текущим токеном (код обновится)
```

### Что делает режим `r`:
- ✅ Создаёт резервную копию .env
- ✅ Останавливает контейнер
- ✅ Пересобирает образ **БЕЗ кэша** (важно!)
- ✅ Запускает новый контейнер
- ✅ Предлагает настроить ИИ (опционально)

### Рекомендуемый способ: через Docker Compose

Проект использует Docker Compose с двумя сервисами (бот + API):

```bash
# На сервере
cd /opt/TelegramHelper

# Остановить все контейнеры
docker compose down

# Пересобрать образы без кэша
docker compose build --no-cache

# Запустить контейнеры в фоновом режиме
docker compose up -d

# Проверить статус
docker ps | grep telegram
```

**Что запускается:**
| Контейнер | Назначение | Порт |
|-----------|------------|------|
| telegram-helper | Telegram бот | — |
| telegram-api | REST API для BOMCategorizer | 8000 |

---

## 🔁 Переустановка с нуля

Если нужно полностью переустановить проект:

```bash
# На сервере
cd /opt/TelegramHelper

# Остановить и удалить контейнеры
docker compose down

# Удалить образы
docker image prune -a

# Удалить директорию (сохраните .env!)
cp .env /tmp/telegramhelper.env.backup
cd /opt
rm -rf TelegramHelper

# Склонировать заново
git clone https://github.com/kureinmaxim/TelegramHelper.git
cd TelegramHelper

# Восстановить .env
cp /tmp/telegramhelper.env.backup .env

# Запустить
./scripts/change_token.sh
```

---

## 🔧 Решение проблем

### Очистка места на диске

```bash
# Проверить занятое место
df -h

# Проверить Docker
docker system df

# Удалить неиспользуемые образы и контейнеры
docker system prune -a

# Очистить логи systemd
journalctl --vacuum-size=100M

# Очистить кэш apt
apt clean
```

### Проблема: No space left on device

```bash
# Посмотреть что занимает место
du -sh /var/log /var/cache /var/lib/docker /root /tmp 2>/dev/null

# Скрытые файлы в /root
du -sh /root/.[!.]* 2>/dev/null | sort -hr | head -10

# Удалить неиспользуемые Docker образы
docker image prune -a
```

### Проблема: bad interpreter ^M

```bash
apt-get install -y dos2unix
dos2unix scripts/*.sh
```

### Проблема: Permission denied

```bash
chmod +x scripts/*.sh
```

### Проблема: Docker не запускается

```bash
# Проверить статус
systemctl status docker

# Перезапустить
systemctl restart docker

# Посмотреть логи
journalctl -u docker --no-pager | tail -50
```

---

## 📁 Файлы и пути

| Файл/Путь | Назначение |
|-----------|------------|
| `/opt/TelegramHelper/` | Код проекта на сервере |
| `/opt/TelegramHelper/.env` | Переменные окружения (токен, API ключи) |
| `./scripts/change_token.sh` | Универсальный скрипт управления |
| `./scripts/api_key.sh` | Управление API ключом для BOMCategorizer |
| `./scripts/deploy_to_server.sh` | Автоматический деплой |

---

## 🔧 Режимы работы change_token.sh

| Режим | Описание |
|-------|----------|
| `y` | Заменить токен + настроить ИИ + пересобрать + перезапустить |
| `r` | Перезапустить с текущим токеном + обновить код |
| `N` | Отмена |

---

## 📚 Связанная документация

- [BOT_TOKEN_CHANGE_GUIDE.md](BOT_TOKEN_CHANGE_GUIDE.md) — полная инструкция по токенам и API ключам
- [SECURITY_GUIDE.md](SECURITY_GUIDE.md) — руководство по безопасности
- [LOCAL_USAGE.md](LOCAL_USAGE.md) — локальное использование
- [README.md](../README.md) — основная документация

---

**💡 Главное правило**: Для любых операций с ботом используйте `./scripts/change_token.sh` — он автоматически пересобирает образ без кэша и настраивает всё необходимое.
