企业官网建设流程全解析

1. 为什么要在 Windows IIS 上部署 Django？这不是“倒退”，而是现实刚需

Django 项目默认用runserver启动，开发阶段够用，但一到上线就露馅——它不是生产级服务器，扛不住并发，没 HTTPS 支持，不支持多进程隔离，更没法和 Windows 域环境、AD 认证、现有 IIS 管理体系打通。很多政企、教育、医疗类客户，内网环境清一色是 Windows Server + IIS + SQL Server 组合，服务器上不允许装 Linux 虚拟机，也不允许开额外端口跑 Nginx 或 Gunicorn。这时候硬推 Docker 或 WSL2，不是技术不行，是流程过不了审批：IT 运维只认 IIS 管理器里的“应用程序池”和“网站绑定”，安全审计只查C:\inetpub\wwwroot下的配置文件和权限日志。我去年帮某省疾控中心部署疫情数据上报后台，就是卡在这一关——他们连 Python 解释器安装都要走三重审批，但 IIS 的“添加网站”按钮，点一下就能进白名单。

所以，“Django 部署到 Windows IIS”不是技术怀旧，而是把 Django 的业务逻辑能力，塞进 Windows 生态的合规管道里。核心目标就三个：让manage.py runserver能被 IIS 接管、让/static/路径下的 CSS/JS/图片真能加载出来、让所有页面样式不崩、字体不乱、图标不缺。别小看最后这点——我见过太多团队花三天调通 WSGI，结果首页背景图死活 404，排查半天发现是web.config里<staticContent>没开.woff2类型，浏览器直接拒收字体文件。这根本不是 Django 问题，是 IIS 的 MIME 类型白名单太保守。

关键词里反复出现的static和web.config，恰恰暴露了最大痛点：Django 的collectstatic生成的文件，IIS 默认当“静态资源”处理，但默认配置只认.css.js.png这几类，遇到.svg.woff.ttf就返回 404；而web.config这个 XML 文件，本质是 IIS 的“本地路由规则+模块开关+静态文件开关”三合一配置中心，不是可有可无的装饰品。它得写对位置（必须放在STATIC_ROOT目录下）、写对节点（<staticContent>和<handlers>必须共存）、写对顺序（<remove fileExtension=".svg" />必须在<mimeMap>之前），否则 IIS 会静默忽略。下面我就从零开始，带你把这套组合拳打扎实。

2. 整体架构设计：为什么选 FastCGI 而不是 HTTPPlatformHandler？

部署 Django 到 IIS，主流方案就两个：HTTPPlatformHandler（微软官方推荐）和FastCGI（老牌稳定方案）。网上很多教程直接抄微软文档用 HTTPPlatformHandler，结果在 Windows Server 2016 上跑崩——因为它的底层依赖httpPlatformHandler.dll，而这个 DLL 在 Server 2016 默认没启用，手动启用又常和 .NET Framework 版本冲突。我实测过 7 个不同补丁版本的 Server 2016，有 4 个会报错0x80070005（访问被拒绝），根源是httpPlatformHandler尝试以ApplicationPoolIdentity身份读取python.exe的注册表权限，但默认策略禁止跨用户读取。

FastCGI 就稳得多。它本质是 IIS 和 Python 进程之间的“翻译官”：IIS 把 HTTP 请求打包成 FastCGI 协议发给 Python 进程，Python 处理完再按协议回传响应。整个过程不碰注册表，不依赖 .NET，只靠wfastcgi.py这个轻量脚本桥接。微软自己也承认：“FastCGI 是目前 Windows 上最兼容、最可控的 Python Web 应用托管方式”。关键它还能和virtualenv完美共存——你完全可以在C:\myproject\venv\Scripts\python.exe下运行，IIS 只需指定这个路径，不用全局装 Python。

所以我的架构选型是：

• IIS 作为反向代理和静态文件服务层：接管所有/static/和/media/请求，直接返回文件，不走 Python；
• FastCGI 作为动态请求处理器：只处理/admin/、/api/、/login/这类需要 Django 逻辑的路径；
• web.config作为总开关：用<location path="static">显式声明静态目录，用<handlers>指定.py文件由 FastCGI 处理，用<staticContent>开放所有前端需要的 MIME 类型。

这个设计的好处是：静态资源 100% 由 IIS 原生服务，速度比 DjangoStaticFilesHandler快 3 倍以上（实测 TTFB 从 80ms 降到 22ms）；动态请求全走 FastCGI，避免httpPlatformHandler的权限坑；web.config一文件管所有，运维改个 MIME 类型不用重启 Python 进程。

提示：别信“用 Nginx 做反向代理”的方案。在纯 Windows 环境里，多装一个 Nginx 不仅增加运维复杂度，还会让安全审计多出一条“未授权第三方服务”的扣分项。IIS 本身就有成熟的 URL 重写、SSL 终止、IP 限制功能，何必画蛇添足？

3. 核心细节解析：STATIC_ROOT、STATIC_URL 和 web.config 的三角关系

Django 的静态文件机制，表面看就三个配置项：STATIC_URL、STATICFILES_DIRS、STATIC_ROOT。但放到 IIS 环境里，它们的关系就变成“三方博弈”。

• STATIC_URL = '/static/'：这是 Django 模板里{% static 'css/app.css' %}生成的 URL 前缀，告诉浏览器“去/static/css/app.css拿文件”。它必须和 IIS 绑定的物理路径一致，否则浏览器发错请求。
• STATICFILES_DIRS = [BASE_DIR / 'static']：这是开发时存放原始 CSS/JS 的目录，collectstatic会把这里和各 App 的static目录合并拷贝到STATIC_ROOT。
• STATIC_ROOT = BASE_DIR / 'staticfiles'：这是collectstatic最终输出的“成品静态文件仓库”，IIS 必须把这个目录设为网站的物理路径，或者用虚拟目录映射过去。很多人部署失败，就是因为STATIC_ROOT指向C:\myproject\staticfiles，但 IIS 网站根目录却指向C:\myproject，导致/static/请求找不到文件。

web.config就是协调这三方的“裁判”。它必须放在STATIC_ROOT目录下（即C:\myproject\staticfiles\web.config），内容分三块：

第一块<handlers>告诉 IIS：“.py文件别自己处理，转给 FastCGI”：

<handlers> <add name="Python FastCGI" path="*" verb="*" modules="FastCgiModule" scriptProcessor="C:\myproject\venv\Scripts\python.exe|C:\Python39\Lib\site-packages\wfastcgi.py" resourceType="Unspecified" requireAccess="Script" /> </handlers>

注意scriptProcessor的路径：前半段是你的虚拟环境python.exe，后半段是wfastcgi.py的绝对路径。wfastcgi必须用pip install wfastcgi安装，不能用conda，因为 conda 安装的路径常含空格，IIS 解析会失败。

第二块<staticContent>开放 MIME 类型，这是页面样式不崩的关键：

<staticContent> <remove fileExtension=".svg" /> <remove fileExtension=".woff" /> <remove fileExtension=".woff2" /> <remove fileExtension=".ttf" /> <remove fileExtension=".eot" /> <mimeMap fileExtension=".svg" mimeType="image/svg+xml" /> <mimeMap fileExtension=".woff" mimeType="application/font-woff" /> <mimeMap fileExtension=".woff2" mimeType="font/woff2" /> <mimeMap fileExtension=".ttf" mimeType="application/octet-stream" /> <mimeMap fileExtension=".eot" mimeType="application/vnd.ms-fontobject" /> </staticContent>

为什么先<remove>再<mimeMap>？因为 IIS 有内置 MIME 类型列表，.woff2默认不在其中，直接<mimeMap>会被忽略。必须先删掉（如果存在），再重新加。mimeType="font/woff2"是 W3C 标准，别写成application/font-woff2，Chrome 会拒收。

第三块<location path="static">是保险丝，确保/static/请求绝不进 Python：

<location path="static"> <system.webServer> <handlers> <clear /> <add name="StaticFile" path="*" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" /> </handlers> </system.webServer> </location>

<clear />是重点——它清空所有 handler，强制 IIS 用StaticFileModule直接读文件，不经过 FastCGI。没有这行，.css文件可能被当成 Python 脚本执行，返回 500 错误。

注意：web.config必须用 UTF-8 无 BOM 编码保存。Windows 记事本默认存为 ANSI，用 VS Code 或 Notepad++ 打开，右下角确认编码是 “UTF-8”，再保存。否则 IIS 加载时会报Configuration error: unrecognized element 'configuration'。

4. 实操全流程：从 Python 环境准备到 IIS 网站上线

4.1 Python 环境与依赖安装（避开 Windows 权限雷区）

第一步不是写代码，是搞定 Python 安装路径。绝对不要装在C:\Program Files\Python39。原因：IIS 应用程序池默认以ApplicationPoolIdentity用户运行，这个用户对Program Files有写权限限制，pip install时会卡在Permission denied。正确路径是C:\Python39或C:\myproject\venv。

我推荐用pyenv-win管理多版本（比官方安装包更干净）：

# 以管理员身份打开 PowerShell Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1" # 重启 PowerShell，然后安装 Python 3.9.13（LTS 版本，兼容性最好） pyenv install 3.9.13 pyenv global 3.9.13

验证python --version输出3.9.13，再创建项目虚拟环境：

cd C:\myproject python -m venv venv venv\Scripts\activate.bat pip install django==4.2.7 wfastcgi # 固定 Django 版本，避免 4.3+ 的 ASGI 兼容问题

wfastcgi安装后，运行wfastcgi-enable，它会输出一行注册表路径，比如HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\PYTHON\WFASTCGI\{GUID}。记下这个 GUID，后面 IIS 配置要用。

4.2 Django 项目配置：STATIC_ROOT 必须绝对路径

在settings.py里，STATIC_ROOT不能用Path对象或相对路径：

import os from pathlib import Path BASE_DIR = Path(__file__).resolve().parent.parent.parent # 错误写法（相对路径，IIS 无法解析）： # STATIC_ROOT = BASE_DIR / 'staticfiles' # 正确写法（绝对路径，IIS 认得）： STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles') STATIC_URL = '/static/' # 开发时的静态目录（collectstatic 会合并到这里） STATICFILES_DIRS = [ os.path.join(BASE_DIR, 'static'), ]

然后执行python manage.py collectstatic --noinput。你会看到Copying 'static\css\app.css' to 'C:\myproject\staticfiles\css\app.css'。检查C:\myproject\staticfiles目录下是否有完整的css/、js/、images/子目录——这是 IIS 的“粮仓”，必须满员。

4.3 IIS 配置四步法：从应用池到网站绑定

第一步：创建专用应用池

• 打开 IIS 管理器 → “应用池” → 右键“添加应用池”
• 名称填MyDjangoAppPool
• .NET 版本选“无托管代码”（Django 不用 .NET）
• 托管管道模式选“集成”
• 点击“高级设置” → “标识” → 点击右侧“...” → 选择“自定义账户” → 输入.\IIS_IUSRS（不是ApplicationPoolIdentity！因为IIS_IUSRS对C:\myproject有读取权限，ApplicationPoolIdentity默认没有）

第二步：创建网站并绑定

• “网站” → 右键“添加网站”
• 网站名称：MyDjangoSite
• 物理路径：C:\myproject\staticfiles（注意！是staticfiles，不是myproject）
• 绑定：类型http，IP 地址全部未分配，端口8000（别用 80，避免和默认网站冲突），主机名留空
• 应用程序池选刚建的MyDjangoAppPool

第三步：配置 FastCGI 设置

• IIS 管理器 → 左侧“连接”树 → 选中服务器名 → 双击“FastCGI 设置”
• 右键“添加应用程序” → “完整路径”填C:\myproject\venv\Scripts\python.exe
• “参数”填C:\Python39\Lib\site-packages\wfastcgi.py
• “监视句柄”填wfastcgi.handle
• “活动状态”勾选“启用”

第四步：设置网站权限

• Windows 资源管理器 → 右键C:\myproject→ “属性” → “安全” → “编辑” → “添加”
• 输入IIS_IUSRS→ 点击“检查名称” → 确定
• 勾选“读取 & 执行”、“列出文件夹内容”、“读取”
• 同样给IIS_IUSRS添加对C:\myproject\venv的“读取 & 执行”权限（Python 解释器需要读取.pyd文件）

4.4 web.config 编写与验证：三分钟定位 404

web.config必须放在C:\myproject\staticfiles目录下，内容如下（已整合前文所有要点）：

<?xml version="1.0" encoding="UTF-8"?> <configuration> <system.webServer> <handlers> <add name="Python FastCGI" path="*" verb="*" modules="FastCgiModule" scriptProcessor="C:\myproject\venv\Scripts\python.exe|C:\Python39\Lib\site-packages\wfastcgi.py" resourceType="Unspecified" requireAccess="Script" /> </handlers> <staticContent> <remove fileExtension=".svg" /> <remove fileExtension=".woff" /> <remove fileExtension=".woff2" /> <remove fileExtension=".ttf" /> <remove fileExtension=".eot" /> <mimeMap fileExtension=".svg" mimeType="image/svg+xml" /> <mimeMap fileExtension=".woff" mimeType="application/font-woff" /> <mimeMap fileExtension=".woff2" mimeType="font/woff2" /> <mimeMap fileExtension=".ttf" mimeType="application/octet-stream" /> <mimeMap fileExtension=".eot" mimeType="application/vnd.ms-fontobject" /> <mimeMap fileExtension=".png" mimeType="image/png" /> <mimeMap fileExtension=".jpg" mimeType="image/jpeg" /> <mimeMap fileExtension=".css" mimeType="text/css" /> <mimeMap fileExtension=".js" mimeType="application/javascript" /> </staticContent> </system.webServer> <location path="static"> <system.webServer> <handlers> <clear /> <add name="StaticFile" path="*" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" /> </handlers> </system.webServer> </location> <appSettings> <add key="WSGI_HANDLER" value="myproject.wsgi.application" /> <add key="PYTHONPATH" value="C:\myproject" /> <add key="DJANGO_SETTINGS_MODULE" value="myproject.settings" /> </appSettings> </configuration>

关键点验证：

• 打开浏览器访问http://localhost:8000/static/css/app.css，应该直接下载 CSS 文件（不是 404）；
• 访问http://localhost:8000/admin/，应该显示 Django 登录页（不是 500）；
• 查看浏览器开发者工具 Network 标签，所有.css.js.woff2请求状态码都是200，Size 列有实际字节数。

如果static文件 404，90% 是web.config没放对位置，或STATIC_ROOT路径和 IIS 物理路径不一致；如果/admin/500，80% 是WSGI_HANDLER路径写错（比如写成myproject.wsgi:application，多了冒号）。

5. 常见问题与排查技巧实录：那些文档不会写的坑

5.1 问题速查表：症状、原因、解法

5.2 独家避坑技巧：来自 12 个真实项目的血泪经验

技巧 1：用wfastcgi.py的调试模式抓 Python 错误
默认wfastcgi静默失败。在web.config的<appSettings>里加一行：

<add key="WSGI_LOG" value="C:\myproject\logs\wfastcgi.log" />

然后创建C:\myproject\logs目录，给IIS_IUSRS写入权限。重启网站，访问触发错误的页面，wfastcgi.log里会有完整的 Python traceback，比 IIS 事件日志详细十倍。

技巧 2：解决collectstatic后 CSS 背景图路径失效
Django 的collectstatic会把static/css/app.css里的url(../images/logo.png)改成url(../../static/images/logo.png)，但 IIS 的web.config把/static/当根目录，导致路径错位。解决方案：在settings.py加：

STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.StaticFilesStorage' # 强制不修改 CSS 中的 url() 路径

或者用django-compressor替代原生collectstatic，它能自动重写路径。

技巧 3：IIS 应用程序池“意外退出”的终极解法
现象：网站运行几小时后自动停止，事件日志报Application pool 'MyDjangoAppPool' is being automatically disabled。根源是 IIS 默认“空闲超时”设为 20 分钟，Python 进程空闲就杀。解决：IIS 管理器 → 应用池 → 右键“高级设置” → “空闲超时（分钟）”改为0（永不超时）→ “禁用重叠回收”设为True。

技巧 4：让DEBUG=False时静态文件仍能加载
生产环境DEBUG=False，Django 默认不提供静态文件服务。但我们的web.config已接管/static/，所以只要STATIC_ROOT正确，DEBUG设为False完全不影响。唯一要注意的是ALLOWED_HOSTS必须包含localhost和你的域名，否则 Django 会直接返回 400。

技巧 5：快速验证 FastCGI 是否生效
不用等页面加载，直接用curl测试：

curl -v http://localhost:8000/admin/login/

如果返回HTTP/1.1 200 OK和 HTML 内容，说明 FastCGI 通了；如果返回HTTP/1.1 500 Internal Server Error，看wfastcgi.log；如果返回HTTP/1.1 404 Not Found，说明请求没进 FastCGI，检查web.config的<handlers>是否生效。

最后分享个小技巧：每次改完web.config，不用重启 IIS，只需在 IIS 管理器里右键网站 → “重新启动”。因为web.config是实时加载的，重启网站比重启整个 IIS 服务快 10 秒，且不影响其他网站。我在某银行项目里，用这个技巧把部署验证时间从 5 分钟压到 40 秒——毕竟运维同事等着下班，没人想陪你等 IIS 重启。