django-alive 🕺

为您的Django应用程序提供两个健康检查端点

Alive

验证WSGI服务器是否正在响应。

• 默认URL: /-/alive/
• 成功
  • 状态码: 200
  • 内容: ok
• 失败：此视图永远不会返回失败。失败意味着您的WSGI服务器没有运行。

Health

验证服务是否就绪。

• 默认URL: /-/health/
• 成功
  • 状态码: 200
  • 内容: {"healthy": true}
• 失败
  • 状态码: 503
  • 内容: {"healthy": false, "errors": ["错误 1", "错误 2"]}

默认情况下，健康端点将测试数据库连接，但可以配置为检查缓存、静态文件或任何其他自定义检查。

支持Django 3.2+和Python 3.6+。

安装

pip install django-alive

配置

将此添加到您项目的urlpatterns

path("-/", include("django_alive.urls"))

如果您想使用 healthcheck 管理命令，请将 django_alive 添加到 INSTALLED_APPS。

启用检查

默认的“健康”端点将在数据库上执行简单的 SELECT 1 查询。您可以在 Django 设置中启用其他检查。

使用 ALIVE_CHECKS 设置来配置要包含的检查。它是一个包含第一个参数（Python 函数的路径）和第二个参数（传递给该函数的关键字参数字典）的元组列表。一个完整的示例

ALIVE_CHECKS = [
    ("django_alive.checks.check_database", {}),
    ("django_alive.checks.check_staticfile", {
        "filename": "img/favicon.ico",
    }),
    ("django_alive.checks.check_cache", {
        "cache": "session",
        "key": "test123",
    }),
    ("django_alive.checks.check_migrations", {}),
]

⚠️ 警告：从版本 1.3.0 开始更改 ⚠️

注意：旧设置中将 ALIVE_CHECKS 作为字典已被废弃，改为列表形式。

内置检查

在 django_alive.checks 中定义。

def check_cache(key="django-alive", cache="default")

针对指定的缓存获取缓存键。

参数

• key (str)：要获取的缓存键（不需要存在）
• cache (str)：要执行的缓存别名

def check_database(query="SELECT 1", database="default")

针对指定的数据库运行 SQL 查询。

参数

• query (str)：要执行的 SQL
• database (str)：要执行的数据库别名

def check_migrations(alias=None)

验证所有定义的迁移都已应用

参数

• alias (str)：可选的数据库别名（默认：检查所有定义的数据库）

def check_staticfile(filename)

验证静态文件是否可达

参数

• filename (str)：要验证的静态文件

管理命令

除了视图外，还可以通过 manage.py healthcheck 管理命令运行配置的健康检查。如果所有健康检查未通过，它将以错误代码退出。

自定义检查

django-alive 设计得很容易通过您自己的自定义检查进行扩展。只需定义一个执行检查的函数，并在失败时抛出 django_alive.HealthcheckFailure 异常。有关如何编写检查的示例，请参阅 checks.py。

禁用健康检查的 ALLOWED_HOSTS

通常，负载均衡器在探测健康检查端点时不会传递 Host 标头。这为 Django 的主机头验证带来了问题。包含了一个中间件，它将仅在健康检查端点关闭主机检查。这是安全的，因为这些视图永远不会对 Host 标头做任何事情。

在您的 MIDDLEWARE 的 开头 插入此中间件以启用它

MIDDLEWARE = [
    "django_alive.middleware.healthcheck_bypass_host_check",
    # ...
]

处理 SECURE_SSL_REDIRECT

如果您的负载均衡器执行 HTTPS 终止，并且您在设置中设置了 SECURE_SSL_REDIRECT=True，请确保您的健康检查 URL 不会也重定向到 HTTPS。在这种情况下，请将以下内容添加到您的设置中

SECURE_REDIRECT_EXEMPT = [r"^-/"]  # django-alive URLs

2.0.0 (2024-08-30)

• 允许以不同的参数多次执行检查；ALIVE_CHECKS 现在应是一个元组列表（将其设置为字典会导致弃用警告）。

1.2.2 (2024-08-14)

• 添加 GitHub Action 以运行针对受支持版本的测试
• 从 GitHub Actions 发布

1.2.1 (2021-07-23)

• 更新 PyPI 元数据

1.2.0 (2021-07-23)

• 更新测试矩阵。Python 2 不再“官方”支持。
• 如果 URL 未设置，防止中间件中出现回溯

1.1.0 (2019-11-06)

• 添加 healthcheck 管理命令
• 添加可选的 check_migrations 健康检查

1.0.1 (2018-09-10)

• 文档改进
• Python 3.7 支持

1.0.0 (2018-08-21)

• 初始发布