Healthchecks 是一个用 Python 和 Django 编写的开源心跳监控系统，它的核心思路是“反向上报”：你在服务器上配置好定时任务，任务每次执行完成后向 Healthchecks 平台发送一个 HTTP 请求，平台收到请求就认为任务正常；如果超过预设时间没有收到请求，系统会判定任务异常并通过邮件、Webhook 等方式发出告警。这种方式对监控备份脚本、数据同步、报表生成等周期性任务特别有效。本文介绍如何在 phpEnv 环境下完整搭建并运行 Healthchecks。
一、准备工作与环境要求
Healthchecks 本身是基于 Python 3.10 以上版本开发的 Django 项目，它并不依赖 PHP 运行，但在 phpEnv 中搭建有实际意义：phpEnv 提供了 Nginx 或 Apache 反向代理、MySQL 数据库以及站点管理的图形界面，我们可以借助 phpEnv 创建站点和数据库，再通过反向代理把请求转发给 Healthchecks 的 Python 进程。
开始之前请确认以下条件：phpEnv 已正常启动；安装了 Python 3.10 及以上版本（命令 python --version 可以查看）；MySQL 数据库服务运行正常；Composer 不是必需的，Healthchecks 使用 pip 管理依赖。如果机器上没有 Python，先去官网下载安装包，安装时记得勾选 Add Python to PATH，否则后续命令行无法直接调用。
接着打开 phpEnv 的站点管理面板，新建一个站点，例如域名为 hc.ipipp.com，PHP 版本可以随意选择，因为后面我们会把这个站点的请求全部代理到 Python 服务。同时在数据库管理中创建一个数据库，命名为 healthchecks，字符集选择 utf8mb4，并记下数据库账号和密码。
二、下载 Healthchecks 并初始化项目
Healthchecks 的源码托管在 GitHub 上，可以直接用 git 命令克隆，也可以下载压缩包解压。假设我们把项目放在 D 盘的 site 目录下，进入 phpEnv 的站点目录后执行：
cd D:\phpenv\www\hc.ipipp.com git clone https://github.com/healthchecks/healthchecks.git cd healthchecks
下载完成后进入项目目录，先创建 Python 虚拟环境，避免依赖包污染系统环境：
python -m venv venv venv\Scripts\activate pip install -r requirements.txt
依赖安装可能需要几分钟时间，国内网络环境下建议先切换 pip 镜像源，例如执行 pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/，速度会明显提升。安装完成后，需要复制一份配置文件：
copy .env.example .env</code>
然后编辑 .env 文件，填写数据库连接信息。Healthchecks 默认使用 SQLite，但既然 phpEnv 已经提供了 MySQL，用 MySQL 更稳妥，连接字符串格式如下：
DATABASE_URL = "mysql://用户名:密码@127.0.0.1:3306/healthchecks"
保存后执行数据库迁移，生成所有数据表，并创建管理员账号：
python manage.py migrate python manage.py createsuperuser
createsuperuser 会提示输入邮箱和密码，这个账号用于登录后台。全部命令执行成功后，项目初始化就完成了。
三、启动服务并配置 phpEnv 反向代理
Healthchecks 自带开发服务器，先在命令行启动它验证功能是否正常：
python manage.py runserver 0.0.0.0:8000
浏览器访问 http://127.0.0.1:8000 能看到登录页面就说明服务已经跑起来了。但生产环境不建议直接使用 runserver，推荐用 uwsgi 或 waitress 承载。以 waitress 为例：
pip install waitress waitress-serve --port=8000 hc.wsgi:application
接下来配置 phpEnv 让域名请求转发到 8000 端口。如果你使用的是 Nginx，打开 phpEnv 中该站点的配置文件，在 server 块中加入以下内容：
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}保存后在 phpEnv 中重启 Nginx，然后通过域名访问，看到 Healthchecks 首页即代表反向代理配置成功。如果是 Apache 站点，则需要启用 proxy 和 proxy_http 模块，配置方式类似，使用 ProxyPass 指令指向本机 8000 端口即可。
需要注意端口冲突问题：phpEnv 自身管理的端口列表里看不到 Python 进程占用的 8000 端口，如果启动 waitress 时提示端口被占用，执行 netstat -ano | findstr 8000 找到占用进程的 PID，再通过任务管理器结束它即可。
四、添加检查项并接入定时任务
登录后台后点击 Add Check 创建第一个检查项，这里最关键的三个参数是 Schedule（执行周期）、Grace（宽限时间）和 Ping URL。例如某个备份脚本每天凌晨 2 点执行，就把 Period 设置为 1 天，Grace 设置为 30 分钟，表示超过一天零三十分钟没收到心跳才判定失败，避免网络抖动造成误报。
拿到 Ping URL 后，把它加到定时任务末尾。Linux 下使用 curl 访问即可：
0 2 * * * /root/backup.sh && curl -s https://hc.ipipp.com/ping/xxxx-xxxx >/dev/null
Windows 下可以写一个批处理文件，利用 phpEnv 所在机器的任务计划程序调用：
@echo off call D:\scripts\backup.bat curl -s https://hc.ipipp.com/ping/xxxx-xxxx >nul
把任务脚本放在 curl 前面有个好处：只有任务成功执行才会发送心跳，任务中途报错退出时不会上报，Healthchecks 就能准确捕捉到失败状态。如果希望失败也上报，可以在脚本里做错误判断，失败时访问以 /fail 结尾的 URL，平台会明确标记该次执行为失败而不是简单超时。
五、开启邮件告警与常见问题
监控系统如果不能主动通知就失去了大半价值。Healthchecks 支持邮件、钉钉、企业微信、Telegram 等多种通知渠道，邮件配置在管理后台的 Settings 中进行，填写 SMTP 服务器、端口、账号和授权码。phpEnv 环境本身自带邮件发送组件，但 Healthchecks 是独立 Python 进程，必须单独配置 SMTP，不能复用 phpEnv 的设置。
配置完成后可以先发一封测试邮件验证连通性。之后在检查项的详情页，把 Email 通知渠道勾选上，一旦心跳超时，绑定的邮箱就会收到告警。这里有个容易踩的坑：如果反向代理没有传递 X-Forwarded-Proto 头，Healthchecks 生成的 Ping URL 可能显示为 http 而不是 https，导致部分客户端上报异常，检查前面 Nginx 配置里的 proxy_set_header 是否写全即可解决。
最后建议把 waitress 进程注册为 Windows 服务或使用 nssm 工具托管，这样机器重启后监控平台能自动恢复运行，避免出现“监控系统本身挂了没人知道”的尴尬情况。整套方案搭建成本很低，但能显著提升定时任务的可观测性，值得花一点时间配置。
phpEnvHealthchecks任务监控修改时间：2026-09-03 13:37:05