Django Admin 後台管理介面入門 | Django 教學

2026/06/08 2026/05/26
python django
Django Admin 後台管理介面入門 | Django 教學

Django 內建了一套功能強大的 Admin 後台管理介面（Admin Site），只需少量設定就能為你的 Model 自動產生完整的 CRUD（Create、Read、Update、Delete）管理頁面。這是 Django「電池包含」（batteries included）哲學的最佳體現之一。本篇將從啟用 Admin、建立管理員帳號開始，一步步帶你掌握 ModelAdmin 的常用配置，打造一個功能完善的後台管理介面。

Django Admin 是什麼？

Django Admin 是 Django 框架內建的自動化後台管理介面，掛載在 django.contrib.admin 這個 Application 中。它會讀取你定義的 Model 結構與 ModelAdmin 配置，自動產生以下功能：

  • 物件列表頁（支援搜尋、過濾、排序、分頁）
  • 物件新增 / 編輯頁（自動生成表單）
  • 批次操作介面（Actions）
  • 歷史記錄追蹤（History）

Admin 的正確定位

在開始使用之前，必須先釐清一個重要觀念：Django Admin 是給開發者與內部團隊使用的管理工具，而非面向終端使用者的前台介面。

適用場景不適用場景
內部管理工具面向一般使用者的前台
內容管理系統（CMS）需要高度客製化 UX 的後台
快速原型與資料驗證高效能要求的大量資料操作
技術人員的資料維護工具複雜工作流程管理

Admin 是「能用、夠用」的管理工具。當管理需求變得複雜時，建議自建管理後台或採用 Wagtail、django-cms 等專業 CMS 框架。

啟用 Admin

Django 預設的專案範本已經幫你啟用了 Admin。你可以打開 settings.py 確認 INSTALLED_APPS 中包含以下項目：

# settings.py
INSTALLED_APPS = [
    'django.contrib.admin',          # Admin 應用本體
    'django.contrib.auth',           # 認證系統（Admin 依賴）
    'django.contrib.contenttypes',   # ContentType 框架（Admin 依賴）
    'django.contrib.sessions',       # Session 框架（Admin 登入需要）
    'django.contrib.messages',       # 訊息框架（Admin 通知需要）
    'django.contrib.staticfiles',    # 靜態檔案（Admin CSS/JS 需要）
    # ... 你的應用
]

同時確認 urls.py 中已經包含 Admin 的 URL 配置：

# urls.py
from django.contrib import admin
from django.urls import path

urlpatterns = [
    path('admin/', admin.site.urls),
    # ... 其他 URL
]

如果你是使用 django-admin startproject 建立的專案，以上設定預設都已經完成，不需要額外修改。

建立 Superuser（超級使用者）

要登入 Admin 後台，你需要一個具有管理員權限的帳號。透過 createsuperuser 指令來建立：

python manage.py createsuperuser

執行後會依序要求你輸入以下資訊：

Username (leave blank to use 'yourname'): admin
Email address: admin@example.com
Password: ********
Password (again): ********
Superuser created successfully.

注意事項：

  • 密碼至少需要 8 個字元，且不能過於簡單（Django 內建密碼驗證器會檢查）
  • 在執行此指令之前，請確保已經執行過 python manage.py migrate，因為使用者資料存放在 auth_user 資料表中

存取 Admin 介面

啟動開發伺服器後，瀏覽 http://127.0.0.1:8000/admin/ 即可進入登入頁面：

python manage.py runserver

使用剛才建立的 Superuser 帳號登入後，你會看到 Admin 首頁。預設已經包含 Groups（群組）與 Users（使用者）兩個 Model 的管理功能，這是由 django.contrib.auth 提供的。

此時你自己定義的 Model 還不會出現在 Admin 中，因為你還沒有「註冊」它們。

註冊 Model 到 Admin

要讓你的 Model 出現在 Admin 後台，需要在應用的 admin.py 中進行註冊（Register）。假設我們有以下兩個 Model：

# blog/models.py
from django.db import models
from django.utils import timezone


class Category(models.Model):
    """文章分類"""
    name = models.CharField(max_length=100, verbose_name='分類名稱')
    description = models.TextField(blank=True, verbose_name='分類描述')
    created_at = models.DateTimeField(auto_now_add=True, verbose_name='建立時間')

    class Meta:
        verbose_name = '分類'
        verbose_name_plural = '分類列表'
        ordering = ['name']

    def __str__(self):
        return self.name


class Post(models.Model):
    """部落格文章"""
    title = models.CharField(max_length=200, verbose_name='標題')
    content = models.TextField(verbose_name='內文')
    category = models.ForeignKey(
        Category,
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        verbose_name='分類',
    )
    author = models.CharField(max_length=100, verbose_name='作者')
    is_published = models.BooleanField(default=False, verbose_name='是否發布')
    views = models.PositiveIntegerField(default=0, verbose_name='瀏覽次數')
    created_at = models.DateTimeField(default=timezone.now, verbose_name='建立時間')
    updated_at = models.DateTimeField(auto_now=True, verbose_name='更新時間')

    class Meta:
        verbose_name = '文章'
        verbose_name_plural = '文章列表'
        ordering = ['-created_at']

    def __str__(self):
        return self.title

最簡單的註冊方式

# blog/admin.py
from django.contrib import admin
from .models import Post, Category

# 最簡單的註冊：使用預設配置
admin.site.register(Post)
admin.site.register(Category)

這樣 Post 和 Category 就會出現在 Admin 後台了。不過預設的列表頁只會顯示 __str__ 方法回傳的字串，功能非常陽春。接下來我們用 ModelAdmin 來自訂管理介面。

ModelAdmin 基礎設定

ModelAdmin 是控制 Model 在 Admin 介面中一切行為的配置類別。透過繼承 admin.ModelAdmin 並設定各種屬性，你可以大幅改善管理體驗。

註冊 ModelAdmin 有兩種語法，推薦使用 裝飾器語法（Decorator Syntax）：

# 方法一：傳統寫法
class PostAdmin(admin.ModelAdmin):
    pass

admin.site.register(Post, PostAdmin)

# 方法二：裝飾器寫法（推薦）
@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    pass

以下介紹 ModelAdmin 中最常用的列表頁配置選項。

list_display：自訂列表顯示欄位

list_display 控制列表頁要顯示哪些欄位，接受一個 list 或 tuple。

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    # 列表頁顯示的欄位
    list_display = ['title', 'author', 'category', 'is_published', 'views', 'created_at']

設定後，列表頁會以表格形式清楚地顯示每篇文章的標題、作者、分類、發布狀態、瀏覽次數與建立時間。BooleanField 類型的欄位會自動以勾選圖示呈現。

list_filter：側邊欄過濾器

list_filter 會在列表頁右側產生過濾器，讓你可以快速篩選資料。

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ['title', 'author', 'category', 'is_published', 'created_at']
    # 右側過濾器
    list_filter = ['is_published', 'category', 'author', 'created_at']

Django 會根據欄位類型自動選擇合適的過濾器樣式：

  • BooleanField：顯示「全部 / 是 / 否」選項
  • ForeignKey：顯示所有關聯物件作為選項
  • DateTimeField：顯示「任何日期 / 今天 / 過去 7 天 / 本月 / 今年」選項

search_fields：搜尋功能

search_fields 會在列表頁上方加入搜尋框，讓你可以輸入關鍵字快速找到資料。

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ['title', 'author', 'category', 'is_published', 'created_at']
    list_filter = ['is_published', 'category']
    # 啟用搜尋，可搜尋標題、內文與作者
    search_fields = ['title', 'content', 'author']

search_fields 也支援跨關聯查詢，使用 雙底線語法（Double Underscore Syntax）存取關聯 Model 的欄位：

# 搜尋時也會查詢分類名稱
search_fields = ['title', 'content', 'author', 'category__name']

ordering：預設排序

ordering 設定列表頁的預設排序方式，覆蓋 Model 的 Meta.ordering。

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ['title', 'author', 'is_published', 'created_at']
    # 依建立時間降冪排序（最新的排在前面）
    ordering = ['-created_at']

使用 - 前綴代表降冪排序（Descending），不加 - 則為升冪排序（Ascending）。也可以指定多個欄位進行多重排序：

# 先依發布狀態降冪（已發布優先），再依建立時間降冪
ordering = ['-is_published', '-created_at']

list_per_page：每頁顯示筆數

list_per_page 控制每頁顯示的資料筆數，預設為 100。

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ['title', 'author', 'is_published', 'created_at']
    # 每頁顯示 25 筆
    list_per_page = 25

date_hierarchy：日期層級導航

date_hierarchy 會在列表頁上方產生日期層級導航列，讓你可以按年、月、日快速瀏覽資料。

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ['title', 'author', 'is_published', 'created_at']
    # 以建立時間作為日期層級導航
    date_hierarchy = 'created_at'

注意 date_hierarchy 的值是一個字串（欄位名稱），不是 list。它只能指定一個 DateField 或 DateTimeField 欄位。

新增 / 編輯頁面設定

除了列表頁的配置，ModelAdmin 也提供了控制新增與編輯頁面的選項。

fields 與 exclude

fields 指定新增 / 編輯頁面要顯示哪些欄位，以及它們的排列順序：

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ['title', 'author', 'is_published', 'created_at']
    # 指定編輯頁面的欄位與順序
    fields = ['title', 'category', 'author', 'content', 'is_published']

如果你想要排除特定欄位而非逐一列出，可以使用 exclude：

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ['title', 'author', 'is_published', 'created_at']
    # 排除 views 欄位，其餘欄位都顯示
    exclude = ['views']

注意：fields 和 exclude 不可同時使用。

readonly_fields

readonly_fields 讓指定的欄位在編輯頁面中以唯讀模式顯示，使用者可以看到值但無法修改。

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ['title', 'author', 'is_published', 'views', 'created_at']
    # 唯讀欄位：瀏覽次數與更新時間不允許手動修改
    readonly_fields = ['views', 'created_at', 'updated_at']

這在某些由系統自動維護的欄位上特別實用，例如瀏覽次數、建立時間、更新時間等，避免管理員不小心修改到這些值。

完整範例：Post 與 Category 的 Admin 設定

將前面介紹的所有配置組合起來，以下是一個完整的 admin.py 範例：

# blog/admin.py
from django.contrib import admin
from .models import Post, Category


@admin.register(Category)
class CategoryAdmin(admin.ModelAdmin):
    # 列表頁設定
    list_display = ['name', 'description', 'created_at']
    search_fields = ['name']
    ordering = ['name']
    list_per_page = 20


@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    # 列表頁設定
    list_display = [
        'title',
        'author',
        'category',
        'is_published',
        'views',
        'created_at',
    ]
    list_filter = ['is_published', 'category', 'created_at']
    search_fields = ['title', 'content', 'author', 'category__name']
    ordering = ['-created_at']
    list_per_page = 25
    date_hierarchy = 'created_at'

    # 新增 / 編輯頁面設定
    fields = [
        'title',
        'category',
        'author',
        'content',
        'is_published',
        'views',
        'created_at',
        'updated_at',
    ]
    readonly_fields = ['views', 'created_at', 'updated_at']

完成後啟動開發伺服器，進入 http://127.0.0.1:8000/admin/，你就能看到功能完整的管理介面：

  • Category 列表頁：顯示分類名稱與描述，支援搜尋
  • Post 列表頁：顯示文章標題、作者、分類、發布狀態、瀏覽次數與建立時間，右側有過濾器，上方有搜尋框與日期導航
  • Post 編輯頁：可編輯標題、分類、作者、內文與發布狀態，瀏覽次數與時間欄位為唯讀

總結

本篇介紹了 Django Admin 後台管理介面的基礎用法。我們首先釐清了 Admin 的正確定位——它是給開發者與內部團隊使用的管理工具，並非面向終端使用者的前台。接著從啟用 Admin、確認 INSTALLED_APPS 設定開始，學習了如何透過 createsuperuser 建立超級使用者帳號、存取 /admin/ 管理介面，以及使用 admin.site.register() 與 @admin.register() 裝飾器註冊 Model。

在 ModelAdmin 配置方面，我們掌握了 list_display 自訂列表欄位、list_filter 側邊欄過濾器、search_fields 搜尋功能、ordering 預設排序、list_per_page 分頁設定、date_hierarchy 日期導航等列表頁選項，以及 fields、exclude、readonly_fields 等編輯頁選項。最後透過 Post 與 Category 的完整範例，將所有配置整合在一起。

Django Admin 的強大之處在於，僅靠少量的 Python 程式碼就能建立一個功能完善的管理後台。下一篇我們將深入探討 ModelAdmin 的進階配置，包含 fieldsets 欄位分組、InlineModelAdmin 關聯編輯、自訂 Admin Actions 批次操作等功能。

BenZ Software Developer

熱愛技術的軟體開發者，在這裡分享程式開發經驗與學習筆記。