ptp/INFO/Deployment/ERRORS_COLLECTION.md

🐛 Коллекция ошибок при развертывании на VPS

Документация всех проблем и решений при установке PTP на VPS

---

📋 Содержание

1. Git Push Problems
2. S3 Upload Issues
3. Telegram Bot Path Issues
4. Forms White Page (AJAX/Redirect)
5. .env File Parsing Bug
6. Permission Errors
7. Script Line Endings

---

1. Git Push Problems

❌ Проблема

fatal: The current branch main has no upstream branch.

🔍 Причина

Локальная ветка main не связана с удалённой github/main.

✅ Решение

git branch --set-upstream-to=github/main main
git pull --no-rebase
git push

📝 Урок

Всегда проверять связь веток перед первым push после клонирования.

---

2. S3 Upload Issues

❌ Проблема

Telegram бот не может загружать фото на S3 REG.RU:

which aws
/usr/bin/aws

aws configure list
      Name                    Value             Type    Location
      ----                    -----             ----    --------
   profile                <not set>             None    None
access_key                <not set>             None    None
secret_key                <not set>             None    None
    region                <not set>             None    None

🔍 Причина

AWS CLI установлен, но не настроен. Пытались установить через pip3, но получили:

error: externally-managed-environment

✅ Решение

Не использовать AWS CLI! Переключиться на direct HTTP upload метод:

# В telegram_bot.py использовать:
upload_photo_direct()  # вместо upload_photo_s3()

Этот метод использует только requests библиотеку и прямой HTTP PUT запрос к S3.

📝 Урок

На Ubuntu 24.04+ pip установка блокируется по умолчанию. Лучше использовать HTTP API напрямую без CLI инструментов.

---

3. Telegram Bot Path Issues

❌ Проблема

fatal: not a git repository

Бот не может выполнить git команды.

🔍 Причина

В коде бота путь к репозиторию был захардкожен:

GIT_REPO_PATH = '/var/www/hugo-site'  # Неправильный путь!

✅ Решение

Читать из .env:

GIT_REPO_PATH = os.getenv('GIT_REPO_PATH', '/var/www/hugo-source')
TRIPS_JSON_PATH = os.path.join(GIT_REPO_PATH, 'static/data/upcoming-trips.json')

В /var/www/telegram-bot/.env:

GIT_REPO_PATH=/var/www/hugo-source

📝 Урок

Никогда не хардкодить пути. Всегда использовать переменные окружения.

---

4. Forms White Page (AJAX/Redirect)

❌ Проблема

После отправки формы - белая страница, хотя POST данные приходят:

=== Request at 2025-10-27 15:02:32 ===
Array (
    [name] => Test
    [email] => test@test.com
    ...
)

🔍 Причина

Несовместимость AJAX и HTTP redirect:

JavaScript в plan.md:

fetch('/forms/send_plan.php', {
    method: 'POST',
    body: formData
})
.then(response => response.text())
.then(text => {
    const data = JSON.parse(text);  // Ожидает JSON!
    ...
})

PHP в send_plan.php (старая версия):

header("Location: /plan/?success=" . urlencode($success));  // Редирект!
exit;

fetch() API НЕ следует редиректам автоматически → получает пустой ответ → белая страница!

✅ Решение (3 части)

1. PHP - вернуть JSON вместо redirect:

// send_plan.php и send_ask.php
if (isset($success)) {
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode([
        'success' => true,
        'message' => $success
    ], JSON_UNESCAPED_UNICODE);
    exit;
}

2. HTML - привязать JavaScript обработчик к форме:

<form ... onsubmit="return handleFormSubmit(event)">

3. Добавить fallback на случай если переменные не установлены:

// В конце send_plan.php перед ?>
if (!isset($success) && !isset($error)) {
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode(['success' => false, 'error' => 'Неизвестная ошибка обработки']);
    exit;
}

📝 Урок

• AJAX формы ВСЕГДА должны возвращать JSON, не redirect
• Проверять что обработчик формы привязан через onsubmit
• История проблем важна - нашли решение в CHANGELOG.md от 2025-09-03!

---

5. .env File Parsing Bug

❌ Проблема

Форма возвращает ошибку "Неизвестная ошибка обработки", хотя в .env установлено:

FORMS_SEND_TELEGRAM=true       # Уведомления в Telegram
FORMS_NOTIFICATIONS=true       # Push-уведомления

Проверка настроек показывает:

Send telegram: false  ❌
Notifications: false  ❌

🔍 Причина

Пробелы и комментарии в .env файле!

При парсинге строки:

FORMS_SEND_TELEGRAM=true       # Уведомления в Telegram

Функция load_env_file() сохраняет:

$_ENV['FORMS_SEND_TELEGRAM'] = 'true       # Уведомления в Telegram'
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                    Лишние символы!

Затем проверка:

getenv('FORMS_SEND_TELEGRAM') === 'true'  // FALSE!
// 'true       # Уведомления...' !== 'true'

Видимость с cat -A:

FORMS_SEND_TELEGRAM=true       # M-PM-#M-PM-2...
                         ^^^^^^^^ Пробелы!

✅ Решение

Метод 1: Исправить .env файл (быстро):

# Убрать всё после # и лишние пробелы
sudo sed -i 's/=\(.*\)#.*/=\1/' /var/www/forms/.env
sudo sed -i 's/= */=/g' /var/www/forms/.env
sudo sed -i 's/ *$//g' /var/www/forms/.env

Результат:

FORMS_SEND_EMAIL=false
FORMS_SEND_TELEGRAM=true
FORMS_NOTIFICATIONS=true

Метод 2: Улучшить load_env_file() (надёжно):

function load_env_file($file_path = '../.env') {
    if (!file_exists($file_path)) {
        return false;
    }

    $lines = file($file_path, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
    foreach ($lines as $line) {
        // Пропускаем комментарии
        if (strpos(trim($line), '#') === 0) {
            continue;
        }

        // Убираем inline комментарии
        if (strpos($line, '#') !== false) {
            $line = substr($line, 0, strpos($line, '#'));
        }

        list($name, $value) = explode('=', $line, 2);
        $name = trim($name);
        $value = trim($value);  // ← Важно! Убирает пробелы

        if (!array_key_exists($name, $_SERVER) && !array_key_exists($name, $_ENV)) {
            putenv(sprintf('%s=%s', $name, $value));
            $_ENV[$name] = $value;
            $_SERVER[$name] = $value;
        }
    }
    return true;
}

📝 Урок

• ВСЕГДА trim() значения из .env файлов!
• Использовать cat -A для проверки невидимых символов
• .env формат не стандартизирован - парсить осторожно
• Эта проблема встречалась ДВА раза:
  1. В начале октября - отступы в начале строк
  2. Сегодня - пробелы перед комментариями

---

6. Permission Errors

❌ Проблема

fatal: could not create work tree dir: Permission denied

🔍 Причина

Неправильные владельцы файлов. Telegram бот работает от www-data, но файлы принадлежат root.

✅ Решение

# Git репозиторий
sudo chown -R www-data:www-data /var/www/hugo-source

# Формы
sudo chown -R www-data:www-data /var/www/forms
sudo chmod 600 /var/www/forms/.env

# Secure storage
sudo chown -R www-data:www-data /var/secure/forms
sudo chmod 700 /var/secure/forms

📝 Урок

Всегда проверять кто запускает процесс (systemctl status service | grep User) и выставлять права соответственно.

Создан набор скриптов: INFO/Deployment/permissions/*.sh

---

7. Script Line Endings

❌ Проблема

./enable-forms-debug.sh
-bash: ./enable-forms-debug.sh: cannot execute: required file not found

🔍 Причина

CRLF line endings (Windows/Mac) вместо LF (Unix):

#!/bin/bash\r\n  # ← \r\n вместо \n

Bash ищет интерпретатор /bin/bash\r который не существует!

✅ Решение

# Конвертировать в Unix формат
sed -i 's/\r$//' /var/www/enable-forms-debug.sh

# Или через dos2unix
sudo apt install dos2unix
dos2unix /var/www/enable-forms-debug.sh

📝 Урок

При создании скриптов на Mac/Windows для Linux:

• Использовать редактор с LF endings (не CRLF)
• Или конвертировать через dos2unix перед запуском

---

🎯 Общие уроки

1. Документация критична

Создание CHANGELOG.md помогло найти решение для AJAX проблемы через 2 месяца!

2. Debug логи спасают

file_put_contents("/tmp/debug.log", print_r($data, true), FILE_APPEND);

Помогли найти что POST данные приходят, но ответ пустой.

3. Системные инструменты

• cat -A - показывает невидимые символы
• ls -la - проверяет права
• grep -n - находит строки с номерами
• curl -v - тестирует HTTP запросы

4. Порядок проверки при пустом ответе PHP

1. ✅ POST данные приходят? → Debug лог
2. ✅ PHP ошибки? → /var/log/php8.3-fpm.log
3. ✅ Content-Type правильный? → curl -I
4. ✅ Переменные устанавливаются? → Debug перед выводом
5. ✅ .env загружается? → Тест парсинга
6. ✅ Значения правильные? → cat -A для невидимых символов

5. Git workflow важен

• Формы теперь в git → автоматический deploy через webhook
• .env защищён через .gitignore
• Версионирование всех изменений

---

📊 Статистика проблем

Категория	Количество	Критичность
Права доступа	5	Высокая
Парсинг .env	2	Критическая
AJAX/HTTP	1	Критическая
Пути к файлам	3	Средняя
Line endings	1	Низкая
AWS CLI	1	Средняя

Общее время на решение: ~4 часа чистого времени отладки

Самая долгая проблема: Forms white page (2+ часа)

Самая коварная: .env пробелы (не видны глазом!)

---

🚀 Профилактика

Перед развертыванием проверить:

1. Права:

   ./INFO/Deployment/permissions/check-permissions.sh
   

2. .env файлы:

   cat -A .env | grep "="  # Проверить на пробелы
   

3. Line endings скриптов:

   file script.sh  # Должно быть "ASCII text", не "CRLF"
   

4. Git remote:

   git remote -v
   git branch -vv  # Проверить upstream
   

5. Формы AJAX:

   • Проверить onsubmit привязан
   • PHP возвращает JSON
   • JavaScript ожидает JSON

---

Создано: 2025-10-27 Последнее обновление: 2025-10-27 Автор: Собрано в процессе развертывания PTP на VPS

Этот документ будет обновляться по мере обнаружения новых проблем.