Справочник API: система и управление платформой

Содержит интерфейсы системной информации уровня развёртывания и управления платформой, включая глобальные настройки, очереди задач, платформенные API-ключи, аудит между пространствами и сброс пароля пользователей. Описание функций см. в Управление платформой и системный администратор.

Вся группа /system/admin/* защищена стражем SystemAdmin(); платформенные API-ключи разделены по возможностям (system_settings_read/manage, system_runtime_read/manage, system_tenants_read/manage, system_audit_read).

Системная информация (/api/v1/system)

Handler: internal/handler/system.go. API-ключ: manage_vector_stores/full. Ответы этой группы обёрнуты в {"code":0,"msg":"success","data":...}.

GET /api/v1/system/capabilities

Viewer+; API-ключом доступно чтение. Возвращает {code:0,data:{edition,capabilities}}; для каждой capability указываются supported/reason. Фронтенд управляет пунктами меню по версии развёртывания, фактически зарегистрированным маршрутам и переключателям Docker; скрытый пункт меню не заменяет проверку прав на бэкенде.

curl "$BASE/api/v1/system/capabilities" -H "Authorization: Bearer $TOKEN"

settings.sandbox.host в capabilities показывает, может ли текущее развёртывание использовать песочницу операционной системы на данной машине; сейчас supported возможно только для нативного настольного приложения macOS.

POST /api/v1/system/host-project-dir

Назначение: открыть на машине, где запущена платформа, системный диалог выбора папки, чтобы новая сессия могла привязаться к локальному каталогу проекта (с v0.8.2, только нативное настольное приложение). Права: Viewer+, только JWT, API-ключи отклоняются всегда. Без тела запроса.

Ответ: 200 {"code":0,"msg":"success","data":{"dir":"/Users/me/project"}}; если пользователь отменяет выбор, dir — пустая строка; для не-настольного развёртывания возвращается 404.

GET /api/v1/system/info

Назначение: версия системы и информация о движках. Права: Viewer+.

Ответ: 200 {"code":0,"msg":"success","data":{version,edition,commit_id,build_time,go_version,keyword_index_engine,vector_store_engine,graph_database_engine,minio_enabled,db_version,started_at,uptime_seconds}}

curl $BASE/api/v1/system/info -H "Authorization: Bearer $TOKEN"

GET /api/v1/system/parser-engines

Назначение: список движков разбора и состояние соединения с DocReader. Права: Viewer+.

Ответ: 200 {"code":0,"msg":"success","data":[...],"docreader_addr","docreader_transport","connected"}

curl $BASE/api/v1/system/parser-engines -H "Authorization: Bearer $TOKEN"

POST /api/v1/system/parser-engines/check

Назначение: проверить движок разбора с заданной конфигурацией (тело запроса types.ParserEngineConfig). Права: Admin+.

Ответ: 200, как выше.

curl -X POST $BASE/api/v1/system/parser-engines/check -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{}'

POST /api/v1/system/docreader/reconnect

Назначение: переподключить DocReader. Права: Admin+. Тело запроса: {"addr":"host:port"} (binding:"required").

Ответ: 200 {"code":0,"msg":"Соединение установлено",...,"connected":true}

curl -X POST $BASE/api/v1/system/docreader/reconnect -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"addr":"docreader:50051"}'

GET /api/v1/system/storage-engine-status

Назначение: доступность движков объектного хранилища. Права: Viewer+.

Ответ: 200 {"code":0,"msg":"success","data":{"engines":[{name,allowed,available,description}],"allowed_providers":[...],"minio_env_available":bool}}

curl $BASE/api/v1/system/storage-engine-status -H "Authorization: Bearer $TOKEN"

POST /api/v1/system/storage-engine-check

Назначение: проверить конфигурацию хранилища (проверка с защитой от SSRF). Права: Admin+. Тело запроса: provider (обязательно, minio/cos/tos/s3/oss/ks3/obs) + соответствующий объект конфигурации minio|cos|tos|s3|oss|ks3|obs.

Ответ: 200 {"code":0,"data":{"ok","message","bucket_created"}}

curl -X POST $BASE/api/v1/system/storage-engine-check -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"provider":"minio","minio":{"endpoint":"minio:9000"}}'

Системное администрирование (/api/v1/system/admin, только SystemAdmin)

На уровне группы установлен страж SystemAdmin() (всегда принудительно, независимо от EnableRBAC); платформенному API-ключу нужна соответствующая capability system_*. Интерфейсы чтения этой группы в основном возвращают необработанные строки/массивы (без обёртки). Handler: internal/handler/system.go, internal/handler/audit_log.go.

POST /api/v1/system/admin/promote

Назначение: выдать SystemAdmin. Тело запроса: user_id (UUID, приоритетно) или email (одно из двух).

Ответ: 200 UserInfo (необработанный объект).

curl -X POST $BASE/api/v1/system/admin/promote -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"email":"admin@ex.com"}'

POST /api/v1/system/admin/revoke

Назначение: отозвать SystemAdmin. Тело запроса: {"user_id":"..."} (binding:"required").

Ответ: 200 UserInfo

curl -X POST $BASE/api/v1/system/admin/revoke -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"user_id":"u-1"}'

GET /api/v1/system/admin/list

Назначение: список SystemAdmin. Параметры запроса: offset (по умолчанию 0), limit (по умолчанию 50, максимум 200).

Ответ: 200 {"total":N,"admins":[UserInfo]}

curl $BASE/api/v1/system/admin/list -H "Authorization: Bearer $TOKEN"

POST /api/v1/system/admin/users/create

Только системный администратор; этот интерфейс не открыт для платформенного API-ключа. Поля запроса: username (2–50 символов), email (корректный адрес), password (необязательно; null или отсутствие — автоматическая генерация). Явно пустая строка всё равно проходит проверку политики паролей и не считается автоматической генерацией.

HTTP-статус	Ответ и значение
201	{user:UserInfo,generated_password?}, создан новый; пароль возвращается только при автоматической генерации
200	{user:UserInfo}, учётная запись уже существует, аккаунт или пароль не изменяются
400	Параметры или политика паролей не соблюдены
409	Email и имя пользователя соответствуют разным учётным записям

Это необработанный объект ответа, без обёртки success/data и без поля idempotent. Новый и существующий аккаунт различаются по HTTP-статусу. Распределение пространств следует auth.default_tenant_mode.

curl -i -X POST "$BASE/api/v1/system/admin/users/create" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"username":"alice","email":"alice@example.com"}'

POST /api/v1/system/admin/users/reset-password

Назначение: сброс пароля пользователя. Тело запроса: email (binding:"required,email"), new_password (binding:"required").

Ответ: 200 {"message":"Password reset successfully"}

curl -X POST $BASE/api/v1/system/admin/users/reset-password -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"email":"a@ex.com","new_password":"newpass1"}'

GET /api/v1/system/admin/api-keys

Назначение: список платформенных API-ключей (с маскированием).

Ответ: 200 {"success":true,"data":[{id,name,api_key,capabilities,expires_at_unix,...}]}

curl $BASE/api/v1/system/admin/api-keys -H "Authorization: Bearer $TOKEN"

POST /api/v1/system/admin/api-keys

Назначение: создание платформенного API-ключа (открытый текст возвращается только один раз). Тело запроса: name (непустое), capabilities (список system_*, обязательно), expires_at_unix (необязательно, должно быть в будущем).

Ответ: 201 {"success":true,"data":{...,"api_key":"<plaintext>","token":"<plaintext>"}}

curl -X POST $BASE/api/v1/system/admin/api-keys -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"ops","capabilities":["system_tenants_read"]}'

DELETE /api/v1/system/admin/api-keys/:key_id

Назначение: удаление платформенного API-ключа.

Ответ: 200 {"success":true}

curl -X DELETE $BASE/api/v1/system/admin/api-keys/3 -H "Authorization: Bearer $TOKEN"

GET /api/v1/system/admin/settings и GET /api/v1/system/admin/settings/:key

Назначение: список / отдельный элемент настроек времени выполнения платформы (платформенному ключу нужны system_settings_read|manage).

Ответ: 200 [SystemSetting] / SystemSetting (необработанный, без обёртки; поля: key,value,value_type,description,last_modified_by,last_modified_at).

curl $BASE/api/v1/system/admin/settings -H "Authorization: Bearer $TOKEN"

PUT /api/v1/system/admin/settings/:key

Назначение: обновление настройки (платформенному ключу нужен system_settings_manage). Тело запроса: {"value":<любой JSON, проверяется по типу из реестра>} (обязательно).

Ответ: 200 SystemSetting

curl -X PUT $BASE/api/v1/system/admin/settings/default_storage_quota -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"value":10737418240}'

DELETE /api/v1/system/admin/settings/:key

Назначение: восстановление значения настройки по умолчанию.

Ответ: 200 {"success":true}

curl -X DELETE $BASE/api/v1/system/admin/settings/default_storage_quota -H "Authorization: Bearer $TOKEN"

GET /api/v1/system/admin/runtime/queues

Назначение: глубина очередей asynq и состояние параллелизма (в режиме Lite возвращается available:false; платформенному ключу нужны system_runtime_read|manage).

Ответ: 200 {"available",upstream_concurrency,parse_concurrency,wiki_concurrency,pools,queues,model_limiter_available,models,timestamp}

curl $BASE/api/v1/system/admin/runtime/queues -H "Authorization: Bearer $TOKEN"

GET /api/v1/system/admin/runtime/queues/:queue/tasks

Назначение: список задач очереди. Параметры запроса: state (pending/active/scheduled/retry/archived/completed), cursor, page_size (по умолчанию 20, максимум 100).

Ответ: 200 {"available","tasks":[RuntimeTaskInfo],"page_size","has_more","next_cursor"}

curl "$BASE/api/v1/system/admin/runtime/queues/default/tasks?state=pending" -H "Authorization: Bearer $TOKEN"

POST /api/v1/system/admin/runtime/queues/:queue/tasks/:task_id/actions/:action

Назначение: операция над задачей (action ∈ cancel/run_now/delete; платформенному ключу нужен system_runtime_manage).

Ответ: 200 {"success":true}

curl -X POST $BASE/api/v1/system/admin/runtime/queues/default/tasks/t-1/actions/cancel \
  -H "Authorization: Bearer $TOKEN"

DELETE /api/v1/system/admin/runtime/queues/:queue/archived

Назначение: очистка архивированных задач.

Ответ: 200 {"success":true,"deleted":N}

curl -X DELETE $BASE/api/v1/system/admin/runtime/queues/default/archived -H "Authorization: Bearer $TOKEN"

POST /api/v1/system/admin/tenants/apply-default-storage-quota

Назначение: массово записать текущую квоту хранилища по умолчанию во все пространства (платформенному ключу нужен system_tenants_manage). Без тела запроса.

Ответ: 200 {"affected":N,"quota_bytes":N,"quota_gb":N}

curl -X POST $BASE/api/v1/system/admin/tenants/apply-default-storage-quota -H "Authorization: Bearer $TOKEN"

GET /api/v1/system/admin/audit-log

Назначение: журнал аудита уровня платформы (строки tenant_id=0; платформенному ключу нужен system_audit_read). Параметры запроса те же, что в аудите пространства (after_id/limit/action/outcome/actor). Handler: internal/handler/audit_log.go

Ответ: 200 {"success":true,"data":[AuditLog],"next_cursor":N}

curl $BASE/api/v1/system/admin/audit-log -H "Authorization: Bearer $TOKEN"

Справочник по реализации

Регистрация маршрутов: RegisterSystemAdminRoutes и RegisterSystemRoutes в internal/router/routes_auth_tenant.go. Handler: internal/handler/system.go, internal/handler/audit_log.go.

Управление пользователями платформы

Следующие интерфейсы доступны только в пользовательской сессии системного администратора, через API Key не открыты.

GET /api/v1/system/admin/users

Постраничный список всех пользователей развёртывания. Параметр запроса offset по умолчанию 0; limit по умолчанию 50, максимум 200. Ответ — нераспакованный объект {"users":[UserInfo],"offset":0,"limit":50,"has_more":false}, пароли и хэши не возвращаются.

POST /api/v1/system/admin/users/status

Тело запроса {"user_id":"ID целевого пользователя","is_active":false}, оба поля обязательны. Деактивация отзывает существующие сессии целевого пользователя; нельзя деактивировать себя или последнего активного системного администратора (400), если пользователя нет — 404. Успешный ответ — {"message":"User status updated","user":UserInfo,"is_active":false}. Создание учётной записи и сброс пароля по-прежнему через /users/create и /users/reset-password из раздела выше.

Каталог моделей (/api/v1/system/admin/model-catalog)

Доступно только пользовательским сессиям системного администратора; для API-ключей эта группа интерфейсов не открыта.

Метод и путь	Назначение
GET /system/admin/model-catalog	Возвращает текущие version, baseline, административный overlay, последние 20 исторических версий, а также каталоги builtin / deployment / effective
POST /system/admin/model-catalog/preview	Проверяет документ переопределения и возвращает каталог-кандидат (только effective и нормализованный overlay; history / builtin / deployment равны null), не сохраняет и не публикует
PUT /system/admin/model-catalog	Проверяет, сохраняет новую версию и публикует; в аудит записываются только метаданные версии

Предпросмотр и публикация используют одно и то же тело запроса:

{
  "version": 0,
  "baseline": "идентификатор базовой линии развёртывания, возвращённый GET",
  "overlay": {
    "providers": {
      "openai": {
        "models": [{"id": "gpt-5", "context_window": 128000}]
      }
    }
  }
}

Ответ — необёрнутый объект состояния каталога. Каждая запись вендора дополнительно несёт model_thinking_levels (по id диалоговой модели перечисляет доступные уровни после включения рассуждений; объединяет сопоставление вендора и возможности протокола) и vendor_thinking_levels (уровни вендора по умолчанию для моделей без отдельно настроенных уровней). Недопустимый документ возвращает 400; устаревшая версия или несовпадение базовой линии развёртывания у запрошенного экземпляра — 409. Публикация сначала сохраняется, затем переключает данный экземпляр; другие экземпляры синхронизируются примерно за 5 секунд. Откат выполняется повторной публикацией с историческим overlay и текущими version / baseline. Полные правила и ограничения см. в Управление моделями.