Skip to content

launch.md

Latest commit

 

History

History
241 lines (166 loc) · 9.38 KB

launch.md

File metadata and controls

241 lines (166 loc) · 9.38 KB

Запуск проекта

🇬🇧 English version

Как собрать фронтенд, запустить бэкенд и развернуть SocksTank на роботе.

Разработка на macOS / Linux

1. Установка зависимостей

cd ~/work/SocksTank

# Python (через uv, рекомендуется)
uv venv
source .venv/bin/activate
uv pip install -e .

# Или через pip
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Сборка фронтенда

cd frontend
npm install        # один раз
npm run build      # собрать в frontend/dist/

3. Запуск (mock-режим)

./main.py serve --mock

Открыть: http://localhost:8080

Флаг --mock заменяет GPIO, камеру и сенсоры на заглушки — можно разрабатывать без RPi.

Режим разработки с hot-reload

Для работы над фронтендом — два терминала:

# Терминал 1: бэкенд
./main.py serve --mock

# Терминал 2: Vite dev server (hot-reload)
cd frontend && npm run dev

Фронтенд: http://localhost:5173 (с hot-reload, проксирует API на порт 8080).

Деплой на Raspberry Pi

Перед тем как использовать rpi5 как hostname в командах ниже, убедись, что твоя dev-машина его резолвит. Типовой вариант:

# ~/.ssh/config
Host rpi5
    HostName 192.168.0.158
    User user

Host blackops
    HostName 192.168.0.124
    User user
    IdentityFile ~/.ssh/blackops

# /etc/hosts (необязательный fallback, если mDNS работает нестабильно)
192.168.0.158 rpi5
192.168.0.124 blackops

См. также: infrastructure.md

Рекомендуемый способ: main.py deploy

Самый удобный сценарий деплоя — встроенная команда:

./main.py deploy rpi5

# Эквивалентная явная форма
./main.py deploy --host rpi5

Используй этот путь по умолчанию, если только ты специально не отлаживаешь сам процесс деплоя или не делаешь разовую ручную установку.

Что она делает:

  • локально собирает фронтенд (если не указан --skip-build)
  • синхронизирует проект в ~/sockstank через rsync
  • ставит runtime-зависимости на RPi (uv, если доступен, иначе pip)
  • перезапускает sockstank.service (через systemd), если unit существует, иначе использует fallback через nohup python3 main.py serve ...
  • ждёт health check /api/status на порту 8080

Полезные флаги:

  • --skip-build
  • --skip-install
  • --skip-restart
  • --dry-run

Связанные команды для эксплуатации:

# Только перезапустить удалённый сервер
./main.py restart rpi5

# Показать последние логи
./main.py logs rpi5 --lines 100

Необязательно: один раз установить systemd unit

Если хочешь, чтобы deploy и restart использовали systemctl, а не fallback через nohup, один раз установи bundled unit:

./main.py install-service rpi5

Требования:

  • SSH-пользователь должен уметь выполнять sudo без интерактивного запроса пароля (sudo -n)1
  • проект уже должен быть на хосте (например, после ./main.py deploy rpi5)

Внутри команда рендерит scripts/sockstank.service под текущего SSH-пользователя, копирует его в /etc/systemd/system/, выполняет daemon-reload и включает сервис. После этого веб-сервер работает от этого пользователя, а не от root.

После этого можно использовать:

./main.py restart rpi5
./main.py logs rpi5

Ручной деплой (fallback)

Используй этот путь только если нужно пройти деплой по шагам для отладки или если встроенная команда deploy временно недоступна.

1. Копирование проекта

rsync -avz --exclude .venv --exclude frontend/node_modules --exclude __pycache__ --exclude .git \
  ~/work/SocksTank/ rpi5:~/sockstank/

2. Установка зависимостей на RPi

ssh rpi5

# Предпочтительно (если установлен uv)
uv pip install --system "typer>=0.9" ultralytics opencv-python-headless numpy "fastapi>=0.104" "uvicorn[standard]>=0.24" "pydantic-settings>=2.0" "websockets>=12.0" "httpx>=0.25" "paramiko>=3.0" "pyyaml>=6.0"

# Fallback (если uv нет)
python3 -m pip install "typer>=0.9" ultralytics opencv-python-headless numpy "fastapi>=0.104" "uvicorn[standard]>=0.24" "pydantic-settings>=2.0" "websockets>=12.0" "httpx>=0.25" "paramiko>=3.0" "pyyaml>=6.0" --break-system-packages

picamera2 уже предустановлен в Raspberry Pi OS.

3. Запуск на RPi

cd ~/sockstank

# Простой запуск
sudo -E python3 main.py serve --model models/yolo11_best_ncnn_model --conf 0.5

# С NcnnNativeDetector (14.9–15.8 FPS на RPi 5)
sudo -E python3 main.py serve --model models/yolo11_best_ncnn_model --conf 0.5 --ncnn-cpp --ncnn-threads 4

# В фоне (рекомендуется)
sudo -E nohup python3 main.py serve --model models/yolo11_best_ncnn_model --conf 0.5 > /tmp/sockstank.log 2>&1 &

Открыть: http://rpi5:8080

Логи: tail -f /tmp/sockstank.log

sudo -E — sudo для доступа к камере и GPIO, -E наследует PYTHONPATH.

Параметры main.py serve

Параметр По умолчанию Описание
--model auto (.pt на dev/GPU, ncnn на RPi) Путь к модели (см. ниже)
--conf 0.5 Порог уверенности (0.0–1.0)
--host 0.0.0.0 Адрес привязки
--port 8080 HTTP/WebSocket порт
--mock false Mock-режим (без GPIO/камеры)
--ncnn-cpp false NcnnNativeDetector (pip ncnn + OMP workaround)
--ncnn-threads 2 Количество OMP потоков для ncnn (1–4)
--pcb-version 1 PCB версия платы Freenove (1 или 2)

Какую модель указывать в --model?

  • RPi (продакшен): models/yolo11_best_ncnn_model — NCNN FP32, 15 FPS
  • GPU-сервер: models/yolo11_best.pt — PyTorch, 314 FPS на CUDA
  • macOS / dev: models/yolo11_best.pt — PyTorch (или --mock без модели)

Если --model не указан, SocksTank выбирает автоматически: .pt на dev/GPU-хостах и models/yolo11_best_ncnn_model на Raspberry Pi. Явный путь по-прежнему имеет приоритет.

Все параметры можно задать через переменные окружения с префиксом SOCKSTANK_:

SOCKSTANK_MODEL_PATH="models/yolo11_best_ncnn_model" SOCKSTANK_MOCK=true python3 main.py serve

Обновление фронтенда на RPi

После изменений в frontend/:

# На dev-машине
cd frontend && npm run build

# Скопировать на RPi
rsync -avz frontend/dist/ rpi5:~/sockstank/frontend/dist/

Перезапустить serve на RPi.

GPU-инференс (удалённый)

Подробнее: inference.md — Удалённый инференс

# На GPU-сервере (blackops)
python3 -m server.inference_server --port 8090  # на Linux использовать python3; автоматически выберет models/yolo11_best.pt на GPU/dev-хостах

В веб-панели: Inference → + Add GPU Server → ввести хост, порт, SSH-ключ → Save.

← Предыдущая README Следующая →
Тренировка модели Вернуться к README Запуск на роботе

Footnotes

  1. Пример на RPi: выполни sudo visudo -f /etc/sudoers.d/sockstank, затем добавь правило вида zeus ALL=(ALL) NOPASSWD: /bin/cp, /bin/systemctl. Замени zeus на своего SSH-пользователя. Так passwordless sudo остаётся ограниченным только командами, которые нужны для установки и перезапуска сервиса. ↩