Doctor 模块

Doctor 是一个可复用的 ZTBCMS 运行环境自检模块，用于统一检查数据库、Redis、队列 Worker、计划任务、必要配置和可写目录等运行依赖。

安装

将模块放入 ZTBCMS 的 app/doctor 目录，在 ThinkPHP 项目根目录执行：

php think module:install doctor

Doctor V1.0 不创建业务数据表和管理菜单。

使用

输出人类可读报告：

php think doctor

输出可供部署脚本解析的 JSON：

php think doctor --json

JSON 模式的标准输出只包含一个 JSON 文档。

退出码

退出码	含义
0	仅存在 PASS 或 SKIP
1	存在 WARN 且不存在 FAIL
2	至少存在一个 FAIL

注册检查项

宿主项目在 config/doctor.php 的 checks 中按执行顺序注册 Check：

<?php

use app\doctor\check\DatabaseConnectionCheck;
use app\platform\doctor\check\CronSchedulerCheck;

return [
    'checks' => [
        [
            'class' => DatabaseConnectionCheck::class,
        ],
        [
            'class' => CronSchedulerCheck::class,
            'options' => [
                'max_idle_seconds' => 180,
                'stale_lock_seconds' => 600,
            ],
        ],
    ],
];

注册规则：

• class 必须实现 DoctorCheckInterface
• options 可选，默认为空数组
• 配置中出现的 Check 即为启用，关闭时从 checks 中移除
• Check ID 默认根据类名生成，普通场景不需要配置
• 同一个 Check 类注册多次时，每项必须配置唯一 id

自定义 Check

业务 Check 继承 BaseDoctorCheck，必须实现 name() 和 check()，description() 按需覆盖：

<?php

namespace app\platform\doctor\check;

use app\doctor\base\BaseDoctorCheck;
use app\doctor\dto\DoctorResult;

/**
 * 示例业务检查
 */
class ExampleCheck extends BaseDoctorCheck
{
    /**
     * 获取检查项名称
     *
     * @return string
     */
    public function name(): string
    {
        return '示例检查';
    }

    /**
     * 获取检查项描述
     *
     * @return string
     */
    public function description(): string
    {
        return '检查示例业务依赖是否可用';
    }

    /**
     * 执行检查
     *
     * @param array $options 检查参数
     * @return DoctorResult
     */
    public function check(array $options = []): DoctorResult
    {
        $available = (bool)($options['available'] ?? true);
        if ($available) {
            return $this->pass('示例依赖正常');
        }

        return $this->fail('示例依赖异常', '检查示例服务配置');
    }
}

BaseDoctorCheck 提供以下结果构造方法：

$this->pass($message, $details);
$this->warn($message, $suggestion, $details);
$this->fail($message, $suggestion, $details);
$this->skip($message, $details);

Check 只返回 DoctorResult，不应直接输出控制台文本。单个 Check 抛出异常时，Doctor 会记录为 FAIL 并继续执行其他项。

同类多实例

通用 Check 检查多个对象时，使用可选 id 区分：

[
    'id' => 'queue_notice_import',
    'class' => ProcessCheck::class,
    'options' => [
        'match' => ['php', 'think', 'queue:work', '--queue', 'notice_import'],
        'start_command' => 'php think queue:work --queue notice_import',
    ],
],

id 仅允许小写字母、数字和下划线，且必须以小写字母开头。配置 id 的优先级高于 Check 的 checkId()。

安全注意事项

• Check 应以只读诊断为原则，不自动启动进程、删除锁或重试任务
• details 不得放入密码、Token、Secret、Cookie、完整 DSN 或队列 Payload
• 网络和外部连接检查必须设置有限超时
• 进程检查只证明当前主机存在目标进程，不证明 Worker 已成功消费任务
• Doctor V1.0 不支持跨主机或跨容器进程检查