6.9. Flask

   master process (PID 1)
       │  управляет, перезапускает упавших
       ├── worker 1  ──► обрабатывает запросы
       ├── worker 2  ──► обрабатывает запросы
       └── worker N  ──► обрабатывает запросы

workers = int(os.environ.get("WEB_CONCURRENCY", "2"))

   слушает 127.0.0.1        слушает 0.0.0.0
   ──────────────────       ─────────────────
   доступен только          доступен со всех
   изнутри container        интерфейсов container
          │                        │
          ▼                        ▼
   -p 8000:8000 не помогает  -p 8000:8000 работает

bind = f"0.0.0.0:{os.environ.get('PORT', '8000')}"

accesslog = "-"    # "-" означает stdout
errorlog = "-"     # stderr

   docker stop
       │
       ├─ 0 c    SIGTERM → Gunicorn прекращает приём
       │
       ├─ 8 c    graceful_timeout истёк → Gunicorn убивает worker'ов
       │
       └─ 10 c   grace period Docker истёк → SIGKILL (не понадобился)

max_requests = 1000
max_requests_jitter = 100

def worker_exit(server, worker):
    """Вызывается при завершении worker'а."""
    close_connections()

cd resources/examples/flask-basic
docker build -q -t flask-basic . > /dev/null && echo "образ собран"
docker run -d --name flask -p 8000:8000 flask-basic > /dev/null
sleep 3
curl -s localhost:8000/ | python3 -m json.tool

образ собран
{
    "pid": 8,
    "service": "flask-basic",
    "worker": "gunicorn"
}

# ps в python:*-slim нет — читаем /proc.
# Шаблон [g]unicorn, а не gunicorn: иначе команда находит саму себя —
# её текст тоже лежит в /proc/PID/cmdline.
docker exec flask sh -c '
    for f in /proc/[0-9]*/cmdline; do
        pid=$(basename "$(dirname "$f")")
        cmd=$(tr "\0" " " < "$f")
        case "$cmd" in *[g]unicorn*) printf "%5s %s\n" "$pid" "$cmd" ;; esac
    done | sort -n'

    1 /usr/local/bin/python3.13 /usr/local/bin/gunicorn --config gunicorn.conf.py app.main:app
    7 /usr/local/bin/python3.13 /usr/local/bin/gunicorn --config gunicorn.conf.py app.main:app
    8 /usr/local/bin/python3.13 /usr/local/bin/gunicorn --config gunicorn.conf.py app.main:app

mkdir -p /tmp/flask-demo/app && cd /tmp/flask-demo

cat > app/main.py <<'PY'
import os
import time

from flask import Flask, jsonify

app = Flask(__name__)


@app.get("/")
def index():
    return jsonify(pid=os.getpid())


@app.get("/slow")
def slow():
    time.sleep(3)
    return jsonify(done=True)


@app.get("/crash")
def crash():
    raise RuntimeError("намеренная ошибка")
PY

cat > requirements.txt <<'EOF'
flask==3.1.3
gunicorn==26.0.0
EOF

cat > Dockerfile.devserver <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1 FLASK_APP=app.main
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000"]
EOF

docker build -q -f Dockerfile.devserver -t flask:dev . > /dev/null
docker run -d --name f-dev -p 8001:8000 flask:dev > /dev/null
sleep 3
docker logs f-dev 2>&1 | grep -i 'warning\|development' | head -2

WARNING: This is a development server. Do not use it in a production deployment.
Use a production WSGI server instead.

echo "=== один медленный запрос блокирует остальные ==="
curl -s -o /dev/null localhost:8001/slow &
sleep 0.3
s="$(date +%s.%N)"
curl -s -o /dev/null -m 10 localhost:8001/
e="$(date +%s.%N)"
wait
printf '  быстрый запрос ждал: %.1f c\n' "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')"

=== один медленный запрос блокирует остальные ===
  быстрый запрос ждал: 2.7 c

curl -s -o /dev/null localhost:8000/ > /dev/null 2>&1
docker exec flask sh -c 'true'   # проверка доступности

curl -s -o /dev/null "localhost:8000/" &
sleep 0.2
s="$(date +%s.%N)"
curl -s -o /dev/null -m 10 localhost:8000/
e="$(date +%s.%N)"
wait
printf '  под Gunicorn быстрый запрос ждал: %.2f c\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')"

  под Gunicorn быстрый запрос ждал: 0.01 c

cat > Dockerfile.debug <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1 FLASK_APP=app.main FLASK_DEBUG=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000"]
EOF

docker build -q -f Dockerfile.debug -t flask:debug . > /dev/null
docker run -d --name f-debug -p 8002:8000 flask:debug > /dev/null
sleep 3

echo "=== ответ на ошибку при FLASK_DEBUG=1 ==="
curl -s localhost:8002/crash | grep -o 'Werkzeug Debugger\|console\|Traceback' | sort -u | head -3
echo
echo "=== PIN отладчика в логах ==="
docker logs f-debug 2>&1 | grep -i 'pin' | head -2

=== ответ на ошибку при FLASK_DEBUG=1 ===
Traceback
Werkzeug Debugger
console

curl -s -o /dev/null -w 'HTTP %{http_code}\n' localhost:8000/boom
curl -s localhost:8000/boom | grep -o 'Werkzeug Debugger' || echo "отладчика в ответе нет"

HTTP 500
отладчика в ответе нет

docker rm -f f-dev f-debug > /dev/null

cat > Dockerfile.localhost <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
CMD ["gunicorn", "--bind", "127.0.0.1:8000", "app.main:app"]
EOF

docker build -q -f Dockerfile.localhost -t flask:localhost . > /dev/null
docker run -d --name f-local -p 8003:8000 flask:localhost > /dev/null
sleep 3

echo "=== снаружи ==="
curl -s -m 3 -o /dev/null -w 'HTTP %{http_code}\n' localhost:8003/ 2>&1 || echo "  недоступен"

echo "=== изнутри container ==="
docker exec f-local python -c "
import urllib.request
print('HTTP', urllib.request.urlopen('http://127.0.0.1:8000/', timeout=2).status)
"

echo "=== что слушает процесс ==="
CPID="$(docker inspect f-local --format '{{.State.Pid}}')"
sudo nsenter -t "$CPID" -n ss -tlnp 2>/dev/null | tail -2 || \
    docker exec f-local python -c "
import socket
s = socket.socket()
try:
    s.bind(('0.0.0.0', 8000)); print('порт 8000 на 0.0.0.0 свободен — значит слушают только 127.0.0.1')
except OSError:
    print('порт занят')
"
docker rm -f f-local > /dev/null

=== снаружи ===
  недоступен
=== изнутри container ===
HTTP 200
=== что слушает процесс ===
LISTEN 0  2048  127.0.0.1:8000  0.0.0.0:*

cd resources/examples/flask-basic
cat gunicorn.conf.py

"""Конфигурация Gunicorn.

Число worker-процессов берётся из переменной окружения, а не из os.cpu_count():
внутри container os.cpu_count() возвращает число CPU хоста, игнорируя --cpus.
См. урок 6.11.
"""
import os

bind = f"0.0.0.0:{os.environ.get('PORT', '8000')}"

# WEB_CONCURRENCY — стандартное имя переменной, его понимают многие PaaS
workers = int(os.environ.get("WEB_CONCURRENCY", "2"))
worker_class = "sync"
threads = int(os.environ.get("GUNICORN_THREADS", "1"))

# Логи в stdout/stderr: только так их увидит docker logs
accesslog = "-"
errorlog = "-"
loglevel = os.environ.get("LOG_LEVEL", "info").lower()

# graceful_timeout должен укладываться в grace period docker stop (10 c)
timeout = int(os.environ.get("GUNICORN_TIMEOUT", "30"))
graceful_timeout = int(os.environ.get("GUNICORN_GRACEFUL_TIMEOUT", "8"))

# Перезапуск worker'ов защищает от накопления утечек памяти
max_requests = int(os.environ.get("GUNICORN_MAX_REQUESTS", "1000"))
max_requests_jitter = 100

# В python:*-slim нет ps: считаем процессы по /proc.
# Наивное `ps | grep -c` в таком образе печатает 0 — не ошибку,
# а правдоподобное неверное число.
COUNT_GUNICORN='for f in /proc/[0-9]*/cmdline; do tr "\0" " " < "$f"; echo; done | grep -c "[g]unicorn"'

for n in 1 4; do
    docker run -d --name "f-w$n" -e WEB_CONCURRENCY="$n" -p "80$n:8000" flask-basic > /dev/null
    sleep 3
    printf 'WEB_CONCURRENCY=%s → процессов gunicorn: %s\n' "$n" \
        "$(docker exec "f-w$n" sh -c "$COUNT_GUNICORN")"
    docker rm -f "f-w$n" > /dev/null
done

WEB_CONCURRENCY=1 → процессов gunicorn: 2
WEB_CONCURRENCY=4 → процессов gunicorn: 5

echo "=== container видит все CPU хоста, игнорируя лимит ==="
docker run --rm --cpus=1 python:3.13-slim python -c "
import os
cpus = os.cpu_count()
print(f'  os.cpu_count() = {cpus}')
print(f'  формула 2*cpu+1 дала бы {2*cpus+1} worker-процессов')
print(f'  при этом --cpus=1, то есть доступно одно ядро')
"

echo
echo "=== реальный лимит читается из cgroup ==="
docker run --rm --cpus=1 python:3.13-slim sh -c '
quota=$(cut -d" " -f1 /sys/fs/cgroup/cpu.max)
period=$(cut -d" " -f2 /sys/fs/cgroup/cpu.max)
if [ "$quota" = "max" ]; then echo "  лимит не задан"; else
  echo "  cpu.max = $quota/$period = $(awk -v q=$quota -v p=$period "BEGIN{printf \"%.1f\", q/p}") ядра"
fi'

=== container видит все CPU хоста, игнорируя лимит ===
  os.cpu_count() = 8
  формула 2*cpu+1 дала бы 17 worker-процессов
  при этом --cpus=1, то есть доступно одно ядро
=== реальный лимит читается из cgroup ===
  cpu.max = 100000/100000 = 1.0 ядра

docker run -d --name f-stop -p 8010:8000 flask-basic > /dev/null
sleep 3

echo "=== остановка без активных запросов ==="
s="$(date +%s.%N)"; docker stop f-stop > /dev/null; e="$(date +%s.%N)"
printf '  время: %.2f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect f-stop --format '{{.State.ExitCode}}')"
docker rm f-stop > /dev/null

=== остановка без активных запросов ===
  время: 0.34 c, код: 0

cd /tmp/flask-demo
cat > Dockerfile.slow <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "2", \
     "--graceful-timeout", "8", "--access-logfile", "-", "app.main:app"]
EOF

docker build -q -f Dockerfile.slow -t flask:slow . > /dev/null
docker run -d --name f-drain -p 8011:8000 flask:slow > /dev/null
sleep 3

curl -s -m 15 localhost:8011/slow > /tmp/drain-result.txt &
CURL_PID=$!
sleep 0.5
s="$(date +%s.%N)"; docker stop f-drain > /dev/null; e="$(date +%s.%N)"
wait $CURL_PID 2>/dev/null
printf '  время stop: %.1f c (ждал завершения запроса)\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')"
echo -n "  ответ клиенту: "; cat /tmp/drain-result.txt; echo
docker rm f-drain > /dev/null; rm -f /tmp/drain-result.txt

  время stop: 2.6 c (ждал завершения запроса)
  ответ клиенту: {"done":true}

cat > Dockerfile.badtimeout <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
# graceful_timeout БОЛЬШЕ grace period Docker (10 c)
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "2", \
     "--graceful-timeout", "60", "app.main:app"]
EOF

cat > app/verylong.py <<'PY'
PY
sed -i 's|time.sleep(3)|time.sleep(30)|' app/main.py

docker build -q -f Dockerfile.badtimeout -t flask:badtimeout . > /dev/null
docker run -d --name f-bad -p 8012:8000 flask:badtimeout > /dev/null
sleep 3

curl -s -m 40 -o /dev/null localhost:8012/slow &
sleep 0.5
s="$(date +%s.%N)"; docker stop f-bad > /dev/null; e="$(date +%s.%N)"
wait 2>/dev/null
printf '  время stop: %.1f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect f-bad --format '{{.State.ExitCode}}')"
docker rm f-bad > /dev/null
sed -i 's|time.sleep(30)|time.sleep(3)|' app/main.py

  время stop: 10.3 c, код: 137

cd /tmp/flask-demo
cat > gunicorn_json.py <<'PY'
"""Логи Gunicorn в JSON, в одном формате с логами приложения."""
import json
import logging
import os
import sys
from datetime import datetime, timezone


class JsonFormatter(logging.Formatter):
    def format(self, record):
        payload = {
            "ts": datetime.fromtimestamp(record.created, tz=timezone.utc)
            .isoformat(timespec="milliseconds").replace("+00:00", "Z"),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage(),
        }
        if record.exc_info:
            payload["exception"] = self.formatException(record.exc_info)
        return json.dumps(payload, ensure_ascii=False)


bind = f"0.0.0.0:{os.environ.get('PORT', '8000')}"
workers = int(os.environ.get("WEB_CONCURRENCY", "2"))
accesslog = "-"
errorlog = "-"
graceful_timeout = 8


def on_starting(server):
    """Хук: вызывается один раз при старте master."""
    handler = logging.StreamHandler(sys.stdout)
    handler.setFormatter(JsonFormatter())
    for name in ("gunicorn.error", "gunicorn.access"):
        lg = logging.getLogger(name)
        lg.handlers.clear()
        lg.addHandler(handler)
        lg.propagate = False
PY

cat > Dockerfile.jsonlog <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
COPY gunicorn_json.py .
CMD ["gunicorn", "--config", "gunicorn_json.py", "app.main:app"]
EOF

docker build -q -f Dockerfile.jsonlog -t flask:jsonlog . > /dev/null
docker run -d --name f-json -p 8013:8000 flask:jsonlog > /dev/null
sleep 4
curl -s -o /dev/null localhost:8013/
sleep 1

echo "=== логи Gunicorn в JSON ==="
docker logs f-json 2>&1 | grep '^{' | tail -3 | python3 -c "
import json, sys
for line in sys.stdin:
    try:
        r = json.loads(line)
        print(f\"  [{r['logger']:<16}] {r['message'][:60]}\")
    except json.JSONDecodeError:
        pass
"
docker rm -f f-json > /dev/null

=== логи Gunicorn в JSON ===
  [gunicorn.error  ] Starting gunicorn 26.0.0
  [gunicorn.error  ] Listening at: http://0.0.0.0:8000 (1)
  [gunicorn.access ] 172.17.0.1 - - [30/Jul/2026:14:52:11 +0000] "GET / HTTP/1.1" 200 46

cat > Dockerfile.multistage <<'EOF'
# syntax=docker/dockerfile:1

FROM python:3.13-slim AS base
ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PATH="/opt/venv/bin:$PATH"
WORKDIR /app
RUN useradd --create-home --uid 10001 appuser

FROM base AS builder
RUN python -m venv /opt/venv
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt

# Стадия разработки: автоперезагрузка, отладчик разрешён
FROM base AS dev
COPY --from=builder /opt/venv /opt/venv
ENV FLASK_APP=app.main FLASK_DEBUG=1
COPY app/ ./app/
EXPOSE 8000
CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000", "--reload"]

# Стадия production: Gunicorn, non-root
FROM base AS prod
COPY --from=builder --chown=10001:10001 /opt/venv /opt/venv
COPY --chown=10001:10001 app/ ./app/
USER 10001:10001
EXPOSE 8000
HEALTHCHECK --interval=15s --timeout=3s --start-period=10s --retries=3 \
  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/',timeout=2).status==200 else 1)"
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "2", \
     "--graceful-timeout", "8", "--access-logfile", "-", "--error-logfile", "-", \
     "app.main:app"]
EOF

for target in dev prod; do
    docker build -q --target "$target" -f Dockerfile.multistage -t "flask:$target" . > /dev/null
    printf '%-6s размер: %-8s UID: %s\n' "$target" \
        "$(docker images "flask:$target" --format '{{.Size}}')" \
        "$(docker run --rm --entrypoint id "flask:$target" -u)"
done

dev    размер: 168MB   UID: 0
prod   размер: 168MB   UID: 10001

cd /tmp
docker rm -f flask 2>/dev/null || true
docker rmi -f $(docker images -q --filter 'reference=flask:*') flask-basic 2>/dev/null || true
rm -rf /tmp/flask-demo

cd resources/examples/flask-basic
docker build -q -t fb . > /dev/null
docker run -d --name fbt -p 8030:8000 fb > /dev/null
sleep 4
curl -s -o /dev/null -w 'HTTP %{http_code}\n' localhost:8030/healthz
docker exec fbt sh -c 'for f in /proc/[0-9]*/cmdline; do tr "\0" " " < "$f"; echo; done | grep -c "[g]unicorn"'
time docker stop fbt
docker inspect fbt --format 'код: {{.State.ExitCode}}'
docker rm -f fbt > /dev/null; docker rmi -f fb > /dev/null