Tornado-基本入门
这篇讲什么
- Tornado 既是 Web 框架也是 HTTP 服务器,核心卖点是异步非阻塞 IO,适合长连接、WebSocket 和高并发场景;这篇先把「一个能跑的最小服务」写出来。
- 覆盖安装、两种启动写法、
bind()与start()的多进程语义、tornado.options的命令行与配置文件、日志开关,以及访问日志和 keep-alive 的实测行为。 - 所有结论都在本机跑过:Windows 用 Tornado 6.6 + Python 3.14.10,多进程部分另在 WSL Ubuntu(8 核)实测,因为
fork在 Windows 上根本不可用。
Tornado 是什么
-
官方首页的定义是一句话:Tornado is a Python web framework using non-blocking I/O(用非阻塞 IO 的 Python Web 框架),并且强调它「scales to tens of thousands of open connections」——能撑住上万个同时打开的连接。
-
所以 Tornado 其实是三个东西装在一个包里,这也是它和 Django、Flask 最大的区别:
- 一个 Web 框架:路由 +
RequestHandler+ 模板渲染。 - 一个 HTTP 服务器:
tornado.httpserver.HTTPServer,自己监听端口,不需要再套一层 WSGI 服务器。 - 一个 异步网络库:
AsyncHTTPClient、IOLoop、WebSocket 这些都能单独用,跟 Web 无关。
- 一个 Web 框架:路由 +
-
「高效原理」这张老图仍然说得通:单个进程内用一个事件循环(IOLoop)盯着所有 socket,谁可读可读谁,不靠线程也不靠进程数堆并发。

C10K 是什么
-
C10K = Concurrently handling 10K connections,即单机同时扛一万个连接,是当年 Linux 网络编程的一个门槛指标,Tornado 就是为这类场景设计的。
-
传统「一个连接一个线程/进程」的模型,一万个连接就要一万个线程,光调度和内存就撑不住;Tornado 用非阻塞 IO + 事件循环,一个线程管几千个连接。
-
官方对平台的说法(原文口径):Python 3 是硬要求;在支持 epoll(Linux)、kqueue(BSD/macOS)的系统上性能和扩展性最好;Windows 能跑,但不是官方推荐的生产平台。
-
本机实测印证了「Windows 能跑」:
IOLoop.current()拿到的其实是 asyncio 的ProactorEventLoop,服务起得来、请求答得了。1
2IOLoop.current() 实际类型: AsyncIOMainLoop
跑起来的事件循环: ProactorEventLoop -
结论:学习和开发用 Windows 完全没问题;真要上线扛并发,按官方口径放 Linux。
什么时候该用它
- 长连接场景(WebSocket 聊天、实时推送、长轮询)——这是 Tornado 的主场。
- 需要同时向外发很多请求(爬虫、聚合多个上游接口)——
AsyncHTTPClient很合适。 - 普通 CRUD 后台、要现成的 ORM 和管理页面——用 Django 更省事,别为了「异步」二字上 Tornado。
与 Django 的分工
-
老笔记拿 Tornado 和 Web.py 类比,那个框架早就没人用了;现在对比的参照物是 Django 和 Flask。
维度 Django Flask Tornado 定位 大而全,注重开发效率 微框架,注重灵活 少而精,注重并发 自带 HTTP 服务器 只有开发用的 只有开发用的 自带生产可用的 IO 模型 同步阻塞(另有 ASGI 异步路线) 同步阻塞 异步非阻塞 ORM 内置且和框架深度绑定 靠扩展(Flask-SQLAlchemy) 没有,随便挑(SQLAlchemy/Tortoise/原生驱动) 管理后台 内置 admin 无 无 模板 Django Template Jinja2 自带 Tornado 模板(也是 Jinja 风格) WebSocket 要靠 Channels 要靠扩展 内置 -
耦合度这条老笔记说得对:Django 的便利是绑在它的 ORM 上的,换掉 ORM 就享受不到那一堆自动化;Tornado 反过来,核心很薄,什么都得自己接。
-
两者不是二选一:常见做法是业务后台用 Django,实时那块单独用 Tornado 服务,前面用 nginx 按路径分流。
安装与最小服务
-
装最新的就行,本系列基线是 Tornado 6.6:
1
pip install tornado
1
2
3tornado 6.6 | python 3.14.10
Requires-Python: >= 3.11
Summary: Tornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed. -
官方文档把
pycurl、pycares列为可选前置依赖,本机两个都没装也照常跑:默认的异步 HTTP 客户端是纯 Python 的SimpleAsyncHTTPClient;只有你去import tornado.curl_httpclient才会因为缺 pycurl 报ModuleNotFoundError。 -
老笔记钉的是
pip install tornado==5.1.1。5.x 从 2018 年起就没再发版,tornado.web.run_simple、web.execute、@web.asynchronous、web.stream_callback这些入口在 6.x 里已经删干净(实测hasattr全为 False),所以别照抄 5.1.1 那套。 -
最小可跑服务,一个文件就够:
app.py 1
2
3
4
5
6
7
8
9
10
11
12
13import tornado.ioloop
import tornado.web
class IndexHandler(tornado.web.RequestHandler):
def get(self):
self.write("hello, tornado")
if __name__ == "__main__":
app = tornado.web.Application([(r"/", IndexHandler)])
app.listen(8888)
tornado.ioloop.IOLoop.current().start() -
实测浏览器或 curl 访问
http://127.0.0.1:8888/:1
2
3
4
5HTTP/1.1 200 OK
Server: TornadoServer/6.6
Content-Type: text/html; charset=UTF-8
hello, tornado终端同时打一行访问日志:
1
200 GET / (127.0.0.1) 0.33ms
-
逐行看懂:
RequestHandler是「一个 URL 对应一个类」,相当于 Django 的视图函数;类里写了哪个 HTTP 方法名的方法,就只接哪个方法。Application([(r"/", IndexHandler)])收的是「正则 → 处理类」的列表,这就是路由表;r"/"里的r是 Python 的原始字符串,正则里反斜杠不用 double。app.listen(8888)只是把端口占上,真正开始处理请求要等最后一行的事件循环启动。
-
只写
get的 handler,收到 POST 会直接 405,实测:1
2POST / -> HTTP 405
405 POST / (127.0.0.1) 0.33ms -
能接哪些方法由类属性决定,实测默认值:
1
RequestHandler.SUPPORTED_METHODS -> ('GET', 'HEAD', 'POST', 'DELETE', 'PATCH', 'PUT', 'OPTIONS')
两种启动写法
-
app.listen(port)是简写,内部就是造一个HTTPServer。等价的「显式」写法:app.py 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import tornado.httpserver
import tornado.ioloop
import tornado.web
class IndexHandler(tornado.web.RequestHandler):
def get(self):
self.write("hello, tornado")
if __name__ == "__main__":
app = tornado.web.Application([(r"/", IndexHandler)])
http_server = tornado.httpserver.HTTPServer(app)
http_server.listen(8888)
tornado.ioloop.IOLoop.current().start() -
app.listen()的返回值就是那个HTTPServer对象,实测类型:1
app.listen(8905) -> <class 'tornado.httpserver.HTTPServer'>
-
两个签名放这里,参数名以后要查就用得上:
1
2
3
4
5Application.listen(port, address=None, *, family=AF_UNSPEC, backlog=128,
flags=None, reuse_port=False, **kwargs) -> HTTPServer
HTTPServer.bind(port, address=None, family=AF_UNSPEC, backlog=128,
flags=None, reuse_port=False) -> None
HTTPServer.start(num_processes=1, max_restarts=None) -> None
listen 之后到底有没有在监听
-
老笔记那句「绑定监听端口,注意:此时服务器并没有开启监听」半对半错,实测拆开看:
test_bind.py 1
2
3
4
5
6
7
8
9
10
11import socket
import tornado.httpserver
import tornado.web
app = tornado.web.Application([(r"/", IndexHandler)])
http_server = tornado.httpserver.HTTPServer(app)
http_server.bind(8902) # 没有 start(),也没进事件循环
s = socket.create_connection(("127.0.0.1", 8902), timeout=2)
s.sendall(b"GET / HTTP/1.1\r\nHost: x\r\n\r\n")
print(s.recv(100)) # 等 2 秒,超时1
2TCP 三次握手: 成功(OS 层已经在 LISTEN)
发 HTTP 请求后 2 秒没响应(没人 accept,事件循环没跑) -
准确说法是:
bind()(以及listen())已经把端口占住、内核也开始收连接进 backlog,但没有 accept、也没有处理请求,所以端口是「占着但不干活」。要真正服务,必须让IOLoop跑起来。 -
也正因为如此,
listen()之后不start()的进程会把端口一直占住,调试时 Ctrl+C 不干净就会留下「Address already in use」。
用 asyncio 起(现代写法)
-
Tornado 6 就是 asyncio 之上的封装,所以也可以反过来用
asyncio.run():app_async.py 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import asyncio
import tornado.ioloop
import tornado.web
class IndexHandler(tornado.web.RequestHandler):
def get(self):
self.write("hello, tornado")
async def main():
app = tornado.web.Application([(r"/", IndexHandler)])
http_server = tornado.httpserver.HTTPServer(app)
http_server.listen(8888)
await asyncio.Event().wait() # 让循环一直跑着
if __name__ == "__main__":
asyncio.run(main()) -
两种写法实测都能正常起服务。老笔记那种
IOLoop.current().start()仍然有效,是官方文档里一直在用的写法,继续用没问题。
多进程
-
Tornado 默认单进程:一个进程一个事件循环,靠异步扛并发。要吃满多核 CPU,才需要多进程。
-
官方给的多进程入口是
bind()+start():app.py 1
2
3
4
5
6if __name__ == "__main__":
app = tornado.web.Application([(r"/", IndexHandler)])
http_server = tornado.httpserver.HTTPServer(app)
http_server.bind(8888)
http_server.start(4) # 1 个父进程 + 4 个子进程
tornado.ioloop.IOLoop.current().start() -
start(n)的语义实测(WSL Ubuntu,nproc为 8):写法 进程数实测 说明 start(1)1 不 fork,父进程自己干 start(4)5 1 父 + 4 子 start(0)9 按 CPU 核数(8)+ 父进程 -
老笔记写的是「值为 None 或者小于等于 0,开启 CPU 核心数个子进程」,实测要补一句:
start(None)会直接AssertionError,能触发「按核数」的只有0(或负数)。 -
请求确实分散在不同子进程里(handler 返回自己的 pid):
1
六次请求返回的 pid: 85094 85094 85094 85095 85095 85095
注意只落在 4 个 worker 中的 2 个上——多个子进程共享同一个监听 socket,内核唤醒谁没有保证,分发本来就不均匀,别拿「请求数 ÷ 进程数」去预期。
-
Windows 上这条路是断的,实测三种写法:
1
2
3start(2) -> Exception: fork not available on windows
start(0) -> Exception: fork not available on windows
start(None) -> AssertionError原因是
start()靠fork复制进程,Windows 没有fork。所以在 Windows 上要开多进程,只能「一个进程一个端口」手动起多个实例,或者用reuse_port=True让多个进程各自 bind 同一端口(Linux 才支持)。 -
老笔记「不建议用
start()起多进程,推荐手动多进程」的三条理由仍然成立,值得原样记住:- 子进程是从父进程复制来的,创建子进程之前改过
IOLoop,会影响所有子进程。 - 所有进程由一条命令带起来,改代码必须整体重启,做不到不停服滚动更新。
- 所有进程共享一个端口,单独监控某个进程很麻烦。
- 子进程是从父进程复制来的,创建子进程之前改过
-
生产上更常见的做法是让进程管理器去管:Linux 用 systemd/supervisord 起 N 个单进程实例,或者干脆用
tornado.process.fork_processes();HTTPServer.start()适合「本机多核跑满」这种简单需求。
tornado.options
-
tornado.options是 Tornado 自带的一套「全局参数定义 + 从命令行/配置文件读值」的小框架,作用就是把port、debug这类参数集中起来,不用自己写argparse。 -
6.6 实测的
define()签名:1
2define(name, default=None, type=None, help=None, metavar=None,
multiple=False, group=None, callback=None) -
定义完就挂在
tornado.options.options这个全局对象上,取值为options.port。它自带一批内置选项,实测清单:1
2help, logging, log-to-stderr, log-file-prefix, log-file-max-size,
log-file-num-backups, log-rotate-when, log-rotate-interval, log-rotate-mode -
键名有个容易懵的细节:
define('max_body_count')存进去是max-body-count(下划线转连字符),但三种取法都通:options.max_body_count、options['max-body-count']、命令行--max-body-count=25或--max_body_count=30实测都能改到同一个值。
从命令行取值
-
完整可跑的示例:
app.py 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import tornado.httpserver
import tornado.ioloop
import tornado.options
import tornado.web
tornado.options.define("port", default=8000, type=int)
tornado.options.define("mylist", default=[], type=str, multiple=True)
class IndexHandler(tornado.web.RequestHandler):
def get(self):
self.write("port=%s list=%s" % (
tornado.options.options.port, tornado.options.options.mylist))
if __name__ == "__main__":
tornado.options.parse_command_line()
app = tornado.web.Application([(r"/", IndexHandler)])
http_server = tornado.httpserver.HTTPServer(app)
http_server.bind(tornado.options.options.port)
http_server.start(1)
tornado.ioloop.IOLoop.current().start()1
python app.py --port=8848 --mylist=good,nice,handsome,cool
1
GET / -> port=8848 list=['good', 'nice', 'handsome', 'cool']
-
类型会按
type转换,实测这些写法:定义 命令行 实测值 type=int--port=88488848(int)type=str, multiple=True--mylist=a,b,c['a', 'b', 'c']type=int, multiple=True--nums=1:4[1, 2, 3, 4](x:y是区间写法)type=bool--debug(不带值)True,等价--debug=truetype=bool--debug=falseFalsetype=datetime.timedelta--delta=90s/--delta=5mtimedelta(seconds=90)/timedelta(seconds=300)type=datetime.datetime--when=2026-11-06datetime(2026, 11, 6, 0, 0) -
type不写时按default的类型推断,实测default=7000推断成int;default也不写则按str处理(内部type记为str、值为None)。
三个实测到的坑
-
坑一:
parse_command_line(args)的第一个元素会被当成程序名跳过。它默认吃sys.argv,而sys.argv[0]就是脚本名。手工传列表时必须补一个占位,否则第一个参数白写:1
2parse_command_line(['--port=8848']) -> port 仍是默认值 8000
parse_command_line(['prog', '--port=8848']) -> port = 8848 -
坑二:不认识的选项会先打印整页帮助再报错,报错原文:
1
Error: Unrecognized command line option: 'nope'
-
坑三:转换失败抛的异常不一定友好,实测三种:
1
2
3--port=abc(type=int) -> ValueError: invalid literal for int() with base 10: 'abc'
--name(type=str 却不带值) -> Error: Option 'name' requires a value
--delta=abc(type=timedelta)-> Exception: (空消息,光秃秃一个 Exception) -
重复
define同一个名字,报错原文(老笔记说会报already define,实际措辞是这样):1
Error: Option 'port' already defined in E:\...\app.py
从配置文件取值
-
parse_config_file(path)读的是一个按 Python 语法写的文件(老笔记里那个文件就叫config,没有扩展名也行):config 1
2port = 7000
mylist = ['good', 'nice']app.py 1
tornado.options.parse_config_file("config")
1
port = 7000 | mylist = ['good', 'nice']
-
老笔记说「不支持字典类型」,实测结论要精确一点:字典能不能读进来,取决于你有没有
define它、以及type是什么。1
2
3配置文件里有 adict = {'k': 1}
没 define adict -> 这个键被直接忽略,options 里查不到
define('adict', type=dict) 再 parse -> adict = {'k': 1} -
同理,配置文件里那些没 define 过的键(哪怕是
computed = 2 * 3这种表达式)都不报错、也不进 options——它确实是按 Python 执行的,只是结果没人接。 -
第三种做法(老笔记的「最终版本」)跟
tornado.options无关,就是普通地写个配置模块再 import:config.py 1
2
3
4options = {
"port": 8080,
"mylist": ["good", "nice", "handsome"],
}app.py 1
2
3import config
http_server.bind(config.options["port"])这种做法没有命令行覆盖、没有类型转换,好处是零依赖;项目一大还是前两种更成体系。
日志
-
只要调了
parse_command_line()或parse_config_file(),Tornado 就顺手把logging配好了,实测:1
2没 parse -> handlers=0 级别=WARNING
parse_command_line -> handlers=1 级别=INFO默认的日志格式串(实测从 handler 的 formatter 里读出来的):
1
%(color)s[%(levelname)1.1s %(asctime)s %(module)s:%(lineno)d]%(end_color)s %(message)s
-
关掉日志的两种办法,实测在新进程里都真的关掉了(
handlers=0):app.py 1
2
3
4import tornado.options
tornado.options.options.logging = None # 必须在 parse 之前
tornado.options.parse_config_file("config")1
python app.py --port=8848 --logging=none
-
--logging的取值实测:取值 根 logger 级别 debugDEBUGinfo(默认)INFOwarningWARNINGerrorERRORnone不配 handler(等于关掉) -
访问日志由
RequestHandler的log_request负责,格式实测:1
2
3200 GET / (127.0.0.1) 0.33ms
404 GET /x?a=1 (127.0.0.1) 0.39ms
405 POST / (127.0.0.1) 0.33ms即「状态码 方法 路径 (客户端 IP) 耗时」,路径带查询串、耗时精确到 0.01ms,排查慢请求很方便。
-
出未捕获异常时,日志里是完整的 traceback,响应是 500 页面:
1
2
3
4
5
6Uncaught exception GET / (127.0.0.1)
HTTPServerRequest(protocol='http', host='x', method='GET', uri='/', version='HTTP/1.1', remote_ip='127.0.0.1')
Traceback (most recent call last):
...
AttributeError: 'HTTPServerRequest' object has no attribute 'remote_addr'
500 GET / (127.0.0.1) 3.20ms这条 traceback 本身也是个实测结论:取客户端 IP 要写
self.request.remote_ip,remote_addr不存在(那是 Flask/Werkzeug 那边的名字)。
连接与转发头
-
老笔记「使用场景」里讲的 HTTP 持久连接,在 Tornado 上是默认行为,实测在同一条 TCP 连接上连发两个 HTTP/1.1 请求:
1
2第一个响应头 Connection: (没有这个头,即默认 keep-alive)
同一连接第二个请求也拿到了: True- HTTP/1.1 默认持久连接,所以服务端不用带
Connection: keep-alive。 - 用 HTTP/1.0 请求时,响应同样不带
Connection头,连接按 1.0 的语义关闭。
- HTTP/1.1 默认持久连接,所以服务端不用带
-
反向代理场景下取真实客户端 IP,Tornado 的做法是给
HTTPServer传xheaders=True,它会读X-Real-IP(以及X-Scheme):app.py 1
http_server = tornado.httpserver.HTTPServer(app, xheaders=True)
实测同一个请求(客户端伪造了
X-Real-IP: 9.9.9.9):1
2xheaders=False -> remote_ip = '127.0.0.1'
xheaders=True -> remote_ip = '9.9.9.9' -
这条开关的安全含义和 Flask 那边一模一样:只有前面确实是一层可信代理时才开,否则客户端自己塞一个头就能伪造来源 IP。Tornado 没有
ProxyFix那种「按层数取第 N 个」的处理,xheaders就是简单地信X-Real-IP,多层代理时要在 nginx 侧把X-Real-IP设成正确的值。
性能说法怎么看
-
老笔记那句「官方用 nginx 反向代理做对比,最大浏览量超过第二名近 40%」,现在在官方文档里找不到这个榜单,属于早期(FriendFeed 时代)的宣传口径,别再当依据引用。
-
想要量级感,本机自己测一个数才有意义。同一台机器、同一个 handler,用 Tornado 自己的异步客户端打 5000 个请求:
bench.py 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import asyncio
import tornado.httpclient
import tornado.ioloop
import tornado.web
class IndexHandler(tornado.web.RequestHandler):
def get(self):
self.write("ok")
async def run(n_conn=50, n_each=100):
client = tornado.httpclient.AsyncHTTPClient()
async def worker():
for _ in range(n_each):
await client.fetch("http://127.0.0.1:8899/")
loop = asyncio.get_running_loop()
t0 = loop.time()
await asyncio.gather(*(worker() for _ in range(n_conn)))
dt = loop.time() - t0
return n_conn * n_each, dt
if __name__ == "__main__":
app = tornado.web.Application([(r"/", IndexHandler)])
server = app.listen(8899)
total, dt = tornado.ioloop.IOLoop.current().run_sync(run)
print("%d 个请求 / %.2f s = %.0f req/s" % (total, dt, total / dt))
server.stop()1
5000 个请求 / 11.60 s = 431 req/s(50 并发 × 100 次)
-
这个数字只能说明「Windows + 纯 Python 客户端 + 回环」这一套的量级,不能拿去和任何 Linux 榜单比:压测工具本身(这里是
SimpleAsyncHTTPClient)往往比服务端先到瓶颈。真要评估,用wrk/hey这类工具在目标部署平台上测,并且同时看 CPU、内存和 p99 延迟。 -
能确定的只有方向:连接数越高、单连接越「挂着不动」,Tornado 相对同步框架的优势越明显;纯 CPU 计算密集的场景,异步帮不上忙。