运行和部署

因为Tornado内置了自己的HTTPServer, 运行和部署它与其他Python web框架不 太一样. 你需要写一个 main() 函数来启动服务, 而不是配置一个WSGI容器 来运行你的应用:

.. testcode::

  1. def main():
  2.     app = make_app()
  3.     app.listen(8888)
  4.     IOLoop.current().start()
  6. if __name__ == '__main__':
  7.     main()

.. testoutput:: :hide:

配置你的操作系统或者进程管理器来运行这个程序以启动服务. 请注意, 增加每个 进程允许打开的最大文件句柄数是可能是必要的(为了避免”Too many open files” 的错误). 为了增加这个上限(例如设置为50000 ) 你可以使用ulimit命令, 修改/etc/security/limits.conf 或者设置 minfds 在你的supervisord配置中.

进程和端口

  2. 由于Python的GIL(全局解释器锁), 为了充分利用多CPU的机器, 运行多个Python
  3. 进程是很有必要的. 通常, 最好是每个CPU运行一个进程.
  5. Tornado包含了一个内置的多进程模式来一次启动多个进程. 这需要一个在main
  6. 函数上做点微小的改变:
  8. .. testcode::
  10.     def main():
  11.         app = make_app()
  12.         server = tornado.httpserver.HTTPServer(app)
  13.         server.bind(8888)
  14.         server.start(0)  # forks one process per cpu
  15.         IOLoop.current().start()
  17. .. testoutput::
  18.    :hide:
  20. 这是最简单的方式来启动多进程并让他们共享同样的端口, 虽然它有一些局限
  21. 性. 首先, 每个子进程将有它自己的IOLoop, 所以fork之前, 不接触全局
  22. IOLoop实例是重要的(甚至是间接的). 其次, 在这个模型中, 很难做到零停机
  23. (zero-downtime)更新. 最后, 因为所有的进程共享相同的端口, 想单独监控
  24. 它们就更加困难了.
  26. 对更复杂的部署, 建议启动独立的进程, 并让它们各自监听不同的端口.
  27. `supervisord <http://www.supervisord.org>`_ 的"进程组(process groups)"
  28. 功能是一个很好的方式来安排这些. 当每个进程使用不同的端口, 一个外部的
  29. 负载均衡器例如HAProxy 或nginx通常需要对外向访客提供一个单一的地址.
  32. 运行在负载均衡器后面
  33. ~~~~~~~~~~~

当运行在一个负载均衡器例如nginx, 建议传递 xheaders=True 给 .HTTPServer 的构造器. 这将告诉Tornado使用类似 X-Real-IP 这样的HTTP头来获取用户的IP地址而不是把所有流量都认为来自于 负载均衡器的IP地址.

这是一份原始的nginx配置文件, 在结构上类似于我们在FriendFeed所使用的 配置. 这是假设nginx和Tornado server运行在同一台机器上的, 并且四个 Tornado server正运行在8000 - 8003端口::

  1. user nginx;
  2. worker_processes 1;
  4. error_log /var/log/nginx/error.log;
  5. pid /var/run/nginx.pid;
  7. events {
  8.     worker_connections 1024;
  9.     use epoll;
  10. }
  12. http {
  13.     # Enumerate all the Tornado servers here
  14.     upstream frontends {
  15.         server 127.0.0.1:8000;
  16.         server 127.0.0.1:8001;
  17.         server 127.0.0.1:8002;
  18.         server 127.0.0.1:8003;
  19.     }
  21.     include /etc/nginx/mime.types;
  22.     default_type application/octet-stream;
  24.     access_log /var/log/nginx/access.log;
  26.     keepalive_timeout 65;
  27.     proxy_read_timeout 200;
  28.     sendfile on;
  29.     tcp_nopush on;
  30.     tcp_nodelay on;
  31.     gzip on;
  32.     gzip_min_length 1000;
  33.     gzip_proxied any;
  34.     gzip_types text/plain text/html text/css text/xml
  35.                application/x-javascript application/xml
  36.                application/atom+xml text/javascript;
  38.     # Only retry if there was a communication error, not a timeout
  39.     # on the Tornado server (to avoid propagating "queries of death"
  40.     # to all frontends)
  41.     proxy_next_upstream error;
  43.     server {
  44.         listen 80;
  46.         # Allow file uploads
  47.         client_max_body_size 50M;
  49.         location ^~ /static/ {
  50.             root /var/www;
  51.             if ($query_string) {
  52.                 expires max;
  53.             }
  54.         }
  55.         location = /favicon.ico {
  56.             rewrite (.*) /static/favicon.ico;
  57.         }
  58.         location = /robots.txt {
  59.             rewrite (.*) /static/robots.txt;
  60.         }
  62.         location / {
  63.             proxy_pass_header Server;
  64.             proxy_set_header Host $http_host;
  65.             proxy_redirect off;
  66.             proxy_set_header X-Real-IP $remote_addr;
  67.             proxy_set_header X-Scheme $scheme;
  68.             proxy_pass http://frontends;
  69.         }
  70.     }
  71. }

静态文件和文件缓存

  2. Tornado中, 你可以通过在应用程序中指定特殊的 ``static_path`` 来提供静态文
  3. 件服务::
  5.     settings = {
  6.         "static_path": os.path.join(os.path.dirname(__file__), "static"),
  7.         "cookie_secret": "__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__",
  8.         "login_url": "/login",
  9.         "xsrf_cookies": True,
  10.     }
  11.     application = tornado.web.Application([
  12.         (r"/", MainHandler),
  13.         (r"/login", LoginHandler),
  14.         (r"/(apple-touch-icon\.png)", tornado.web.StaticFileHandler,
  15.          dict(path=settings['static_path'])),
  16.     ], **settings)
  18. 这些设置将自动的把所有以 ``/static/`` 开头的请求从static目录进行提供,
  19. e.g., ``http://localhost:8888/static/foo.png`` 将会通过指定的static目录
  20. 提供 ``foo.png`` 文件. 我们也自动的会从static目录提供 ``/robots.txt``
  21. 和 ``/favicon.ico`` (尽管它们并没有以 ``/static/`` 前缀开始).
  23. 在上面的设置中, 我们明确的配置Tornado 提供 ``apple-touch-icon.png``
  24. 文件从 `.StaticFileHandler` 根下, 虽然文件在static文件目录中.
  25. (正则表达式捕获组必须告诉 `.StaticFileHandler` 请求的文件名; 调用捕获组
  26. 把文件名作为方法的参数传递给处理程序.) 你可以做同样的事情 e.g.
  27. 从网站的根提供 ``sitemap.xml`` 文件. 当然, 你也可以通过在你的HTML中使用
  28. ``<link />`` 标签来避免伪造根目录的 ``apple-touch-icon.png`` .
  30. 为了改善性能, 通常情况下, 让浏览器主动缓存静态资源是个好主意, 这样浏览器
  31. 就不会发送不必要的可能在渲染页面时阻塞的 ``If-Modified-Since`` 或
  32. ``Etag`` 请求了. Tornado使用 *静态内容版本(static content versioning)*
  33. 来支持此项功能.
  35. 为了使用这些功能, 在你的模板中使用 `~.RequestHandler.static_url` 方法
  36. 而不是直接在你的HTML中输入静态文件的URL::
  38.     <html>
  39.        <head>
  40.           <title>FriendFeed - {{ _("Home") }}</title>
  41.        </head>
  42.        <body>
  43.          <div><img src="{{ static_url("images/logo.png") }}"/></div>
  44.        </body>
  45.      </html>
  47. ``static_url()`` 函数将把相对路径翻译成一个URI类似于
  48. ``/static/images/logo.png?v=aae54``. 其中的 ``v`` 参数是 ``logo.png``
  49. 内容的哈希(hash), 并且它的存在使得Tornado服务向用户的浏览器发送缓存头,
  50. 这将使浏览器无限期的缓存内容.
  52. 因为参数 ``v`` 是基于文件内容的, 如果你更新一个文件并重启服务, 它将发送
  53. 一个新的 ``v`` 值, 所以用户的浏览器将会自动的拉去新的文件. 如果文件的内
  54. 容没有改变, 浏览器将会继续使用本地缓存的副本, 而不会从服务器检查更新,
  55. 显著的提高了渲染性能.
  57. 在生产中, 你可能想提供静态文件通过一个更优的静态服务器, 比如
  58. `nginx <http://nginx.net/>`_ . 你可以配置任何web服务器识别通过
  59. ``static_url()`` 提供的版本标签并相应的设置缓存头. 下面是我们在
  60. FriendFeed 使用的nginx相关配置的一部分::
  62.     location /static/ {
  63.         root /var/friendfeed/static;
  64.         if ($query_string) {
  65.             expires max;
  66.         }
  67.      }
  69. .. _debug-mode:
  71. 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 把一个Tornado .Application 转换成WSGI应用. 在这个例子中, 配置你的WSGI容器发 现 application 对象:

.. testcode::

  1. import tornado.web
  2. import tornado.wsgi
  4. class MainHandler(tornado.web.RequestHandler):
  5.     def get(self):
  6.         self.write("Hello, world")
  8. tornado_app = tornado.web.Application([
  9.     (r"/", MainHandler),
  10. ])
  11. application = tornado.wsgi.WSGIAdapter(tornado_app)

.. testoutput:: :hide:

查看 appengine example application <https://github.com/tornadoweb/tornado/tree/stable/demos/appengine>_ 以 了解AppEngine在Tornado上开发的完整功能.