# 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.