Uruchamianie aplikacji przez Uvicorn
Uruchomisz aplikację ASGI przez Uvicorn na lokalnym porcie serwera i przeprowadzisz podstawową diagnostykę odpowiedzi HTTP, nasłuchującego portu oraz procesu.
1. Krótka teoria
ASGI jest interfejsem łączącym asynchroniczną aplikację Python z serwerem obsługującym ruch sieciowy. Uvicorn jest serwerem ASGI, który importuje aplikację i nasłuchuje na wskazanym adresie oraz porcie. Zapis app.main:app oznacza moduł app.main i obiekt app. W układzie z Nginxem Uvicorn może nasłuchiwać na 127.0.0.1:8000. Adres pętli zwrotnej jest dostępny lokalnie na serwerze, dzięki czemu publiczny ruch trafia najpierw do reverse proxy. Opcje --host i --port określają miejsce nasłuchu. Tryb --reload obserwuje pliki i restartuje proces podczas pracy programistycznej, lecz nie jest przeznaczony do produkcji. Po uruchomieniu trzeba niezależnie sprawdzić odpowiedź przez curl, port przez ss oraz proces przez ps. Komunikat o zajętym adresie zwykle oznacza, że inny proces już używa tego samego połączenia adresu i portu.
2. Przykłady komend
/opt/example-app/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000
Uruchamia aplikację na lokalnym adresie i porcie 8000.
$ /opt/example-app/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000
curl -i http://127.0.0.1:8000/
Wysyła lokalne żądanie i pokazuje nagłówki oraz treść odpowiedzi.
$ curl -i http://127.0.0.1:8000/
curl -fsS http://127.0.0.1:8000/health
Sprawdza przykładowy endpoint health i zwraca błąd przy nieudanej odpowiedzi.
$ curl -fsS http://127.0.0.1:8000/health
ss -lntp | grep ':8000'
Pokazuje proces nasłuchujący na porcie TCP 8000.
$ ss -lntp | grep ':8000'
ps -ef | grep '[u]vicorn'
Wyszukuje uruchomione procesy Uvicorna bez dopasowania samego grep.
$ ps -ef | grep '[u]vicorn'
sudo lsof -iTCP:8000 -sTCP:LISTEN
Pomaga ustalić, który proces zajmuje port 8000, jeśli lsof jest dostępny.
$ sudo lsof -iTCP:8000 -sTCP:LISTEN3. Zadanie praktyczne
/opt/example-app uruchom laboratoryjną aplikację poleceniem /opt/example-app/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000. W drugiej sesji wykonaj curl -i http://127.0.0.1:8000/, sprawdź port przez ss -lntp i odszukaj proces przez ps. Następnie spróbuj uruchomić drugą instancję na tym samym porcie, odczytaj błąd i uruchom ją na innym porcie. Zakończ procesy laboratoryjne po ćwiczeniu.
4. Typowe błędy
- Pomylenie ścieżki pliku z zapisem moduł:obiekt wymaganym przez Uvicorn.
- Uruchamianie polecenia z katalogu, z którego moduł aplikacji nie jest importowalny.
- Używanie --reload w środowisku produkcyjnym.
- Wystawianie Uvicorna publicznie mimo planowanego użycia Nginxa jako reverse proxy.
- Restartowanie procesu bez sprawdzenia, kto już zajmuje port.
- Sprawdzanie wyłącznie procesu bez testu rzeczywistej odpowiedzi HTTP.
5. Podsumowanie
Uvicorn uruchamia aplikację ASGI wskazaną zapisem moduł:obiekt. W typowym wdrożeniu z Nginxem nasłuchuje lokalnie na 127.0.0.1:8000. Poprawne działanie należy sprawdzić na trzech poziomach: proces istnieje, port nasłuchuje i aplikacja odpowiada przez HTTP. --reload jest wygodny lokalnie, ale nie powinien być częścią uruchomienia produkcyjnego.