680 lines
17 KiB
Markdown
680 lines
17 KiB
Markdown
# 🪟 Инструкция по развертыванию Nakama на Windows
|
||
|
||
## 📋 Содержание
|
||
|
||
1. [Предварительные требования](#предварительные-требования)
|
||
2. [Установка зависимостей](#установка-зависимостей)
|
||
3. [Настройка окружения](#настройка-окружения)
|
||
4. [Запуск MongoDB](#запуск-mongodb)
|
||
5. [Запуск приложения](#запуск-приложения)
|
||
6. [Отключение проверки initData для разработки](#отключение-проверки-initdata-для-разработки)
|
||
7. [Тестирование без Telegram](#тестирование-без-telegram)
|
||
8. [Полезные команды](#полезные-команды)
|
||
9. [Устранение проблем](#устранение-проблем)
|
||
|
||
---
|
||
|
||
## 🔧 Предварительные требования
|
||
|
||
### 1. Node.js
|
||
Установите Node.js версии 18 или выше:
|
||
- Скачайте с [nodejs.org](https://nodejs.org/)
|
||
- Проверьте установку:
|
||
```cmd
|
||
node --version
|
||
npm --version
|
||
```
|
||
|
||
### 2. MongoDB
|
||
Установите MongoDB Community Edition:
|
||
- Скачайте с [mongodb.com/try/download/community](https://www.mongodb.com/try/download/community)
|
||
- Или используйте MongoDB в Docker (см. ниже)
|
||
|
||
### 3. Git (опционально)
|
||
Для работы с репозиторием:
|
||
- Скачайте с [git-scm.com](https://git-scm.com/)
|
||
|
||
---
|
||
|
||
## 📦 Установка зависимостей
|
||
|
||
### 1. Клонируйте репозиторий (если еще не клонирован)
|
||
```cmd
|
||
git clone <repository-url>
|
||
cd nakama
|
||
```
|
||
|
||
### 2. Установите зависимости для backend
|
||
```cmd
|
||
npm install
|
||
```
|
||
|
||
### 3. Установите дополнительные пакеты для музыкального модуля
|
||
```cmd
|
||
npm install adm-zip music-metadata
|
||
```
|
||
|
||
### 4. Установите зависимости для frontend
|
||
```cmd
|
||
cd frontend
|
||
npm install
|
||
cd ..
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ Настройка окружения
|
||
|
||
### 1. Создайте файл `.env` в корне проекта
|
||
|
||
```cmd
|
||
REM Скопируйте пример
|
||
copy ENV_EXAMPLE.txt .env
|
||
```
|
||
|
||
**Для PowerShell:**
|
||
```powershell
|
||
# Скопируйте пример
|
||
Copy-Item ENV_EXAMPLE.txt .env
|
||
```
|
||
|
||
### 2. Минимальная конфигурация для локальной разработки
|
||
|
||
Откройте `.env` в текстовом редакторе и настройте:
|
||
|
||
```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
|
||
|
||
```cmd
|
||
cd frontend
|
||
echo VITE_API_URL=http://localhost:3000/api > .env
|
||
cd ..
|
||
```
|
||
|
||
**Для PowerShell:**
|
||
```powershell
|
||
cd frontend
|
||
"VITE_API_URL=http://localhost:3000/api" | Out-File -Encoding UTF8 .env
|
||
cd ..
|
||
```
|
||
|
||
---
|
||
|
||
## 🗄️ Запуск MongoDB
|
||
|
||
### Вариант 1: MongoDB как сервис Windows
|
||
|
||
1. Запустите MongoDB из меню Пуск или через службы:
|
||
```cmd
|
||
net start MongoDB
|
||
```
|
||
|
||
2. Проверьте подключение:
|
||
```cmd
|
||
mongosh
|
||
REM Должно подключиться к mongodb://localhost:27017
|
||
```
|
||
|
||
### Вариант 2: MongoDB в Docker
|
||
|
||
```cmd
|
||
docker run -d -p 27017:27017 --name mongodb-nakama mongo:latest
|
||
```
|
||
|
||
### Вариант 3: MongoDB вручную
|
||
|
||
Если MongoDB не установлен как сервис:
|
||
|
||
```cmd
|
||
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
|
||
|
||
В корневой папке проекта:
|
||
|
||
```cmd
|
||
npm run server
|
||
```
|
||
|
||
Или для автоматической перезагрузки при изменениях:
|
||
|
||
```cmd
|
||
npm run dev
|
||
```
|
||
|
||
Backend будет доступен на `http://localhost:3000`
|
||
|
||
### 2. Запуск Frontend
|
||
|
||
Откройте **новое окно Command Prompt** (Win+R → `cmd`):
|
||
|
||
```cmd
|
||
cd C:\путь\к\проекту\nakama\frontend
|
||
npm run dev
|
||
```
|
||
|
||
Frontend будет доступен на `http://localhost:5173`
|
||
|
||
### 3. Запуск обоих одновременно
|
||
|
||
Из корневой папки:
|
||
|
||
```cmd
|
||
npm run dev
|
||
```
|
||
|
||
Эта команда запустит и backend, и frontend одновременно.
|
||
|
||
---
|
||
|
||
## 🔓 Отключение проверки initData для разработки
|
||
|
||
Для тестирования без Telegram Mini App нужно временно отключить проверку initData.
|
||
|
||
### Метод 1: Переменная окружения (Рекомендуется)
|
||
|
||
1. Добавьте в `.env`:
|
||
```env
|
||
DISABLE_TELEGRAM_AUTH=true
|
||
DEV_USER_ID=123456789
|
||
```
|
||
|
||
2. Создайте файл `backend/middleware/devAuth.js`:
|
||
|
||
```javascript
|
||
// 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` (все роуты с авторизацией):
|
||
|
||
```javascript
|
||
// Было:
|
||
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`:
|
||
|
||
```javascript
|
||
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`:
|
||
|
||
```javascript
|
||
// 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`:
|
||
|
||
```javascript
|
||
// В начале файла
|
||
import { mockTelegram } from './utils/mockTelegram'
|
||
|
||
// В useEffect перед initTelegramApp()
|
||
useEffect(() => {
|
||
// Mock Telegram для разработки
|
||
if (import.meta.env.DEV && !window.Telegram?.WebApp) {
|
||
mockTelegram()
|
||
}
|
||
|
||
initTheme()
|
||
// ...
|
||
}, [])
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 Тестирование без Telegram
|
||
|
||
### 1. Настройте среду разработки
|
||
|
||
В `.env`:
|
||
```env
|
||
DISABLE_TELEGRAM_AUTH=true
|
||
DEV_USER_ID=123456789
|
||
NODE_ENV=development
|
||
```
|
||
|
||
### 2. Запустите приложение
|
||
|
||
**Окно CMD 1 - Backend:**
|
||
```cmd
|
||
npm run server
|
||
```
|
||
|
||
**Окно CMD 2 - Frontend:**
|
||
```cmd
|
||
cd frontend
|
||
npm run dev
|
||
```
|
||
|
||
### 3. Откройте браузер
|
||
|
||
Перейдите на `http://localhost:5173`
|
||
|
||
Приложение должно работать без Telegram Mini App!
|
||
|
||
### 4. Тестирование API напрямую
|
||
|
||
Используйте **Postman**, **Thunder Client** или **curl** (если установлен):
|
||
|
||
```cmd
|
||
REM Получить посты
|
||
curl http://localhost:3000/api/posts
|
||
|
||
REM Создать пост (с mock auth) - для PowerShell
|
||
```
|
||
|
||
**Для 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 скрипты
|
||
|
||
```cmd
|
||
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
|
||
|
||
```cmd
|
||
REM Подключиться к базе
|
||
mongosh mongodb://localhost:27017/nakama-dev
|
||
```
|
||
|
||
Внутри mongosh:
|
||
```javascript
|
||
// Показать базы
|
||
show dbs
|
||
|
||
// Использовать базу
|
||
use nakama-dev
|
||
|
||
// Показать коллекции
|
||
show collections
|
||
|
||
// Найти пользователей
|
||
db.users.find().pretty()
|
||
|
||
// Очистить посты
|
||
db.posts.deleteMany({})
|
||
```
|
||
|
||
### Остановка процессов
|
||
|
||
```cmd
|
||
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 запущен:
|
||
```cmd
|
||
net start MongoDB
|
||
```
|
||
или
|
||
```cmd
|
||
mongosh
|
||
```
|
||
|
||
2. Проверьте `MONGODB_URI` в `.env`:
|
||
```env
|
||
MONGODB_URI=mongodb://localhost:27017/nakama-dev
|
||
```
|
||
|
||
### Ошибка: "Port 3000 already in use"
|
||
|
||
**Решение:**
|
||
```cmd
|
||
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'"
|
||
|
||
**Решение:**
|
||
```cmd
|
||
npm install adm-zip music-metadata
|
||
```
|
||
|
||
### Frontend не подключается к Backend
|
||
|
||
**Решение:**
|
||
1. Проверьте `VITE_API_URL` в `frontend\.env`:
|
||
```env
|
||
VITE_API_URL=http://localhost:3000/api
|
||
```
|
||
|
||
2. Проверьте CORS в backend `.env`:
|
||
```env
|
||
CORS_ORIGIN=*
|
||
```
|
||
|
||
3. Перезапустите frontend:
|
||
```cmd
|
||
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) для лучшей производительности:
|
||
```cmd
|
||
wsl --install
|
||
```
|
||
Перезагрузите компьютер после установки, затем установите проект в WSL.
|
||
|
||
3. Очистите кеш npm:
|
||
```cmd
|
||
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 документация](https://nodejs.org/docs/)
|
||
- [MongoDB документация](https://www.mongodb.com/docs/)
|
||
- [Vite документация](https://vitejs.dev/)
|
||
- [React документация](https://react.dev/)
|
||
- [Express.js документация](https://expressjs.com/)
|
||
|
||
---
|
||
|
||
## 🆘 Поддержка
|
||
|
||
Если возникли проблемы:
|
||
|
||
1. Проверьте логи в консоли backend и frontend
|
||
2. Проверьте `.env` файлы
|
||
3. Очистите `node_modules` и переустановите:
|
||
```cmd
|
||
REM Удалить node_modules
|
||
rmdir /s /q node_modules
|
||
rmdir /s /q frontend\node_modules
|
||
|
||
REM Переустановить зависимости
|
||
npm install
|
||
cd frontend
|
||
npm install
|
||
cd ..
|
||
```
|
||
4. Создайте issue в репозитории
|
||
|
||
---
|
||
|
||
**Удачной разработки! 🚀**
|
||
|