容器中的 Python

在本教學課程中，您將學習如何：

• 建立描述簡單 Python 容器的 Dockerfile 檔案。
• 建置、執行並驗證 Django、Flask 或一般 Python 應用程式的功能。
• 對在容器中執行的應用程式進行偵錯。

先決條件

• 在您的機器上安裝 Docker，並將其加入系統路徑 (System Path)。

• 在 Linux 上，您也應該為非 root 使用者帳戶啟用 Docker CLI，以便用來執行 VS Code。

• Container Tools 延伸模組。若要安裝此延伸模組，請開啟「延伸模組」檢視 (⇧⌘X (Windows, Linux Ctrl+Shift+X))，搜尋 container tools 以篩選結果，並選取由 Microsoft 所發行的 Container Tools 延伸模組。

  

建立 Python 專案

如果您尚未擁有 Python 專案，請依照開始使用 Python 教學課程進行操作。

注意：如果您想要將完整的 Django 或 Flask Web 應用程式容器化，可以從以下其中一個範例開始：

• python-sample-vscode-django-tutorial，這是依照 Django 教學課程操作後的結果。

• python-sample-vscode-flask-tutorial，這是依照 Flask 教學課程操作後的結果。

注意：在本教學課程中，請務必使用範例儲存庫的 tutorial 分支。

在驗證您的應用程式執行正常後，您現在可以將應用程式容器化。

將 Docker 檔案加入專案

1. 在 VS Code 中開啟該專案資料夾。

2. 開啟命令選擇區 (⇧⌘P (Windows, Linux Ctrl+Shift+P))，並選擇 Containers: Add Docker Files to Workspace...

   

3. 當系統提示輸入應用程式類型時，請選擇 Python: Django、Python: Flask 或 Python: General。本教學課程將重點介紹 Python: General 的情況，但也會包含針對 Django 和 Flask 的說明。

4. 輸入應用程式進入點的相對路徑。這不包含您啟動時的工作區資料夾。如果您已依照開始使用 Python 教學課程建立包含 hello.py 的 Python 應用程式，請選擇該檔案。

   Django：選擇 manage.py（根目錄）或 subfolder_name/manage.py。請參閱官方 Django 文件。

   Flask：選擇您建立 Flask 執行個體所在的路徑。請參閱官方 Flask 文件。

   提示：只要該資料夾包含 __main__.py 檔案，您也可以輸入資料夾名稱的路徑。

5. 選取連接埠號碼。我們建議選取 1024 或以上的連接埠，以減輕因以 root 使用者身分執行而帶來的安全性疑慮。任何未使用的連接埠皆可，但 Django 和 Flask 使用標準預設連接埠。

   Django：預設連接埠為 8000。

   Flask：預設連接埠為 5000。

6. 當系統提示是否包含 Docker Compose 時，如果您不需要 Docker Compose 檔案，請選擇 No。如果您選擇 Yes，則需要在 Dockerfile 中驗證 wsgi.py 檔案的路徑，以便成功執行 Compose Up 命令。Compose 通常用於同時執行多個容器的情況。

7. 有了這些資訊，Container Tools 延伸模組會建立下列檔案：

   • 一個 Dockerfile。若要深入了解此檔案中的 IntelliSense，請參閱總覽。

   • 一個 .dockerignore 檔案，用來透過排除 .git、.vscode 和 __pycache__ 等不必要的檔案與資料夾，以縮減映像大小。

   • 如果您使用 Docker Compose，則會包含 docker-compose.yml 和 docker-compose.debug.yml 檔案。

   • 如果尚未存在，則會建立一個用於擷取所有應用程式相依性的 requirements.txt 檔案。

   重要注意事項：若要使用我們的設定，Python 架構 (Django/Flask) 和 Gunicorn 必須包含在 requirements.txt 檔案中。如果虛擬環境/主機機器已安裝這些必要條件，且預期與容器環境相同，請確保透過在終端機中執行 pip freeze > requirements.txt 將應用程式相依性匯出。這將會覆寫您目前的 requirements.txt 檔案。

（選用）在映像中新增環境變數

此步驟並非強制，但在此提供是為了幫助您了解如何新增需要在容器環境中設定的環境變數。

Container Tools 延伸模組透過使用 IntelliSense 提供自動完成和內容相關說明，協助您撰寫 Dockerfile。若要查看此功能的實際運作：

1. 開啟 Dockerfile。

2. 在 EXPOSE 陳述式下方，輸入 ⌃Space (Windows, Linux Ctrl+Space) 來觸發 IntelliSense，並捲動至 ENV。

   

3. 按下 Tab 或 Enter 完成該陳述式，然後將 key 設定為變數名稱，並設定 value。

如需關於在 Dockerfile 中設定與使用環境變數的詳細資訊，請參閱 Docker 文件中的 ENV 指令與環境替換 (Environment replacement) 章節。

針對 Django 和 Flask 應用程式的 Gunicorn 修改

為了讓 Python Web 開發人員有絕佳的起點，我們選擇使用 Gunicorn 作為預設的 Web 伺服器。由於它在預設 Dockerfile 中被參照，因此它會作為相依性包含在 requirements.txt 檔案中。如果您在 requirements.txt 中沒看到它，請執行 pip install gunicorn，然後執行 pip freeze > requirements.txt 來重新產生 requirements.txt 檔案。

• Django：若要使用 Gunicorn，它必須綁定到一個應用程式可呼叫物件 (application callable，即應用程式伺服器與您的程式碼通訊的方式) 作為進入點。此可呼叫物件是在 Django 應用程式的 wsgi.py 檔案中宣告的。為了實現此綁定，Dockerfile 中的最後一行寫道：

  CMD ["gunicorn", "--bind", "0.0.0.0:8000", "{workspace_folder_name}.wsgi"]
  

  如果您的專案未遵循 Django 的預設專案結構（即工作區資料夾中包含與工作區同名的子資料夾，且內部有 wsgi.py 檔案），則必須覆寫 Dockerfile 中的 Gunicorn 進入點，以定位正確的 wsgi.py 檔案。

  如果您的 wsgi.py 檔案位於根目錄，上述命令中的最後一個參數將是 "wsgi"。如果位於子資料夾內，該參數將會是 "subfolder1_name.subfolder2_name.wsgi"。

• Flask：若要使用 Gunicorn，它必須綁定到一個應用程式可呼叫物件作為進入點。此可呼叫物件對應於您建立的 Flask 執行個體的檔案位置與變數名稱。根據官方 Flask 文件，使用者通常會以這種方式在主模組或封裝的 __init__.py 檔案中建立 Flask 執行個體：

  from flask import Flask
  app = Flask(__name__) # Flask instance named app
  

  為了實現此綁定，Dockerfile 中的最後一行寫道：

  CMD ["gunicorn", "--bind", "0.0.0.0:5000", "{subfolder}.{module_file}:app"]
  

  在執行 Containers: Add Docker Files to Workspace... 命令期間，您可以設定 Flask 執行個體的路徑；不過，Container Tools 延伸模組會預設您的 Flask 執行個體變數名稱為 app。如果不是這種情況，您必須變更 Dockerfile 中的變數名稱。

  如果您的主模組位於根目錄中，且檔案名稱為 main.py，而 Flask 執行個體變數命名為 myapp，則上述命令的最後一個參數將會是 "main:myapp"。如果在子資料夾內，參數將會是 "subfolder1_name.subfolder2_name.main:myapp"。

建置、執行並偵錯容器

Containers: Add Docker Files to Workspace... 命令會自動建立 Docker 啟動設定，以在偵錯模式下建置並執行您的容器。若要偵錯您的 Python 應用程式容器：

1. 瀏覽至包含應用程式啟動程式碼的檔案，並設定中斷點。

2. 瀏覽至執行並偵錯 (Run and Debug)，並視情況選取 Containers: Python - General、Containers: Python - Django 或 Containers: Python - Flask。

   

3. 使用 F5 鍵開始偵錯。

   • 容器映像進行建置。
   • 容器開始執行。
   • Python 偵錯工具會在中斷點處停止。

4. 單步跳過該行一次。

5. 準備好後，按一下「繼續」。

Container Tools 延伸模組會將您的瀏覽器啟動至隨機對應的連接埠。

提示：若要修改 Docker 建置設定（例如變更映像標籤），請瀏覽至 .vscode -> tasks.json，在 docker-build 工作中的 dockerBuild 屬性下進行修改。在檔案內使用 IntelliSense (⌃Space (Windows, Linux Ctrl+Space)) 以顯示所有其他有效的指令。

使用容器總管 (Container Explorer)

容器總管提供互動式體驗，可檢視與管理容器資產（如容器、映像等）。若要查看範例：

1. 瀏覽至容器總管。

2. 在容器索引標籤中，對您的容器按一下滑鼠右鍵，並選擇 View Logs。

   

3. 輸出結果將顯示在終端機中。

在 Azure 中建置映像

您可以使用 Azure Container Registry: Build Image in Azure 命令來建置映像，然後將其部署至 Azure App Service 或 Azure Container Apps。

1. 安裝 Azure Resources 延伸模組。開啟命令選擇區 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 並搜尋 Azure: Sign In 命令。如果您沒有 Azure 帳戶，可以註冊免費試用版。

2. 有兩種方法可以呼叫 Azure 建置命令。您可以對 Dockerfile 按一下滑鼠右鍵，選擇 Build Image in Azure。您也可以使用命令選擇區 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 並搜尋 Azure Container Registry: Build Image in Azure 命令。

   

3. 選擇所建置映像的名稱與標籤。您將使用此標籤在容器登錄中識別它。

   

4. 選擇您要使用的 Azure 訂用帳戶。

5. 選擇現有的 Azure Container Registry，或建立一個新的。建立新的時，系統會要求您提供名稱、資源群組、位置以及定價選項（例如 Basic、Standard 或 Premium）。您可以閱讀關於這些選項的成本資訊：Container Registry 定價。

6. 指定基礎作業系統（Linux 或 Windows）。此選擇必須與 Dockerfile 一致。

   

建置映像的過程可能需要幾分鐘。您可以在終端機中追蹤進度。如果您遇到錯誤 (Error: failed to download context.)，請嘗試使用容器登錄上的重新整理 (Refresh) 選項，然後重新要求建置。重新建置之前，請手動刪除舊的映像。

部署至 Azure App Service 或 Azure Container Apps

容器映像建置完成後，它應該會出現在容器登錄中，並帶有您指定的標籤。現在它已建置完成，您可以將其部署至 Azure App Service 或 Azure Container Apps。建議使用 Azure App Service 延伸模組進行部署，而部署至 Azure Container Apps 則需要 Azure Container Apps 延伸模組。您可以透過安裝 Azure Tools 延伸模組套件來同時取得兩者，該套件包含針對多種 Azure 開發情境的工具。

1. 對映像標籤按一下滑鼠右鍵，並選擇 Deploy Image to Azure App Service 或 Deploy Image to Azure Container Apps。

   

2. 提供網站名稱。這必須是唯一的名稱；對於 Django 應用程式，它也必須在 settings.py 檔案的 ALLOWED_HOSTS 清單中列為有效的主機名稱。

3. 提供資源群組、位置與 App Service 方案。如果您剛開始，可以選擇免費方案。

4. 映像隨即部署；此過程可能需要幾分鐘。部署完成後，會出現一個按鈕，可用來存取網站。您也可以使用網站位址 {appname}.azurewebsites.net，其中 {appname} 是您建立時給予的名稱。如果最初無法運作，請過幾分鐘再試。初次幾次嘗試逾時或回傳錯誤並不罕見，這僅表示 App Service 尚未準備好接收要求。

5. 在應用程式程式碼中進行細微修改（可在其中一個頁面上看到），並儲存檔案。

6. 使用 Azure 圖示開啟資源 (Resources) 檢視，展開訂用帳戶的節點以找到您在前一個步驟中部署的 App Service。

7. 對 App Service 節點按一下滑鼠右鍵，查看可用選項。選擇 Deploy to Web App，然後指定您的應用程式資料夾進行部署。

   

   當系統警告這將覆寫先前的部署時，選擇 Deploy 以確認。

   這可能需要幾分鐘；您可以在終端機視窗中監控進度。完成後，將會提供一個存取網站的按鈕。

   

   使用該按鈕並驗證您的變更是否已反映在網站上。

恭喜，您已在 VS Code 中使用 Python 建立並部署了一個託管於雲端且已上線的網站！

釋放資源

在 Azure 入口網站中，刪除該資源群組以釋放您在此練習期間建立的所有資源。

後續步驟

完成！現在容器已準備就緒，您可能想要：

• 了解如何使用 Docker Compose
• 使用 Docker Compose 偵錯
• 自訂如何在容器中偵錯 Python 應用程式
• 自訂您的 Docker 建置與執行工作
• 將您的 Django 映像推送至 Azure Container Registry
• 部署至 Azure Container Apps