Улучшение документации

2026-01-08 15:13:07 +03:00
parent b111d5136a
commit 771ec55e4e
2 changed files with 220 additions and 15 deletions
@@ -1,7 +1,35 @@
-# nifi-docker
+> **Последнее обновление:** 2026-01-08 | **Версия NiFi:** 1.x.x

 Учебный стенд для знакомства с Apache NiFi и Kafka: NiFi + NiFi Registry + Postgres + Kafka + Kafka UI.

+## Содержание
+
+- [Содержание](#содержание)
+- [Быстрый старт](#быстрый-старт)
+  - [Что сохраняется между перезапусками](#что-сохраняется-между-перезапусками)
+- [Адреса и доступы](#адреса-и-доступы)
+- [Важно про адреса (внутри Docker и с хоста)](#важно-про-адреса-внутри-docker-и-с-хоста)
+- [PostgreSQL](#postgresql)
+  - [Подключение через DBeaver (удобнее всего)](#подключение-через-dbeaver-удобнее-всего)
+  - [Через консоль (если нужно)](#через-консоль-если-нужно)
+- [Kafka](#kafka)
+  - [Работа с Kafka](#работа-с-kafka)
+    - [Базовые команды CLI (опционально)](#базовые-команды-cli-опционально)
+- [Примеры flow (шаблоны)](#примеры-flow-шаблоны)
+  - [Памятка: как импортировать Process Group / Flow в NiFi](#памятка-как-импортировать-process-group--flow-в-nifi)
+- [Shared folder (общая папка)](#shared-folder-общая-папка)
+- [Полезные команды](#полезные-команды)
+- [Проверка работоспособности](#проверка-работоспособности)
+  - [Checklist](#checklist)
+  - [Проверка flow](#проверка-flow)
+- [Если что-то не работает](#если-что-то-не-работает)
+  - [Проблемы с запуском контейнеров](#проблемы-с-запуском-контейнеров)
+  - [Проблемы с подключением в NiFi](#проблемы-с-подключением-в-nifi)
+  - [Проблемы с Kafka](#проблемы-с-kafka)
+  - [Проблемы с Postgres](#проблемы-с-postgres)
+  - [Проблемы с правами доступа](#проблемы-с-правами-доступа)
+  - [Дополнительная диагностика](#дополнительная-диагностика)
+
 ## Быстрый старт
 ```sh
 docker compose up -d
@@ -40,7 +68,8 @@ docker compose down -v
 Примечание: в этой конфигурации Kafka-сообщения/топики не сохраняются между `docker compose down` → `up` (чтобы не копить дисковое пространство). Между `stop` → `start` Kafka сохраняется. Пример подключения тома (volume) для Kafka есть в `docker-compose.yml`.

 ## Адреса и доступы
- NiFi: http://localhost:18443/nifi/ (логин `admin`, пароль `Password123456`)
+- NiFi: http://localhost:18443/nifi/
+  > 💡 **Примечание:** В текущей конфигурации аутентификация отключена для упрощения обучения. Логин и пароль не требуются.
 - NiFi docs: https://nifi.apache.org/documentation/
 - Registry: http://localhost:18080/nifi-registry
 - Registry docs: https://nifi.apache.org/docs/nifi-registry-docs/
@@ -48,7 +77,8 @@ docker compose down -v
 - Kafka UI docs: https://docs.kafka-ui.provectus.io/

 ## Важно про адреса (внутри Docker и с хоста)
-Если вы настраиваете подключение *в NiFi*, то `localhost` почти всегда будет неправильным (NiFi живёт в контейнере).
+
+> ⚠️ **Критически важно:** Если вы настраиваете подключение *в NiFi*, то `localhost` почти всегда будет неправильным (NiFi живёт в контейнере).

 Используйте имена сервисов из `docker-compose.yml`:
 - Postgres (из NiFi): `jdbc:postgresql://postgres:5432/app`
@@ -96,6 +126,40 @@ select * from ods.samplekafka2postgres order by id desc limit 10;
 - С локальной машины (например, для консольных утилит): `localhost:9092`
 - Из NiFi (внутри Docker): `kafka:29092`

+### Работа с Kafka
+
+> 💡 **Рекомендация:** Для большинства задач используйте **Kafka UI** (http://localhost:8082/) — это удобный и наглядный веб-интерфейс для просмотра топиков, сообщений и consumer groups.
+
+**Kafka CLI** (командная строка) полезен для:
+- Автоматизации и скриптов
+- Продвинутых операций (например, изменение конфигурации топиков)
+- Быстрой проверки без браузера
+
+#### Базовые команды CLI (опционально)
+
+Все команды выполняются через `docker compose exec kafka`:
+
+**Чтение сообщений:**
+```sh
+docker compose exec kafka kafka-console-consumer.sh \
+  --bootstrap-server localhost:9092 \
+  --topic Sample2Kafka \
+  --from-beginning
+```
+
+**Запись сообщений:**
+```sh
+docker compose exec kafka kafka-console-producer.sh \
+  --bootstrap-server localhost:9092 \
+  --topic Sample2Kafka
+```
+Пример JSON-сообщения: `{"dttm": 1704698992000, "txt": "Тестовое сообщение"}`
+
+**Просмотр списка топиков:**
+```sh
+docker compose exec kafka kafka-topics.sh --bootstrap-server localhost:9092 --list
+```
+
 ## Примеры flow (шаблоны)
 Короткий гайд для менти по JSON-версии потоков: `MENTEE_GUIDE_JSON_FLOWS.md`.

@@ -138,7 +202,99 @@ docker compose exec postgres bash

 Для доступа из NiFi к сервисам на локальной машине используйте `host.docker.internal` вместо `localhost`.

+## Проверка работоспособности
+
+После запуска стенда проверьте, что все компоненты работают корректно:
+
+### Checklist
+
+- [ ] **NiFi UI открывается** по адресу http://localhost:18443/nifi/ (аутентификация не требуется)
+- [ ] **Kafka UI показывает кластер** по адресу http://localhost:8082/
+- [ ] **В Kafka UI виден topic `Sample2Kafka`** (если flow уже запущен)
+- [ ] **Postgres отвечает на подключение** через DBeaver или консоль:
+  ```sh
+  docker compose exec -it postgres bash -c "export PGPASSWORD=postgres; psql -U postgres -d app -c 'SELECT version();'"
+  ```
+- [ ] **Контейнеры запущены** (все в статусе `Up`):
+  ```sh
+  docker compose ps
+  ```
+
+### Проверка flow
+
+Если вы импортировали и запустили примеры flow:
+- [ ] В NiFi процессоры запущены (зелёный индикатор)
+- [ ] В Kafka UI в topic `Sample2Kafka` появляются сообщения
+- [ ] В Postgres таблица `ods.samplekafka2postgres` заполняется данными:
+  ```sh
+  docker compose exec -it postgres bash -c "export PGPASSWORD=postgres; psql -U postgres -d app -c 'SELECT COUNT(*) FROM ods.samplekafka2postgres;'"
+  ```
+
 ## Если что-то не работает
- NiFi может запускаться 1–3 минуты; смотрите `docker compose logs -f nifi`.
- Если процессор в NiFi не подключается к Kafka/Postgres, проверьте, что используете адреса “из NiFi” (см. раздел про Docker).
- Если порты заняты, измените проброс портов в `docker-compose.yml`.
+
+### Проблемы с запуском контейнеров
+
+**Симптом:** Контейнеры не запускаются или сразу падают.
+- **Решение:** Проверьте логи:
+  ```sh
+  docker compose logs -f nifi
+  docker compose logs -f kafka
+  docker compose logs -f postgres
+  ```
+- NiFi может запускаться 1–3 минуты — это нормально.
+
+**Симптом:** Ошибка "port is already allocated".
+- **Решение:** Порты заняты. Измените проброс портов в `docker-compose.yml` или остановите процессы, использующие эти порты.
+
+### Проблемы с подключением в NiFi
+
+**Симптом:** Процессор в NiFi не подключается к Kafka или Postgres.
+- **Решение:** Проверьте, что используете адреса "из NiFi" (см. раздел [Важно про адреса](#важно-про-адреса-внутри-docker-и-с-хоста)):
+  - Postgres: `postgres:5432` (не `localhost:5437`)
+  - Kafka: `kafka:29092` (не `localhost:9092`)
+
+**Симптом:** Controller Services выключены.
+- **Решение:** Внутри process group откройте `Controller Services` → выберите сервисы → `Enable`.
+
+### Проблемы с Kafka
+
+**Симптом:** Сообщения не появляются в Kafka UI.
+- **Решение:**
+  - Проверьте, что процессор `PublishKafkaRecord_2_6` запущен и растёт счётчик "out"
+  - Убедитесь, что topic `Sample2Kafka` существует (создаётся автоматически при первой записи)
+  - Проверьте логи Kafka: `docker compose logs -f kafka`
+
+**Симптом:** Consumer в NiFi не читает сообщения.
+- **Решение:**
+  - Проверьте, что используете правильный `bootstrap.servers`: `kafka:29092`
+  - Убедитесь, что consumer group не зафиксирован на другом offset (можно создать новый consumer group)
+
+### Проблемы с Postgres
+
+**Симптом:** Ошибка при вставке данных в Postgres.
+- **Решение:**
+  - Проверьте, что таблицы существуют: выполните SQL-скрипт `SampleKafka2Postgres.sql`
+  - Убедитесь, что JDBC-драйвер подключён: `/opt/nifi/nifi-current/drivers/postgresql-42.7.4.jar`
+  - Проверьте параметры подключения: `jdbc:postgresql://postgres:5432/app`, пользователь `postgres`, пароль `postgres`
+
+**Симптом:** Таблица пустая, хотя flow работает.
+- **Решение:**
+  - Проверьте, что сообщения проходят фильтр `QueryRecord` (relationship `GOOD_DATE`)
+  - Посмотрите логи процессора `PutDatabaseRecord` на наличие ошибок
+  - Убедитесь, что процедура `ods.load_samplekafka2postgres()` существует
+
+### Проблемы с правами доступа
+
+**Симптом:** Ошибки доступа к `shared-folder/`.
+- **Решение:** Исправьте права:
+  ```sh
+  sudo chown -R $USER shared-folder
+  ```
+
+### Дополнительная диагностика
+
+Если проблема не решена:
+1. Посмотрите логи всех сервисов: `docker compose logs`
+2. Перезапустите проблемный контейнер: `docker compose restart nifi` (или другой сервис)
+3. Попробуйте полный сброс: `docker compose down -v && docker compose up -d`
+   > ⚠️ **Внимание:** Это удалит все данные из Postgres, NiFi и Registry.