A. 前言
部署 Channels 應用程式時,需要由 Daphne、Uvicorn 等 ASGI 伺服器載入根應用程式,再依工作負載安排程序與反向代理;若功能使用 channel layer,還需另外配置共用後端。以下分別說明 Daphne、Uvicorn、Nginx 與 Supervisor 的設定,檔案路徑、使用者及服務位置須依環境調整。
B. 設定ASGI應用程式
如同在安裝和路由一節中所討論的,您將有一個類似於 myproject/asgi.py 的文件,該文件將定義您的根應用程式。這幾乎可以確定是您的頂層(協議類型)路由器。
下面是一個可能的 asgi.py 文件範例:
import os
from channels.auth import AuthMiddlewareStack
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.security.websocket import AllowedHostsOriginValidator
from django.core.asgi import get_asgi_application
from django.urls import path
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "mysite.settings")
# Initialize Django ASGI application early to ensure the AppRegistry
# is populated before importing code that may import ORM models.
django_asgi_app = get_asgi_application()
from chat.consumers import AdminChatConsumer, PublicChatConsumer
application = ProtocolTypeRouter({
# Django's ASGI application to handle traditional HTTP requests
"http": django_asgi_app,
# WebSocket chat handler
"websocket": AllowedHostsOriginValidator(
AuthMiddlewareStack(
URLRouter([
path("chat/admin/", AdminChatConsumer.as_asgi()),
path("chat/", PublicChatConsumer.as_asgi()),
])
)
),
})
C. 設定Channel後端服務
通常,頻道後端會連接到一個或多個作為通信層的中央伺服器。例如,Redis 後端會連接到一個 Redis 伺服器。所有這些設置都放在 CHANNEL_LAYERS 設定中;以下是一個遠端 Redis 伺服器的範例:
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {
"hosts": [("redis-server-name", 6379)],
},
},
}
使用 Redis 後端前,先安裝 channels_redis,再設定連線位址與存取方式。下列 pip install -U channels_redis 同時會更新套件,既有專案應先確認相依版本,再決定是否使用 -U。
D. Run protocol servers
為了與外界溝通,您的 Channels/ASGI 應用程序需要加載至協議伺服器中。這些伺服器可以像 WSGI 伺服器一樣以 HTTP 模式運行您的應用程序,但它們也可以橋接至各種協議(例如聊天協議、物聯網(IoT)協議,甚至是無線電網路)。所有這些伺服器都有其自身的配置選項,但它們都有一個共同點 – 它們會要求您向其提供一個 ASGI 應用程序來運行。您只需將專案的 asgi.py 文件中的應用程序對象傳遞給協議伺服器作為其應運行的應用程序即可。
daphne -p 8001 myproject.asgi:application
E. HTTP and WebSocket
本篇聚焦在 HTTP 與 WebSocket 部署。ASGI 定義通用介面,但伺服器實際支援哪些協定、擴展與配置選項,仍需要逐一確認,不能因為都標示 ASGI 就假定功能完全相同。
Channels 專案維護了一個官方的 ASGI HTTP/WebSocket 伺服器,名為 Daphne,我們將討論其配置。其他的 HTTP/WebSocket ASGI 伺服器也是可能的且只要遵循規範就能正常運作,但它們的配置可能會有所不同。
您可以選擇使用 Daphne 來處理所有的請求——無論是 HTTP 還是 WebSocket——或者如果您對穩定性較為保守,可以將標準的 HTTP 請求繼續通過 WSGI 伺服器運行,並僅使用 Daphne 來處理 WSGI 無法處理的事情,如 HTTP 長輪詢和 WebSockets。如果您選擇分開,則需要在 Daphne 和 WSGI 伺服器前放置某些東西來判斷哪些請求應發送到哪一個(可以使用 HTTP 路徑或網域),這裡沒有覆蓋這部分,但請知道您可以這麼做。
Daphne 可以在同一個服務處理 HTTP 與 WebSocket,不必單純為了這兩種流量就拆成不同網域;但仍可用路徑分開管理。是否共享 Cookie 取決於 Cookie 的網域、路徑、Secure 及其他設定,不能簡化為只要跨網域就絕對無法共享。
運行 Daphne 時,只需提供一個應用程序,就像需要為 WSGI 伺服器提供應用程序一樣。確保您有一個如上所述的 asgi.py 文件。
然後,您可以運行 Daphne 並將 ASGI 應用程序作為參數提供:
daphne myproject.asgi:application
你應該在一個進程管理器(如 systemd、supervisord)或容器編排系統(如 Kubernetes、Nomad)中運行 Daphne,以確保在需要時 Daphne 能夠重新啟動,並允許你調整進程的數量。如果你想要將多個 Daphne 實例綁定到機器上的同一個端口,使用能在端口上監聽並將文件描述符傳遞給啟動進程的進程管理器,然後通過 –fd NUM 傳遞文件描述符。你也可以指定 Daphne 綁定的端口和 IP:
daphne -b 0.0.0.0 -p 8001 myproject.asgi:application
你可以在 GitHub 上查看關於 Daphne 和其選項的更多資訊。
F. 其他的Web伺服器
您也可以選擇使用其他 ASGI 伺服器來服務 Django Channels。在某種程度上,ASGI 網頁伺服器應該是可以互換的,因為它們都具備基本的功能來處理 HTTP 和 WebSocket 請求。伺服器之間可能存在差異的方面包括其配置和預設值、效能特徵、資源限制的支援、不同的協議與套接字支援,以及程序管理的方法。您可以在 ASGI 實現的文檔中看到更多替代伺服器,例如 Uvicorn。
1. Uvicorn設定
Uvicorn使用方式與Daphne類似,步驟如下:
若使用 Uvicorn 服務 WebSocket,需要安裝其可用的 WebSocket 協定實作。下面採用 uvicorn[standard],再以 module:attribute 的形式指定 ASGI 入口;實際套件版本應與原專案的 Python 及相依套件相容。
pip3 install "uvicorn[standard]"
uvicorn myproject.asgi:application
以下命令分別示範監聽位址、開發用自動重載與多 worker。--reload 和 --workers 是互斥選項,不是要把三行參數合併在同一次啟動中;使用 0.0.0.0 時也要確認實際網路可存取範圍。
# 指定 Host 和 Port
uvicorn myproject.asgi:application --host 0.0.0.0 --port 8000
# 重新載入
uvicorn myproject.asgi:application --reload
# 設置Worker數量
uvicorn myproject.asgi:application --workers 4
G. 設定指引
這些是可能的設定範例——它們不保證能立即運行,應被視為指引而非直接的教學。
1. Nginx/Supervisor (Ubuntu)
此範例將在 Ubuntu 伺服器上設置一個 Django 站點,使用 Nginx 作為主要的網頁伺服器,並使用 supervisord 來運行和管理 Daphne。首先,安裝 Nginx 和 Supervisor:
sudo apt install nginx supervisor
現在,您需要創建一個 Supervisor 配置文件(通常位於 /etc/supervisor/conf.d/ 目錄中——這裡我們讓 Supervisor 監聽 TCP 埠,然後將該套接字傳遞給子進程,以便它們能夠共享同一綁定埠:
[fcgi-program:asgi]
# TCP socket used by Nginx backend upstream
socket=tcp://localhost:8000
# Directory where your site's project files are located
directory=/my/app/path
# Each process needs to have a separate socket file, so we use process_num
# Make sure to update "mysite.asgi" to match your project name
command=daphne -u /run/daphne/daphne%(process_num)d.sock --fd 0 --access-log - --proxy-headers mysite.asgi:application
# Number of processes to startup, roughly the number of CPUs you have
numprocs=4
# Give each process a unique name so they can be told apart
process_name=asgi%(process_num)d
# Automatically start and recover processes
autostart=true
autorestart=true
# Choose where you want your log to go
stdout_logfile=/your/log/asgi.log
redirect_stderr=true
為在 Supervisor 配置文件中引用的套接字創建運行目錄:
sudo mkdir /run/daphne/
當以不同的使用者運行 supervisor fcgi-program 時,請更改運行目錄的擁有者設定:
sudo chown <user>.<group> /run/daphne/
/run/ 資料夾在伺服器重啟時會被清空。要使 /run/daphne 資料夾保持持久,請建立一個檔案 /usr/lib/tmpfiles.d/daphne.conf,並將以下內容寫入該檔案:
d /run/daphne 0755 <user> <group>
讓 supervisor 重新閱讀並更新其作業:
sudo supervisorctl reread
sudo supervisorctl update
在命令行中運行帶有 –fd 0 的 daphne 命令會失敗,並導致錯誤 [Errno 88]:在非套接字上的套接字操作。
Supervisor 將自動創建套接字、綁定並在分叉群組中的第一個子進程之前進行監聽。該套接字將通過文件描述符編號 0(零)傳遞給每個子進程。請參閱 https://supervisord.org/configuration.html#fcgi-program-x-section-settings。
接下來,必須告訴 Nginx 將流量代理到正在運行的 Daphne 實例:
upstream channels-backend {
server localhost:8000;
}
...
server {
...
location / {
try_files $uri @proxy_to_app;
}
...
location @proxy_to_app {
proxy_pass http://channels-backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_redirect off;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $server_name;
}
...
}
這份 Nginx 範例使用 HTTP/1.1 的 Upgrade 方式代理 WebSocket,因此明確設定 proxy_http_version 1.1。這是在說明此配置的上游協定,不代表所有版本、所有 WebSocket 傳輸方式都只能使用同一種握手。
接著,WebSocket 協議是透過 HTTP 請求的升級機制而實現的,這使得一個普通的 HTTP 連接可以轉變成 WebSocket 連接。為此,需要利用 `proxy_set_header Upgrade $http_upgrade;` 指令來告知 Nginx 傳遞 `Upgrade` 頭部,從而支持這種協議升級。
proxy_set_header Connection "upgrade"; 配合 Upgrade 標頭,把這次請求的升級意圖傳給上游;它不是讓任何 HTTP 連線永久保持「升級狀態」。如果同一個 location 也代理一般 HTTP,可依 $http_upgrade 是否存在,以 map 決定 Connection 值,並另外檢查閒置逾時與心跳需求。
重新載入 nginx 以套用更改:
sudo service nginx reload
H. 總結
部署流程需要對齊 ASGI 入口、協定伺服器、必要的 channel layer,以及 Nginx 和程序管理器的責任。共用 socket、--fd、執行目錄與代理標頭都要依環境配置,特別是代理轉送資訊與後端監聽位址,應只信任預期的代理來源。
