部署Django REST API至Azure遇阻：请求排查及部署指导

一、前置准备 #

• 本地Django项目可正常运行，已完成PostgreSQL本地迁移
• 已创建Azure App Service实例、Azure PostgreSQL数据库实例

二、settings.py核心配置调整 #

修改项目根目录下的settings.py，重点调整以下部分（其余配置保留原有逻辑即可）：

import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

# 安全与域名配置
DEBUG = os.environ.get('DEBUG', 'False') == 'True'
ALLOWED_HOSTS = [os.environ.get('ALLOWED_HOSTS', 'localhost'), '.azurewebsites.net']
SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'your-local-secret-key')

# Azure PostgreSQL数据库配置（完全通过环境变量读取）
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME'),
        'USER': os.environ.get('DB_USER'),
        'PASSWORD': os.environ.get('DB_PASSWORD'),
        'HOST': os.environ.get('DB_HOST'),
        'PORT': os.environ.get('DB_PORT', '5432'),
        'OPTIONS': {
            'sslmode': 'require'  # Azure PostgreSQL强制SSL连接
        }
    }
}

# 静态文件适配Azure App Service
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
STATICFILES_DIRS = [os.path.join(BASE_DIR, 'static')]

# 媒体文件配置（如果项目用到）
MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

说明：生产环境下DEBUG必须设为False，ALLOWED_HOSTS必须包含.azurewebsites.net；数据库配置添加sslmode是因为Azure PostgreSQL强制要求SSL连接。

三、Azure环境变量配置 #

1. 登录Azure门户，进入你的App Service实例
2. 左侧菜单选择「配置」>「应用程序设置」
3. 点击「新建应用程序设置」，添加以下键值对：
   • DEBUG: False
   • ALLOWED_HOSTS: 你的App Service域名（如xxx.azurewebsites.net）
   • DJANGO_SECRET_KEY: 本地settings里的SECRET_KEY（生产环境务必保密）
   • DB_NAME: Azure PostgreSQL的数据库名称（创建实例时指定的）
   • DB_USER: Azure PostgreSQL的管理员用户名（格式为<admin-name>@<server-name>）
   • DB_PASSWORD: PostgreSQL管理员密码
   • DB_HOST: PostgreSQL服务器的完整域名（如xxx.postgres.database.azure.com）
   • DB_PORT: 5432
4. 点击「保存」，App Service会自动重启加载新配置

四、数据库迁移执行 #

方法1：通过Azure SSH终端执行 #

1. 进入App Service实例的「开发工具」>「SSH」，打开在线终端
2. 切换到项目根目录：cd site/wwwroot
3. 激活默认虚拟环境：source /antenv/bin/activate
4. 执行迁移命令：

   python manage.py makemigrations --noinput
   python manage.py migrate --noinput
   

5. 如需创建超级用户，可提前添加DJANGO_SUPERUSER_USERNAME、DJANGO_SUPERUSER_PASSWORD、DJANGO_SUPERUSER_EMAIL环境变量，然后执行：

   python manage.py createsuperuser --noinput
   

方法2：通过本地Azure CLI远程执行 #

1. 本地安装Azure CLI并登录：az login
2. 连接到App Service终端：

   az webapp ssh --name <your-app-name> --resource-group <your-resource-group>
   

3. 后续步骤同方法1

五、404/应用异常排查步骤 #

1. 查看实时运行日志 #

• 进入App Service的「监控」>「日志流」，实时查看应用报错信息，重点关注：
  • 数据库连接失败（如psycopg2.OperationalError）
  • 静态文件找不到（如404 Not Found: /static/xxx.css）
  • 路由匹配失败（如Page not found (404)）
• 也可在「日志」>「应用日志」下载完整日志文件分析

2. 验证数据库连接 #

• 在SSH终端执行以下命令测试连接：

  psql -h $DB_HOST -U $DB_USER -d $DB_NAME
  

• 若连接失败，检查Azure PostgreSQL的「连接安全性」：
  • 开启「允许访问Azure服务」选项
  • 确认本地/服务IP已加入防火墙规则（如果手动设置了IP限制）

3. 静态文件与路由检查 #

• 确保部署过程中执行了collectstatic：在Azure部署中心的「构建选项」里添加构建命令：

  pip install -r requirements.txt && python manage.py collectstatic --noinput
  

• 检查urls.py是否配置了静态文件路由（生产环境必须）：

  from django.conf import settings
  from django.conf.urls.static import static
  
  urlpatterns = [
      # 你的业务路由
  ] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
  

• 若DEBUG为False，需在templates目录下创建自定义404.html模板，否则会显示默认服务器404页面

4. 依赖包检查 #

• 确认requirements.txt包含所有生产环境依赖，尤其是psycopg2-binary（PostgreSQL驱动）、django等核心包
• 在SSH终端执行pip list查看已安装的依赖版本，确保与本地一致

六、models.py注意事项 #

确保models定义与迁移文件一致，示例如下：

from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=200)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.name

• 不要在models中硬编码数据库相关逻辑
• 外键、多对多字段需正确设置关联模型，避免迁移时出现关联错误

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