[Flask] Flask 基于子域名的蓝图管理

在 Flask 中，蓝图（Blueprint）通常是基于路径进行分派的，因此我们看到典型的注册代码一般类似这样：

app.register_blueprint(home_bp, url_prefix='...')

相对少见的另一种用法是，Blueprint 也可以通过子域名来分派，这涉及到程序结构上会有一些改变，同时也会带来一些新的问题（当然都是可以解决的）。使用子域名是大型网站的常规做法，同时也使得 URL 路径更有针对性，比如提供一个 https://api.mydomain.com/... 比起所有页面都堆到 https://mydomain.com/ 下面，看上去也显得更专业一些。我自己也在尝试通过这种方式重构自己的网站，最开始尝试的是每个域名使用一个单独的 app 去管理，但很快发现如果一些比较小的功能也做成独立的网站，会带来比较多额外的管理负担。因此，把这些功能合并到一个app，对外又能通过子域名公开，是不错的做法。因此，我对这种实现做了一些尝试，并对遇到的问题和解决办法做一个记录，以供自己和其他朋友参考。

域名管理

首先需要注意的是，由于需要区分不同的域名，以前那种在开发环境下统一用 localhost 做域名的做法现在行不通了。大型的网站可能会考虑用自定义域名解析的方式实现统一管理，我们现在的场景没那么复杂，简单在 hosts 里面加几条记录也就足够了。

127.0.0.1              yuhao.space
127.0.0.1              www.yuhao.space
127.0.0.1              blog.yuhao.space

基本应用

添加域名记录以后，我们来写一个简单的测试程序，检查一下域名分派在开发环境下是否正常。这里需要注意的几个点：

• app.config['SERVER_NAME'] 需要指向基本域名，包括端口（Flask 默认为5000）;
• 创建 Blueprint 需要添加 subdomain 参数指向子域名（除主域名外）。

我们模拟两个域名来测试：一个主域名和一个博客域名（blog）。

from flask import Flask, Blueprint

home_bp = Blueprint('home', __name__)
blog_bp = Blueprint('blog', __name__)

@home_bp.route('/')
def home_index():
    return 'home index'

@blog_bp.route('/')
def blog_index():
    return 'blog index'


def create_app():

    def register_blueprints(app):
        app.register_blueprint(home_bp)
        app.register_blueprint(blog_bp, subdomain='blog')

    app = Flask(__name__)
    app.config['SERVER_NAME'] = 'yuhao.space:5000'
    register_blueprints(app)
    return app

app = create_app()

if __name__ == '__main__':
    app.run(debug=True)

运行程序，然后打开浏览器，分别浏览如下地址：

• http://yuhao.space:5000/
• http://blog.yuhao.space:5000/

很好，一切正常。接下来看看在生产环境下表现如何。

使用 Nginx 作为反向代理

在生产环境下，我们基本上不会把 Flask 应用直接暴露在公网上，而是使用类似 Nginx 这样的服务器作为前端代理。这种部署模式会带来一些额外的复杂性，而且容易出错（特别是配置方面），需要仔细验证。同时，正式环境一般也要在公网上启用 HTTPS，这又要求我们有一个有效的证书。因为我已经用 Let's Encrypt 申请过证书，所以这里就偷懒直接拿来用了，想自行验证的读者请在本地生成一个测试证书，不想搞太麻烦的同学就接着往下看吧。

Nginx 的配置不太相关的部分就略过了，其实和普通网站基本没有太大区别：

server {
    listen 443 ssl;
    server_name         yuhao.space *.yuhao.space;
    ssl_certificate     ...;
    ssl_certificate_key ...;

    location / {
        proxy_set_header    Host            $http_host;
        proxy_set_header    X-Real-IP       $remote_addr;
        proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header    X-Scheme        $scheme;
        proxy_pass          http://localhost:5000;
    }
}

这里我们让所有域名都通过相同的服务端口，为了识别到域名，别忘了设置 HOST。

设置完毕并重新加载 Nginx，然后用生产模式运行应用：

FLASK_ENV=production FLASK_APP=app flask run

然后打开浏览器访问...404？怎么回事？回想一下代码能猜到，通过生产环境访问时，浏览器发来的 Host 已经不带 5000 端口号了，因此我们这里要对应修改一下。为了同时保证开发环境仍然正常工作，需要判断一下环境：

    app = Flask(__name__)
    server_name = 'yuhao.space'
    env = os.getenv('FLASK_ENV', 'development')
    if env != 'production':
        server_name += ':5000'
    app.config['SERVER_NAME'] = server_name

当然，这不是足够灵活的生产代码，但我在这里希望作为示例尽量简单明了。

再次运行程序，这次访问应该正常了。

检查反向地址

地址访问正常只是成功的一半。另一半是从客户请求中生成可访问的地址————也就是我们熟悉的 url_for() ，同样应该检查它们是否工作正常。为此，我们把视图函数稍稍修改一下，让它们返回模板内容：

@home_bp.route('/')
def home_index():
    return render_template('home.html')

然后写一个简单的模板：

<a href="{{ url_for('home.home_index') }}">Home Index</a>
<a href="{{ url_for('blog.blog_index') }}">Blog Index</a>
<br/>

<a href="{{ url_for('home.home_index', _external=True) }}">Home Index</a>
<a href="{{ url_for('blog.blog_index', _external=True) }}">Blog Index</a>

好消息是，内部地址是正确的; 坏消息则是外部地址（使用 _external 参数）路径虽然没错，但却返回了 http:// 的地址，这可不是我们想要的结果。

一个简单粗暴的处理办法是, 为 url_for 强制指定协议：

<a href="{{ url_for('home.home_index', _external=True, _scheme='https') }}">Home Index</a>

但可想而知，如果网站有很多链接的话，这样会增加不小的工作量。

从官方文档和代码中的备注来看，应用程序配置中有一项 PREFERED_URL_SCHEME 似乎应当与此有关，但文档对此解释不太明确，我尝试过添加该配置也不起作用。Stackoverflow 和 Github 上也有人提过类似的问题： PREFERRED_URL_SCHEME doesn't seem to work in Jinja2 Flask Template 。 官方对此也没有明确的答复。

既然没有正规途径，只要自己解决了。所幸 url_for 已经有参数可以利用，所以这也并不难。我们只要定义一个模板函数来强制指定 scheme 就好了：

    def external_url_for(endpoint, **values):
        values.setdefault('_external', True)
        values.setdefault('_scheme', 'https')
        return url_for(endpoint, **values)

    ...
    app.add_template_global(external_url_for, 'external_url_for')

然后在模板中用 external_url_for 代替 url_for 调用即可。

结语

本文讨论了基于子域名的 Flask Blueprint 开发实践和相关问题的处理。要处理多个域名，另一种做法是通过 WSGI 接口分配多个应用，这种做法在 官方文档 Application Dispatching 部分 有所涉及。但我觉个这种方法略“重”，因此还是走了 Blueprint 的路子。如果子应用的规模很大，那么单独分配 app 或许是更灵活的做法。从实践中我们也可以体会到，尽管 Flask 在个别地方功能略显不足，但还是给我们提供了很多灵活性，值得好好去挖掘。