Initial server source import

2026-09-30 20:30:56 +03:00
commit 170dd941b9
498 changed files with 261563 additions and 0 deletions
@@ -0,0 +1,98 @@
+# TRUF worker: установка и работа
+
+Worker получает задания от сервера, скачивает публичные targets и отправляет
+только результат сканирования. Для каждого компьютера или Docker volume нужен
+отдельный device token.
+
+Сервер: `https://pregnant.horsecock.store`
+
+## Что получить у администратора
+
+1. Проверенный artifact для своей платформы и соседний файл с SHA-256.
+2. Одноразово показанный device token. Не отправляйте его в чат, лог или снимок
+   экрана.
+3. Подтверждение, что server-side User и Device включены и artifact зарегистрирован.
+
+Администратор создаёт отдельные User и Device на странице `Workers / Dispatch`,
+выдаёт token и назначает положительный assignment cap. Один token нельзя
+использовать на нескольких устройствах.
+
+## Приватный install YAML
+
+Token не нужно передавать в аргументах процесса. Создайте локальный
+`worker-install.yaml` в приватной папке через текстовый редактор:
+
+```yaml
+server: https://pregnant.horsecock.store
+token: PASTE_DEVICE_TOKEN_HERE
+parallelism: 1
+```
+
+`parallelism` задаёт число локальных занятых slots и должен быть от 1 до 128.
+После `install` worker сохраняет настройки в своём приватном
+`worker.config.json`; исходный YAML нужно удалить. При обычных `start`, `stop`,
+`status`, `attach` и `watch` token больше не вводится.
+
+## Шпаргалки
+
+- [Windows](remote-worker-cheatsheet-windows-ru.md)
+- [Linux без Docker](remote-worker-cheatsheet-linux-ru.md)
+- [Docker Engine / Docker Desktop](remote-worker-cheatsheet-docker-ru.md)
+
+Каждая шпаргалка начинается из корня распакованного artifact или Compose bundle
+и содержит проверенные команды установки и lifecycle.
+
+## Что делают lifecycle-команды
+
+| Команда | Результат |
+| --- | --- |
+| `start` | Запускает установленный worker в фоне; повторный запуск не создаёт второй instance. |
+| `stop --timeout 120` | Локально закрывает новые claims, завершает текущую работу и требует clean drain receipt. |
+| `status` | Показывает instance, slots, текущие phases, deadlines и retained state. |
+| `attach` | Подключает live status/event view; `q` или `Ctrl-C` только отсоединяет. |
+| `watch --follow-seconds 300` | Запускает bounded live status view и затем отсоединяется. |
+| `logs --follow --follow-seconds 300` | Показывает bounded live event/log stream. |
+| `doctor --json` | Проверяет package, config, пути, native tools, TLS endpoint и singleton state. |
+
+`stop` управляет только выбранным локальным worker. Менять server assignment cap
+для обычного stop, restart или обновления не требуется. Не завершайте процесс и
+не удаляйте state, пока clean drain receipt не подтверждён.
+
+## Capacity и backpressure
+
+- Один result bundle имеет hard limit 64 MiB.
+- При выдаче remote assignment server резервирует baseline 2 MiB для bundle и
+  2 MiB для projection; это не новый hard limit.
+- Валидный результат больше baseline атомарно расширяет reservation по фактическому
+  размеру. При временной нехватке capacity worker повторяет upload позже.
+- Server допускает не более 50 unresolved remote assignments глобально и
+  одновременно применяет положительный per-user cap. Фактический предел равен
+  меньшему из доступной capacity, global limit и user cap.
+- Client `parallelism` ограничивает только локальные slots и не повышает server cap.
+
+## Частые состояния
+
+- `idle` или `claiming`: slot свободен или запрашивает задание.
+- `downloading`, `cloning`, `scanning`: выполняется задание.
+- `uploading`, `awaiting_receipt`: результат отправляется или ждёт подтверждения.
+- `backoff`: временная ошибка; причину и следующую попытку показывает `status`.
+- `draining`: новые локальные claims закрыты, текущая работа завершается.
+- `stopped`: clean shutdown завершён.
+
+При проблеме сохраните вывод `doctor --json`, `status --json` и
+`logs --tail 200`. Никогда не прикладывайте device token, install YAML или
+приватный `worker.config.json`.
+
+## Безопасное обновление
+
+1. Выполните локальный `stop --timeout 120 --json` и получите `drained: true`,
+   `exit_code: 0`.
+2. Сохраните предыдущий точный artifact/image и весь state/volume.
+3. Проверьте SHA-256 и package identity новой версии.
+4. Windows/Linux: распакуйте новую версию в отдельную папку. Docker: загрузите
+   новый image и пересоздайте только container с прежним volume.
+5. Выполните `doctor`, `start`, `status` и bounded `watch`.
+
+Не удаляйте локальные `state`, `work`, `bundles`, `events`, `history` или Docker
+volume при ошибке и не используйте `docker compose down --volumes`. Они нужны
+для безопасного продолжения и authoritative receipt recovery.