Django + FastAPI Windows 部署完整教程：从零到开机自启

WINDOWS DEPLOY GUIDE // 2026

Django + FastAPI Windows 部署完整教程

从零到开机自启，一台 Windows 机器，两个框架，一份保姆级对照教程

Django 项目用 waitress（WSGI 服务器）跑在 8000 端口，Nginx 通过 80 端口转发

FastAPI 项目用 uvicorn（ASGI 服务器）跑在 8001 端口，Nginx 通过 81 端口转发

三个进程（waitress、uvicorn、Nginx）都通过 NSSM 注册为 Windows 服务，开机自动启动

为什么 Django 用 waitress 而不是 Gunicorn？

Gunicorn 依赖 fork() 系统调用，Windows 没有这个调用，装上也跑不起来。uWSGI 同理。waitress 是纯 Python 实现，不依赖任何 Linux 专用系统调用，天然适配 Windows 的线程模型。

为什么 FastAPI 用 uvicorn？

FastAPI 本身就是基于 ASGI 标准设计的，uvicorn 是它的标配 ASGI 服务器，Windows 上直接能用。唯一需要注意的是 --workers 参数在 Windows 上因缺少 fork 支持而受限，建议单进程运行，靠 NSSM 管理服务稳定性。

一、环境准备

1.1 确认 Python 版本

打开命令提示符（CMD），输入：

python --version

建议使用 Python 3.10 及以上版本。如果系统提示找不到 python 命令，去 python.org 下载安装，安装时务必勾选 "Add Python to PATH"。

1.2 pip 换国内源（可选但推荐）

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

1.3 创建项目目录

在 C 盘根目录下创建 projects 文件夹，两个项目分别放在下面：

C:\projects\ ├── django_app\ # Django 项目 │ ├── venv\ # 虚拟环境 │ ├── myproject\ # Django 项目配置目录 │ ├── manage.py │ └── ... └── fastapi_app\ # FastAPI 项目 ├── venv\ # 虚拟环境 ├── main.py # FastAPI 入口文件 └── ...

⚠ 重要提示：项目路径不要包含空格和中文。用 C:\projects\django_app 没问题，但 C:\Program Files\我的项目 这种路径后面配 NSSM 服务时会有各种莫名其妙的报错。

mkdir C:\projects\django_app mkdir C:\projects\fastapi_app

1.4 创建虚拟环境

虚拟环境的作用是把每个项目的依赖隔离开，互不干扰。

Django 项目虚拟环境：

cd C:\projects\django_app python -m venv venv

FastAPI 项目虚拟环境：

cd C:\projects\fastapi_app python -m venv venv

1.5 激活虚拟环境

后续所有操作都需要在激活的虚拟环境中进行。

Django 项目：

cd C:\projects\django_app venv\Scripts\activate

FastAPI 项目：

cd C:\projects\fastapi_app venv\Scripts\activate

激活成功后，命令行前面会出现 (venv) 标识。每次打开新的 CMD 窗口操作某个项目时，都需要先 cd 到项目目录，再激活虚拟环境。

二、Django 项目部署

2.1 安装依赖

确保你已激活 Django 项目的虚拟环境，然后安装项目所需的依赖：

cd C:\projects\django_app venv\Scripts\activate # 安装 Django 和 waitress pip install django waitress # 如果项目有 requirements.txt pip install -r requirements.txt

2.2 生产环境配置（settings.py）

打开 Django 项目配置文件 myproject/settings.py，修改以下几项：

# myproject/settings.pyimport os# 1. SECRET_KEY 从环境变量读取（不要硬编码在代码里）SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', '开发时用的默认密钥')# 2. 关闭 DEBUG 模式（生产环境必须关闭）DEBUG = False# 3. 允许访问的主机ALLOWED_HOSTS = ['127.0.0.1', 'localhost']# 4. 信任 Nginx 转发的协议头SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')# 5. 静态文件配置STATIC_URL = '/static/' STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')# 6. 媒体文件配置MEDIA_URL = '/media/' MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

为什么要改这些？

开发时 DEBUG=True，Django 会自动帮你处理静态文件、显示详细错误页面。但生产环境关闭 DEBUG 后，Django 不再处理静态文件请求——CSS、JS 全部 404。所以我们需要配置 STATIC_ROOT，然后手动收集静态文件，最后让 Nginx 来提供静态文件服务。

注意：STATIC_ROOT 不要和 STATICFILES_DIRS 指向同一个目录。STATICFILES_DIRS 是开发时存放静态文件的源目录，STATIC_ROOT 是 collectstatic 收集文件的目标目录，两者不能重合。

2.3 收集静态文件

python manage.py collectstatic

执行后会提示你确认，输入 yes 回车。完成后项目目录下会多出一个 staticfiles 文件夹，里面是所有静态文件的集合。

2.4 测试 Django 项目能否正常启动

在正式用 waitress 之前，先用 Django 自带服务器确认项目本身没问题：

python manage.py runserver 127.0.0.1:8000

浏览器访问 http://127.0.0.1:8000，如果页面正常显示，说明项目本身没问题。按 Ctrl+C 停止。

2.5 用 waitress 启动 Django

waitress-serve --listen=127.0.0.1:8000 --threads=4 myproject.wsgi:application

⚠ 踩坑提醒：waitress 默认绑定 0.0.0.0:8080（监听所有网卡的 8080 端口），如果你不显式指定 --listen，它会跑在 8080 端口而不是 8000，后面配 Nginx 时端口对不上就会 502。而且默认监听所有网卡在生产环境有安全风险，所以一定要显式指定 127.0.0.1。

启动后浏览器访问 http://127.0.0.1:8000，确认页面正常。此时静态文件可能加载不出来（因为 DEBUG=False），这是正常的，后面 Nginx 会处理。按 Ctrl+C 先停掉。

2.6 创建启动脚本（方便后续注册服务）

在项目根目录创建 start_waitress.py：

# C:\projects\django_app\start_waitress.pyimport os from waitress import serve os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings') from myproject.wsgi import application if __name__ == '__main__': serve( application, host='127.0.0.1', port=8000, threads=4, )

后面用 NSSM 注册 Windows 服务时，用 Python 脚本启动比直接用 waitress-serve.exe 更稳定，路径配置也更直观。myproject 替换成你实际的项目名。

测试脚本能否正常启动：

python start_waitress.py

三、FastAPI 项目部署

3.1 安装依赖

cd C:\projects\fastapi_app venv\Scripts\activate # 推荐：安装 FastAPI 标准全家桶（包含 uvicorn + 常用依赖） pip install "fastapi[standard]" # 如果项目有 requirements.txt pip install -r requirements.txt

3.2 确认入口文件

确保你的 FastAPI 入口文件（比如 main.py）中有一个 app 变量：

# C:\projects\fastapi_app\main.pyfrom fastapi import FastAPI app = FastAPI() @app.get("/") def root(): return {"message": "Hello World"}

后续启动命令中的 main:app 指的就是 main.py 文件里的 app 变量。如果你的入口文件叫别的名字（比如 app.py），启动命令就改成 app:app。

3.3 用 uvicorn 启动 FastAPI

uvicorn main:app --host 127.0.0.1 --port 8001

浏览器访问 http://127.0.0.1:8001，看到 {"message":"Hello World"} 就说明启动成功了。也可以访问 http://127.0.0.1:8001/docs 查看 FastAPI 自动生成的接口文档。按 Ctrl+C 停掉。

Windows 上的限制：uvicorn 的 --workers 多进程模式在 Windows 上使用 spawn 方式启动子进程，可能遇到兼容性问题。建议在 Windows 上单进程运行，靠 NSSM 管理服务自动重启来保证稳定性。如果你确实需要多进程，考虑后续迁移到 Linux 部署。

3.4 Django 与 FastAPI 部署对照

核心区别在于 WSGI vs ASGI：Django 传统上是同步框架，用 WSGI 服务器（waitress）跑；FastAPI 是异步框架，用 ASGI 服务器（uvicorn）跑。两者的 Nginx 反向代理配置几乎一样，但 FastAPI 如果用到 WebSocket，Nginx 那边需要额外加几行配置。

四、Nginx 反向代理配置

两个后端服务都能跑起来了，但它们各占一个端口（8000 和 8001），外部访问不方便。Nginx 的作用就是做统一入口：80 端口转发给 Django，81 端口转发给 FastAPI。

4.1 下载安装 Windows 版 Nginx

访问 Nginx 官网下载页 nginx.org/en/download.html，下载 Stable version（稳定版）最新版本，解压到 C:\nginx（路径不要有空格和中文）。

C:\nginx\ ├── conf\ │ └── nginx.conf # 主配置文件 ├── html\ │ └── index.html # 默认欢迎页 ├── logs\ # 日志目录 └── nginx.exe # 启动程序

4.2 验证 Nginx 能正常运行

cd C:\nginx start nginx

浏览器访问 http://127.0.0.1，看到 Nginx 欢迎页就说明没问题。

# 停止 Nginxnginx -s stop# 重新加载配置（修改配置后不用重启）nginx -s reload# 测试配置文件语法是否正确nginx -t

4.3 配置 nginx.conf

用文本编辑器打开 C:\nginx\conf\nginx.conf，把内容替换为以下配置：

4.4 配置说明

Django 的 80 端口配置了三个 location：

• /static/ — 静态文件由 Nginx 直接从 staticfiles 目录提供，不走 waitress

• /media/ — 用户上传的文件同理，由 Nginx 直接提供

• / — 其他所有请求转发给 waitress（127.0.0.1:8000）

FastAPI 的 81 端口所有请求转发给 uvicorn，额外配置了 WebSocket 支持所需的 proxy_http_version 1.1 和 Upgrade、Connection 头。

proxy_set_header 四件套（两个 server 都有）：

没有这些，后端拿到的客户端 IP 永远是 127.0.0.1（Nginx 的地址），日志和权限判断都会出问题。

Nginx 自身日志：配置中的 access_log 和 error_log 写在 C:\nginx\logs\ 目录下。排错时除了看 NSSM 重定向的 Python 日志，别忘了 Nginx 自己的日志也能查——502、404 等错误在 Nginx 的 error.log 里都有记录。

4.5 测试 Nginx 配置

cd C:\nginx nginx -t

如果输出 syntax is ok 和 test is successful，说明配置没问题。如果有报错，仔细检查拼写和路径。

4.6 启动测试

现在需要同时启动三个进程来测试。打开三个 CMD 窗口：

窗口 1 — 启动 Django（waitress）：

cd C:\projects\django_app venv\Scripts\activate python start_waitress.py

窗口 2 — 启动 FastAPI（uvicorn）：

cd C:\projects\fastapi_app venv\Scripts\activate uvicorn main:app --host 127.0.0.1 --port 8001

窗口 3 — 启动 Nginx：

cd C:\nginx start nginx

浏览器测试：

• 访问 http://127.0.0.1 → 应该看到 Django 页面，且静态文件正常加载

• 访问 http://127.0.0.1:81 → 应该看到 FastAPI 的 JSON 响应

• 访问 http://127.0.0.1:81/docs → 应该看到 FastAPI 接口文档

如果静态文件还是 404，检查 C:\projects\django_app\staticfiles\ 目录是否存在且有内容（前面 collectstatic 命令是否执行成功），以及 nginx.conf 中 alias 路径是否正确。

五、Windows 服务化（NSSM）

前面我们都是手动在命令行启动三个进程，窗口一关服务就停了。这一节我们用 NSSM（Non-Sucking Service Manager）把 waitress、uvicorn、Nginx 分别注册为 Windows 服务，实现开机自启、后台运行、崩溃自动重启。

5.1 下载安装 NSSM

访问 NSSM 官网 nssm.cc/download，下载 nssm-2.24.zip，解压后进入 win64 文件夹，把 nssm.exe 复制到 C:\Windows\System32\ 目录下。

nssm version

⚠ 以下所有 NSSM 命令都必须在「以管理员身份运行的 CMD」中执行！普通 CMD 执行会报 "Access is denied" 错误。右键点击命令提示符 → "以管理员身份运行"。

5.2 注册 Django 服务（DjangoService）

nssm install DjangoService "C:\projects\django_app\venv\Scripts\python.exe" "start_waitress.py" nssm set DjangoService AppDirectory "C:\projects\django_app"

5.3 注册 FastAPI 服务（FastAPIService）

nssm install FastAPIService "C:\projects\fastapi_app\venv\Scripts\python.exe" "-m uvicorn main:app --host 127.0.0.1 --port 8001" nssm set FastAPIService AppDirectory "C:\projects\fastapi_app"

为什么用 python -m uvicorn 而不是直接用 uvicorn.exe？python -m uvicorn 方式更可靠，能确保使用的是虚拟环境中的 uvicorn 包。直接用 uvicorn.exe 有时会出现路径找不到的问题。

5.4 注册 Nginx 服务（NginxService）

nssm install NginxService "C:\nginx\nginx.exe" nssm set NginxService AppDirectory "C:\nginx"

5.5 配置日志重定向（推荐）

服务跑在后台，如果出错了你看不到报错信息。配置日志重定向，把输出写到文件里：

# 先创建日志目录mkdir C:\projects\django_app\logs mkdir C:\projects\fastapi_app\logs# Django 服务日志nssm set DjangoService AppStdout "C:\projects\django_app\logs\stdout.log" nssm set DjangoService AppStderr "C:\projects\django_app\logs\stderr.log"# FastAPI 服务日志nssm set FastAPIService AppStdout "C:\projects\fastapi_app\logs\stdout.log" nssm set FastAPIService AppStderr "C:\projects\fastapi_app\logs\stderr.log"

日志文件会随着服务运行不断增长，长期运行需要配置日志轮转：

# 开启日志轮转（10MB 自动切割）nssm set DjangoService AppRotateFiles 1 nssm set DjangoService AppRotateBytes 10485760 nssm set FastAPIService AppRotateFiles 1 nssm set FastAPIService AppRotateBytes 10485760

5.6 配置自动重启

nssm set DjangoService AppExit Default Restart nssm set FastAPIService AppExit Default Restart nssm set NginxService AppExit Default Restart

5.7 配置服务启动依赖

nssm set NginxService DependOnService DjangoService FastAPIService

DependOnService 只保证 Nginx 在后端服务之后启动，但不保证后端已经完成初始化。waitress 和 uvicorn 从启动到真正监听端口之间有几秒延迟，所以 Nginx 刚启动时的首次请求可能返回 502，刷新一下就好。如果持续 502，说明后端服务启动失败了，去看日志排查。

5.8 启动服务并验证

nssm start DjangoService nssm start FastAPIService nssm start NginxService

也可以通过 Windows 服务管理器操作：Win + R → 输入 services.msc → 回车，在列表中找到对应服务，右键启动。

验证：

• 浏览器访问 http://127.0.0.1 → Django 页面正常

• 浏览器访问 http://127.0.0.1:81 → FastAPI 响应正常

• 重启电脑，等一会儿再访问 → 两个服务应该自动启动

如果服务启动失败，去查看日志文件：

type C:\projects\django_app\logs\stderr.log type C:\projects\fastapi_app\logs\stderr.log

5.9 NSSM 常用管理命令速查

nssm start DjangoService # 启动服务nssm stop DjangoService # 停止服务nssm restart DjangoService # 重启服务nssm edit DjangoService # 打开 GUI 编辑服务配置nssm remove DjangoService # 删除服务（先 stop 再 remove）

删除服务的正确姿势：先 nssm stop 服务名 停掉服务，再 nssm remove 服务名 confirm 删除。不加 confirm 会弹确认框。

六、常见问题与排错

Q1：访问页面显示 502 Bad Gateway

原因：Nginx 启动了，但后端服务（waitress 或 uvicorn）没起来，或者端口不对。

# 检查后端服务是否在运行nssm status DjangoService nssm status FastAPIService# 检查端口是否被监听netstat -ano | findstr :8000 netstat -ano | findstr :8001

Q2：Django 页面样式丢失（CSS/JS 加载不出来）

原因：DEBUG=False 后 Django 不再处理静态文件。确认以下三步都做了：

1. settings.py 中配置了 STATIC_ROOT

2. 执行了 python manage.py collectstatic

3. nginx.conf 中 location /static/ 的 alias 路径指向了 staticfiles 目录

Q3：端口被占用

# 查看哪个进程占用了端口（以 8000 为例）netstat -ano | findstr :8000# 查看 PID 对应的进程tasklist | findstr 12345# 杀掉进程taskkill /PID 12345 /F

Q4：NSSM 服务启动失败

Q5：Nginx 配置修改后不生效

cd C:\nginx nginx -t # 先测试配置语法nginx -s reload # 重新加载配置nginx -s stop # 如果 reload 不生效，强制重启start nginx

Q6：防火墙阻止了外部访问

以管理员身份执行：

netsh advfirewall firewall add rule name="Nginx HTTP" dir=in action=allow protocol=TCP localport=80 netsh advfirewall firewall add rule name="FastAPI HTTP" dir=in action=allow protocol=TCP localport=81

Q7：WebSocket 连接失败（FastAPI）

确认 FastAPI 的 server 块中有以下三行：

proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";

Q8：重启电脑后服务没有自动启动

1. 打开 services.msc，确认三个服务的"启动类型"是"自动"

2. 检查服务依赖：NginxService 配置了 DependOnService，如果 DjangoService 或 FastAPIService 启动失败，NginxService 也不会启动

3. 查看 Windows 事件查看器：Win + R → eventvwr → Windows 日志 → 系统，查找服务启动相关的错误

总结

最终端口分配

三个 Windows 服务

服务管理常用命令

nssm start DjangoService # 启动nssm stop DjangoService # 停止nssm restart DjangoService # 重启nssm edit DjangoService # 编辑配置nssm remove DjangoService confirm # 删除

部署过程中遇到任何问题，先看日志文件，再看本文第六部分的排错指南。大多数问题都是路径、端口和权限三类，耐心排查一定能解决。

CYBER_GREEN // DEPLOY GUIDE // 2026