Управление регистрацией агентов

POA с идентификатором сети 77 — основная сеть. Публичная регистрация создаёт кошелёк с нулевым балансом и bearer-токен с правами read и transfer. Она не предоставляет право faucet и не начисляет средства.

Закрытая консоль

Откройте /admin/agents на закрытом адресе серверного приложения через операторскую сеть или SSH-туннель. На poa.net/77 этот путь не публикуется. HTML-страница сама по себе не содержит операционных данных.

Для чтения нужен действующий токен администратора API. Для изменения настроек или доступа аккаунта дополнительно нужен AGENT_REGISTRATION_ADMIN_SECRET. Секреты хранятся в памяти страницы, передаются только в заголовках запросов на тот же закрытый адрес и очищаются при уходе со страницы. Используйте HTTPS либо локальное соединение через аутентифицированный SSH-туннель.

Консоль показывает:

постоянные счётчики попыток регистрации и выданных токенов;
остаток проверенных ключей и квоты;
последние 50 публичных учётных записей и хешированные группы IP-адресов;
до 200 локальных групп счётчиков API за последние 60 секунд.

Счётчики API сбрасываются после перезапуска и относятся к одному узлу. Текущий лимит — 600 запросов на агента за 60 секунд на узел. Счётчики регистрации отражают попытки, дошедшие до проверки допуска в БД. Они не включают некорректные запросы и отказы на сетевом входе или в предварительном локальном ограничителе. При паузе или исчерпанной глобальной квоте проверка не изменяет счётчики допуска.

Включение

Разверните миграцию и серверный API при выключенной выдаче. До её включения опубликуйте форму в обозревателе и Worker, который передаёт обязательные заголовки регистрации.
Задайте AGENT_GATEWAY_ENABLED=true, AGENT_PUBLIC_REGISTRATION_ENABLED=true и независимые случайные секреты длиной не менее 32 байт в AGENT_REGISTRATION_IP_SECRET и AGENT_REGISTRATION_ADMIN_SECRET. Настройте адрес доверенного пограничного прокси, общий секрет и список доверенных прокси. Не храните секреты в исходниках или публичных переменных Worker. Начальная политика БД остаётся на паузе.
Установите Cloudflare Pseudo IPv4 в режим off или add-header, без перезаписи исходного адреса. Проверьте, что Worker перезаписывает X-2d-Registration-IP из метаданных клиента Cloudflare и аутентифицируется на сервере. Отсутствующий, некорректный или приватный IP, а также общий адрес Worker вместо IP клиента должны отклоняться. Не доверяйте клиентскому XFF и не открывайте через туннель /admin. Запрос формы или fetch с другого сайта должен отклоняться без расходования ключа.
Подготовьте проверенные ключи с резервными копиями. Согласуйте квоты и резерв с размером пула и скоростью его пополнения. Начальные значения: 3 успешные регистрации на IP в сутки, 100 на всю сеть в сутки, общий предел 1 000 и резерв 10 ключей. Эти значения не заменяют расчёт ёмкости для рабочей сети.
Снимите паузу, указав причину. Проверьте одну разрешённую регистрацию, выданный адрес, журнал и счётчики. Сохраните токен до пополнения кошелька. Отдельно проверьте политику переводов, лимиты сумм, контрольную проверку подписанта и результаты проверки восстановления ключей.

Worker должен быть опубликован до включения серверной выдачи. Если обязательных заголовков нет, сервер отклоняет регистрацию.

Лимиты и ответы

Суточные окна отсчитываются по UTC. Лимиты попыток хранятся в PostgreSQL: 10 на IP в минуту и 120 на всю сеть в минуту. IPv6-адреса группируются по подсети /64. Глобальные квоты нужны, поскольку один атакующий может контролировать много адресов.

Публичная выдача сериализуется блокировкой строки политики. Назначение ключа, счётчики успешной выдачи и журнал фиксируются одной транзакцией. Допуск к попытке фиксируется отдельно: ошибка создания учётной записи не возвращает израсходованную попытку.

Ответ 429 содержит Retry-After. Ответ 503 означает выключенную выдачу, паузу, достижение общего предела, нехватку проверенных ключей или недоступность сервиса. При потере ответа учётная запись уже могла быть создана: не повторяйте регистрацию автоматически. Восстановление токена и повторное назначение ключей не предусмотрены. Даже кошелёк, который пока не используется, может позднее получить средства, поэтому его ключ не возвращается в пул.

Резерв ограничивает только публичную выдачу. Ручная выдача оператором может расходовать тот же пул, включая резерв. Согласуйте её с пополнением. Настройте внешние оповещения о малом запасе ключей, росте ошибок и постоянном достижении квот: консоль сама не отправляет оповещения.

Изменения настроек записываются в журнал со значениями до и после изменения и указанной причиной. Отключение аккаунта обратимо и проверяется при следующих API-запросах. Оно не перемещает средства и не отменяет уже отправленную транзакцию. Консоль использует общие операторские учётные данные, поэтому журнал не устанавливает, какой человек выполнил действие. Учёт доступа и материалы расследования ведите отдельно. При утечке токена перед повторным включением аккаунта требуется план восстановления доступа.

API-контракт

Закрытое чтение: GET /admin/agents/registration, заголовок x-admin-api-token. Изменения: POST /admin/agents/registration/settings и /identity, дополнительно с x-registration-admin-token. Неизвестные настройки, некорректные диапазоны и пустые причины отклоняются. Административные маршруты не доступны через публичный Worker.

Публичная регистрация: POST https://poa.net/77/agent/v1/register, Content-Type: application/json, X-POA-Registration: 1, тело {}. В браузере запрос должен исходить с того же сайта; серверные клиенты могут не передавать Origin. Успешный ответ 201 содержит токен, идентификатор агента, адрес кошелька, права доступа и идентификатор сети. Ответ нельзя записывать в журнал или кешировать.

Для немедленной остановки выдачи включите паузу в консоли. Чтобы выключить выдачу конфигурацией, также отключите AGENT_PUBLIC_REGISTRATION_ENABLED. Пауза не меняет существующие токены и независимые политики переводов. При откате версии сохраняйте миграцию, журнал и общие счётчики выдачи.