使用说明书
##########


常见参数
========

uwsgi option::

    -s|--socket                            bind to the specified UNIX/TCP socket using default protocol
    -s|--uwsgi-socket                      bind to the specified UNIX/TCP socket using uwsgi protocol
    -p|--processes                         spawn the specified number of workers/processes
    -d|--daemonize                         daemonize uWSGI
    --env                                  set environment variable
    --ini                                  load config from ini file
    --touch-reload                         reload uWSGI if the specified file is modified/touched
    -w|--module                            load a WSGI module
    -R|--max-requests                      reload workers after the specified amount of managed requests
    -t|--harakiri                          set harakiri timeout
    --limit-as                             limit processes address space/vsz
    -M|--master                             enable master process

..note:: master process (will respawn your processes when they die). For all practical serving deployments it is generally a good idea to use master mode. uWSGI 内置的预派生 + 线程 多 worker 管理模式，通过打开 master 开关激活。对于所有实际的服务部署，使用 master 模式是个好主意。




example::

    //并发4个thread
    uwsgi -s :9090 -w myapp -p 4
    //主控thread+4个thread
    uwsgi -s :9090 -w myapp -M -p 4
    //运行超30秒的client直接忽略
    uwsgi -s :9090 -w myapp -M -p 4 -t 30
    //限制memory空间128M
    uwsgi -s :9090 -w myapp -M -p 4 -t 30 --limit-as 128
    //服务超10000req自动respawn
    uwsgi -s :9090 -w myapp -M -p 4 -t 30 --limit-as 128 -R 10000
    后台运行
    uwsgi -s :9090 -w myapp -M -p 4 -t 30 --limit-as 128 -R 10000 -d uwsgi.log




基本使用
========

::

    $ uwsgi --http :9090 --wsgi-file foobar.py

等同 ``uwsgi yourfile.ini`` ::

    [uwsgi]
    http = :9090
    wsgi-file = myproject/wsgi.py


.. warning:: Note Do not use ``--http`` when you have a frontend webserver or you are doing some form of benchmark, use ``--http-socket``. ``--http`` 生成一个额外的进程，转发请求到一系列的 worker (将它想象为一种形式的盾牌，与 apache 或者 nginx 同级)，而 ``--http-socket`` 设置 worker 为原生使用 http 协议。



并发
====

用 --processes 选项添加更多的进程，或者使用 --threads 选项添加更多的线程::

    uwsgi --http :9090 --wsgi-file foobar.py --master --processes 4 --threads 2

A note on Python threads
------------------------

* If you start uWSGI without threads, the Python GIL will not be enabled, so threads generated by your application will never run. 
* If you want to maintain Python threads support without starting multiple threads for your application, just add the --enable-threads option (or enable-threads = true in ini style).



GIL
---

* GIL（全局解释器锁）是 Python 解释器中的一个特性，用于管理多线程的执行。在 CPython 解释器中，由于存在 GIL，同一时刻只有一个线程能够执行 Python 字节码。这意味着在多核系统上，Python 多线程程序并不能充分利用多核处理器的性能优势。
* GIL 的存在是为了简化内存管理和实现解释器的设计，但同时也引入了一些限制。由于 GIL 的存在，Python 多线程在 CPU 密集型任务上的性能表现不如单线程或者使用多进程的方式。然而，在 I/O 密集型任务上，多线程仍然可以提供一定的性能改进，因为 GIL 在等待 I/O 时会释放，允许其他线程执行。
* 需要注意的是，不是所有的 Python 解释器都有 GIL。例如，Jython 和 IronPython 等解释器在设计上就没有 GIL，因此在多线程方面可能有不同的行为。在 Python 中，如果需要充分利用多核处理器，可以考虑使用多进程、异步编程或者使用其他支持并行性的工具和库。





stats监控
=========

启动::

    $ uwsgi --http :9090 --wsgi-file foobar.py --master \
        --processes 4 --threads 2 --stats 127.0.0.1:9191



监控::

    1. telnet 到端口 9191
    2. uwsgitop (需专门安装软件)
    3. uwsgi --connect-and-read 127.0.0.1:9191


.. warning:: Attention Bind the stats socket to a private address (unless you know what you are doing), otherwise everyone could access it!


webserver
=========

* uWSGI natively speaks HTTP, FastCGI, SCGI and its specific protocol named “uwsgi”(The best performing protocol is obviously uwsgi)

Nginx
-----

A common nginx config is the following::

    location / {
        include uwsgi_params;
        uwsgi_pass 127.0.0.1:3031;
    }

* This means “pass every request to the server bound to port 3031 speaking the uwsgi protocol”.
* Now we can spawn uWSGI to natively speak the uwsgi protocol::

    uwsgi --socket 127.0.0.1:3031 --wsgi-file foobar.py \
        --master --processes 4 --threads 2 --stats 127.0.0.1:9191

    # 指定sock文件
    uwsgi --socket /var/run/uwsgi.sock --wsgi-file foobar.py \
        --master --processes 4 --threads 2 --stats 127.0.0.1:9191

If your proxy/webserver/router speaks HTTP, tell uWSGI to natively speak the http protocol::

    uwsgi --http-socket 127.0.0.1:3031 --wsgi-file foobar.py \
        --master --processes 4 --threads 2 --stats 127.0.0.1:9191

    注: this is different from --http that will spawn a proxy by itself



Flask
-----

示例::

    $ uwsgi --socket 127.0.0.1:3031 --wsgi-file myflaskapp.py --callable app \
        --processes 4 --threads 2 --stats 127.0.0.1:9191





Security and availability
=========================

::

    [uwsgi]

    # 指定https
    https = :9090,foobar.crt,foobar.key

    # 需要绑定到特许端口 (例如用于 HTTPS 的 443)，那么使用共享 socket
    # 它们在去除权限之前创建，并且可以通过 =N 语法引用，其中， N 是 socket 号 (从 0 开始)
    shared-socket = :443
    https = =0,foobar.crt,foobar.key

    # drop privileges using the uid and gid options
    # 使用 uid 和 gid 选项来去除 root 用户权限
    uid = foo
    gid = bar

    chdir = path_to_web2py
    module = wsgihandler
    master = true

    # 并发
    processes = 8

    # 定时器: 它是一个监控器 (由 master 进程管理)，会摧毁那些阻塞超过 30 秒的 worker
    # 解决 卡住的请求 问题
    harakiri = 30