build(photo-ai): loopback-порт 8081 и раздел про фото-ИИ в README

photo-ai не имел ports, а хостовый 8080 уже занят text-corrector: ручные
проверки из плана попадали не туда. Проброшено 127.0.0.1:8081:8080 — только
loopback, наружу ничего не публикуется.

Заодно исправлен рассинхрон .env.example: там стоял пустой PHOTO_AI_URL с
комментарием «пусто = контейнер photo-ai», из-за чего копирование примера
молча выключало фото-ИИ (в compose дефолт http://photo-ai:8080). Теперь
дефолт указан явно, пустое значение описано как «выключить сервис».

.env.example

@@ -36,8 +36,13 @@ CLOUDFLARE_TUNNEL_URL=http://app:3003
 # туннеля без VPN (сек). Если VPN-провайдер не отвечает — сайт всё равно поднимется.
 WG_HANDSHAKE_TIMEOUT=60
 
-# ИИ-улучшение фото (Real-ESRGAN), пусто = контейнер photo-ai
-PHOTO_AI_URL=
+# === ИИ-улучшение фото (контейнер photo-ai, Real-ESRGAN) ===
+# По умолчанию фото-ИИ включено: сервис photo-ai поднимается вместе со стеком
+# и работает на CPU. Оставьте значение пустым, чтобы выключить сервис —
+# тогда кнопка «🤖 ИИ» скрыта, а /api/entries/:id/photo/enhance-ai отвечает 503.
+# Ручные проверки сервиса идут по loopback-порту 127.0.0.1:8081 (наружу не публикуется):
+#   curl http://127.0.0.1:8081/health
+PHOTO_AI_URL=http://photo-ai:8080
 PHOTO_AI_MAX_PIXELS=4000000
 # Сколько раз воркер повторит задание, если photo-ai недоступен (503/обрыв сети),
 # не увеличивая attempts; после исчерпания — одна честная ошибка в задании.

README.md

@@ -119,6 +119,32 @@ REDIS_PASSWORD=случайная-длинная-строка
 
 Имя узла Tailscale задаётся в `docker-compose.yml` (`tailscale.hostname`, по умолчанию `whatido`).
 
+## ИИ-улучшение фото (photo-ai)
+
+Сервис `photo-ai` (Real-ESRGAN) поднимается вместе со стеком и **включён по умолчанию**: `PHOTO_AI_URL`
+в `docker-compose.yml` равен `http://photo-ai:8080`, кнопка «🤖 ИИ» активна, а задания обрабатывает
+фоновый воркер. Работает на CPU, GPU не требуется.
+
+| Переменная | По умолчанию | Назначение |
+|---|---|---|
+| `PHOTO_AI_URL` | `http://photo-ai:8080` | Адрес сервиса. **Пустое значение = сервис выключен**: кнопка «🤖 ИИ» скрыта, `POST /api/entries/:id/photo/enhance-ai` отвечает `503`, приложение при этом полностью работоспособно |
+| `PHOTO_AI_MAX_PIXELS` | `4000000` | Максимум пикселей входного изображения, вход большего размера уменьшается |
+| `PHOTO_AI_SOFT_MAX_RETRIES` | `60` | Сколько раз задание ждёт недоступный сервис, не увеличивая счётчик попыток; после исчерпания — честная ошибка |
+| `PHOTO_AI_SOFT_BACKOFF_MS` | `10000` | Первая пауза перед мягким повтором |
+| `PHOTO_AI_SOFT_BACKOFF_MAX_MS` | `300000` | Потолок паузы (задержка растёт вдвое) |
+
+Порт `8081` на `127.0.0.1` — только loopback хоста, наружу ничего не публикуется (хостовый `8080` занят
+`text-corrector`). Ручные проверки сервиса:
+
+```bash
+curl http://127.0.0.1:8081/health
+curl -F "image=@photo.jpg" -F "scale=2" http://127.0.0.1:8081/enhance -o out.jpg
+```
+
+Состояние сервиса и воркера — в `GET /api/photo-jobs/status` (admin): `service` отдаёт health фото-сервиса
+(`configured`, `reachable`, `latency_ms`, `error`), `ai_configured` — задан ли `PHOTO_AI_URL`,
+`worker` — состояние очереди и конфигурация воркера.
+
 ## Публичный доступ через Tailscale
 
 Стек не требует внешнего IP и проброса портов: контейнер `tailscale` запускается с `network_mode: host`, входит в вашу tailnet-сеть и через **Serve** открывает приложение внутри tailnet, а через **Funnel** — в публичном интернете.

docker-compose.yml

@@ -191,6 +191,8 @@ services:
 
   # ИИ-улучшение фотографий (Real-ESRGAN x2, CPU).
   # Поднимается вместе со стеком; если не нужен — PHOTO_AI_URL пустой в .env.
+  # Порт 8081 пробрасывается только на loopback хоста — наружу ничего не публикуется,
+  # хостовый 8080 уже занят text-corrector. Ручные проверки: curl http://127.0.0.1:8081/health
   photo-ai:
     build: ./photo-ai
     container_name: photo-ai
@@ -201,6 +203,8 @@ services:
       TZ: Europe/Moscow
     volumes:
       - photo-ai-models:/models
+    ports:
+      - "127.0.0.1:8081:8080"
 
 
 volumes: