如何通过Flask应用安全提供依赖包的Sphinx文档访问服务

原方案风险说明 #

直接将路由指向虚拟环境目录存在两个核心问题：

• 硬编码的/venv/Lib/路径仅适配Windows环境，macOS/Linux下虚拟环境的依赖存放路径为lib/python<版本号>/site-packages，跨平台兼容性极差
• 若未做严格的路径校验，攻击者可通过路径遍历 payload （如/docs/../../../../xx）访问虚拟环境内的所有文件，包括依赖包源码、配置文件中存储的密钥等敏感数据，存在严重安全隐患

推荐实现方案 #

方案1：预拷贝文档到projB静态目录（生产环境首选） #

这是安全性、兼容性最高的方案，完全隔离虚拟环境访问入口：

• 部署projB时在构建脚本中添加步骤，从已安装的projA依赖中拷贝docs/build/html整个目录到projB的static/projA_docs目录下
• 直接使用Flask原生静态文件能力提供服务，代码示例：

from flask import send_from_directory
import os

@app.route('/docs/')
def serve_docs_index():
    return send_from_directory(os.path.join(app.static_folder, 'projA_docs'), 'index.html')

@app.route('/docs/<path:filename>')
def serve_docs(filename):
    return send_from_directory(os.path.join(app.static_folder, 'projA_docs'), filename)

该方案优势：无路径遍历风险、静态文件服务性能高、支持对接CDN做缓存加速。

方案2：运行时动态定位+路径校验（适合小型项目/开发环境） #

如果不想额外添加构建步骤，可以通过Python标准库动态定位projA安装路径，搭配严格的路径校验保证安全：

import importlib.resources
import os
from flask import abort, send_from_directory

# 动态获取projA安装根路径，自动适配所有操作系统
with importlib.resources.path("projA", "__init__.py") as init_path:
    PROJ_A_ROOT = os.path.dirname(init_path)
# 拼接文档目录路径
PROJ_A_DOCS_DIR = os.path.normpath(os.path.join(PROJ_A_ROOT, "docs", "build", "html"))

@app.route('/docs/')
def docs_index():
    return send_from_directory(PROJ_A_DOCS_DIR, "index.html")

@app.route('/docs/<path:filename>')
def serve_docs(filename):
    # 校验目标路径是否在合法的文档目录下，拦截路径遍历攻击
    target_path = os.path.normpath(os.path.join(PROJ_A_DOCS_DIR, filename))
    if not target_path.startswith(PROJ_A_DOCS_DIR + os.sep):
        abort(403)
    if not os.path.isfile(target_path):
        abort(404)
    return send_from_directory(PROJ_A_DOCS_DIR, filename)

该方案优势：无需额外构建步骤、自动适配所有操作系统、安全强度足够。

额外优化建议 #

可以在打包projA时将构建好的Sphinx文档声明为包数据，这样安装projA时文档会自动被放到对应安装目录下，避免出现找不到文档路径的问题。

内容的提问来源于stack exchange，提问作者CaffeinatedMike