busya/ss-tools

Fork 0

Files

busya ce3955ed2e chore: commit remaining workspace changes

2026-03-03 19:51:17 +03:00

12 KiB

Raw Blame History

Установка и настройка ss-tools

Эта документация описывает процесс установки и настройки ss-tools для локальной разработки и продакшн-среды.

Содержание

Требования
Установка через Docker
Локальная установка
Первая настройка
Конфигурация окружений
Troubleshooting

Требования

Минимальные требования для локальной разработки

Python: 3.9 или новее
Node.js: 18 или новее
npm: 9 или новее
RAM: 4 GB
Диск: 5 GB свободного места
Операционная система: Linux, macOS или WSL2

Дополнительные зависимости

Для локальной разработки могут потребоваться:

Git: для клонирования репозитория
Curl: для тестирования API
Python-разработчик: для компиляции некоторых Python пакетов

Установка через Docker

1. Клонирование репозитория

git clone <repository-url>
cd ss-tools

2. Настройка переменных окружения

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

# 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. Запуск контейнеров

# Сборка и запуск всех сервисов
docker compose up --build

# Запуск в фоне с логами
docker compose up -d

# Мониторинг логов
docker compose logs -f

4. Проверка установки

После запуска проверьте доступность сервисов:

# Frontend
curl http://localhost:8000

# Backend API
curl http://localhost:8001/docs

# PostgreSQL
docker exec ss_tools_db pg_isready -U postgres

Локальная установка

1. Backend установка

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 установка

Откройте новый терминал:

cd frontend

# Установка зависимостей
npm install

# Запуск dev сервера
npm run dev -- --port 5173

3. Настройка PostgreSQL

Для локальной разработки можно использовать встроенную PostgreSQL или подключиться к существующей:

# Создание БД (если не создана через Docker)
createdb ss_tools

# Или подключение к существующей
psql -U postgres -d ss_tools

Первая настройка

1. Инициализация базы данных

cd backend
source .venv/bin/activate

# Создание таблиц
python src/scripts/init_auth_db.py

2. Создание администратора

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-интеграцию:

Перейдите в Settings → Git
Добавьте конфигурацию Git-сервера:
- Name: идентификатор (например, "GitHub Production")
- Type: GitHub, GitLab или Bitbucket
- URL: URL репозитория
- Username: имя пользователя
- Personal Access Token: токен с правами на репозитории

5. Настройка LLM-провайдеров

Для LLM-аналитики и документации:

Перейдите в Settings → LLM
Добавьте провайдера:
- Name: идентификатор (например, "OpenAI Production")
- Provider: OpenAI, Anthropic и т.д.
- API Key: ключ API (будет зашифрован)
- Model: используемая модель (например, gpt-4-turbo)
- Binding: для каких задач использовать (validation, docs, commit)

Конфигурация окружений

Структура конфигурации

Конфигурация хранится в PostgreSQL в таблице app_configurations:

SELECT * FROM app_configurations WHERE key = 'global_settings';

Основные настройки

{
  "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"
    }
  ]
}

Переменные окружения

Основные переменные окружения:

# 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

Включение/отключение функций

# Включение belief state логирования
export ENABLE_BELIEF_STATE_LOGGING=true

# Уровень логирования задач
export TASK_LOG_LEVEL=DEBUG

# Период retention (в днях)
export RETENTION_PERIOD_DAYS=90

Troubleshooting

Проблемы с Docker

Проблема: Контейнеры не запускаются

# Проверка статуса
docker compose ps

# Просмотр логов
docker compose logs backend
docker compose logs frontend

# Очистка и пересборка
docker compose down -v
docker compose up --build

Проблема: PostgreSQL порт занят

# Изменение порта в .env
POSTGRES_HOST_PORT=5433

# Перезапуск
docker compose down
docker compose up -d

Проблемы с Python

Проблема: ImportError при импорте модулей

# Проверка Python версии
python3 --version  # Должен быть 3.9+

# Пересоздание виртуального окружения
cd backend
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt --upgrade

Проблема: Нет прав на создание файлов

# На Linux/macOS
chmod +x run.sh
chmod +x build.sh

# На Windows
# Права обычно не требуются для .sh скриптов

Проблемы с Node.js

Проблема: npm не устанавливает зависимости

# Очистка кэша npm
npm cache clean --force

# Пересоздание node_modules
cd frontend
rm -rf node_modules package-lock.json
npm install

Проблемы с БД

Проблема: Подключение к PostgreSQL не удается

# Проверка доступности БД
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

Проблема: Сломанные миграции

# Откат последней миграции
cd backend
source .venv/bin/activate
alembic downgrade -1

# Повторная инициализация
python src/scripts/init_auth_db.py

Проблемы с Git-интеграцией

Проблема: Не удается инициализировать репозиторий

# Проверка прав на директорию
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

Проблема: Нет доступа к репозиторию

# Проверка токена
# Токен должен иметь права на:
# - Push
# - Pull
# - Create branches
# - Delete branches (если нужно)

Проверка установки

Тестирование API

# Тестирование 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"}'

Тестирование фронтенда

Откройте браузер на http://localhost:8000
Проверьте, что вы можете войти с учетными данными администратора
Проверьте доступность основных разделов:
- Dashboard Hub
- Dataset Hub
- Settings
- Reports

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

Поддержка

Если вы столкнулись с проблемами, не описанными в этом документе:

Проверьте раздел Troubleshooting
Посмотрите логи в Docker: docker compose logs -f
Откройте issue на GitHub с подробным описанием проблемы
Обратитесь в техническую поддержку

12 KiB Raw Blame History Unescape Escape