busya/ss-tools

Fork 0

Files

busya feb07bf366 security: rotate bootstrap and clean workspace

2026-03-13 12:14:37 +03:00

21 KiB

Raw Permalink Blame History

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

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

Содержание

Требования
Установка через Docker
Offline Docker Bundle
Локальная установка
Первая настройка
Конфигурация окружений
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

Offline Docker Bundle

Этот режим предназначен для enterprise clean-развёртывания в контуре без доступа к внешнему интернету.

1. Сборка bundle в подключённом контуре

cd /home/busya/dev/ss-tools
./scripts/build_offline_docker_bundle.sh v1.0.0-rc2-docker

Результат появится в dist/docker/:

backend.v1.0.0-rc2-docker.tar
frontend.v1.0.0-rc2-docker.tar
postgres.v1.0.0-rc2-docker.tar
sha256sums.v1.0.0-rc2-docker.txt
manifest.v1.0.0-rc2-docker.txt
docker-compose.enterprise-clean.yml
.env.enterprise-clean.example

2. Перенос bundle в изолированный контур

Передайте каталог dist/docker/ во внутреннюю сеть любым утверждённым способом.

3. Импорт образов

docker load -i backend.v1.0.0-rc2-docker.tar
docker load -i frontend.v1.0.0-rc2-docker.tar
docker load -i postgres.v1.0.0-rc2-docker.tar

4. Подготовка конфигурации

cp .env.enterprise-clean.example .env.enterprise-clean

Минимально проверьте:

BACKEND_IMAGE
FRONTEND_IMAGE
POSTGRES_IMAGE
POSTGRES_PASSWORD
STORAGE_ROOT

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

INITIAL_ADMIN_CREATE=true
INITIAL_ADMIN_USERNAME=<org-admin-login>
INITIAL_ADMIN_PASSWORD=<temporary-strong-secret>
INITIAL_ADMIN_EMAIL=<optional>

Также проверьте, что теги образов в .env.enterprise-clean совпадают с реально загруженными:

BACKEND_IMAGE=ss-tools-backend:v1.0.0-rc2-docker
FRONTEND_IMAGE=ss-tools-frontend:v1.0.0-rc2-docker

5. Запуск в offline-контуре

docker compose --env-file .env.enterprise-clean -f docker-compose.enterprise-clean.yml up -d

Compose-файл использует pull_policy: never, поэтому runtime не должен обращаться к внешним registry.

6. Bootstrap администратора в контейнере

При INITIAL_ADMIN_CREATE=true backend container автоматически:

инициализирует auth DB;
запускает create_admin.py с runtime-параметрами;
создаёт пользователя только если его ещё нет;
при повторном старте не изменяет существующего администратора.

После первого успешного входа обязательно:

смените bootstrap-пароль на постоянный организационный секрет;
установите INITIAL_ADMIN_CREATE=false;
перезапустите stack с обновлённым .env.enterprise-clean.

Если bootstrap завершается ошибкой, backend не стартует — это ожидаемый fail-fast режим для безопасного ввода в эксплуатацию.

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

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

cd backend
source .venv/bin/activate

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

При первом запуске скрипт создаёт backend/.env и записывает туда ENCRYPTION_KEY, если ключ не был задан через окружение заранее.

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

python src/scripts/create_admin.py --username admin --password '<strong-temporary-secret>'

Важно: После создания администратора измените пароль в продакшн-среде!

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

Enterprise Clean Release (изолированный контур)

Назначение

Сценарий enterprise clean-профиля предназначен для подготовки дистрибутива:

без test/demo/load-test данных;
без внешних интернет-источников;
только с внутренними серверами ресурсов компании.

Операторский цикл (CLI/API/TUI)

A) Headless CLI (основной сценарий для CI/CD)

cd /home/busya/dev/ss-tools/backend

# Регистрация кандидата
.venv/bin/python3 -m src.scripts.clean_release_cli candidate-register \
  --candidate-id 2026.03.09-rc1 \
  --version 1.0.0 \
  --source-snapshot-ref git:release/2026.03.09-rc1 \
  --created-by release-operator

# Импорт артефакта
.venv/bin/python3 -m src.scripts.clean_release_cli artifact-import \
  --candidate-id 2026.03.09-rc1 \
  --artifact-id artifact-001 \
  --path backend/dist/package.tar.gz \
  --sha256 deadbeef \
  --size 1024

# Сборка манифеста
.venv/bin/python3 -m src.scripts.clean_release_cli manifest-build \
  --candidate-id 2026.03.09-rc1 \
  --created-by release-operator

# Запуск compliance
.venv/bin/python3 -m src.scripts.clean_release_cli compliance-run \
  --candidate-id 2026.03.09-rc1 \
  --actor release-operator

B) API-автоматизация

Поддерживаемые endpoint’ы:

V2 lifecycle:
- POST /api/clean-release/candidates
- POST /api/clean-release/candidates/{candidate_id}/artifacts
- POST /api/clean-release/candidates/{candidate_id}/manifests
- GET /api/clean-release/candidates/{candidate_id}/overview
Legacy compatibility (для постепенной миграции интеграций):
- POST /api/clean-release/candidates/prepare
- POST /api/clean-release/checks
- GET /api/clean-release/checks/{check_run_id}

C) TUI thin client

cd /home/busya/dev/ss-tools
./run_clean_tui.sh <candidate_id>

Горячие клавиши:

F5: Run Compliance
F6: Build Manifest
F7: Reset Draft
F8: Approve
F9: Publish
F10: Refresh Overview

Ожидаемый flow:

Выбрать candidate_id.
Подтвердить profile=enterprise-clean.
Выполнить F6 (если манифест отсутствует).
Выполнить F5 для compliance.
При COMPLIANT — перейти к F8 и F9.
При BLOCKED — устранить нарушения и повторить F5.

По умолчанию run_clean_tui.sh запускает TUI в real режиме (CLEAN_TUI_MODE=real) без инъекции демонстрационных нарушений. Важно: TUI запускается только в интерактивном TTY; для headless-среды используйте CLI/API.

Переменные запуска `run_clean_tui.sh`

# Опционально: явный режим (real|demo), по умолчанию real
export CLEAN_TUI_MODE=real

# Опционально: bootstrap данных кандидата/политики/реестра
export CLEAN_TUI_BOOTSTRAP_JSON=/absolute/path/bootstrap.json

# Опционально: артефакты для подготовки manifest, если он еще не создан
export CLEAN_TUI_ARTIFACTS_JSON=/absolute/path/artifacts.json

# Запуск (candidate_id можно передать первым аргументом)
./run_clean_tui.sh 2026.03.03-rc1

# Явный демонстрационный режим
./run_clean_tui.sh --demo

Минимальный пример bootstrap.json:

{
  "candidate_id": "2026.03.03-rc1",
  "version": "1.0.0",
  "source_snapshot_ref": "v1.0.0-rc1",
  "created_by": "operator",
  "allowed_hosts": ["internal-repo.company.com"],
  "prohibited_artifact_categories": ["test-data", "demo", "load-test"],
  "required_system_categories": ["core"]
}

Минимальный пример artifacts.json:

{
  "artifacts": [
    {
      "id": "artifact-backend-dist",
      "path": "backend/dist/package.tar.gz",
      "sha256": "deadbeef",
      "size": 1024,
      "category": "core",
      "source_uri": "https://repo.intra.company.local/releases/backend/dist/package.tar.gz",
      "source_host": "repo.intra.company.local"
    }
  ]
}

Политика источников (internal-only)

Разрешены только хосты из внутреннего реестра компании, например:

repo.intra.company.local
artifacts.intra.company.local
pypi.intra.company.local

Любой внешний endpoint (например pypi.org) трактуется как external-source и блокирует выпуск.

Recovery при BLOCKED

Открыть детали нарушений (категория, location, remediation).
Удалить запрещённые данные или заменить внешний источник на внутренний.
Повторить запуск проверки (F5) до статуса COMPLIANT.

Обязательный CI gate

После операторского TUI-прогона тот же профиль должен пройти в CI. Только COMPLIANT в CI допускает релиз в корпоративный контур.

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 с подробным описанием проблемы
Обратитесь в техническую поддержку

21 KiB Raw Permalink Blame History Unescape Escape