Healthchecks v4.4 配置参数详解

目标：系统梳理 Healthchecks v4.4 的全部配置参数——读取机制与优先级、逐项含义与默认值、实测生效验证，并给出小规模/生产两套推荐模板。已在 Ubuntu 22.04 源码部署与官方镜像部署两种形态下实测通过。

一、环境信息

• Healthchecks：v4.4（源码部署 /opt/healthchecks + 官方镜像 healthchecks/healthchecks:v4.4 双环境实测）
• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Python：3.12.15；Django：6.1
• 配置文件位置：源码部署 /opt/healthchecks/hc/local_settings.py 与 systemd 环境文件 /etc/healthchecks；镜像部署 .env（配合 env_file: 注入）
• 数据库：PostgreSQL 16（DB=postgres）与 SQLite（默认）两种形态均验证

二、前置条件

• 已按《Healthchecks v4.4 Ubuntu 22.04 安装指南》或《Healthchecks v4.4 Docker Compose 部署指南》完成部署并可登录；
• 知道自己的部署形态（源码/镜像），两种形态的配置入口见下表：

三、参数查看与修改方式

3.1 运行时查看实际生效值

Django 提供权威的运行时自查入口 manage.py shell，直接读 settings 对象即可确认当前生效值：

cd /opt/healthchecks
/opt/venv/bin/python manage.py shell -c "from django.conf import settings; print('SITE_ROOT =', settings.SITE_ROOT); print('SITE_NAME =', settings.SITE_NAME); print('DEBUG =', settings.DEBUG); print('ALLOWED_HOSTS =', settings.ALLOWED_HOSTS); print('DB ENGINE =', settings.DATABASES['default']['ENGINE'])"

实测输出：

SITE_ROOT = http://localhost:8000
SITE_NAME = Mychecks
DEBUG = False
ALLOWED_HOSTS = ['localhost', '127.0.0.1', 'hc-server']
DB ENGINE = django.db.backends.postgresql

镜像部署等价命令（替换容器名/服务名）：

docker compose exec -T web /opt/healthchecks/manage.py shell -c "from django.conf import settings; print(settings.SITE_ROOT, settings.SITE_NAME)"

3.2 修改方式与优先级

v4.4 的 hc/settings.py 统一从环境变量读取（os.getenv 系列），最后加载可选的 hc/local_settings.py 覆盖同名字段。源码中的加载逻辑（实测代码，hc/settings.py 末尾）：

# Read additional configuration from hc/local_settings.py if it exists
if (BASE_DIR / "hc/local_settings.py").exists():
    from .local_settings import *

结论：环境变量先读，local_settings.py 后加载、同名即覆盖；local_settings.py 不存在时完全走环境变量（镜像部署的形态）。两个易踩坑点实测：

• 敏感值支持文件注入：SECRET_KEY_FILE=/run/secrets/hc_secret 形式对 envsecret 类参数（如 SECRET_KEY、EMAIL_HOST_PASSWORD）有效，settings 会读文件内容并去除首尾空白；
• 环境变量有格式校验：布尔类参数只接受 True/False 字符串，写 true 会直接启动失败，报 Unexpected value XXX=true, use 'True' or 'False'。

四、参数总览

按功能分组的完整清单（默认值取自 hc/settings.py 与镜像内 docker/.env.example 实际内容）：

💡 说明：镜像专属参数（UWSGI_*、LISTEN_IPV6、SMTPD_PORT）由 uWSGI/启动脚本消费，源码部署不生效；其余参数两种形态通用。带 *_CLIENT_ID/SECRET/TOKEN 的集成项不配置时对应渠道在界面隐藏，配置即启用。

五、核心参数分类详解

5.1 站点标识与访问

SECRET_KEY（必改）。默认值 "---"（settings 中的占位符，等于没有密钥）。Django 会话签名、CSRF、以及 API Key 的 HMAC 派生都以它为根。生成：

python3 -c "import secrets; print(secrets.token_urlsafe(40))"

S4YD-1n8D2pQmXJ7bKzvLw3hTgUeRcA9F0sVqWxZkOyE

⚠️ 注意：更换 SECRET_KEY 后所有登录会话失效、已签发的 API Key 立即不可用（库中存的是 HMAC(SECRET_KEY, key)，换根后校验全失败），需重新生成 API Key。生产可用 SECRET_KEY_FILE 从密钥管理服务挂载。

DEBUG。默认 True，生产必须 False。为 True 时 Django 会在错误页暴露配置与调用栈。

ALLOWED_HOSTS。Host 头白名单，逗号分隔。默认只含 localhost。实测拦截行为——伪造不在白名单的 Host 直接 400：

curl -s -H "Host: evil.example.com" http://127.0.0.1:8000/accounts/login/ -o /dev/null -w "Host=evil.example.com -> %{http_code}\n"
curl -s -H "Host: localhost" http://127.0.0.1:8000/accounts/login/ -o /dev/null -w "Host=localhost -> %{http_code}\n"

Host=evil.example.com -> 400
Host=localhost -> 200

接入反代/域名后必须把域名补进白名单（Nginx 反代实测从 400 变 302 的完整过程见《Healthchecks v4.4 Docker Compose 部署指南》第十章）。

SITE_ROOT。对外访问的基础 URL，默认 http://localhost:8000。邮件正文里的链接、Check 的 ping URL、徽章 URL 都由它派生——上 TLS 或换域名后要同步修改，否则告警邮件里的链接指向旧地址。

SITE_NAME。站点名，默认 Mychecks，出现在页面标题与邮件落款。实测改后即时反映在登录页：

# .env 中 SITE_NAME=Mychecks 改为 OpsWatch，重建容器后：

<title>Log In - OpsWatch</title>

MASTER_BADGE_LABEL。全局徽章上的项目标签文字，默认取 SITE_NAME。

REGISTRATION_OPEN。默认 True；设为 False 后关闭自助注册（登录页不再提供注册入口），私有部署建议关闭、由管理员 createsuperuser 发账号。

SECURE_PROXY_SSL_HEADER。放在反代之后启用 HTTPS 判定，格式如 "X-Forwarded-Proto, https"；只有反代确实设置了该头才配置，否则有请求伪造风险。

REMOTE_USER_HEADER。配置后信任反代传入的用户头（如 X-Forwarded-User）实现 SSO 免登，默认未启用。

RP_ID。WebAuthn 硬件密钥登录的有效域，默认空（不启用）。

5.2 数据库

数据库引擎由 DB 选择（postgres/mysql/mariadb），不设置 DB 时走 SQLite（默认库名 hc.sqlite，路径 BASE_DIR 下，可用 DB_NAME 改写）。这是 settings.py 的实测分支逻辑：DB=postgres 时启用下方 HOST/PORT/NAME/USER/PASSWORD 连接参数；均不设置时仅 DB_NAME 生效为 SQLite 文件路径。

版本硬约束实测：v4.4（Django 6.1）要求 PostgreSQL ≥ 15，低于此版本 migrate 直接抛错：

django.db.utils.NotSupportedError: PostgreSQL 15 or later is required (found 14.24).

💡 技术拓展：Django 支持的数据库后端对比——

后端	Healthchecks 场景评价	适用
PostgreSQL	官方默认与推荐，jsonb/并发写好	生产首选
MySQL/MariaDB	需 mysqlclient 编译与 libmariadb-dev	已有 MySQL 运维体系
SQLite	零部署、单文件	个人/小规模；写入并发弱

本文环境采用 PostgreSQL 16（官方镜像 compose 默认组合）。

5.3 邮件

邮件既是告警出口也是入站 ping 的对端配置源，是自托管最常调的一组参数：

实测证据一：未配置 EMAIL_HOST 时执行任意管理命令会打印告警（配置后消失）：

?: (hc.api.W002) No SMTP configuration, cannot send email
        HINT: See https://github.com/healthchecks/healthchecks#sending-emails
?: (mail.W001) Your MAILERS setting has no 'default' entry. Sending email without a valid mailer will fail.

实测证据二：shell 里未加载环境变量直接跑管理命令，发信时报错与提示一致：

AssertionError: No SMTP configuration, see https://github.com/healthchecks/healthchecks#sending-emails

源码部署推荐把邮件变量放 systemd 环境文件（/etc/healthchecks，权限 600），web 与 sendalerts 单元共用：

EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=alert@example.com
EMAIL_HOST_PASSWORD=q1w2e3r4
DEFAULT_FROM_EMAIL=alert@example.com

PING_EMAIL_DOMAIN（默认 localhost）：入站邮件 ping 的收件域名。配合镜像参数 SMTPD_PORT（或源码部署 manage.py smtpd）启用后，向 <check-uuid>@<PING_EMAIL_DOMAIN> 发邮件即产生一次成功 ping。该 smtpd 只接受 Check 地址，发给人用的邮箱地址会被拒收（实测 550 5.1.1 Recipient rejected），属设计行为而非故障。

5.4 ping 与数据保留

⚠️ 注意：PING_BODY_LIMIT 只管 HTTP 上报的 body；邮件 ping 的正文留存策略由数据库定期清理任务控制，见《Healthchecks v4.4 进阶实战与运维》。

5.5 集成开关

每个集成渠道有独立开关（*_ENABLED=True/False）与凭据参数，默认值来自镜像 .env.example：APPRISE_ENABLED=False、MATTERMOST_ENABLED=True、MSTEAMS_ENABLED=True、OPSGENIE_ENABLED=True、PAGERTREE_ENABLED=True、PD_ENABLED=True、ROCKETCHAT_ENABLED=True、SLACK_ENABLED=True、SPIKE_ENABLED=True、VICTOROPS_ENABLED=True、ZULIP_ENABLED=True、WEBHOOKS_ENABLED=True、PROMETHEUS_ENABLED=True。

要点：

• 开关为 True 且凭据为空时，界面显示渠道但不可用；凭据齐全才真正可用；
• INTEGRATIONS_ALLOW_PRIVATE_IPS=False（默认）：Webhook 目标为内网地址时默认拒绝（防 SSRF），内网集成（如推给内网告警网关）需显式改 True；
• Telegram 需 TELEGRAM_TOKEN 并执行 manage.py settelegramwebhook 注册回调；Slack/Discord 等 OAuth 类需 CLIENT_ID/SECRET。

5.6 可观测性与运维

METRICS_KEY（默认空）。设置后开放 Prometheus 指标文档端点 /api/v3/metrics/，请求须带 X-Metrics-Key 头。实测（设置 METRICS_KEY=q1w2e3r4-metrics 后）：

curl -s http://127.0.0.1:8000/api/v3/metrics/ -o /dev/null -w "无密钥 -> %{http_code}\n"
curl -s -H "X-Metrics-Key: q1w2e3r4-metrics" http://127.0.0.1:8000/api/v3/metrics/

无密钥 -> 403
{"ts": 1792166213, "max_ping_id": 11, "max_notification_id": 6, "num_unprocessed_flips": 0}

返回的是抓取游标文档（配合官方 prometheus exporter 使用），num_unprocessed_flips 持续增长说明 sendalerts 派发积压，是告警链路健康度的重要指标。

STATSD_HOST（默认空）。配置 StatsD 地址后推送 hc.sendalerts.* 等打点指标。

SHELL_ENABLED（默认 False）。界面「Run This Command」调试面板的开关，生产保持关闭。

镜像专属：UWSGI_PROCESSES（默认 4，小内存可调 2）、UWSGI_DISABLE_LOGGING（关闭访问日志）、LISTEN_IPV6=1（额外监听 IPv6，纯 IPv4 系统开启会导致 uWSGI 启动失败）、SMTPD_PORT（容器内启动入站邮件服务监听该端口，Compose 需同步映射端口）。

六、生产配置模板

小规模（≤50 Check，2G 内存，SQLite 快速起步）——.env：

SECRET_KEY=<python3 -c "import secrets; print(secrets.token_urlsafe(40))" 生成>
DEBUG=False
ALLOWED_HOSTS=hc.example.org
SITE_ROOT=https://hc.example.org
SITE_NAME=OpsWatch
REGISTRATION_OPEN=False
DB_NAME=/opt/healthchecks-data/hc.sqlite
PING_BODY_LIMIT=10000
SHELL_ENABLED=False

生产（数百 Check，PostgreSQL 16，Nginx TLS 反代）——.env：

SECRET_KEY=<同上生成，妥善备份>
DEBUG=False
ALLOWED_HOSTS=hc.example.org
SITE_ROOT=https://hc.example.org
SITE_NAME=OpsWatch
MASTER_BADGE_LABEL=OpsWatch
REGISTRATION_OPEN=False
DB=postgres
DB_HOST=db
DB_PORT=5432
DB_NAME=hc
DB_USER=hc
DB_PASSWORD=<强密码>
DB_CONN_MAX_AGE=60
DB_SSLMODE=prefer
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=alert@example.com
EMAIL_HOST_PASSWORD=<SMTP密码>
DEFAULT_FROM_EMAIL=alert@example.com
PING_EMAIL_DOMAIN=hc.example.org
PING_BODY_LIMIT=10000
METRICS_KEY=<随机值>
SHELL_ENABLED=False
INTEGRATIONS_ALLOW_PRIVATE_IPS=False
UWSGI_PROCESSES=4

两套模板的适用边界：小规模模板面向个人/家庭实验室（SQLite 单文件、备份即拷贝）；生产模板面向团队（PG 独立持久化、TLS 域名、告警邮件、指标端点、Webhook 防内网）。上线前逐项核对：SECRET_KEY 已备份到密码管理器、SITE_ROOT 与反代域名一致、ALLOWED_HOSTS 含全部访问域名。

七、常见问题（FAQ）

Q1：改了 .env / 环境文件没生效？

镜像部署用 docker compose restart web 无效（env_file 只在容器创建时注入），必须 docker compose up -d web 重建；源码部署确认改动写入了 systemd 实际引用的 /etc/healthchecks 并执行 systemctl restart healthchecks-web（逐个服务重启）。复核手段用 3.1 的 manage.py shell 读 settings 对象，所见即生效值。

Q2：布尔参数写成小写 true 启动失败？

settings 对布尔环境变量有严格校验，实测报错：

ImproperlyConfigured: Unexpected value XXX=true, use 'True' or 'False'

统一写首字母大写的 True/False。

Q3：告警邮件里的链接是 localhost，点开不对？

SITE_ROOT 还是默认值。它决定邮件链接、ping URL、徽章 URL 的派生来源，改成对外域名后重启 web 与 sendalerts 两个服务（源码部署）或重建容器（镜像部署）。注意已创建 Check 的 ping URL 界面上会按新 SITE_ROOT 展示，历史邮件里的旧链接无法追溯修正。

Q4：API Key 突然全部失效？

SECRET_KEY 被更换。API Key 在库中存的是 HMAC(SECRET_KEY, key)，换根后旧 Key 校验失败是预期行为，重新生成即可；也说明 SECRET_KEY 必须备份且不随意轮换。

Q5：Webhook 推不到内网地址？

默认 INTEGRATIONS_ALLOW_PRIVATE_IPS=False 拒绝私有 IP 目标（SSRF 防护）。内网告警网关场景显式改 True，但要确保 Webhook 目标可信。

Q6：/metrics/ 返回 404 或 403？

404 说明路径不对——指标端点在 API 前缀下，是 /api/v3/metrics/；403 说明 METRICS_KEY 未配置或请求未带 X-Metrics-Key 头（实测两种情形见 5.6）。

八、参考链接

• 官方自托管配置文档：https://healthchecks.io/docs/self_hosted_configuration/
• settings 源码（v4.4）：https://github.com/healthchecks/healthchecks/blob/v4.4/hc/settings.py
• 镜像 .env 示例：https://github.com/healthchecks/healthchecks/blob/v4.4/docker/.env.example
• 本系列其他篇：《Healthchecks v4.4 Ubuntu 22.04 安装指南》《Healthchecks v4.4 Docker Compose 部署指南》《Healthchecks v4.4 快速入门与集成示例》《Healthchecks v4.4 进阶实战与运维》