chore: commit remaining workspace changes
This commit is contained in:
0
docs/architecture.md
Normal file
0
docs/architecture.md
Normal file
453
docs/installation.md
Normal file
453
docs/installation.md
Normal file
@@ -0,0 +1,453 @@
|
||||
# Установка и настройка ss-tools
|
||||
|
||||
Эта документация описывает процесс установки и настройки ss-tools для локальной разработки и продакшн-среды.
|
||||
|
||||
## Содержание
|
||||
|
||||
- [Требования](#требования)
|
||||
- [Установка через Docker](#установка-через-docker)
|
||||
- [Локальная установка](#локальная-установка)
|
||||
- [Первая настройка](#первая-настройка)
|
||||
- [Конфигурация окружений](#конфигурация-окружений)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Требования
|
||||
|
||||
### Минимальные требования для локальной разработки
|
||||
|
||||
- **Python**: 3.9 или новее
|
||||
- **Node.js**: 18 или новее
|
||||
- **npm**: 9 или новее
|
||||
- **RAM**: 4 GB
|
||||
- **Диск**: 5 GB свободного места
|
||||
- **Операционная система**: Linux, macOS или WSL2
|
||||
|
||||
### Рекомендуемые требования для продакшн
|
||||
|
||||
- **Docker Engine**: 24 или новее
|
||||
- **Docker Compose**: v2.3 или новее
|
||||
- **RAM**: 8 GB
|
||||
- **Диск**: 15+ GB свободного места
|
||||
- **PostgreSQL**: 16 (через Docker)
|
||||
|
||||
### Дополнительные зависимости
|
||||
|
||||
Для локальной разработки могут потребоваться:
|
||||
|
||||
- **Git**: для клонирования репозитория
|
||||
- **Curl**: для тестирования API
|
||||
- **Python-разработчик**: для компиляции некоторых Python пакетов
|
||||
|
||||
## Установка через Docker
|
||||
|
||||
### 1. Клонирование репозитория
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd ss-tools
|
||||
```
|
||||
|
||||
### 2. Настройка переменных окружения
|
||||
|
||||
Создайте файл `.env` в корневой директории:
|
||||
|
||||
```bash
|
||||
# Backend и Frontend порты
|
||||
BACKEND_PORT=8000
|
||||
FRONTEND_PORT=5173
|
||||
|
||||
# PostgreSQL порт
|
||||
POSTGRES_HOST_PORT=5432
|
||||
|
||||
# Альтернативные образы PostgreSQL (если есть проблемы с основным)
|
||||
POSTGRES_IMAGE=postgres:16-alpine
|
||||
|
||||
# Порты для Docker контейнеров
|
||||
BACKEND_HOST_PORT=8001
|
||||
FRONTEND_HOST_PORT=8000
|
||||
```
|
||||
|
||||
### 3. Запуск контейнеров
|
||||
|
||||
```bash
|
||||
# Сборка и запуск всех сервисов
|
||||
docker compose up --build
|
||||
|
||||
# Запуск в фоне с логами
|
||||
docker compose up -d
|
||||
|
||||
# Мониторинг логов
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
### 4. Проверка установки
|
||||
|
||||
После запуска проверьте доступность сервисов:
|
||||
|
||||
```bash
|
||||
# Frontend
|
||||
curl http://localhost:8000
|
||||
|
||||
# Backend API
|
||||
curl http://localhost:8001/docs
|
||||
|
||||
# PostgreSQL
|
||||
docker exec ss_tools_db pg_isready -U postgres
|
||||
```
|
||||
|
||||
## Локальная установка
|
||||
|
||||
### 1. Backend установка
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Создание виртуального окружения
|
||||
python3 -m venv .venv
|
||||
|
||||
# Активация виртуального окружения
|
||||
source .venv/bin/activate # На Linux/macOS
|
||||
# или
|
||||
.venv\Scripts\activate # На Windows
|
||||
|
||||
# Установка зависимостей
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Запуск backend
|
||||
python3 -m uvicorn src.app:app --reload --port 8000
|
||||
```
|
||||
|
||||
### 2. Frontend установка
|
||||
|
||||
Откройте новый терминал:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Установка зависимостей
|
||||
npm install
|
||||
|
||||
# Запуск dev сервера
|
||||
npm run dev -- --port 5173
|
||||
```
|
||||
|
||||
### 3. Настройка PostgreSQL
|
||||
|
||||
Для локальной разработки можно использовать встроенную PostgreSQL или подключиться к существующей:
|
||||
|
||||
```bash
|
||||
# Создание БД (если не создана через Docker)
|
||||
createdb ss_tools
|
||||
|
||||
# Или подключение к существующей
|
||||
psql -U postgres -d ss_tools
|
||||
```
|
||||
|
||||
## Первая настройка
|
||||
|
||||
### 1. Инициализация базы данных
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
source .venv/bin/activate
|
||||
|
||||
# Создание таблиц
|
||||
python src/scripts/init_auth_db.py
|
||||
```
|
||||
|
||||
### 2. Создание администратора
|
||||
|
||||
```bash
|
||||
python src/scripts/create_admin.py --username admin --password admin
|
||||
```
|
||||
|
||||
**Важно**: После создания администратора измените пароль в продакшн-среде!
|
||||
|
||||
### 3. Настройка окружений
|
||||
|
||||
Перейдите в админ-панель (http://localhost:8000/settings) и добавьте свои Superset окружения:
|
||||
|
||||
- **Source Environment**: окружение для миграции данных
|
||||
- **Target Environment**: целевое окружение
|
||||
- **Superset URL**: базовый URL Superset (например, https://superset.example.com)
|
||||
- **API URL**: URL API Superset (обычно /api/v1)
|
||||
- **Auth Type**: Basic Auth или OAuth2
|
||||
|
||||
### 4. Настройка Git-конфигураций
|
||||
|
||||
Если планируете использовать Git-интеграцию:
|
||||
|
||||
1. Перейдите в **Settings → Git**
|
||||
2. Добавьте конфигурацию Git-сервера:
|
||||
- **Name**: идентификатор (например, "GitHub Production")
|
||||
- **Type**: GitHub, GitLab или Bitbucket
|
||||
- **URL**: URL репозитория
|
||||
- **Username**: имя пользователя
|
||||
- **Personal Access Token**: токен с правами на репозитории
|
||||
|
||||
### 5. Настройка LLM-провайдеров
|
||||
|
||||
Для LLM-аналитики и документации:
|
||||
|
||||
1. Перейдите в **Settings → LLM**
|
||||
2. Добавьте провайдера:
|
||||
- **Name**: идентификатор (например, "OpenAI Production")
|
||||
- **Provider**: OpenAI, Anthropic и т.д.
|
||||
- **API Key**: ключ API (будет зашифрован)
|
||||
- **Model**: используемая модель (например, gpt-4-turbo)
|
||||
- **Binding**: для каких задач использовать (validation, docs, commit)
|
||||
|
||||
## Конфигурация окружений
|
||||
|
||||
### Структура конфигурации
|
||||
|
||||
Конфигурация хранится в PostgreSQL в таблице `app_configurations`:
|
||||
|
||||
```sql
|
||||
SELECT * FROM app_configurations WHERE key = 'global_settings';
|
||||
```
|
||||
|
||||
### Основные настройки
|
||||
|
||||
```json
|
||||
{
|
||||
"global_settings": {
|
||||
"enable_belief_state_logging": true,
|
||||
"task_log_level": "INFO",
|
||||
"retention_period_days": 30,
|
||||
"storage_path": "/app/storage",
|
||||
"git_repos_path": "/app/backend/git_repos"
|
||||
},
|
||||
"environments": [
|
||||
{
|
||||
"id": "dev",
|
||||
"name": "Development",
|
||||
"superset_url": "http://localhost:8088",
|
||||
"api_url": "/api/v1",
|
||||
"auth_type": "basic",
|
||||
"username": "admin",
|
||||
"password": "password"
|
||||
},
|
||||
{
|
||||
"id": "staging",
|
||||
"name": "Staging",
|
||||
"superset_url": "https://staging.superset.example.com",
|
||||
"api_url": "/api/v1",
|
||||
"auth_type": "oauth2",
|
||||
"oauth_url": "https://sso.example.com/oauth2/authorize",
|
||||
"token_url": "https://sso.example.com/oauth2/token"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Переменные окружения
|
||||
|
||||
Основные переменные окружения:
|
||||
|
||||
```bash
|
||||
# Database
|
||||
DATABASE_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools
|
||||
TASKS_DATABASE_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools
|
||||
AUTH_DATABASE_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools
|
||||
|
||||
# Server
|
||||
BACKEND_PORT=8000
|
||||
FRONTEND_PORT=5173
|
||||
|
||||
# Security
|
||||
SECRET_KEY=your-secret-key-here
|
||||
JWT_ALGORITHM=HS256
|
||||
JWT_EXPIRE_MINUTES=1440
|
||||
|
||||
# LLM (опционально)
|
||||
OPENAI_API_KEY=sk-...
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
|
||||
# Git (опционально)
|
||||
GIT_USERNAME=your-git-username
|
||||
GIT_EMAIL=your-email@example.com
|
||||
```
|
||||
|
||||
### Включение/отключение функций
|
||||
|
||||
```bash
|
||||
# Включение belief state логирования
|
||||
export ENABLE_BELIEF_STATE_LOGGING=true
|
||||
|
||||
# Уровень логирования задач
|
||||
export TASK_LOG_LEVEL=DEBUG
|
||||
|
||||
# Период retention (в днях)
|
||||
export RETENTION_PERIOD_DAYS=90
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Проблемы с Docker
|
||||
|
||||
**Проблема**: Контейнеры не запускаются
|
||||
|
||||
```bash
|
||||
# Проверка статуса
|
||||
docker compose ps
|
||||
|
||||
# Просмотр логов
|
||||
docker compose logs backend
|
||||
docker compose logs frontend
|
||||
|
||||
# Очистка и пересборка
|
||||
docker compose down -v
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
**Проблема**: PostgreSQL порт занят
|
||||
|
||||
```bash
|
||||
# Изменение порта в .env
|
||||
POSTGRES_HOST_PORT=5433
|
||||
|
||||
# Перезапуск
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Проблемы с Python
|
||||
|
||||
**Проблема**: ImportError при импорте модулей
|
||||
|
||||
```bash
|
||||
# Проверка Python версии
|
||||
python3 --version # Должен быть 3.9+
|
||||
|
||||
# Пересоздание виртуального окружения
|
||||
cd backend
|
||||
rm -rf .venv
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt --upgrade
|
||||
```
|
||||
|
||||
**Проблема**: Нет прав на создание файлов
|
||||
|
||||
```bash
|
||||
# На Linux/macOS
|
||||
chmod +x run.sh
|
||||
chmod +x build.sh
|
||||
|
||||
# На Windows
|
||||
# Права обычно не требуются для .sh скриптов
|
||||
```
|
||||
|
||||
### Проблемы с Node.js
|
||||
|
||||
**Проблема**: npm не устанавливает зависимости
|
||||
|
||||
```bash
|
||||
# Очистка кэша npm
|
||||
npm cache clean --force
|
||||
|
||||
# Пересоздание node_modules
|
||||
cd frontend
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
### Проблемы с БД
|
||||
|
||||
**Проблема**: Подключение к PostgreSQL не удается
|
||||
|
||||
```bash
|
||||
# Проверка доступности БД
|
||||
docker exec ss_tools_db pg_isready -U postgres
|
||||
|
||||
# Проверка таблиц
|
||||
docker exec ss_tools_db psql -U postgres -d ss_tools -c "\dt"
|
||||
|
||||
# Ручная инициализация
|
||||
docker exec -it ss_tools_db psql -U postgres -d ss_tools
|
||||
```
|
||||
|
||||
**Проблема**: Сломанные миграции
|
||||
|
||||
```bash
|
||||
# Откат последней миграции
|
||||
cd backend
|
||||
source .venv/bin/activate
|
||||
alembic downgrade -1
|
||||
|
||||
# Повторная инициализация
|
||||
python src/scripts/init_auth_db.py
|
||||
```
|
||||
|
||||
### Проблемы с Git-интеграцией
|
||||
|
||||
**Проблема**: Не удается инициализировать репозиторий
|
||||
|
||||
```bash
|
||||
# Проверка прав на директорию
|
||||
ls -la backend/git_repos/
|
||||
|
||||
# Создание директории вручную
|
||||
mkdir -p backend/git_repos/
|
||||
chmod 755 backend/git_repos/
|
||||
|
||||
# Проверка Git конфигураций
|
||||
git config --global user.name
|
||||
git config --global user.email
|
||||
```
|
||||
|
||||
**Проблема**: Нет доступа к репозиторию
|
||||
|
||||
```bash
|
||||
# Проверка токена
|
||||
# Токен должен иметь права на:
|
||||
# - Push
|
||||
# - Pull
|
||||
# - Create branches
|
||||
# - Delete branches (если нужно)
|
||||
```
|
||||
|
||||
## Проверка установки
|
||||
|
||||
### Тестирование API
|
||||
|
||||
```bash
|
||||
# Тестирование health endpoint
|
||||
curl http://localhost:8001/health
|
||||
|
||||
# Тестирование списка плагинов
|
||||
curl http://localhost:8001/api/plugins
|
||||
|
||||
# Тестовая аутентификация
|
||||
curl -X POST http://localhost:8001/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username": "admin", "password": "admin"}'
|
||||
```
|
||||
|
||||
### Тестирование фронтенда
|
||||
|
||||
1. Откройте браузер на http://localhost:8000
|
||||
2. Проверьте, что вы можете войти с учетными данными администратора
|
||||
3. Проверьте доступность основных разделов:
|
||||
- Dashboard Hub
|
||||
- Dataset Hub
|
||||
- Settings
|
||||
- Reports
|
||||
|
||||
## Дополнительные ресурсы
|
||||
|
||||
- [Архитектура системы](architecture.md)
|
||||
- [Настройка окружений](settings.md)
|
||||
- [Разработка плагинов](plugin_dev.md)
|
||||
- [API документация](http://localhost:8001/docs)
|
||||
- [GitHub Issues](https://github.com/yourusername/ss-tools/issues)
|
||||
|
||||
## Поддержка
|
||||
|
||||
Если вы столкнулись с проблемами, не описанными в этом документе:
|
||||
|
||||
1. Проверьте раздел [Troubleshooting](#troubleshooting)
|
||||
2. Посмотрите логи в Docker: `docker compose logs -f`
|
||||
3. Откройте issue на GitHub с подробным описанием проблемы
|
||||
4. Обратитесь в техническую поддержку
|
||||
Reference in New Issue
Block a user