Подготовка устройств к продаже — гайд продавца¶

Этот документ для тех, кто готовит физические устройства dix.su к отправке покупателям. Описывает весь процесс: от чистой ОС до готовой коробки с QR.

Техническая архитектура provisioning — в docs/DEVICES.md.

Поддерживаемые платформы¶

Устройство	ОС	Архитектура	Init
Raspberry Pi 4/5	Raspberry Pi OS (Debian) / Ubuntu	ARM64	systemd
Любой x86-мини-ПК	Debian / Ubuntu	x86_64	systemd
Смартфон (OnePlus, Redmi, …)	postmarketOS	ARM64	OpenRC

Требования перед прошивкой¶

Устройство с установленной ОС и доступом в интернет
Root-доступ к устройству (физически или по SSH)
curl или wget (обычно уже есть; если нет — apt-get install curl / apk add curl)
Устройство должно видеть dix.su по сети

Прошивка устройства: `flash_device.sh`¶

Скрипт находится в dixsu-infra/device/flash_device.sh.

Стандартная прошивка¶

# Скопировать скрипт на устройство (если не на нём напрямую)
scp device/flash_device.sh user@device-ip:/tmp/

# Запустить на устройстве
sudo sh /tmp/flash_device.sh --label "RPi 5 #007"

Параметры¶

Параметр	Описание	По умолчанию
`--label "…"`	Метка для идентификации в панели администратора	(пусто)
`--port N`	Порт локального сервиса на устройстве	`80`
`--reuse-id`	Сохранить существующий UUID (при перепрошивке)	(генерировать новый)

Что делает скрипт¶

Генерирует UUID и записывает в /etc/dixsu/device_id
Скачивает provision.sh с dix.su/api/client/provision.sh
Устанавливает как сервис: systemd (dixsu-provision.service) или OpenRC (dixsu-provision)
Печатает QR-код в терминал
Сохраняет QR PNG → /etc/dixsu/activation_qr.png

После прошивки устройство сразу начинает опрашивать сервер. До привязки покупателем туннель не запускается.

Что происходит внутри устройства¶

После прошивки работает фоновый сервис dixsu-provision:

каждые 60 секунд:
  GET dix.su/api/provision/{UUID}
    → status: pending  → ждём
    → status: active   → запускаем device_client с полученными slug/token
    → нет ответа       → работаем на сохранённом конфиге

При смене аккаунта (отвязка + повторная привязка к другому) сервис автоматически перезапускает туннель с новыми credentials — вмешательства продавца не требуется.

Карточка активации¶

QR-файл сохраняется в /etc/dixsu/activation_qr.png — его нужно распечатать и вложить в коробку с устройством.

Скопировать QR с устройства¶

scp user@device-ip:/etc/dixsu/activation_qr.png ./qr-XXXXX.png

Требования к печати¶

Размер: рекомендуется не менее 3×3 см
Поля: есть (4 модуля — задаётся при генерации)
Контраст: чёрный на белом, матовая бумага предпочтительнее глянцевой

Что должно быть на карточке¶

QR-код
Ссылка текстом: dix.su/activate/<UUID> (для случая, когда QR не читается)
UUID (первые 8 символов достаточно для идентификации при обращении в поддержку)
Короткая инструкция: «Отсканируйте QR и войдите в аккаунт dix.su»

Проверка перед отправкой¶

После прошивки убедитесь, что сервис запущен и опрашивает сервер:

Debian / Raspberry Pi OS¶

systemctl status dixsu-provision
journalctl -u dixsu-provision -f
# Должно быть: "Устройство ожидает привязки. Отсканируйте QR-код: dix.su/activate/…"

postmarketOS / Alpine¶

rc-service dixsu-provision status
tail -f /var/log/dixsu-provision.log

Тестовая активация¶

Для проверки всего флоу до отправки:

Откройте браузер и перейдите по ссылке из лога (dix.su/activate/{UUID})
Войдите в тестовый аккаунт dix.su
Нажмите «Привязать» → убедитесь, что в логе появилось status=active и запустился туннель
Отвяжите устройство в ЛК → убедитесь, что в логе status=pending, туннель остановился
Готово — устройство ведёт себя правильно

Перепрошивка возвращённого устройства¶

При возврате товара устройство нужно перепрошить с новым UUID, чтобы старый QR-код прежнего покупателя перестал работать.

# БЕЗ --reuse-id — генерирует новый UUID, старая ссылка станет недействительной
sudo sh flash_device.sh --label "RPi 5 #007 (refurb)"

Если вы хотите сохранить UUID (например, для замены одного юнита на другой в рамках гарантии), используйте --reuse-id — тогда QR-карточку менять не нужно.

Управление через панель администратора¶

В случае если нужно вручную переназначить устройство без участия покупателя:

# Назначить устройство на slug конкретного пользователя
curl -X POST https://dix.su/api/admin/provision/assign \
  -H "Cookie: ..." \
  -d '{"deviceId":"<UUID>","slug":"<slug>","label":"RPi 5 #007"}'

# Снять привязку
curl -X DELETE https://dix.su/api/admin/provision/<UUID> \
  -H "Cookie: ..."

# Список всех устройств
curl https://dix.su/api/admin/provision/devices \
  -H "Cookie: ..."

Доступно только суперадмину (email совпадает с $ADMIN env-переменной).

Проблемы и решения¶

qrencode не установлен — PNG не создаётся

# Debian / Raspberry Pi OS
apt-get install -y qrencode

# postmarketOS / Alpine
apk add qrencode

Затем запустить flash_device.sh повторно с --reuse-id — UUID сохранится, только QR будет перегенерирован.

Устройство не видит dix.su (нет интернета)

Скрипт flash_device.sh пытается скачать provision.sh с сервера. Если сети нет — положите provision.sh рядом со flash_device.sh на то же устройство, скрипт найдёт его автоматически.

Бинарник dixsu-tunnel не скачивается

provision.sh --install скачивает бинарник с dix.su/api/client/download/linux_arm64 (или linux_x86_64). Если сервер недоступен — скачайте бинарник вручную на машину с интернетом, скопируйте на устройство как /usr/local/bin/dixsu-tunnel, выставьте chmod +x.