umbraco-health-check

Umbraco 健康检查

这是什么？

Umbraco 中的健康检查允许你创建自定义系统诊断，并在健康检查仪表板中显示。它们会验证 Umbraco 安装及相关服务是否正常运行。健康检查可以报告状态、显示警告，并提供可操作的建议来解决问题。

文档

实施前务必获取最新文档：

• 主要文档：https://docs.umbraco.com/umbraco-cms/run-in-production/infrastructure-and-ops/health-check
• 基础：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• 扩展注册表：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry

相关基础技能

• Context API：访问应用程序状态时

  • 参考技能：umbraco-context-api

• 控制器：为检查创建 API 端点时

  • 参考技能：umbraco-controllers

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提问 - 要检查什么？要提供哪些操作？
3. 生成文件 - 基于最新文档创建 manifest + context
4. 说明 - 展示创建的内容以及如何测试

最小示例

Manifest (manifests.ts)

import type { ManifestHealthCheck } from '@umbraco-cms/backoffice/health-check';

export const manifests: Array<ManifestHealthCheck> = [
  {
    type: 'healthCheck',
    alias: 'My.HealthCheck.Custom',
    name: 'Custom Health Check',
    api: () => import('./my-health-check.context.js'),
    meta: {
      label: 'Custom Check',
    },
  },
];

Context 实现 (my-health-check.context.ts)

import { UmbHealthCheckContext } from '@umbraco-cms/backoffice/health-check';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
import type { HealthCheckResultResponseModel } from '@umbraco-cms/backoffice/external/backend-api';

export class MyHealthCheckContext extends UmbHealthCheckContext {
  constructor(host: UmbControllerHost) {
    super(host);
  }

  override async check(): Promise<HealthCheckResultResponseModel> {
    // Perform your health check logic
    const isHealthy = await this.#performCheck();

    return {
      message: isHealthy ? 'All systems operational' : 'Issue detected',
      resultType: isHealthy ? 'Success' : 'Warning',
      actions: isHealthy ? [] : [
        {
          alias: 'fix-issue',
          name: 'Fix Issue',
          description: 'Attempt to automatically fix this issue',
        },
      ],
    };
  }

  async #performCheck(): Promise<boolean> {
    // Your custom check logic here
    return true;
  }

  override async executeAction(actionAlias: string): Promise<HealthCheckResultResponseModel> {
    if (actionAlias === 'fix-issue') {
      // Execute the fix action
      return {
        message: 'Issue has been resolved',
        resultType: 'Success',
        actions: [],
      };
    }

    return {
      message: 'Unknown action',
      resultType: 'Error',
      actions: [],
    };
  }
}

export { MyHealthCheckContext as api };

接口参考

interface ManifestHealthCheck extends ManifestBase {
  type: 'healthCheck';
  api: ApiLoaderProperty; // Should implement UmbHealthCheckContext
  meta: MetaHealthCheck;
}

interface MetaHealthCheck {
  label: string;
}

// Result types: 'Success' | 'Warning' | 'Error' | 'Info'
interface HealthCheckResultResponseModel {
  message: string;
  resultType: string;
  actions?: Array<{
    alias: string;
    name: string;
    description?: string;
  }>;
}

后端 C# 健康检查

健康检查也可以实现为由 Umbraco 自动发现的 C# 类。

using Umbraco.Cms.Core.HealthChecks;

namespace MyPackage.HealthChecks;

[HealthCheck(
    "12345678-1234-1234-1234-123456789012",
    "My Custom Check",
    Description = "Verifies custom services are running",
    Group = "Custom")]
public class MyHealthCheck : HealthCheck
{
    public MyHealthCheck(HealthCheckContext context) : base(context) { }

    public override Task<IEnumerable<HealthCheckStatus>> GetStatus()
    {
        var isHealthy = CheckMyService();
        var status = new HealthCheckStatus(isHealthy ? "Service running" : "Service down")
        {
            ResultType = isHealthy ? StatusResultType.Success : StatusResultType.Error,
            Actions = isHealthy ? null : new List<HealthCheckAction>
            {
                new("restart", Id) { Name = "Restart Service" }
            }
        };
        return Task.FromResult<IEnumerable<HealthCheckStatus>>(new[] { status });
    }

    public override HealthCheckStatus ExecuteAction(HealthCheckAction action)
    {
        if (action.Alias == "restart")
        {
            RestartMyService();
            return new HealthCheckStatus("Restarted") { ResultType = StatusResultType.Success };
        }
        throw new InvalidOperationException("Unknown action");
    }

    private bool CheckMyService() => true;
    private void RestartMyService() { }
}

最佳实践

• 返回清晰、可操作的消息
• 尽可能提供修复操作
• 使用适当的结果类型（Success、Warning、Error、Info）
• 考虑性能——健康检查会定期运行

就是这样！务必获取最新文档，保持示例简洁，并生成完整可运行的代码。