497 lines
14 KiB
Markdown
497 lines
14 KiB
Markdown
# Установка и настройка 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
|
||
```
|
||
|
||
## Enterprise Clean Release (изолированный контур)
|
||
|
||
### Назначение
|
||
|
||
Сценарий enterprise clean-профиля предназначен для подготовки дистрибутива:
|
||
- без test/demo/load-test данных;
|
||
- без внешних интернет-источников;
|
||
- только с внутренними серверами ресурсов компании.
|
||
|
||
### Операторский цикл (TUI)
|
||
|
||
```bash
|
||
cd /home/busya/dev/ss-tools
|
||
./backend/.venv/bin/python3 -m backend.src.scripts.clean_release_tui
|
||
```
|
||
|
||
Ожидаемый flow:
|
||
1. Выбрать `candidate_id`.
|
||
2. Подтвердить `profile=enterprise-clean`.
|
||
3. Запустить проверку (F5).
|
||
4. Дождаться терминального статуса:
|
||
- `COMPLIANT` — кандидат готов к следующему этапу выпуска;
|
||
- `BLOCKED` — выпуск запрещён до устранения нарушений.
|
||
|
||
### Политика источников (internal-only)
|
||
|
||
Разрешены только хосты из внутреннего реестра компании, например:
|
||
- `repo.intra.company.local`
|
||
- `artifacts.intra.company.local`
|
||
- `pypi.intra.company.local`
|
||
|
||
Любой внешний endpoint (например `pypi.org`) трактуется как `external-source` и блокирует выпуск.
|
||
|
||
### Recovery при BLOCKED
|
||
|
||
1. Открыть детали нарушений (категория, location, remediation).
|
||
2. Удалить запрещённые данные или заменить внешний источник на внутренний.
|
||
3. Повторить запуск проверки (F5) до статуса `COMPLIANT`.
|
||
|
||
### Обязательный CI gate
|
||
|
||
После операторского TUI-прогона тот же профиль должен пройти в CI.
|
||
Только `COMPLIANT` в CI допускает релиз в корпоративный контур.
|
||
|
||
## 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. Обратитесь в техническую поддержку |