Матрица субсидирования банков — веб-приложение

Flask-приложение с Docker-деплоем. Замена настольного GUI для серверного использования.

Требования

• Docker Engine ≥ 24
• Docker Compose plugin ≥ 2.20 (или docker-compose ≥ 1.29)
• Минимум 1 ГБ RAM на контейнер (рекомендуется 2 ГБ — OCR тяжёлый)

---

Быстрый старт

# 1. Перейдите в директорию с приложением
cd web_app/

# 2. (Опционально) Создайте .env из шаблона
cp .env.example .env
# Отредактируйте .env при необходимости

# 3. Соберите и запустите
docker compose up --build -d

# 4. Откройте в браузере
# http://localhost:5000

Первая сборка образа занимает 3–7 минут (установка Tesseract + Python-зависимостей).

---

Конфигурация

Параметры задаются через переменные окружения в файле .env:

Переменная	По умолчанию	Описание
APP_PORT	5000	Внешний порт для доступа к приложению
GUNICORN_LOG_LEVEL	info	Уровень логирования (debug/info/warning)

---

Использование

1. Откройте http://<server-ip>:5000
2. Перетащите или выберите файлы банков (PDF, XLSX, DOCX)
3. При необходимости скорректируйте параметры в разделе ⚙️
4. Нажмите ▶ Запустить — в журнале появятся строки парсинга в реальном времени
5. По завершении нажмите 📥 Скачать Excel

Поддерживаемые файлы банков

Банк	Формат
Дом.РФ	DOCX
МКБ	XLSX
Альфа-Банк	XLSX
Совкомбанк	XLSX
ВТБ	PDF
Сбербанк	PDF
ТКБ	XLSX, PDF
Урал ФД	PDF

---

Управление контейнером

# Посмотреть статус
docker compose ps

# Просмотр логов
docker compose logs -f

# Остановить
docker compose down

# Пересобрать после обновления кода
docker compose up --build -d

# Перезапустить без пересборки
docker compose restart

---

Локальный deploy через Forgejo

В проекте есть локальный helper, который делает обычный безопасный цикл: git add → git commit → git push origin <текущая ветка>. После push Forgejo Actions сам поставит workflow в очередь, а уже запущенный Forgejo Runner заберёт job. Скрипт не подключается к серверу по SSH, не запускает runner вручную и не делает force push.

./scripts/deploy-forgejo.sh "Update Docker workflow"

Для релиза передайте тег. Скрипт создаст annotated git tag после commit/push и отправит его в origin без force:

./scripts/deploy-forgejo.sh --release "Release current build"
./scripts/deploy-forgejo.sh --release v1.2.3 "Release v1.2.3"
./scripts/deploy-forgejo.sh --release-tag v1.2.3 "Release v1.2.3"
./scripts/deploy-forgejo.sh release "Release current build"
./scripts/deploy-forgejo.sh release v1.2.3 "Release v1.2.3"

Если --release/release вызван без явного тега, скрипт создаёт тег по локальной дате и времени в формате YYYY.MM.DD-HHMM, например 2026.05.28-1145. Если такой тег уже есть локально или в origin, скрипт добавит числовой суффикс.

То же через npm:

npm run deploy:forgejo -- "Update Docker workflow"
npm run deploy:forgejo -- --release "Release current build"

Скрипт остановится, если commit message не передан, если команда запущена не из git-репозитория, если нет изменений и не передан release tag, если release tag уже существует локально, или если в staged changes попали защищённые файлы: .env, секреты, node_modules, build/cache директории, ключи и локальные .DS_Store, __pycache__/.pyc.

Перед commit/push скрипт локально запускает:

.venv311/bin/python -m unittest discover -s tests
.venv311/bin/python -m py_compile app.py build_subsidy_matrix_web.py
node --check static/ur_common.js

Если нужно отправить изменения без локальных проверок, добавьте --skip-checks. Forgejo workflow всё равно выполнит эти проверки перед сборкой Docker image.

Для текущего Forgejo workflow нужны secrets:

Secret	Для чего нужен
REGISTRY_USER	Логин в Forgejo Container Registry
REGISTRY_PASSWORD	Пароль или token для docker login

Релизный workflow запускается на git tags 1.2.3/YYYY.MM.DD-HHMM и v*, создаёт Forgejo Release, собирает Docker image и публикует теги:

forgejo.shafraaan.freeddns.org/nikita/ipoteka:<git-tag>
forgejo.shafraaan.freeddns.org/nikita/ipoteka:<git-sha>
forgejo.shafraaan.freeddns.org/nikita/ipoteka:latest

Результат сборки смотрите в Forgejo: Repository → Actions.

На сервере обновление контейнера выполняется стандартно:

docker compose pull
docker compose up -d

Важно: docker compose pull работает, когда серверный docker-compose.yml использует image из Forgejo Container Registry. Если compose-файл собирает образ локально через build: ., сервер будет пересобирать контейнер из локального кода.

---

Синхронизация Forgejo → GitLab из Windows

Для синхронизации одного Git-репозитория в другой на Windows есть .bat helper, не требующий PowerShell execution policy:

scripts\sync-git-repos.bat ^
  --source-url "https://forgejo.example.com/nikita/ipoteka.git" ^
  --destination-url "https://gitlab.example.local/group/ipoteka.git"

По умолчанию скрипт пушит branches и tags без force. Для точного зеркала, которое может перезаписать или удалить refs во втором репозитории, используйте:

scripts\sync-git-repos.bat ^
  --source-url "https://forgejo.example.com/nikita/ipoteka.git" ^
  --destination-url "https://gitlab.example.local/group/ipoteka.git" ^
  --mirror

Рекомендуется хранить логины/токены в Git Credential Manager, а не вставлять их в URL. Если используются Git LFS-объекты, установите git-lfs; иначе добавьте --skip-lfs.

---

Работа за обратным прокси (Nginx)

Если вы хотите выставить приложение на 80/443 через Nginx, добавьте в конфиг сервера:

server {
    listen 80;
    server_name your-domain.com;

    # Важно для SSE (стриминг лога): отключаем буферизацию
    proxy_buffering          off;
    proxy_cache              off;

    location / {
        proxy_pass         http://localhost:5000;
        proxy_http_version 1.1;

        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;

        # SSE: не закрывать соединение раньше времени
        proxy_read_timeout  600s;
        proxy_send_timeout  600s;

        # SSE: не буферизовать ответ
        proxy_set_header   X-Accel-Buffering no;
    }
}

---

Устранение неполадок

Ошибка «файл не найден» для PDF-банков (ВТБ, Сбербанк, Урал ФД)

Проверьте, что Tesseract и Poppler установлены в контейнере:

docker compose exec subsidy-matrix tesseract --version
docker compose exec subsidy-matrix pdftoppm -v

Если команды не найдены — пересоберите образ:

docker compose build --no-cache

Ошибка «file too large»

Увеличьте лимит загрузки в app.py (переменная MAX_CONTENT_LENGTH).

Контейнер падает из-за нехватки памяти (OOM)

Увеличьте limits.memory в docker-compose.yml (минимум 1.5g для файлов с OCR).

SSE-лог не стримится (только спиннер)

Скорее всего, обратный прокси буферизует ответ. Убедитесь, что у Nginx задан proxy_buffering off (см. раздел выше).

---

Файловая структура

web_app/
├── app.py                       # Flask-приложение (бэкенд)
├── build_subsidy_matrix_web.py  # Ядро парсинга и формирования Excel
├── templates/
│   └── index.html               # Интерфейс (единственный HTML-файл)
├── static/                      # Статика (зарезервировано)
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md