DEV Community: Юрий

Расширяем Keycloak: Пишем Java-плагин для загрузки пользователей из внешнего API

Юрий — Mon, 16 Jun 2025 15:04:12 +0000

Данная статья написана для людей, имеющих базовый опыт работы с java и тех, кто хотя бы что-то слышал о Keycloak. В ней будет рассказано о том, как написать свой плагин, позволяющий рабоать с внешней базой данных пользователей через API сервис. Я постараюсь объяснить данную тему доступным языком и предоставить практические примеры, чтобы вы могли легко применить полученные знания на практике.

Коллеги, на связи Ваш код еще не готов, сэр! и сегодня мы поговорим о Keycloak, а точнее о том, как написать свой собственный плагин, позволяющий взаимодействовать с внешней базой данных пользователей посредством отправки HTTP-запросов к удаленному сервису.

Но прежде чем мы начнем, возникает вопрос, что же такое Keycloak? По традиции, возьму определение из Вики.

Keycloak — это система управления идентификацией и доступом, которая обеспечивает аутентификацию и авторизацию для веб-приложений и сервисов. Он позволяет легко управлять пользователями и поддерживает различные протоколы, такие как OAuth 2.0 и OpenID Connect, обеспечивая единый вход (SSO) для пользователей.

На первый взгляд, это самодостаточная технология, которая сочетает в себе все, что только можно представить. Однако, представьте, вы хотите интегрировать в уже существующий проект данную технологию, но у вас уже есть база данных пользователей, которую вы хотите использовать. Но авторы предусмотрели и этот момент. Как написано в официальной документации:

Вы можете использовать SPI для хранения пользователей (User Storage SPI), чтобы писать расширения для Keycloak, которые подключаются к внешним базам данных пользователей и хранилищам учетных данных. Встроенная поддержка LDAP и Active Directory является примером реализации этого SPI в действии. По умолчанию Keycloak использует свою локальную базу данных для создания, обновления и поиска пользователей, а также для проверки учетных данных. Однако часто у организаций есть существующие внешние проприетарные базы данных пользователей, которые они не могут мигрировать в модель данных Keycloak. В таких ситуациях разработчики приложений могут написать реализации User Storage SPI, чтобы связать внешнее хранилище пользователей и внутреннюю модель объектов пользователей, которую Keycloak использует для входа пользователей и их управления.

То есть Keycloak предоставляет возможность расширять свою функциональность и все, что необходимо сделать, это реализовать ряд интерфейсов. Список этих интерфейсов и их описание, будут рассмотрены ниже, когда мы дойдем до написания основного функционала.

А сейчас предлагаю перейти к написания самого плагина и начнем с создания пустого maven проекта. Я полагаю, что на вашей рабочей машине уже установлены java, maven и настроены все переменные окружения.

mvn archetype:generate -DgroupId=org.example -DartifactId=keycloak-api-plugin -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Рис. 1 Команда для создания пустого maven проекта

после того, как мы создали проект, добавим необходимые зависимости, для этого дополним pom.xml файл:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>org.example</groupId>
  <artifactId>keycloak_api_plugin</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>jar</packaging>

  <name>keycloak_api_plugin</name>
  <url>http://maven.apache.org</url>

  <properties>
    <keycloak.version>26.2.2</keycloak.version>
    <postgresql.version>42.7.3</postgresql.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <repositories>
    <repository>
      <id>keycloak-releases</id>
      <url>https://s01.oss.sonatype.org/content/repositories/releases</url>
    </repository>
  </repositories>

  <dependencies>
    <dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-core</artifactId>
      <version>${keycloak.version}</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.13.4.2</version>
    </dependency>
    <dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-server-spi</artifactId>
      <version>${keycloak.version}</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-server-spi-private</artifactId>
      <version>${keycloak.version}</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-services</artifactId>
      <version>${keycloak.version}</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>javax.ws.rs</groupId>
      <artifactId>javax.ws.rs-api</artifactId>
      <version>2.1</version>
    </dependency>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-annotations</artifactId>
      <version>2.13.3</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.jboss.resteasy</groupId>
      <artifactId>resteasy-client</artifactId>
      <version>3.15.1.Final</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <version>1.18.38</version>
    </dependency>
    <dependency>
      <groupId>org.jboss.resteasy</groupId>
      <artifactId>resteasy-jackson2-provider</artifactId>
      <version>3.15.1.Final</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.mindrot</groupId>
      <artifactId>jbcrypt</artifactId>
      <version>0.4</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.11.0</version>
        <configuration>
          <source>${maven.compiler.source}</source>
          <target>${maven.compiler.target}</target>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>3.5.1</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>shade</goal>
            </goals>
            <configuration>
              <artifactSet>
                <includes>
                  <include>org.mindrot:jbcrypt</include>
                </includes>
              </artifactSet>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Рис. 2 Основные зависимости

В данном POM-файле указаны все необходимые зависимости для интеграции с Keycloak, включая ключевые компоненты, такие как keycloak-core, keycloak-server-spi, keycloak-server-spi-private и keycloak-services, которые обеспечивают функциональность сервера аутентификации. Также присутствуют библиотеки для работы с JSON, такие как jackson-databind и jackson-annotations, а также JAX-RS компоненты, включая resteasy-client и resteasy-jackson2-provider. Все зависимости, относящиеся к Keycloak, используют одну и ту же версию, что упрощает управление и гарантирует совместимость.

После того, как мы определились с зависимостями, зададим базовую структуру.

keycloak-api-plugin
│
├── pom.xml
│
└── src
    └── main
        └── java
            └── org
                └── example
                    └── keycloakapiplugin
                        ├── adapter
                        │   └── UserAdapter.java
                        │
                        ├── api
                        │   └── UsersApiService.java
                        │
                        ├── dto
                        │   └── UserResponseDto.java
                        │
                        ├── entity
                        │   └── UserEntity.java
                        │
                        ├── mapper
                        │   └── UserMapper.java
                        │
                        ├── ExternalUserStorageProvider.java
                        │
                        └── ExternalUserStorageProviderFactory.java

Рис. 3 Структура maven проекта

Когда структура определена, давайте кратко рассмотрим каждый компонент и выясним, за что он отвечает.

ExternalUserStorageProviderFactory - Фабрика провайдера, создающая экземпляры ExternalUserStorageProvider. Определяет имя и описание плагина для Keycloak.
ExternalUserStorageProvider - Основной провайдер, реализующий интерфейсы для работы с пользователями (поиск, аутентификация, запросы). Интегрируется с внешним API для получения данных пользователей.
UserEntity - Модель данных пользователя, содержащая базовые поля (id, username, email и т.д.). Используется для внутреннего представления данных.
UserResponseDto - DTO для получения данных пользователя из внешнего API. Содержит аннотации для работы с JSON.
UsersApiService - Сервис для взаимодействия с внешним API пользователей через HTTP-запросы. Реализует методы поиска пользователей по разным критериям.
UserAdapter - Адаптер, преобразующий UserEntity в модель Keycloak. Реализует методы работы с атрибутами пользователя для Keycloak.

Теперь, когда мы в общих чертах разобрались, какой компонент за что отвечает, предлагаю вернуться к документации, а именно к следующим строкам раздела User Storage SPI.

Когда среда выполнения Keycloak нуждается в поиске пользователя, например, когда пользователь входит в систему, она выполняет ряд шагов для его локализации. Сначала она проверяет, есть ли пользователь в кэше пользователей; если пользователь найден, используется это представление в памяти. Затем система ищет пользователя в локальной базе данных Keycloak. Если пользователь не найден, она проходит через реализации провайдеров
User Storage SPI, чтобы выполнить запрос пользователя, пока один из них не вернет искомого пользователя. Провайдер запрашивает внешнее хранилище пользователей и сопоставляет внешнее представление данных пользователя с метамоделью пользователя Keycloak.
Реализации провайдеров User Storage SPI также могут выполнять сложные запросы по критериям, выполнять операции CRUD с пользователями, проверять и управлять учетными данными или выполнять массовые обновления многих пользователей одновременно. Это зависит от возможностей внешнего хранилища.

Из сказанного выше, можно сделать вывод, что ключевой «фигурой» в данном контексте является пользователь, с него мы и начнем.

Создадим сущность UserEntity с набором необходимых полей, для интеграции с keycloak:


package org.example.keycloakapiplugin.entity;

import lombok.Getter;
import lombok.Setter;

import java.util.Date;

@Getter @Setter
public class UserEntity {
    private String id;
    private String username;
    private String email;
    private String password;
    private Date createdAt;
    private String phone;
}

Рис. 4 Модель пользователя

Эта модель описывает структуру данных, с помощью которой осуществляется взаимодействие Keycloak и внешнего сервиса.

В свою очередь, внешний сервис отдает нам следующую модель данных:

package org.example.keycloakapiplugin.dto;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import lombok.*;

import java.util.Date;

@Getter @Setter
@AllArgsConstructor
@Data
@NoArgsConstructor
@JsonIgnoreProperties(ignoreUnknown = true)
public class UserResponseDto {
    private String id;
    private String username;
    private String email;
    private String password;
    private String phone;
    private Date createdAt;
}

Рис. 5 DTO для передачи данных пользователя

Также нам доступен ряд основных endpoints:

Получить всех пользователей: GET /users - возвращает список пользователей.
Добавить пользователя: POST /users - добавляет нового пользователя.
Получить пользователя по ID: GET /users/{id} - возвращает пользователя по уникальному ID.
Получить пользователя по имени: GET /users/username/{username} - возвращает пользователя по имени.
Получить пользователя по email: GET /users/email/{email} - возвращает пользователя по электронной почте.
Удалить пользователя по ID: DELETE /users/{id} - удаляет пользователя по уникальному ID.

Для преобразования внешних данный в необходимую нам структуру (UserEntity) напишем простой маппер, задача которого преобразовывать один тип объектов в другой.

package org.example.keycloakapiplugin.mapper;


import org.example.keycloakapiplugin.entity.UserEntity;
import org.example.keycloakapiplugin.dto.UserResponseDto;

import java.util.List;
import java.util.stream.Collectors;

public class UserMapper {

    public static UserEntity mapToUserEntity(UserResponseDto dto) {
        if (dto == null) {
            return null;
        }

        UserEntity userEntity = new UserEntity();
        userEntity.setEmail(dto.getEmail());
        userEntity.setPhone(dto.getPhone());
        userEntity.setUsername(dto.getEmail());
        userEntity.setId(dto.getId());
        userEntity.setPassword(dto.getPassword());
        userEntity.setCreatedAt(dto.getCreatedAt());

        return userEntity;
    }

    public static List<UserEntity> mapToUserEntityList(List<UserResponseDto> dtoList) {
        return dtoList.stream().map(UserMapper::mapToUserEntity).collect(Collectors.toUnmodifiableList());
    }
}

Рис. 6 Класс UserMapper преобразует DTO в сущности пользователей и списки

Теперь, когда мы определились с данными, предлагаю написать сам класс, содержащий ряд методов, отвечающих за взаимодействие с внешним апи. Его основная задача - отправка запросов по http и обработка ответов.

package org.example.keycloakapiplugin.mapper.api;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.Data;
import lombok.Getter;
import lombok.Setter;
import org.jboss.logging.Logger;
import org.keycloak.storage.StorageId;
import org.example.keycloakapiplugin.mapper.dto.UserResponseDto;
import org.example.keycloakapiplugin.mapper.entity.UserEntity;
import org.example.keycloakapiplugin.mapper.mapper.UserMapper;

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Collections;
import java.util.List;

public class UsersApiService {

    private static final ObjectMapper objectMapper = new ObjectMapper();
    private static final Logger logger = Logger.getLogger(UsersApiService.class);
    private static final String USER_BY_USERNAME_URL = "http://localhost:8081/users/username/";
    private static final String USER_SERVICE_URL = "http://localhost:8081/users";
    private static final String USER_BY_ID_URL = "http://localhost:8081/users/";
    private static final String USER_BY_EMAIL_URL = "http://localhost:8081/users/email/";

    private final HttpClient httpClient;

    public UsersApiService() {
        this.httpClient = HttpClient.newHttpClient();
    }

    @Data
    @JsonIgnoreProperties(ignoreUnknown = true)
    @Getter
    @Setter
    public static class ApiResponse {
        @JsonIgnoreProperties(ignoreUnknown = true)
        private List<UserResponseDto> data;
    }

    public List<UserEntity> getAllUsers() {

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(USER_SERVICE_URL))
                .header("Accept", "application/json")
                .GET()
                .build();

        try {
            HttpResponse<String> response = this.httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                ApiResponse apiResponse = objectMapper.readValue(response.body(), ApiResponse.class);

                if (apiResponse != null && apiResponse.getData() != null) {
                    logger.infof("Successfully loaded %d users from external service", apiResponse.getData().size());
                    return UserMapper.mapToUserEntityList(apiResponse.getData());
                } else {
                    logger.error("Received empty response from user service");
                }
            } else {
                logger.errorf("Failed to load users from service. Status code: %d, Response: %s",
                        response.statusCode(), response.body());
            }
        } catch (IOException | InterruptedException e) {
            logger.error("Error while fetching users from external service", e);
            if (e instanceof InterruptedException) {
                Thread.currentThread().interrupt();
            }
        }

        return Collections.emptyList();
    }

    public UserEntity getUserByUsername(String username) {
        try {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(USER_BY_USERNAME_URL + username))
                    .header("Accept", "application/json")
                    .GET()
                    .build();

            HttpResponse<String> response = this.httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                UserResponseDto userResponse = objectMapper.readValue(response.body(), UserResponseDto.class);
                return UserMapper.mapToUserEntity(userResponse);
            }
        } catch (IOException | InterruptedException e) {
            logger.error("Error while fetching user by username from external service", e);
            if (e instanceof InterruptedException) {
                Thread.currentThread().interrupt();
            }
        }

        logger.info("could not find getUserByUsername: " + username);
        return null;
    }

    public UserEntity getUserById(String id) {
        logger.info("getUserById: " + id);
        String externalId = StorageId.externalId(id);

        try {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(USER_BY_ID_URL + externalId))
                    .header("Accept", "application/json")
                    .GET()
                    .build();

            HttpResponse<String> response = this.httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                UserResponseDto userResponse = objectMapper.readValue(response.body(), UserResponseDto.class);
                return UserMapper.mapToUserEntity(userResponse);
            } else {
                logger.error("Failed to get user by id. Status code: %d, Response: %s");
            }
        } catch (IOException | InterruptedException e) {
            logger.error("Error while fetching user by id from external service", e);
            if (e instanceof InterruptedException) {
                Thread.currentThread().interrupt();
            }
        }

        logger.info("could not find user by id: " + id);
        return null;
    }

    public UserEntity getUserByEmail(String email) {
        logger.info("getUserByEmail: " + email);

        try {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(USER_BY_EMAIL_URL + email))
                    .header("Accept", "application/json")
                    .GET()
                    .build();

            HttpResponse<String> response = this.httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                UserResponseDto userResponse = objectMapper.readValue(response.body(), UserResponseDto.class);
                return UserMapper.mapToUserEntity(userResponse);
            } else {
                logger.error("Failed to get user by email. Status code: %d, Response: %s");
            }
        } catch (IOException | InterruptedException e) {
            logger.error("Error while fetching user by email from external service", e);
            if (e instanceof InterruptedException) {
                Thread.currentThread().interrupt();
            }
        }
        return null;
    }
}

Рис. 7 Класс UsersApiService обеспечивает взаимодействие с внешним сервисом для получения и управления данными пользователей.

Что мы видим в данном классе? В конструкторе создается экземпляр httpClient для запросов и набор методов для получения пользовательских данных. Рассмотрим один из методов, а именно getAllUsers.

/**
 * Получает список всех пользователей из внешнего сервиса через HTTP-запрос.
 * 
 * @return список сущностей UserEntity или пустой список в случае ошибки
 */
public List<UserEntity> getAllUsers() {
    // Создаем HTTP GET-запрос к указанному URL
    HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(USER_SERVICE_URL))  // URL внешнего сервиса пользователей
            .header("Accept", "application/json")  // Запрашиваем данные в JSON-формате
            .GET()
            .build();

    try {
        // Отправляем запрос и получаем ответ
        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

        // Обрабатываем успешный ответ (HTTP 200)
        if (response.statusCode() == 200) {
            // Преобразуем JSON-тело ответа в объект ApiResponse
            ApiResponse apiResponse = objectMapper.readValue(response.body(), ApiResponse.class);

            // Проверяем наличие данных в ответе
            if (apiResponse != null && apiResponse.getData() != null) {
                logger.infof("Successfully loaded %d users from external service", apiResponse.getData().size());
                // Маппим DTO пользователей на сущности Keycloak
                return UserMapper.mapToUserEntityList(apiResponse.getData());
            } else {
                logger.error("Received empty response from user service");
            }
        } else {
            // Логируем ошибку при неуспешном статусе ответа
            logger.errorf("Failed to load users from service. Status code: %d, Response: %s",
                    response.statusCode(), response.body());
        }
    } catch (IOException e) {
        // Обработка ошибок ввода-вывода
        logger.error("Error while fetching users from external service", e);
    } catch (InterruptedException e) {
        // Особый случай прерывания потока
        logger.error("Request was interrupted", e);
        Thread.currentThread().interrupt();  // Восстанавливаем флаг прерывания
    }

    // Возвращаем пустой список в случае любых ошибок
    return Collections.emptyList();
}

Рис. 8 Метод getAllUsers

Метод getAllUsers формирует запрос с помощью билдера, в котором указываются адрес внешнего сервиса, необходимые заголовки и тип запроса. После отправки запроса, в случае успешного ответа, полученные данные мапятся в сущность UserEntity, и метод возвращает результат. Остальные методы реализованы аналогичным образом, поэтому не будем на них подробно останавливаться.

Далее перейдём к самой интересной части — реализации Provider в Keycloak.
Но прежде чем погрузиться в код, давайте в очередной раз обратимся к документации, а именно к разделу Capability Interfaces и рассмотрим какие интерфейсы нам доступны и зачем они нужны.

Если кратко, то в данном разделе говорится о том, что интерфейс UserStorageProvider (интерфейс в Keycloak, который позволяет разработчикам интегрировать собственные хранилища пользователей в систему управления идентификацией Keycloak) не содержит методов для поиска или управления пользователями. Эти методы определены в других интерфейсах, в зависимости от возможностей внешнего хранилища пользователей. Например, некоторые хранилища могут быть только для чтения и выполнять лишь простые запросы и проверку учетных данных. И вам нужно реализовать только те интерфейсы, которые соответствуют вашим потребностям и возможностям.

И такие интерфейсы нам любезно предоставляют. Рассмотрим их:

org.keycloak.storage.user.UserLookupProvider
Интерфейс, необходимый для получения информации о пользователях из внешнего хранилища. Позволяет осуществлять поиск пользователей по различным критериям, таким как идентификатор, имя пользователя и электронная почта.
org.keycloak.storage.user.UserQueryMethodsProvider
Интерфейс, который определяет методы для выполнения сложных запросов, используемых для поиска одного или нескольких пользователей. Позволяет управлять пользователями через административную консоль, обеспечивая возможность фильтрации и пагинации результатов.
org.keycloak.storage.user.UserCountMethodsProvider
Интерфейс, который предоставляет методы для выполнения запросов на подсчет пользователей. Позволяет получать общее количество пользователей в хранилище, а также количество пользователей по заданным критериям поиска.
org.keycloak.storage.user.UserQueryProvider
Интерфейс, который объединяет функциональность UserQueryMethodsProvider и UserCountMethodsProvider. Обеспечивает возможность выполнения как запросов на поиск пользователей, так и запросов на их подсчет.
org.keycloak.storage.user.UserRegistrationProvider
Интерфейс, который позволяет добавлять и удалять пользователей в внешнем хранилище. Обеспечивает методы для регистрации новых пользователей и удаления существующих.
org.keycloak.storage.user.UserBulkUpdateProvider
Интерфейс, который поддерживает массовое обновление данных нескольких пользователей одновременно. Позволяет выполнять операции обновления для группы пользователей, что упрощает управление учетными записями.
org.keycloak.credential.CredentialInputValidator
Интерфейс, который позволяет проверять различные типы учетных данных, такие как пароли. Обеспечивает методы для валидации введенных пользователем данных при аутентификации.
org.keycloak.credential.CredentialInputUpdater
Интерфейс, который поддерживает обновление различных типов учетных данных. Позволяет изменять или обновлять учетные данные пользователей, такие как пароли или другие методы аутентификации.

Так как нам необходимо взаимодействовать в внешним сервисом, проверять пароли пользователей и иметь возможность просматривать и изменять пользователей из админки, то понадобится реализовать следующий набор интерфейсов:

UserStorageProvider,
UserLookupProvider,
UserQueryProvider,
CredentialInputValidator,
CredentialInputUpdater

Эти интерфейсы предоставляют набор самодокументированных методов, названия которых отражают суть их функционала, например, getUserById или searchForUserStream. Мы не будем углубляться в детали их реализации, лишь отметим, что эти методы используют функции из класса UsersApiService для получения пользователей, а затем, с помощью адаптера, преобразуют полученные данные из внешнего сервиса в UserModel.

package org.example.keycloakapiplugin;

import org.keycloak.component.ComponentModel;
import org.keycloak.credential.CredentialInput;
import org.keycloak.credential.CredentialInputUpdater;
import org.keycloak.credential.CredentialInputValidator;
import org.keycloak.models.GroupModel;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;
import org.keycloak.models.UserModel;
import org.keycloak.models.credential.PasswordCredentialModel;
import org.keycloak.storage.ReadOnlyException;
import org.keycloak.storage.UserStorageProvider;
import org.keycloak.storage.user.UserLookupProvider;
import org.keycloak.storage.user.UserQueryProvider;
import org.mindrot.jbcrypt.BCrypt;
import org.example.keycloakapiplugin.adapter.UserAdapter;
import org.example.keycloakapiplugin.api.UsersApiService;
import org.example.keycloakapiplugin.entity.UserEntity;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.Map;
import java.util.stream.Stream;

public class ExternalUserStorageProvider implements
        UserStorageProvider,
        UserLookupProvider,
        UserQueryProvider,
        CredentialInputValidator,
        CredentialInputUpdater {

    protected KeycloakSession session;
    protected ComponentModel model;
    private static final Logger logger = LoggerFactory.getLogger(ExternalUserStorageProvider.class);


    private final UsersApiService usersApiService;

    public ExternalUserStorageProvider(KeycloakSession session, ComponentModel model) {
        logger.debug("Creating new PropertyFileUserStorageProvider instance");
        this.session = session;
        this.model = model;
        this.usersApiService = new UsersApiService();
    }

    @Override
    public UserModel getUserByUsername(RealmModel realm, String username) {
        logger.info("getUserByUsername: " + username);

        UserEntity userEntity = this.usersApiService.getUserByUsername(username);
        if (userEntity != null) {
            return new UserAdapter(session, realm, model, userEntity);
        } else {
            logger.error("Failed to get user by username. Status code: %d, Response: %s");
        }

        logger.info("could not find getUserByUsername: " + username);
        return null;
    }

    @Override
    public UserModel getUserById(RealmModel realm, String id) {
        UserEntity userEntity = this.usersApiService.getUserById(id);
                if (userEntity != null) {
                    return new UserAdapter(session, realm, model, userEntity);
            } else {
                logger.error("Failed to get user by id. Status code: %d, Response: %s");
            }
        logger.info("could not find user by id: " + id);
        return null;
    }

    @Override
    public UserModel getUserByEmail(RealmModel realm, String email) {
        logger.info("getUserByEmail: " + email);

            UserEntity userEntity = this.usersApiService.getUserByEmail(email);

                if (userEntity != null) {
                    return new UserAdapter(session, realm, model, userEntity);
            } else {
                logger.error("Failed to get user by email. Status code: %d, Response: %s");
            }
            logger.error("Error while fetching user by email from external service");

        return null;
    }

    @Override
    public boolean supportsCredentialType(String credentialType) {
        logger.debug("Checking support for credential type: {}", credentialType);
        boolean supported = PasswordCredentialModel.TYPE.equals(credentialType);
        logger.debug("Credential type {} supported: {}", credentialType, supported);
        return supported;
    }

    @Override
    public boolean isConfiguredFor(RealmModel realm, UserModel user, String credentialType) {
        logger.debug("Checking if credential type {} is configured for user: {}", credentialType, user.getUsername());

        boolean configured = supportsCredentialType(credentialType) &&
                this.usersApiService.getUserByUsername(user.getUsername()) != null;
        logger.debug("Credential type {} configured for user {}: {}", credentialType, user.getUsername(), configured);
        return configured;
    }

    @Override
    public boolean isValid(RealmModel realm, UserModel user, CredentialInput input) {
        logger.debug("Validating credential for user: {}", user.getUsername());

        if (!supportsCredentialType(input.getType())) {
            logger.debug("Credential type not supported: {}", input.getType());
            return false;
        }

        UserEntity userEntity = this.usersApiService.getUserByUsername(user.getUsername());
        if (userEntity == null) {
            logger.debug("User entity not found for username: {}", user.getUsername());
            return false;
        }

        // Получаем хэш пароля из внешней системы
        String storedPasswordHash = userEntity.getPassword();

        String inputPassword = input.getChallengeResponse();

        return BCrypt.checkpw(inputPassword, storedPasswordHash);
    }

    @Override
    public boolean updateCredential(RealmModel realm, UserModel user, CredentialInput input) {
        logger.warn("Attempt to update credential for read-only storage provider, user: {}", user.getUsername());
        throw new ReadOnlyException("User storage is read-only");
    }

    @Override
    public void disableCredentialType(RealmModel realm, UserModel user, String credentialType) {
        logger.debug("disableCredentialType called for user: {}, type: {}", user.getUsername(), credentialType);
        // Read-only - ничего не делаем
    }

    @Override
    public Stream<String> getDisableableCredentialTypesStream(RealmModel realm, UserModel user) {
        logger.debug("getDisableableCredentialTypesStream called for user: {}", user.getUsername());
        return Stream.empty();
    }

    @Override
    public void close() {
        logger.info("Provider closed successfully");
    }

    @Override
    public Stream<UserModel> searchForUserStream(RealmModel realm, Map<String, String> params, Integer firstResult, Integer maxResults) {
        String search = params.get(UserModel.SEARCH);
        String lower = search != null ? search.toLowerCase() : "";

        logger.debug("Searching for users with search term: {}", lower);

        Stream<UserModel> userStream = this.usersApiService.getAllUsers().stream()
                .filter(userEntity -> userEntity.getUsername().toLowerCase().contains(lower) ||
                        userEntity.getEmail().toLowerCase().contains(lower))
                .map(entity -> new UserAdapter(session, realm, model, entity));

        // Применяем постраничный вывод
        if (firstResult != null) {
            userStream = userStream.skip(firstResult);
        }
        if (maxResults != null) {
            userStream = userStream.limit(maxResults);
        }

        return userStream;
    }

    @Override
    public Stream<UserModel> getGroupMembersStream(RealmModel realmModel, GroupModel groupModel, Integer integer, Integer integer1) {
        return Stream.empty();
    }

    @Override
    public Stream<UserModel> searchForUserByUserAttributeStream(RealmModel realmModel, String s, String s1) {
        return Stream.empty();
    }
}

Рис. 9 Класс ExternalUserStorageProvider реализует интерфейсы Keycloak для управления пользователями, взаимодействуя с внешним сервисом

Однако стоит немного подробнее рассказать о UserModel. Что же это за «модель»?

UserModel — один из ключевых компонентов, описывающий модель пользователя в Keycloak. Это основной интерфейс, представляющий пользователя в системе. У внимательного читателя может возникнуть вопрос: как происходит преобразование UserEntity в UserModel, если UserApiService возвращает только UserEntity и ничего не знает о UserModel? И он будет прав.

Сначала необходимо преобразовать данные, для чего мы реализуем UserAdapter. Этот адаптер преобразует сущность UserEntity (из внешней системы) в модель Keycloak (UserModel).

package org.example.keycloakapiplugin.adapter;

import org.jboss.logging.Logger;
import org.keycloak.common.util.MultivaluedHashMap;
import org.keycloak.component.ComponentModel;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;
import org.keycloak.storage.StorageId;
import org.keycloak.storage.adapter.AbstractUserAdapterFederatedStorage;
import org.example.keycloakapiplugin.entity.UserEntity;

import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.stream.Stream;

public class UserAdapter extends AbstractUserAdapterFederatedStorage {
    private static final Logger logger = Logger.getLogger(UserAdapter.class);
    protected UserEntity entity;
    protected String keycloakId;

    public UserAdapter(KeycloakSession session, RealmModel realm, ComponentModel model, UserEntity entity) {
        super(session, realm, model);
        this.entity = entity;
        keycloakId = StorageId.keycloakId(model, entity.getId());
    }

    @Override
    public String getUsername() {
        return entity.getUsername();
    }

    @Override
    public void setUsername(String username) {
        entity.setUsername(username);

    }

    @Override
    public void setEmail(String email) {
        entity.setEmail(email);
    }

    @Override
    public String getEmail() {
        return entity.getEmail();
    }

    @Override
    public String getId() {
        return keycloakId;
    }

    @Override
    public void setSingleAttribute(String name, String value) {
        if (name.equals("phone")) {
            entity.setPhone(value);
        } else {
            super.setSingleAttribute(name, value);
        }
    }

    @Override
    public void removeAttribute(String name) {
        if (name.equals("phone")) {
            entity.setPhone(null);
        } else {
            super.removeAttribute(name);
        }
    }

    @Override
    public void setAttribute(String name, List<String> values) {
        if (name.equals("phone")) {
            entity.setPhone(values.get(0));
        } else {
            super.setAttribute(name, values);
        }
    }

    @Override
    public String getFirstAttribute(String name) {
        if (name.equals("phone")) {
            return entity.getPhone();
        } else {
            return super.getFirstAttribute(name);
        }
    }

    @Override
    public Map<String, List<String>> getAttributes() {
        Map<String, List<String>> attrs = super.getAttributes();
        MultivaluedHashMap<String, String> all = new MultivaluedHashMap<>();
        all.putAll(attrs);
        all.add("phone", entity.getPhone());
        return all;
    }

    @Override
    public Stream<String> getAttributeStream(String name) {
        if (name.equals("phone")) {
            List<String> phone = new LinkedList<>();
            phone.add(entity.getPhone());
            return phone.stream();
        } else {
            return super.getAttributeStream(name);
        }
    }
}

Рис. 10 Класс UserAdapter адаптирует сущность пользователя для Keycloak

Основная задача UserAdapter — интеграция внешних пользователей в Keycloak без изменения их исходного хранилища. Ключевой особенностью адаптера является то, что он наследуется от AbstractUserAdapterFederatedStorage, что предоставляет следующие преимущества:
• Базовая реализация UserModel.
• Хранение атрибутов в Federated Storage (если не переопределены).
• Поддержка многозначных атрибутов (MultivaluedHashMap).
• Обеспечивается автоматическая работа с атрибутами, которые не описаны явно.

Также я хочу обратить особое внимание на процесс генерации keycloakId:

keycloakId = StorageId.keycloakId(model, entity.getId());

Рис. 11 Создание идентификатор Keycloak для пользователя на основе модели

Почему это важно? Keycloak требует уникальный идентификатор в формате

f:{providerId}:{externalId},

Рис. 12 Формат идентификатора пользователя

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

f:my-provider:123.

Рис. 13 Идентификатор пользователя

Этот формат позволяет Keycloak эффективно управлять пользователями, интегрированными из разных источников, и гарантирует, что каждый пользователь будет уникально идентифицирован в системе. Использование такого подхода также упрощает интеграцию и синхронизацию данных между Keycloak и внешними сервисами, минимизируя риск конфликтов идентификаторов и обеспечивая целостность данных.

И финальный штрих, это реализация фабрики.
Фабрика ExternalUserStorageProviderFactory в данном коде выполняет следующие функции:

Создание провайдера: Реализует метод create, который создает экземпляр ExternalUserStorageProvider для работы с внешней базой данных.
Идентификация: Метод getId возвращает уникальный идентификатор провайдера, который используется для его регистрации в Keycloak.
Описание: Метод getHelpText предоставляет текстовое описание провайдера, объясняющее его функциональность и возможности интеграции с внешней базой данных через HTTP-запросы для аутентификации пользователей.

Таким образом, фабрика обеспечивает интеграцию Keycloak с внешними системами хранения пользователей.

Теперь необходимо собрать наш плагин и добавить его в keycloak. Для сборки плагина выполним команду:

mvn clean install

Рис. 14 Команда для сборки плагина

После сборки, в корне проекта в каталоге target появится наш плагин keycloak_api_plugin-1.0-SNAPSHOT.jar

Я буду использовать keycloak на основе docker образа, поэтому набросаем небольшой compose файл и разместим его в корне проекта:

services:
  keycloak_with_plugin:
    image: quay.io/keycloak/keycloak:26.1.3
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"
    volumes:
      - ./target/keycloak_api_plugin-1.0-SNAPSHOT.jar:/opt/keycloak/providers/keycloak_api_plugin-1.0-SNAPSHOT.jar
    command: start-dev

Рис. 15 docker-compose.yml файл

Обращаю ваше внимание, что *keycloak_api_plugin-1.0-SNAPSHOT.jar *должен быть собран заранее.

Теперь, выполняем команду

docker compose up —build

Рис. 16 Команда для запуска docker compose

и после того как проект будет собран, переходим по адресу http://0.0.0.0:8080

вводим логин и пароль *admin admin *

Затем нам необходимо зайти в раздел User Federation и добавить созданный плагин:

Рис. 17 Раздел User Federation в панели администратора

Осталось проверить, добавлены ли пользователи, предоставляемые внешним сервисом. Для этого переходим в раздел Users

Рис. 18 Раздел Users в панели администратора

Рис. 19 Обзор данных конкретного пользователя в панели администратора

Мы убедились, что все пользователи успешно добавлены.

Разлогинимся и зайдем под пользователем из внешней базы данных

Рис. 20 Кабинет пользователя в панели Keycloak

Поздравляю, вы успешно залогинились используя данные пользователя из стороннего сервиса.

Заключение

Это был долгий путь, однако только что мы написали и успешно протестировали плагин для Keycloak, который позволяет использовать внешнее хранилище пользователей через взаимодействие с удаленным сервисом, предоставляющим API для работы с этими пользователями. Это решение уже демонстрирует свою функциональность, но есть множество возможностей для его улучшения.

Вы можете рассмотреть добавление оптимизаций в класс ExternalUserStorageProvider, чтобы повысить его производительность и эффективность. Также стоит доработать логику UserAdapter, внедрив работу с атрибутами пользователей, что позволит расширить функционал и сделать его более гибким. Кроме того, вы можете реализовать дополнительные интерфейсы, предоставляемые Keycloak, что откроет новые горизонты для интеграции и настройки вашего плагина.

Таким образом, у вас есть отличная основа для дальнейшей работы и развития, я надеюсь, что этот проект вдохновит вас на создание еще более мощных и эффективных решений в экосистеме Keycloak.

Если вам понравилась эта статья, то вы знаете что нужно делать — подписывайтесь, ставьте лайки и делайте репосты. Это лучшая поддержка для автора. С вами был Дубовицкий Юрий, автор канала «Ваш код еще не готов, сэр».
А наш код уже готов. До связи!

Creating Your Own ChatGPT on a Free VPS — Simple and Fast!

Юрий — Fri, 25 Apr 2025 09:06:00 +0000

This article is intended for developers with basic knowledge of Python and Docker. We will explore how to deploy a model from Hugging Face on a free VPS server and create an HTTP service to interact with it. I will try to explain the topic in an accessible way and provide practical examples so you can easily apply the knowledge in practice. Even if you don’t plan to delve deep into the details — just follow the instructions, and in 15 minutes, you’ll have a working service.

Friends, free VPS servers are rare, and those that exist often lack the power to deploy neural networks. But the good news is — it’s still possible to deploy a neural network on limited resources! In this guide, I’ll show you practical methods to run models even on modest free servers.

We’ll use Python as the language for the project, along with the FastAPI library to create the API service, and Docker for easy deployment.

What you’ll need:

A HuggingFace account
Your favorite IDE

Start by creating a new Space

Go to Hugging Face Spaces.
Click New Space
Enter a name for your Space
Select Docker (mandatory!) → FastAPI doesn’t work in Gradio templates.
Choose Blank as the Docker template. We’ll define our own template.
Click “Create”
Clone the created repository:

git clone https://huggingface.co/spaces/your_account_name/your_space_name

Define the project structure

Open the cloned repository in your favorite IDE and create the following structure:

/your_project_root
│
├── .gitattributes
├── Dockerfile
├── README.md
├── main.py
└── requirements.txt

Fig.1 Project structure

Define the Dockerfile

FROM python:3.9-slim  
WORKDIR /app  
RUN apt-get update && \  
    apt-get install -y \--no-install-recommends git g++ make && \  
    apt-get clean && \  
    rm -rf /var/lib/apt/lists/\*  
COPY requirements.txt .  
RUN pip install \--no-cache-dir -r requirements.txt  
COPY main.py .  
ENV HF_HOME=/tmp/huggingface-cache  
ENV TOKENIZERS_PARALLELISM=false  
EXPOSE 7860  
CMD ["uvicorn", "main:app", "\--host", "0.0.0.0", "\--port", "7860"]

Fig.2 Dockerfile

The Dockerfile is straightforward, but I’d like to highlight the environment variables:

ENV HF_HOME=/tmp/huggingface-cache:

Sets the HF_HOME environment variable, which Hugging Face libraries use to cache models and tokenizers. Here, the cache will be stored in the temporary directory /tmp.

_ENV TOKENIZERS_PARALLELISM=false:\

Sets TOKENIZERS_PARALLELISM to false to avoid multithreading issues with Hugging Face tokenizers.

Add dependencies to the project

For our app to work, we’ll need the following dependencies:

fastapi==0.109.0  
uvicorn==0.27.0  
torch==2.2.1 \--index-url https://download.pytorch.org/whl/cpu  
transformers==4.40.2  
accelerate==0.29.3  
sentencepiece==0.2.0  
numpy==1.26.4  
protobuf==3.20.3

Fig.3 List of dependencies

Start writing the API service

We’ve chosen TinyLlama/TinyLlama-1.1B-Chat-v1.0 as our model. It fits well within our limitations and offers decent performance. However, you’re free to choose any other model that suits your needs.

from fastapi import FastAPI, HTTPException  
from pydantic import BaseModel  
from transformers import AutoModelForCausalLM, AutoTokenizer, pipeline  
import torch  
import numpy as np  

# Check NumPy version  
assert np.__version__.startswith('1.'), f"Incompatible NumPy version: {np.__version__}"  

app = FastAPI()  

class RequestData(BaseModel):  
    prompt: str  
    max_tokens: int = 50  

MODEL_NAME = "TinyLlama/TinyLlama-1.1B-Chat-v1.0"  

try:  
    # Load the model with explicit device_map  
    tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)  
    model = AutoModelForCausalLM.from_pretrained(  
        MODEL_NAME,  
        torch_dtype=torch.float32,  
        device_map="auto",  
        low_cpu_mem_usage=True  
    )  
    # Create a pipeline without specifying a device  
    generator = pipeline(  
        "text-generation",  
        model=model,  
        tokenizer=tokenizer  
    )  
except Exception as e:  
    print(f"Model loading error: {str(e)}")  
    generator = None  

@app.post("/generate")  
async def generate_text(request: RequestData):  
    if not generator:  
        raise HTTPException(status_code=503, detail="Model not loaded")  
    try:  
        output = generator(  
            request.prompt,  
            max_new_tokens=min(request.max_tokens, 100),  
            do_sample=False,  
            num_beams=1,  
            temperature=0.7,  
        )  
        return {"response": output[0]["generated_text"]}  
    except Exception as e:  
        raise HTTPException(status_code=500, detail=str(e))  

@app.get("/health")  
async def health_check():  
    return {"status": "ok" if generator else "unavailable"}

Fig.4 Main program code

This program demonstrates how to create a service that accepts POST requests at /generate and returns a JSON response. Pay special attention to this block:

output = generator(  
    request.prompt,  
    max_new_tokens=min(request.max_tokens, 100),  
    do_sample=False,  
    num_beams=1,  
    temperature=0.7,  
)

Fig.5 List of options

These parameters are related to text generation settings in libraries like Hugging Face Transformers. For a full description of all options and their values, refer to the official library documentation.

Now, commit and push all the changes.

Once done, the predefined CI/CD will start on the server. Go to:

https://huggingface.co/spaces/your_account_name/your_space_name?logs=container

You can monitor the build process. Once it’s complete, you can send your first request:

curl -X POST "https://your_account_name-your_space_name.hf.space/generate" \  
  -H "Content-Type: application/json" \  
  -d '{"prompt":"What is weather?"}'

Fig.6 curl request

If everything is done correctly, you’ll receive a response like this:

{"response":"What is Docker?\n\nDocker is a tool for creating and deploying Linux-based containers. It allows you to build and deploy applications on Linux."}

Fig.7 Response to the request

Congratulations! You’ve successfully deployed your own neural network on a VPS, and it’s now linked to your account.

Conclusion

In conclusion, it’s worth noting that free Spaces on Hugging Face run on shared CPU/GPU and have several limitations:

Auto-shutdown: If no requests are made to the API for 48 hours, the Space will “sleep.” The first request after this will be slow (about 30 seconds).
Request timeout: Requests taking longer than 1-2 minutes will be automatically terminated.
No GPU: Models run on CPU, which may slow down large requests.

Additional limitations include:

Sleep mode: If your Space receives no traffic for over 48 hours, it enters “sleep” mode. The first request after waking up may take 30-60 seconds.
Resource limits:
- CPU: 1 core, ~1 GB RAM.
- GPU (free): Only for active Spaces, not running 24/7.
- Auto-deletion: Hugging Face may delete Spaces inactive for over 90 days.

How to avoid “sleep mode”?

Regular requests: Send any request once a day (use cron or services like UptimeRobot).
Notifications: Set up monitoring to receive alerts from Hugging Face for errors.

Alternatives

If you need a free and simple solution → Hugging Face Spaces + FastAPI.
If you need 24/7 without “sleeping” → Google Cloud Run or **Fly.io**.
If you need GPU and low latency → Hugging Face Inference Endpoints.

What’s next?

To restrict access to your service, you can add authorization.

To make the model faster on CPU, try quantization — this reduces its size and speeds up requests without significant loss of accuracy.

When the project is ready for production, deploy it using Hugging Face Inference Endpoints or Google Cloud Run — these services simplify scaling and infrastructure management.

If you liked this article, you know what to do — subscribe, like, and share. It’s the best support for the author. This was Yuri Dubovitsky from the channel “Your Code Is Not Ready Yet, Sir”.

But our code is ready. See you next time!

Свой ChatGPT на бесплатном VPS — просто и быстро!

Юрий — Thu, 24 Apr 2025 15:41:39 +0000

Эта статья предназначена для разработчиков с базовым знанием Python и Docker. Мы разберём, как развернуть модель с Hugging Face на бесплатном VPS-сервере и создать HTTP-сервис для работы с ней. Я постараюсь объяснить данную тему доступным языком и предоставить практические примеры, чтобы вы могли легко применить полученные знания на практике. Даже если вы не планируете глубоко разбираться в тонкостях — просто следуйте инструкциям, и через 15 минут у вас будет работающий сервис..

Друзья, бесплатные VPS почти не встречаются, а те, что есть, часто не обеспечивают достаточную мощность для разворачивания нейросетей. Но хорошие новости — развернуть нейросеть на ограниченных ресурсах всё ещё возможно! В этом руководстве я покажу рабочие методы, которые позволяют запускать модели даже на скромных бесплатных серверах.

В качестве языка, на котором будет разрабатываться проект, будем использован python. Также будет использоваться FastAPI библиотека, для создания API сервиса и конечно контейнеризация через Docker для простоты развёртывания.

Что нам потребуется:

Аккаунт на HuggingFace
Ваша любимая IDE

Для начала создайте новый Space

Перейдите в Hugging Face Spaces.
Нажмите "New Space"
Введите название создаваемого пространства
Выберите Docker (обязательно!) → FastAPI не работает в Gradio-шаблонах.
В качестве docker template выберите Blank. Мы будем описывать свой шаблон
Нажмите на кнопку «Создать»
Склонируем созданный репозиторий с проектом

git clone https://huggingface.co/spaces/введите_имя_вашего_аккаунта/введите_имя_вашего_space

Зададим структуру проекта

Откройте склонированный репозиторий в вашей любимой IDE и задайте следующую структуру:

/your_project_root
│
├── .gitattributes
├── Dockerfile
├── README.md
├── main.py
└── requirements.txt

Рис.1 Структура проекта

Опишем Dockerfile

FROM python:3.9-slim

WORKDIR /app

RUN apt-get update && \
apt-get install -y --no-install-recommends git g++ make && \
apt-get clean && \
rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY main.py .

ENV HF_HOME=/tmp/huggingface-cache
ENV TOKENIZERS_PARALLELISM=false

EXPOSE 7860
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

Рис.2 Dockerfile

Dockerfile достаточно понятен, единственное, хочу заострить ваше внимание на переменных окружение

ENV HF_HOME=/tmp/huggingface-cache:

Устанавливает переменную окружения HF_HOME, которая может использоваться библиотеками Hugging Face для хранения кэша моделей и токенизаторов. В данном случае кэш будет храниться во временной директории /tmp.

ENV TOKENIZERS_PARALLELISM=false:

Устанавливает переменную окружения TOKENIZERS_PARALLELISM в значение false, что может помочь избежать проблем с многопоточностью при использовании токенизаторов Hugging Face.

Добавление зависимостей в проект

Для работы нашего приложения нам потребуются следующий зависимости

fastapi==0.109.0
uvicorn==0.27.0
torch==2.2.1 --index-url https://download.pytorch.org/whl/cpu
transformers==4.40.2
accelerate==0.29.3
sentencepiece==0.2.0
numpy==1.26.4
protobuf==3.20.3

Рис.3 Список зависимостей

Приступим к написанию API сервиса

В качестве модели, была выбрана TinyLlama/TinyLlama-1.1B-Chat-v1.0. Эта модель отлично укладывается в наши ограничения, и дает неплохую производительность. Однако, вы вольны выбрать любую другую модель, удовлетворяющую вашим нуждам.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from transformers import AutoModelForCausalLM, AutoTokenizer, pipeline
import torch
import numpy as np

# Проверка версии NumPy
assert np.__version__.startswith('1.'), f"Несовместимая версия NumPy: {np.__version__}"

app = FastAPI()

class RequestData(BaseModel):
    prompt: str
    max_tokens: int = 50

MODEL_NAME = "TinyLlama/TinyLlama-1.1B-Chat-v1.0"

try:
    # Загрузка модели с явным указанием device_map
    tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)
    model = AutoModelForCausalLM.from_pretrained(
        MODEL_NAME,
        torch_dtype=torch.float32,
        device_map="auto",
        low_cpu_mem_usage=True
    )

    # Создаем pipeline без указания device
    generator = pipeline(
        "text-generation",
        model=model,
        tokenizer=tokenizer
    )
except Exception as e:
    print(f"Ошибка загрузки модели: {str(e)}")
    generator = None

@app.post("/generate")
async def generate_text(request: RequestData):
    if not generator:
        raise HTTPException(status_code=503, detail="Модель не загружена")

    try:
        output = generator(
            request.prompt,
            max_new_tokens=min(request.max_tokens, 100),
            do_sample=False,
            num_beams=1,
            temperature=0.7,
        )
        return {"response": output[0]["generated_text"]}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.get("/health")
async def health_check():
    return {"status": "ok" if generator else "unavailable"}

Рис.4 Основной код программы

В данной программе демонстрируется, как создать свой сервис, который принимает POST запросы по адресу /generate и возвращает ответ в виде json. Особое внимание я хочу уделить следущему блоку кода:

        output = generator(
            request.prompt,
            max_new_tokens=min(request.max_tokens, 100),
            do_sample=False,
            num_beams=1,
            temperature=0.7,
        )

Рис.5. Список опций

Все эти параметры относятся к настройкам генерации текста в библиотеках для работы с нейросетями, такими как Hugging Face Transformers. Чтобы найти полное описание всех опций и их значений, вы можете обратиться к официальной документации библиотеки.

Теперь осталось только закомитить и запушить все сделанные изменения изменения.
После того, как вы это сделали, на сервере запустится преднастроенный CI/CD. Перейдите по ссылке https://huggingface.co/spaces/введите_имя_вашего_аккаунта/введите_имя_вашего_spaces?logs=container

И вы можете наблюдать за процессом сборки. После его завершения, вы можете отправить ваш первый запрос:

curl -X POST "https://введите_имя_вашего_аккаунта-введите_имя_вашего_spaces .hf.space/generate"   -H "Content-Type: application/json"   -d '{"prompt":"Что такое погода?"}'

Рис. 6 curl запрос

Если вы все сделали правильно, то получите ответ на ваш запрос следующего содержания:

{"response":"Что такое Docker?\n\nDocker - это инструмент для создания и развертывания на основе Linux контейнеров. Он позволяет создавать и развертывать приложения на основе Linux"

Рис.7 Ответ на запрос

Поздравляем! Вы успешно развернули свою собственную нейросеть на вашем VPS, и теперь она привязана к вашему аккаунту.

Заключение

В заключении, стоит отметить, что бесплатные Spaces на платформе Hugging Face работают на общих CPU/GPU и имеют ряд ограничений:

Автоотключение: Если к API не поступает запросов в течение 48 часов, Space "уснёт". Первый запрос после этого будет медленным (около 30 секунд).
Таймаут запросов: Запросы, выполняющиеся дольше 1-2 минут, будут автоматически завершены.
Отсутствие GPU: Модели работают на CPU, что может замедлить обработку больших запросов.

Дополнительные ограничения включают:

Спящий режим: Если к вашему Space нет обращений более 48 часов, он переходит в "спящий" режим. Первый запрос после пробуждения может занять 30-60 секунд.
Ограничения ресурсов:
- CPU: 1 ядро, ~1 GB RAM.
- GPU (бесплатно): но только для активных Space, не работающих круглосуточно.
Автоудаление: Hugging Face может удалить Space, если он неактивен более 90 дней.

Как избежать "засыпания"?

Регулярные запросы: Отправляйте любой запрос раз в день (можно использовать cron или сервисы, такие как UptimeRobot).
Уведомления: Настройте мониторинг, чтобы получать уведомления от Hugging Face при возникновении ошибок.

Альтернативы

Если вам нужно бесплатное и простое решение → Hugging Face Spaces + FastAPI.
Если требуется 24/7 без "засыпаний" → Google Cloud Run или Fly.io.
Если нужен GPU и низкая задержка → Hugging Face Inference Endpoints.

Что делать дальше?

Если нужно ограничить доступ к вашему сервису, можно добавить авторизацию.
Чтобы модель работала быстрее на CPU, попробуйте применить quantization — это уменьшит её размер и ускорит обработку запросов без серьёзного падения точности.
Когда проект будет готов к продакшену, разверните его с помощью Hugging Face Inference Endpoints или Google Cloud Run — эти сервисы упростят масштабирование и управление инфраструктурой.

Если вам понравилась эта статья, то вы знаете что нужно делать — подписывайтесь, ставьте лайки и делайте репосты. Это лучшая поддержка для автора. С вами был Дубовицкий Юрий, автор канала «Ваш код еще не готов, сэр».
А наш код уже готов. До связи!

Bash + Telegram: Server Monitoring and Instant Notifications

Юрий — Tue, 15 Apr 2025 13:03:21 +0000

This article is written for people with basic Linux knowledge. It explains how to write a bash script for sending instant server activity notifications to Telegram. I'll try to explain the topic in accessible language and provide practical examples so you can easily apply this knowledge.

Telegram has deeply penetrated our lives. It's no longer just a messenger but a vast ecosystem with various channels, apps, stores, and games. We store notes, make purchases, and communicate with friends and colleagues there. So why not use it as a work tool for monitoring server activity?

How it all began. I have a VPS where I test and deploy my pet projects. To protect my server, I installed the standard fail2ban program, and I was unpleasantly surprised when checking the logs to see 500 daily SSH connection attempts. You might say: add keys, disable SSH access, and the problem is solved. However, that's not always convenient, and this article wouldn't exist if I had done that.
So to monitor such activity, I decided to write a small script that would send notifications with statistics about failed and successful login attempts.

What we'll need:

Install fail2ban
Install curl
Create a Telegram bot, get its token and chat_id (the chat identifier where messages will be sent)

First, let's install fail2ban

sudo apt update
sudo apt install fail2ban

Fig. 1 Installing fail2ban

Note that after installation, Fail2ban isn't configured by default for active protection. However, it includes some preset configurations and filters you can use. For more details, refer to the official website.

Create an empty file in the directory

touch ~/usr/local/bin/telegram_notification.sh

Fig. 2 Command to create an empty file

Let's start writing the script

#!/bin/bash 

# Replace with your token and chat_id 
TOKEN="7904202989:AAHuqZwKD-Piyv62DeeJYlId5d7rxjtWRBk" 
CHAT_ID="5524715173" 

# Function to send Telegram messages 
send_telegram_message() { 
   local message="$1" 
   curl -s -X POST "https://api.telegram.org/bot$TOKEN/sendMessage" \ 
       -d "chat_id=$CHAT_ID" \ 
       -d "text=$message" \ 
       -d "parse_mode=HTML" 
} 

# Variable to track time since last failed attempt/ban notification 
last_failed_time=0 
# Time period (1 day) after which to send notifications about failed attempts
track_time_range=86400

# Function to check and send notifications about failed attempts and bans 
check_failed_attempts() { 
   current_time=$(date +%s) 
   # Check if more than a day has passed since last notification 
   if (( current_time - last_failed_time >= track_time_range )); then 
       # Get info about failed attempts and bans in the last 24 hours 
       failed_attempts=$(grep "Failed password" /var/log/auth.log | wc -l) 
       bans=$(grep "Ban" /var/log/fail2ban.log | wc -l) 

       # Compose the message 
       message=" Statistics for last 24 hours:\n" 
       message+=" Failed login attempts: $failed_attempts\n" 
       message+=" Banned IPs: $bans" 

       # Send the message 
       send_telegram_message "$message" 
       last_failed_time=$current_time 
   fi 
} 

# Monitoring authentication and Fail2Ban logs 
tail -F /var/log/auth.log /var/log/fail2ban.log | while read line; do 
   # Check for successful logins 
   if echo "$line" | grep "Accepted password" &> /dev/null; then 
       send_telegram_message "✅ Successful login: $line" 
   fi 

   # Check for failed attempts 
   if echo "$line" | grep "Failed password" &> /dev/null; then 
       check_failed_attempts 
   fi 

   # Check for banned IPs 
   if echo "$line" | grep "Ban" &> /dev/null; then 
       check_failed_attempts 
   fi 
done

Fig. 3 Script responsible for sending statistics with notifications

This script is quite understandable. Let's focus on a few key points, particularly:

tail -F /var/log/auth.log /var/log/fail2ban.log | while read line;

Fig. 4 The tail command displaying the last lines of a text file

The tail -F command tracks all changes in log files and pipes (|) them into a while loop where changes are written to the 'line' variable. The loop then checks conditions and compiles statistics on failed login attempts, while immediately sending notifications to Telegram about successful attempts.

Now we just need to run the script. For simplicity, we'll use nohup. This command lets you run processes while ignoring the HUP (hangup) signal. This is useful when you want a process to keep running even after logging out or closing the terminal. However, a better alternative would be using systemd or supervisor, but that's beyond this article's scope.

To run the command with nohup, simply add nohup before the command:

nohup telegram_notification.sh &

Fig. 5 The nohup command

Now let's check if our script is running:

ps aux |  telegram_notification*

Fig. 6 Displaying information about the running process

The terminal should show the running process and its PID. Congratulations, you'll now receive notifications about successful and failed SSH login attempts on your server.

Conclusion:

In conclusion, I should note there are other notification methods. For example, you could use jail and action in fail2ban itself with ready-made templates (mail, Telegram, Slack, etc.). However, I prefer using scripts - this provides independence from tools and allows implementing any logic: from monitoring SSH connections to controlling system services, network traffic, and changes in critical files.

If you liked this article, you know what to do - subscribe, like, and repost. It's the best support for the author. This was Yury Dubovitsky from Your Code Isn't Ready Yet, Sir.
Our code is ready now. See you next time!

Bash + Telegram: мониторинг сервера и мгновенные уведомления

Юрий — Tue, 15 Apr 2025 10:06:39 +0000

Данная статья написана для людей, имеющих базовые знания по работе с Linux. В этой статье будет рассказано о том, как написать bash-скрипт для отправки мгновенных уведомлений об активности на сервере в Telegram. Я постараюсь объяснить данную тему доступным языком и предоставить практические примеры, чтобы вы могли легко применить полученные знания на практике.

Telegram глубоко проник в нашу жизнь. Это уже не просто мессенджер, а огромная экосистема, с различными каналами, приложениями, магазинами и играми. Мы храним в нем заметки, совершаем покупки, общаемся с друзьями и коллегами. Так почему бы не использовать его как рабочий инструмент, для отслеживания активности на нашем сервере?

С чего все началось. У меня есть VPS, где я тестирую и разворачиваю свои pet-проекты. Для защиты своего сервера установил стандартную программу fail2ban и как же я был неприятно удивлен, посмотрев логи, что каждый день, делается до 500 попыток подключиться ко мне по ssh. Читатель может сказать, добавь ключи, отключи доступ по ssh и проблема решена. Однако, это не всегда удобно, да и данной статьи бы не было, если бы я все это сделал.
И для мониторинга такой активности было решено написать небольшой скрипт, который будет посылать уведомления со статистикой о неудачных и удачных попытках входа.

Что нам потребуется:

Установить fail2ban
Установить curl
Создать telegram бота, получить его токен и chat_id (это идентификатор чата, куда нам будут приходить сообщения)

Для начала установим fail2ban и curl

sudo apt update
sudo apt install fail2ban curl

Рис. 1 Команды для установки fail2ban и curl

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

Создадим пустой файл в каталоге

touch ~/usr/local/bin/telegram_notification.sh

Рис. 2 Команда для создания пустого файла

Приступим к написанию самого скрипта

#!/bin/bash 

# Замените на ваш токен и chat_id 
TOKEN="123456789:ABCDEFGHIJKLMN_OPQRSTUVWXYZ123456"
CHAT_ID="987654321"

# Функция для отправки сообщения в Telegram 
send_telegram_message() { 
   local message="$1" 
   curl -s -X POST "https://api.telegram.org/bot$TOKEN/sendMessage" \ 
       -d "chat_id=$CHAT_ID" \ 
       -d "text=$message" \ 
       -d "parse_mode=HTML" 
} 

# Переменная для отслеживания времени последнего уведомления о неудачных попытках и блокировках 
last_failed_time=0 
# Время (1 день) через которое следует посылать уведомления о неудачных попытках входа
track_time_range=86400

# Функция для проверки и отправки уведомлений о неудачных попытках и блокировках 
check_failed_attempts() { 
   current_time=$(date +%s) 
   # Проверка, прошло ли больше суток с последнего уведомления 
   if (( current_time - last_failed_time >= track_time_range )); then 
       # Получаем информацию о неудачных попытках и блокировках за последние сутки 
       failed_attempts=$(grep "Failed password" /var/log/auth.log | wc -l) 
       bans=$(grep "Ban" /var/log/fail2ban.log | wc -l) 

       # Формируем сообщение 
       message=" Статистика за последние сутки:\n" 
       message+=" Неудачных попыток входа: $failed_attempts\n" 
       message+=" Заблокированных IP: $bans" 

       # Отправляем сообщение 
       send_telegram_message "$message" 
       last_failed_time=$current_time 
   fi 
} 

# Отслеживание логов аутентификации и Fail2Ban 
tail -F /var/log/auth.log /var/log/fail2ban.log | while read line; do 
   # Проверка на успешные попытки входа 
   if echo "$line" | grep "Accepted password" &> /dev/null; then 
       send_telegram_message "✅ Успешный вход: $line" 
   fi 

   # Проверка на неудачные попытки входа 
   if echo "$line" | grep "Failed password" &> /dev/null; then 
       check_failed_attempts 
   fi 

   # Проверка на заблокированные IP-адреса 
   if echo "$line" | grep "Ban" &> /dev/null; then 
       check_failed_attempts 
   fi 
done

Рис. 3 Скрипт, отвечающий за отправку статистики с уведомлениями

Данный скрипт, достаточно понятен. Стоит только заострить свое внимание на нескольких моментах, а именно на

tail -F /var/log/auth.log /var/log/fail2ban.log | while read line;

Рис. 4 Команда tail отвечающая за отображения последних строк текстового файла

Команда tail -F отслеживает все изменения в log файлах и через pipe (|) передает их в цикл while, где изменения записываются в переменную line. В дальнейшем, цикл пробегается по условиям и формирует статистику неудачных попыток входа, а в случае удачной попытки, сообщение об этом немедленно отправляется в телеграмм.

Теперь осталось запустить данный скрипт. Для простоты, воспользуемся командой nohup. Эта команда позволяет запускать процессы, игнорируя сигнал HUP (hangup). Это полезно, когда вы хотите, чтобы процесс продолжал работать даже после выхода из системы или закрытия терминала. Однако, лучшей альтернативой будет использование systemd или supervisor, но эта статья не об этом.

Чтобы запустить команду с использованием nohup, просто добавьте nohup перед командой. Например:

nohup telegram_notification.sh &

Рис. 5 Команда nohup

Теперь проверим, работает ли наш скрипт

ps aux |  telegram_notification*

Рис. 6 Отображения информации о запущенном процессе

В окне терминала, должен отобразиться запущенный процесс и его PID. Поздравляю, теперь вы будете получать уведомления о удачных и неудачных попытках входа по ssh на ваше сервер.

Заключение:

В заключение хочу отметить, что существуют и другие варианты подключения уведомлений. Например это можно сделать через jail и action в самом fail2ban c уже готовыми шаблонами (mail, telegram, slack и др.). Однако я предпочитаю использовать скрипты — это обеспечивает независимость от инструмента и позволяет реализовать любую логику: от мониторинга SSH-подключений до контроля системных служб, сетевого трафика и изменений в критически важных файлах.