init_guac

guacamole_test_11_26/docs/CORS_CONFIGURATION.md

@@ -0,0 +1,171 @@
+# CORS Configuration Guide
+
+## 🎯 Как добавить новый домен для клиента
+
+### Шаг 1: Добавить домен в `production.env`
+
+Откройте файл `GuacamoleRemoteAccess/production.env` и добавьте ваш домен в переменную `ALLOWED_ORIGINS`:
+
+```env
+# CORS Settings
+# ✅ Добавляйте домены через запятую БЕЗ пробелов
+ALLOWED_ORIGINS=https://mc.exbytestudios.com,https://test.exbytestudios.com,https://YOUR_NEW_DOMAIN.com,http://localhost:5173
+```
+
+**Важно:**
+- Домены разделяются запятой **БЕЗ пробелов**
+- Указывайте полный протокол (`https://` или `http://`)
+- Не добавляйте `/` в конце домена
+- Для production используйте только HTTPS домены (кроме localhost для разработки)
+
+### Шаг 2: Перезапустить API контейнер
+
+После изменения `production.env` необходимо перезапустить API контейнер:
+
+```bash
+cd GuacamoleRemoteAccess
+docker-compose restart api
+```
+
+Или полная пересборка (если изменяли Dockerfile):
+
+```bash
+docker-compose up -d --force-recreate api
+```
+
+### Шаг 3: Проверить изменения
+
+Откройте браузер и проверьте в DevTools → Network → любой API запрос → Headers:
+
+```
+Access-Control-Allow-Origin: https://YOUR_NEW_DOMAIN.com
+Access-Control-Allow-Credentials: true
+```
+
+---
+
+## 📋 Текущая конфигурация
+
+### Nginx роутинг (CORS включен автоматически)
+
+Следующие endpoints имеют CORS headers и работают БЕЗ префикса `/api/`:
+
+```
+✅ /auth/*                 - Аутентификация (login, logout, key-exchange)
+✅ /connect                - Создание подключений
+✅ /connections/*          - Управление подключениями
+✅ /bulk/*                 - Массовые операции
+✅ /health/*               - Health checks
+✅ /machines/*             - Проверка доступности машин
+```
+
+Следующие endpoints работают ЧЕРЕЗ префикс `/api/`:
+
+```
+✅ /api/machines/saved/*   - Сохраненные машины (CRUD)
+✅ /api/*                  - Остальные API endpoints (если добавите новые)
+```
+
+### Клиент (MachineControlCenter)
+
+В файле `MachineControlCenter/.env` укажите:
+
+```env
+VITE_API_URL=https://mc.exbytestudios.com
+```
+
+**НЕ указывайте IP адрес!** Используйте доменное имя, которое добавили в `ALLOWED_ORIGINS`.
+
+---
+
+## 🔧 Troubleshooting
+
+### Проблема: "blocked by CORS policy"
+
+**Причина:** Домен клиента не добавлен в `ALLOWED_ORIGINS`
+
+**Решение:**
+1. Убедитесь, что домен указан в `production.env`
+2. Перезапустите API контейнер: `docker-compose restart api`
+3. Проверьте логи: `docker-compose logs api | grep CORS`
+
+### Проблема: "No 'Access-Control-Allow-Origin' header"
+
+**Причина:** Запрос идет на endpoint, который не включен в nginx конфигурацию
+
+**Решение:**
+1. Проверьте URL запроса в DevTools → Network
+2. Если endpoint новый, добавьте его в regex в `nginx/mc.exbytestudios_gate.com`:
+   ```nginx
+   location ~ ^/(auth|connect|connections|bulk|health|machines|YOUR_ENDPOINT)(/|$) {
+   ```
+3. Перезапустите nginx: `docker-compose restart nginx`
+
+### Проблема: Работает с localhost, но не с доменом
+
+**Причина:** В `.env` клиента указан `localhost` вместо домена
+
+**Решение:**
+```env
+# ❌ Неправильно
+VITE_API_URL=http://localhost:8000
+
+# ✅ Правильно
+VITE_API_URL=https://mc.exbytestudios.com
+```
+
+---
+
+## 🛡️ Security Best Practices
+
+1. **Не используйте `*` (wildcard)** в `ALLOWED_ORIGINS` - это небезопасно
+2. **В production указывайте только HTTPS** домены (кроме localhost для разработки)
+3. **Не добавляйте публичные домены** которые вы не контролируете
+4. **Регулярно проверяйте список** доменов и удаляйте неиспользуемые
+
+---
+
+## 📝 Примеры конфигурации
+
+### Development (локальная разработка)
+
+```env
+ALLOWED_ORIGINS=https://mc.exbytestudios.com,http://localhost:5173,http://localhost:3000
+```
+
+### Staging
+
+```env
+ALLOWED_ORIGINS=https://mc.exbytestudios.com,https://staging.exbytestudios.com
+```
+
+### Production
+
+```env
+ALLOWED_ORIGINS=https://mc.exbytestudios.com,https://app.exbytestudios.com
+```
+
+---
+
+## ✅ Checklist
+
+После добавления нового домена:
+
+- [ ] Домен добавлен в `production.env` → `ALLOWED_ORIGINS`
+- [ ] API контейнер перезапущен: `docker-compose restart api`
+- [ ] В клиенте `.env` указан правильный `VITE_API_URL`
+- [ ] Nginx перезапущен (если менялась конфигурация): `docker-compose restart nginx`
+- [ ] Проверено в браузере DevTools → Network → Headers
+- [ ] CORS headers присутствуют: `Access-Control-Allow-Origin`, `Access-Control-Allow-Credentials`
+
+---
+
+## 📞 Support
+
+Если после выполнения всех шагов CORS все еще не работает:
+
+1. Проверьте логи API: `docker-compose logs api | tail -100`
+2. Проверьте логи nginx: `docker-compose logs nginx | tail -100`
+3. Убедитесь, что домен написан БЕЗ ошибок (без пробелов, с правильным протоколом)
+4. Попробуйте очистить кеш браузера (Ctrl+Shift+Delete)
+