nakama/WIND.md

🪟 Инструкция по развертыванию Nakama на Windows

📋 Содержание

1. Предварительные требования
2. Установка зависимостей
3. Настройка окружения
4. Запуск MongoDB
5. Запуск приложения
6. Отключение проверки initData для разработки
7. Тестирование без Telegram
8. Полезные команды
9. Устранение проблем

---

🔧 Предварительные требования

1. Node.js

Установите Node.js версии 18 или выше:

• Скачайте с nodejs.org
• Проверьте установку:

node --version
npm --version

2. MongoDB

Установите MongoDB Community Edition:

• Скачайте с mongodb.com/try/download/community
• Или используйте MongoDB в Docker (см. ниже)

3. Git (опционально)

Для работы с репозиторием:

• Скачайте с git-scm.com

---

📦 Установка зависимостей

1. Клонируйте репозиторий (если еще не клонирован)

git clone <repository-url>
cd nakama

2. Установите зависимости для backend

npm install

3. Установите дополнительные пакеты для музыкального модуля

npm install adm-zip music-metadata

4. Установите зависимости для frontend

cd frontend
npm install
cd ..

---

⚙️ Настройка окружения

1. Создайте файл .env в корне проекта

REM Скопируйте пример
copy ENV_EXAMPLE.txt .env

Для PowerShell:

# Скопируйте пример
Copy-Item ENV_EXAMPLE.txt .env

2. Минимальная конфигурация для локальной разработки

Откройте .env в текстовом редакторе и настройте:

# Режим разработки
NODE_ENV=development
PORT=3000

# MongoDB (локальная база)
MONGODB_URI=mongodb://localhost:27017/nakama-dev

# JWT Secrets (можно использовать любые строки для разработки)
JWT_SECRET=dev_jwt_secret_change_me_in_production_32chars
JWT_ACCESS_SECRET=dev_access_secret_32chars_minimum_length
JWT_REFRESH_SECRET=dev_refresh_secret_32chars_minimum_length

# Telegram Bot Configuration
# ⚠️ Для разработки без Telegram оставьте пустыми или используйте тестовый токен
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
MODERATION_BOT_TOKEN=

# API ключи для поиска (опционально)
GELBOORU_API_KEY=
GELBOORU_USER_ID=
E621_USERNAME=
E621_API_KEY=

# Frontend URL
FRONTEND_URL=http://localhost:5173
VITE_API_URL=http://localhost:3000/api

# CORS (разрешить все для разработки)
CORS_ORIGIN=*

# Redis (опционально, можно оставить пустым)
REDIS_URL=

# MinIO (отключить для локальной разработки)
MINIO_ENABLED=false

# Rate Limiting (мягкие лимиты для разработки)
RATE_LIMIT_GENERAL=1000
RATE_LIMIT_POSTS=100
RATE_LIMIT_INTERACTIONS=200

# Email (отключить для локальной разработки)
EMAIL_PROVIDER=

3. Создайте .env для frontend

cd frontend
echo VITE_API_URL=http://localhost:3000/api > .env
cd ..

Для PowerShell:

cd frontend
"VITE_API_URL=http://localhost:3000/api" | Out-File -Encoding UTF8 .env
cd ..

---

🗄️ Запуск MongoDB

Вариант 1: MongoDB как сервис Windows

1. Запустите MongoDB из меню Пуск или через службы:

net start MongoDB

2. Проверьте подключение:

mongosh
REM Должно подключиться к mongodb://localhost:27017

Вариант 2: MongoDB в Docker

docker run -d -p 27017:27017 --name mongodb-nakama mongo:latest

Вариант 3: MongoDB вручную

Если MongoDB не установлен как сервис:

REM Перейдите в папку MongoDB
cd "C:\Program Files\MongoDB\Server\7.0\bin"

REM Создайте папку для данных (если не существует)
if not exist C:\data\db mkdir C:\data\db

REM Запустите MongoDB
mongod --dbpath C:\data\db

---

🚀 Запуск приложения

1. Запуск Backend

В корневой папке проекта:

npm run server

Или для автоматической перезагрузки при изменениях:

npm run dev

Backend будет доступен на http://localhost:3000

2. Запуск Frontend

Откройте новое окно Command Prompt (Win+R → cmd):

cd C:\путь\к\проекту\nakama\frontend
npm run dev

Frontend будет доступен на http://localhost:5173

3. Запуск обоих одновременно

Из корневой папки:

npm run dev

Эта команда запустит и backend, и frontend одновременно.

---

🔓 Отключение проверки initData для разработки

Для тестирования без Telegram Mini App нужно временно отключить проверку initData.

Метод 1: Переменная окружения (Рекомендуется)

1. Добавьте в .env:

DISABLE_TELEGRAM_AUTH=true
DEV_USER_ID=123456789

2. Создайте файл backend/middleware/devAuth.js:

// Middleware для разработки без Telegram
const User = require('../models/User');

const devAuthenticate = async (req, res, next) => {
  // Включено только если DISABLE_TELEGRAM_AUTH=true
  if (process.env.DISABLE_TELEGRAM_AUTH !== 'true') {
    return require('./auth').authenticate(req, res, next);
  }

  console.log('⚠️  DEV MODE: Telegram auth disabled');

  try {
    const devUserId = process.env.DEV_USER_ID || '123456789';
    
    // Найти или создать тестового пользователя
    let user = await User.findOne({ telegramId: devUserId });

    if (!user) {
      user = new User({
        telegramId: devUserId,
        username: 'DevUser',
        firstName: 'Dev',
        lastName: 'User',
        photoUrl: null
      });
      await user.save();
      console.log('✅ Created dev user:', user.username);
    }

    // Инициализировать настройки
    if (!user.settings) {
      user.settings = {
        searchPreference: 'furry',
        whitelist: { noNSFW: false, noHomo: false }
      };
      await user.save();
    }

    req.user = user;
    req.telegramUser = {
      id: user.telegramId,
      username: user.username,
      firstName: user.firstName,
      lastName: user.lastName
    };

    next();
  } catch (error) {
    console.error('❌ Dev auth error:', error);
    res.status(500).json({ error: 'Dev auth error' });
  }
};

module.exports = { devAuthenticate };

3. Обновите backend/routes/*.js (все роуты с авторизацией):

// Было:
const { authenticate } = require('../middleware/auth');

// Стало:
const { authenticate } = require('../middleware/auth');
const { devAuthenticate } = require('../middleware/devAuth');

// Используйте devAuthenticate вместо authenticate:
const authMiddleware = process.env.DISABLE_TELEGRAM_AUTH === 'true' 
  ? devAuthenticate 
  : authenticate;

router.get('/', authMiddleware, async (req, res) => {
  // ...
});

Метод 2: Модификация auth.js (Быстрый способ)

Отредактируйте backend/middleware/auth.js:

const authenticate = async (req, res, next) => {
  // 🔥 DEV MODE: Skip Telegram validation
  if (process.env.DISABLE_TELEGRAM_AUTH === 'true') {
    console.log('⚠️  DEV MODE: Skipping Telegram auth');
    
    const devUserId = process.env.DEV_USER_ID || '123456789';
    let user = await User.findOne({ telegramId: devUserId });

    if (!user) {
      user = new User({
        telegramId: devUserId,
        username: 'DevUser',
        firstName: 'Dev',
        lastName: 'User'
      });
      await user.save();
    }

    req.user = user;
    req.telegramUser = {
      id: user.telegramId,
      username: user.username,
      firstName: user.firstName,
      lastName: user.lastName
    };

    return next();
  }

  // Остальной код без изменений...
  try {
    const authHeader = req.headers.authorization || '';
    // ... существующий код ...

Метод 3: Mock Telegram WebApp

Для фронтенда создайте файл frontend\src\utils\mockTelegram.js:

// Mock Telegram WebApp для разработки
export const mockTelegram = () => {
  if (window.Telegram?.WebApp) return; // Уже есть

  const mockInitData = 'query_id=mock&user=%7B%22id%22%3A123456789%2C%22first_name%22%3A%22Dev%22%2C%22last_name%22%3A%22User%22%2C%22username%22%3A%22devuser%22%7D&auth_date=1234567890&hash=mockhash';

  window.Telegram = {
    WebApp: {
      initData: mockInitData,
      initDataUnsafe: {
        query_id: 'mock',
        user: {
          id: 123456789,
          first_name: 'Dev',
          last_name: 'User',
          username: 'devuser'
        },
        auth_date: 1234567890,
        hash: 'mockhash'
      },
      version: '6.0',
      platform: 'web',
      colorScheme: 'light',
      themeParams: {},
      isExpanded: true,
      viewportHeight: 600,
      viewportStableHeight: 600,
      isClosingConfirmationEnabled: false,
      headerColor: '#ffffff',
      backgroundColor: '#ffffff',
      BackButton: { isVisible: false },
      MainButton: { isVisible: false },
      ready: () => console.log('Mock Telegram ready'),
      expand: () => console.log('Mock Telegram expand'),
      close: () => console.log('Mock Telegram close'),
      disableVerticalSwipes: () => {},
      enableClosingConfirmation: () => {},
      disableClosingConfirmation: () => {}
    }
  };

  console.log('✅ Mock Telegram WebApp initialized');
};

Импортируйте и используйте в frontend/src/App.jsx:

// В начале файла
import { mockTelegram } from './utils/mockTelegram'

// В useEffect перед initTelegramApp()
useEffect(() => {
  // Mock Telegram для разработки
  if (import.meta.env.DEV && !window.Telegram?.WebApp) {
    mockTelegram()
  }

  initTheme()
  // ...
}, [])

---

🧪 Тестирование без Telegram

1. Настройте среду разработки

В .env:

DISABLE_TELEGRAM_AUTH=true
DEV_USER_ID=123456789
NODE_ENV=development

2. Запустите приложение

Окно CMD 1 - Backend:

npm run server

Окно CMD 2 - Frontend:

cd frontend
npm run dev

3. Откройте браузер

Перейдите на http://localhost:5173

Приложение должно работать без Telegram Mini App!

4. Тестирование API напрямую

Используйте Postman, Thunder Client или curl (если установлен):

REM Получить посты
curl http://localhost:3000/api/posts

REM Создать пост (с mock auth) - для PowerShell

Для PowerShell:

# Получить посты
Invoke-RestMethod -Uri http://localhost:3000/api/posts -Method Get

# Создать пост
$body = @{
    content = "Test post"
    tags = @("furry", "art")
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:3000/api/posts -Method Post -Body $body -ContentType "application/json"

Рекомендуется использовать Postman или Thunder Client для удобства.

---

📝 Полезные команды

npm скрипты

REM Backend
npm run server          & REM Запустить backend
npm run dev            & REM Backend + Frontend одновременно

REM Frontend
cd frontend
npm run dev            & REM Запустить frontend dev server
npm run build          & REM Собрать production build
npm run preview        & REM Preview production build

MongoDB

REM Подключиться к базе
mongosh mongodb://localhost:27017/nakama-dev

Внутри mongosh:

// Показать базы
show dbs

// Использовать базу
use nakama-dev

// Показать коллекции
show collections

// Найти пользователей
db.users.find().pretty()

// Очистить посты
db.posts.deleteMany({})

Остановка процессов

REM Найти процесс на порту
netstat -ano | findstr :3000
netstat -ano | findstr :5173

REM Убить процесс по PID (замените <PID> на номер процесса)
taskkill /PID <PID> /F

REM Пример:
taskkill /PID 12345 /F

---

🔧 Устранение проблем

Ошибка: "MongoDB connection failed"

Решение:

1. Проверьте, что MongoDB запущен:

net start MongoDB

или

mongosh

2. Проверьте MONGODB_URI в .env:

MONGODB_URI=mongodb://localhost:27017/nakama-dev

Ошибка: "Port 3000 already in use"

Решение:

REM Найти процесс
netstat -ano | findstr :3000

REM Убить процесс (замените <PID> на номер из вывода выше)
taskkill /PID <PID> /F

REM Или измените порт в .env
REM PORT=3001

Ошибка: "Cannot find module 'adm-zip'" или "Cannot find module 'music-metadata'"

Решение:

npm install adm-zip music-metadata

Frontend не подключается к Backend

Решение:

1. Проверьте VITE_API_URL в frontend\.env:

VITE_API_URL=http://localhost:3000/api

2. Проверьте CORS в backend .env:

CORS_ORIGIN=*

3. Перезапустите frontend:

cd frontend
npm run dev

Ошибка: "Требуется авторизация"

Решение:

1. Убедитесь, что DISABLE_TELEGRAM_AUTH=true в .env
2. Реализуйте devAuth middleware (см. выше)
3. Перезапустите backend

Медленная работа на Windows

Решение:

1. Добавьте папки в исключения антивируса:

   • node_modules
   • Папка проекта целиком

2. Используйте WSL2 (Windows Subsystem for Linux) для лучшей производительности:

wsl --install

Перезагрузите компьютер после установки, затем установите проект в WSL.

3. Очистите кеш npm:

npm cache clean --force

---

🎯 Чек-лист запуска

• Node.js установлен (v18+)
• MongoDB запущен
• .env создан и настроен
• npm install выполнен в корне проекта
• npm install выполнен в frontend\
• npm install adm-zip music-metadata выполнен
• DISABLE_TELEGRAM_AUTH=true в .env (для разработки)
• Backend запущен (npm run server)
• Frontend запущен (cd frontend && npm run dev)
• Браузер открыт на http://localhost:5173
• Приложение работает!

---

📚 Дополнительные ресурсы

• Node.js документация
• MongoDB документация
• Vite документация
• React документация
• Express.js документация

---

🆘 Поддержка

Если возникли проблемы:

1. Проверьте логи в консоли backend и frontend
2. Проверьте .env файлы
3. Очистите node_modules и переустановите:

   REM Удалить node_modules
   rmdir /s /q node_modules
   rmdir /s /q frontend\node_modules
   
   REM Переустановить зависимости
   npm install
   cd frontend
   npm install
   cd ..
   

4. Создайте issue в репозитории

---

Удачной разработки! 🚀