譯者說
Tornado 4.3於2015年11月6日釋出，該版本正式支援Python3.5的async/await關鍵字，並且用舊版本CPython編譯Tornado同樣可以使用這兩個關鍵字，這無疑是一種進步。其次，這是最後一個支援Python2.6和Python3.2的版本了，在後續的版本了會移除對它們的相容。現在網路上還沒有Tornado4.3的中文文件，所以為了讓更多的朋友能接觸並學習到它，我開始了這個翻譯專案，希望感興趣的小夥伴可以一起參與翻譯，專案地址是tornado-zh on Github，翻譯好的文件在Read the Docs上直接可以看到。歡迎Issues or PR。
執行和部署
因為Tornado內建了自己的HTTPServer, 執行和部署它與其他Python web框架不太一樣. 你需要寫一個main()函式來啟動服務, 而不是配置一個WSGI容器來執行你的應用:
def main():
app = make_app()
app.listen(8888)
IOLoop.current().start()
if __name__ == `__main__`:
main()配置你的作業系統或者程式管理器來執行這個程式以啟動服務. 請注意, 增加每個程式允許開啟的最大檔案控制程式碼數是可能是必要的(為了避免”Too many open files”的錯誤). 為了增加這個上限(例如設定為50000 ) 你可以使用ulimit命令, 修改/etc/security/limits.conf 或者設定minfds 在你的supervisord配置中.
程式和埠
由於Python的GIL(全域性直譯器鎖), 為了充分利用多CPU的機器, 執行多個Python
程式是很有必要的. 通常, 最好是每個CPU執行一個程式.
Tornado包含了一個內建的多程式模式來一次啟動多個程式. 這需要一個在main
函式上做點微小的改變:
def main():
app = make_app()
server = tornado.httpserver.HTTPServer(app)
server.bind(8888)
server.start(0) # forks one process per cpu
IOLoop.current().start()這是最簡單的方式來啟動多程式並讓他們共享同樣的埠, 雖然它有一些侷限性. 首先, 每個子程式將有它自己的IOLoop, 所以fork之前, 不接觸全域性IOLoop例項是重要的(甚至是間接的). 其次, 在這個模型中, 很難做到零停機(zero-downtime)更新. 最後, 因為所有的程式共享相同的埠, 想單獨監控它們就更加困難了.
對更復雜的部署, 建議啟動獨立的程式, 並讓它們各自監聽不同的埠. supervisord的”程式組(process groups)”功能是一個很好的方式來安排這些. 當每個程式使用不同的埠, 一個外部的負載均衡器例如HAProxy 或nginx通常需要對外向訪客提供一個單一的地址.
執行在負載均衡器後面
當執行在一個負載均衡器例如nginx, 建議傳遞xheaders=True 給.HTTPServer 的構造器. 這將告訴Tornado使用類似 X-Real-IP這樣的HTTP頭來獲取使用者的IP地址而不是把所有流量都認為來自於負載均衡器的IP地址.
這是一份原始的nginx配置檔案, 在結構上類似於我們在FriendFeed所使用的配置. 這是假設nginx和Tornado server執行在同一臺機器上的, 並且四個Tornado server正執行在8000 – 8003埠:
user nginx;
worker_processes 1;
error_log /var/log/nginx/error.log;
pid /var/run/nginx.pid;
events {
worker_connections 1024;
use epoll;
}
http {
# Enumerate all the Tornado servers here
upstream frontends {
server 127.0.0.1:8000;
server 127.0.0.1:8001;
server 127.0.0.1:8002;
server 127.0.0.1:8003;
}
include /etc/nginx/mime.types;
default_type application/octet-stream;
access_log /var/log/nginx/access.log;
keepalive_timeout 65;
proxy_read_timeout 200;
sendfile on;
tcp_nopush on;
tcp_nodelay on;
gzip on;
gzip_min_length 1000;
gzip_proxied any;
gzip_types text/plain text/html text/css text/xml
application/x-javascript application/xml
application/atom+xml text/javascript;
# Only retry if there was a communication error, not a timeout
# on the Tornado server (to avoid propagating "queries of death"
# to all frontends)
proxy_next_upstream error;
server {
listen 80;
# Allow file uploads
client_max_body_size 50M;
location ^~ /static/ {
root /var/www;
if ($query_string) {
expires max;
}
}
location = /favicon.ico {
rewrite (.*) /static/favicon.ico;
}
location = /robots.txt {
rewrite (.*) /static/robots.txt;
}
location / {
proxy_pass_header Server;
proxy_set_header Host $http_host;
proxy_redirect off;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Scheme $scheme;
proxy_pass http://frontends;
}
}
}靜態檔案和檔案快取
Tornado中, 你可以通過在應用程式中指定特殊的 static_path 來提供靜態檔案服務:
settings = {
"static_path": os.path.join(os.path.dirname(__file__), "static"),
"cookie_secret": "__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__",
"login_url": "/login",
"xsrf_cookies": True,
}
application = tornado.web.Application([
(r"/", MainHandler),
(r"/login", LoginHandler),
(r"/(apple-touch-icon.png)", tornado.web.StaticFileHandler,
dict(path=settings[`static_path`])),
], **settings)這些設定將自動的把所有以 /static/ 開頭的請求從static目錄進行提供,e.g.,http://localhost:8888/static/foo.png 將會通過指定的static目錄提供 foo.png 檔案. 我們也自動的會從static目錄提供 /robots.txt和 /favicon.ico (儘管它們並沒有以 /static/ 字首開始).
在上面的設定中, 我們明確的配置Tornado 提供 apple-touch-icon.png檔案從 .StaticFileHandler 根下, 雖然檔案在static檔案目錄中.(正規表示式捕獲組必須告訴 .StaticFileHandler 請求的檔名; 呼叫捕獲組把檔名作為方法的引數傳遞給處理程式.) 你可以做同樣的事情 e.g.從網站的根提供 sitemap.xml 檔案. 當然, 你也可以通過在你的HTML中使用<link /> 標籤來避免偽造根目錄的 apple-touch-icon.png .
為了改善效能, 通常情況下, 讓瀏覽器主動快取靜態資源是個好主意, 這樣瀏覽器就不會傳送不必要的可能在渲染頁面時阻塞的 If-Modified-Since 或Etag 請求了. Tornado使用 靜態內容版本(static content versioning)來支援此項功能.
為了使用這些功能, 在你的模板中使用 ~.RequestHandler.static_url 方法而不是直接在你的HTML中輸入靜態檔案的URL:
<html>
<head>
<title>FriendFeed - {{ _("Home") }}</title>
</head>
<body>
<div><img src="{{ static_url("images/logo.png") }}"/></div>
</body>
</html>static_url() 函式將把相對路徑翻譯成一個URI類似於/static/images/logo.png?v=aae54. 其中的 v 引數是 logo.png內容的雜湊(hash), 並且它的存在使得Tornado服務向使用者的瀏覽器傳送快取頭,這將使瀏覽器無限期的快取內容.
因為引數 v 是基於檔案內容的, 如果你更新一個檔案並重啟服務, 它將傳送一個新的 v 值, 所以使用者的瀏覽器將會自動的拉去新的檔案. 如果檔案的內容沒有改變, 瀏覽器將會繼續使用本地快取的副本, 而不會從伺服器檢查更新,顯著的提高了渲染效能.
在生產中, 你可能想提供靜態檔案通過一個更優的靜態伺服器, 比如nginx. 你可以配置任何web伺服器識別通過static_url() 提供的版本標籤並相應的設定快取頭. 下面是我們在FriendFeed 使用的nginx相關配置的一部分:
location /static/ {
root /var/friendfeed/static;
if ($query_string) {
expires max;
}
}Debug模式和自動過載
如果傳遞debug=True 配置給Application 的建構函式, 應用程式將會執行在debug/開發模式. 在這個模式下, 為了方便於開發的一些功能將被啟用(每一個也可以作為獨立的標籤使用; 如果它們都被專門指定, 那它們都將獲得獨立的優先順序):
-
autoreload=True: 應用程式將會觀察它的原始檔是否改變, 並且當任何檔案改變的時候便過載它自己. 這減少了在開發中需要手動重啟服務的需求. 然而, 在debug模式下, 某些錯誤(例如import的時候有語法錯誤)會導致服務關閉, 並且無法自動恢復. -
compiled_template_cache=False: 模板將不會被快取. -
static_hash_cache=False: 靜態檔案雜湊(被static_url函式使用) 將不會被快取 -
serve_traceback=True: 當一個異常在RequestHandler中沒有捕獲,將會生成一個包含呼叫棧資訊的錯誤頁.
自動過載(autoreload)模式和 .HTTPServer 的多程式模式不相容. 你不能給HTTPServer.start <.TCPServer.start> 傳遞1以外的引數(或者呼叫tornado.process.fork_processes) 當你使用自動過載模式的時候.
debug模式的自動過載功能可作為一個獨立的模組位於tornado.autoreload.以下兩者可以結合使用, 在語法錯誤之時提供額外的健壯性: 設定autoreload=True 可以在app執行時檢測檔案修改, 還有啟動python -m tornado.autoreload myserver.py 來捕獲任意語法錯誤或者其他的啟動時錯誤.
過載會丟失任何Python直譯器命令列引數(e.g. -u). 因為它使用sys.executable 和 sys.argv 重新執行Python. 此外, 修改這些變數將造成過載錯誤.
在一些平臺(包括Windows 和Mac OSX 10.6之前), 程式不能被”原地”更新,所以當檢測到程式碼更新, 舊服務就會退出然後啟動一個新服務. 這已經被公眾知道來混淆一些IDE.
WSGI和Google App Engine
Tornado通常是獨立執行的, 不需要一個WSGI容器. 然而, 在一些環境中(例如Google App Engine), 只執行WSGI, 應用程式不能獨立執行自己的服務. 在這種情況下, Tornado支援一個有限制的操作模式, 不支援非同步操作但允許一個Tornado`s功能的子集在僅WSGI環境中. 以下功能在WSGI模式下是不支援的, 包括協程, @asynchronous 裝飾器,AsyncHTTPClient, auth 模組和WebSockets.
你可以使用 tornado.wsgi.WSGIAdapter 把一個TornadoApplication 轉換成WSGI應用. 在這個例子中, 配置你的WSGI容器發現 application 物件:
import tornado.web
import tornado.wsgi
class MainHandler(tornado.web.RequestHandler):
def get(self):
self.write("Hello, world")
tornado_app = tornado.web.Application([
(r"/", MainHandler),
])
application = tornado.wsgi.WSGIAdapter(tornado_app)檢視 appengine example application 以瞭解AppEngine在Tornado上開發的完整功能.