访问官网
Github
文档
论文Granian
一个用于 Python 应用程序的 Rust HTTP 服务器。
设计理念
Granian 设计的主要原因如下：
- 拥有一个单一、正确的 HTTP 实现，支持 1、2（最终会支持 3）版本
- 为多个平台提供单一软件包
- 避免在 Unix 系统上常见的 Gunicorn + uvicorn + http-tools 依赖组合
- 与现有替代方案相比，提供稳定的性能
特性
- 支持 ASGI/3、RSGI 和 WSGI 接口应用程序
- 实现 HTTP/1 和 HTTP/2 协议
- 支持 HTTPS
- 支持 Websockets
快速入门
你可以使用 pip 安装 Granian：
$ pip install granian
在你的 main.py 中创建一个 ASGI 应用程序：
async def app(scope, receive, send):
assert scope['type'] == 'http'
await send({
'type': 'http.response.start',
'status': 200,
'headers': [
[b'content-type', b'text/plain'],
],
})
await send({
'type': 'http.response.body',
'body': b'Hello, world!',
})
然后运行它：
$ granian --interface asgi main:app
你也可以使用 RSGI 规范创建一个应用程序：
async def app(scope, proto):
assert scope.proto == 'http'
proto.response_str(
status=200,
headers=[
('content-type', 'text/plain')
],
body="Hello, world!"
)
然后使用以下命令运行：
$ granian --interface rsgi main:app
选项
你可以使用 --help 命令查看 Granian 提供的所有选项：
$ granian --help
用法：granian [选项] APP
APP 要运行的应用程序目标。 [必需]
选项：
--host TEXT 要绑定的主机地址 [环境变量：GRANIAN_HOST；默认值：(127.0.0.1)]
--port INTEGER 要绑定的端口 [环境变量：GRANIAN_PORT；默认值：8000]
--interface [asgi|asginl|rsgi|wsgi]
应用程序接口类型 [环境变量：GRANIAN_INTERFACE；默认值：(rsgi)]
--http [auto|1|2] HTTP 版本 [环境变量：GRANIAN_HTTP；默认值：(auto)]
--ws / --no-ws 启用 WebSocket 处理 [环境变量：GRANIAN_WEBSOCKETS；默认：(启用)]
--workers INTEGER RANGE 工作进程数量 [环境变量：GRANIAN_WORKERS；默认值：1；x>=1]
--threads INTEGER RANGE 线程数量（每个工作进程）[环境变量：GRANIAN_THREADS；默认值：1；x>=1]
--blocking-threads INTEGER RANGE
阻塞线程数量（每个工作进程）[环境变量：GRANIAN_BLOCKING_THREADS；x>=1]
--threading-mode [runtime|workers]
使用的线程模式 [环境变量：GRANIAN_THREADING_MODE；默认值：(workers)]
--loop [auto|asyncio|uvloop] 事件循环实现 [环境变量：GRANIAN_LOOP；默认值：(auto)]
--opt / --no-opt 启用循环优化 [环境变量：GRANIAN_LOOP_OPT；默认：(禁用)]
--backlog INTEGER RANGE 最大连接队列长度（全局）[环境变量：GRANIAN_BACKLOG；默认值：1024；x>=128]
--backpressure INTEGER RANGE 并发处理的最大请求数（每个工作进程）[环境变量：GRANIAN_BACKPRESSURE；默认值：(backlog/workers)；x>=1]
--http1-buffer-size INTEGER RANGE
设置 HTTP/1 连接的最大缓冲区大小 [环境变量：GRANIAN_HTTP1_BUFFER_SIZE；默认值：417792；x>=8192]
--http1-keep-alive / --no-http1-keep-alive
启用或禁用 HTTP/1 keep-alive [环境变量：GRANIAN_HTTP1_KEEP_ALIVE；默认：(启用)]
--http1-pipeline-flush / --no-http1-pipeline-flush
聚合 HTTP/1 刷新以更好地支持流水线响应（实验性）[环境变量：GRANIAN_HTTP1_PIPELINE_FLUSH；默认：(禁用)]
--http2-adaptive-window / --no-http2-adaptive-window
设置是否为 HTTP/2 使用自适应流控制 [环境变量：GRANIAN_HTTP2_ADAPTIVE_WINDOW；默认：(禁用)]
--http2-initial-connection-window-size INTEGER
设置 HTTP/2 的最大连接级流控制 [环境变量：GRANIAN_HTTP2_INITIAL_CONNECTION_WINDOW_SIZE；默认值：1048576]
--http2-initial-stream-window-size INTEGER
设置 HTTP/2 流级流控制的 `SETTINGS_INITIAL_WINDOW_SIZE` 选项 [环境变量：GRANIAN_HTTP2_INITIAL_STREAM_WINDOW_SIZE；默认值：1048576]
--http2-keep-alive-interval INTEGER
设置发送 HTTP/2 Ping 帧以保持连接活跃的间隔 [环境变量：GRANIAN_HTTP2_KEEP_ALIVE_INTERVAL]
--http2-keep-alive-timeout INTEGER
设置接收 HTTP/2 keep-alive ping 确认的超时时间 [环境变量：GRANIAN_HTTP2_KEEP_ALIVE_TIMEOUT；默认值：20]
--http2-max-concurrent-streams INTEGER
设置 HTTP/2 连接的 SETTINGS_MAX_CONCURRENT_STREAMS 选项 [环境变量：GRANIAN_HTTP2_MAX_CONCURRENT_STREAMS；默认值：200]
--http2-max-frame-size INTEGER 设置 HTTP/2 使用的最大帧大小 [环境变量：GRANIAN_HTTP2_MAX_FRAME_SIZE；默认值：16384]
--http2-max-headers-size INTEGER
设置接收的头部帧的最大大小 [环境变量：GRANIAN_HTTP2_MAX_HEADERS_SIZE；默认值：16777216]
--http2-max-send-buffer-size INTEGER
设置每个 HTTP/2 流的最大写入缓冲区大小 [环境变量：GRANIAN_HTTP2_MAX_SEND_BUFFER_SIZE；默认值：409600]
--log / --no-log 启用日志记录 [环境变量：GRANIAN_LOG_ENABLED；默认：(启用)]
--log-level [critical|error|warning|warn|info|debug]
日志级别 [环境变量：GRANIAN_LOG_LEVEL；默认值：(info)]
--log-config FILE 日志配置文件（json）[环境变量：GRANIAN_LOG_CONFIG]
--access-log / --no-access-log 启用访问日志 [环境变量：GRANIAN_LOG_ACCESS_ENABLED；默认：(禁用)]
--access-log-fmt TEXT 访问日志格式 [环境变量：GRANIAN_LOG_ACCESS_FMT]
--ssl-keyfile FILE SSL 密钥文件 [环境变量：GRANIAN_SSL_KEYFILE]
--ssl-certificate FILE SSL 证书文件 [环境变量：GRANIAN_SSL_CERTIFICATE]
--url-path-prefix TEXT 应用程序挂载的 URL 路径前缀 [环境变量：GRANIAN_URL_PATH_PREFIX]
--respawn-failed-workers / --no-respawn-failed-workers
在意外退出时启用工作进程重生 [环境变量：GRANIAN_RESPAWN_FAILED_WORKERS；默认：(禁用)]
--respawn-interval FLOAT 工作进程重生之间的睡眠秒数 [环境变量：GRANIAN_RESPAWN_INTERVAL；默认值：3.5]
--reload / --no-reload 启用应用程序文件更改时的自动重载（需要 granian[reload] 额外包）[环境变量：GRANIAN_RELOAD；默认：(禁用)]
--process-name TEXT 设置进程的自定义名称（需要 granian[pname] 额外包）[环境变量：GRANIAN_PROCESS_NAME]
--version 显示版本并退出
--help 显示此消息并退出
访问日志格式
可以通过指定要包含的原子（见下文）来配置访问日志格式。默认情况下，Granian 将使用 `[%(time)s] %(addr)s - "%(method)s %(path)s %(protocol)s" %(status)d %(dt_ms).3f` 作为格式。
访问日志原子
以下原子可供使用：
| 标识符 | 描述 |
| --- | --- |
| addr | 客户端远程地址 |
| time | 请求的日期时间 |
| dt_ms | 请求持续时间（毫秒） |
| status | HTTP 响应状态 |
| path | 请求路径（不含查询字符串） |
| query_string | 请求查询字符串 |
| method | 请求 HTTP 方法 |
| scheme | 请求协议 |
| protocol | HTTP 协议版本 |
进程和线程
Granian 提供了不同的选项来配置要运行的进程和线程数量，特别是：
- **workers**：持有专用 Python 解释器运行应用程序的进程总数
- **threads**：每个 worker 执行网络 I/O 的 Rust 线程数
- **blocking threads**：每个 worker 参与阻塞操作的 Rust 线程数。这些线程的主要作用是处理阻塞 I/O（如打开文件），但在 WSGI 等同步协议中，这些线程还负责与应用程序代码交互。
一般来说，Granian 会尽最大努力自动为线程配置选择适当的值，让你只需负责选择所需的 worker 数量。
这里没有"黄金法则"，因为这些数字在很大程度上取决于你的应用程序行为和部署目标，但我们可以列出一些建议：
- 将 worker 数量与 CPU 核心数量匹配通常是最佳起点；在 Docker 或 K8s 等容器化环境中，最好每个容器使用 1 个 worker，然后使用相关的编排器来扩展容器；
- 默认的线程数对绝大多数应用程序来说都没问题；对于处理多个并发打开的 WebSocket 的应用程序，你可能需要增加这个数字；
- 默认的阻塞线程数应该适用于大多数应用程序；在 WSGI 等同步协议中，这也会影响你可以处理的并发请求数，但你应该使用 `backpressure` 配置参数来控制它，只有当你的应用程序平均响应时间非常低（毫秒级）时，才设置较低的阻塞线程数；
此外，你通常应该避免根据其他服务器的数字来配置 worker 和线程，因为 Granian 的架构与 Gunicorn 或 Uvicorn 等项目有很大不同。
### 线程模式
Granian 提供两种不同的线程范式，这是因为内部 Rust 运行时可以是多线程的——与 Python 事件循环只能作为单线程运行不同。
假设你用相关选项指定 N 个线程，在 **workers** 线程模式下，Granian 将生成 N 个单线程 Rust 运行时，而在 **runtime** 线程模式下，Granian 将生成一个具有 N 个线程的多线程运行时。
基准测试表明，**workers** 模式在进程数量较少时更有效，而 **runtime** 模式在 CPU 数量较多时似乎可以更有效地扩展。但实际性能将取决于特定的应用程序代码，因此 *你的实际情况可能有所不同*。
### 事件循环优化
使用 `--opt` 选项，Granian 将为 Python 协程和可等待对象使用自定义任务处理程序，以提高 Python 代码执行效率。由于这些处理程序的性质，一些依赖 `asyncio` 内部机制的库和特定应用程序代码可能无法正常工作。
你可以测试这些优化对你的应用程序造成的影响，并决定是否启用它们或保持禁用状态（默认情况下）。
## 项目状态
Granian 目前正在积极开发中。
Granian 兼容 Python 3.8 及以上版本。
## 许可证
Granian 在 BSD 许可证下发布。
