龙虾 OpenClaw 容器健康检查怎么写：探活接口与失败策略

一、前言：为什么需要容器健康检查？

在使用 OpenClaw（龙虾）部署服务时，容器的健康检查是保障服务稳定运行的关键环节。通过健康检查，OpenClaw 可以自动判断容器是否正常运行，从而决定是否重启、迁移或扩容容器。本文将详细介绍如何为 OpenClaw 容器编写探活接口，并配置失败策略，确保服务高可用。

二、探活接口设计原则

探活接口（Health Check）是容器健康检查的核心。它需要满足以下条件：

• 轻量级：接口响应时间应尽量短，避免因接口本身耗时导致健康检查失败。
• 幂等性：多次调用接口不应影响服务状态。
• 可配置性：支持自定义路径、方法、超时时间等。
• 可监控性：接口应提供清晰的响应状态码和内容，便于调试。

三、探活接口实现方式

1. 使用 HTTP 接口

这是最常见的方式，适用于 Web 服务或微服务架构。

示例：基于 Flask 的探活接口

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/health', methods=['GET'])
def health():
    return jsonify({
        "status": "ok",
        "message": "Service is running normally."
    }), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

接口说明

• 路径：/health
• 方法：GET
• 响应格式：JSON，包含 status 和 message 字段
• 状态码：200 OK 表示健康，500 Internal Server Error 表示异常

2. 使用 TCP 探活

适用于不提供 HTTP 接口的服务，如数据库、中间件等。

示例：使用 netcat 检测端口连通性

nc -zv 127.0.0.1 5000

• nc：Netcat 工具
• -z：仅扫描，不发送数据
• -v：显示详细信息
• 127.0.0.1 5000：目标地址和端口

3. 使用自定义探活脚本

适用于复杂逻辑，如检查文件是否存在、服务是否启动等。

示例：检查日志文件是否存在

#!/bin/bash
LOG_FILE="/var/log/app.log"
if [ -f "$LOG_FILE" ]; then
    echo "ok"
    exit 0
else
    echo "error"
    exit 1
fi

四、OpenClaw 健康检查配置

OpenClaw 支持通过 healthcheck 配置项定义健康检查策略。

1. 基本配置结构

healthcheck:
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s
  command: ["CMD", "curl", "-f", "http://localhost:5000/health"]

• interval：检查间隔
• timeout：单次检查超时时间
• retries：连续失败次数
• start_period：启动后等待时间
• command：执行的命令（支持 CMD 或 ENTRYPOINT）

2. 配置示例

示例 1：HTTP 探活

healthcheck:
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s
  command: ["CMD", "curl", "-f", "http://localhost:5000/health"]

示例 2：TCP 探活

healthcheck:
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s
  command: ["CMD", "nc", "-z", "localhost", "5000"]

示例 3：自定义脚本探活

healthcheck:
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s
  command: ["CMD", "/app/check_health.sh"]

五、失败策略配置

OpenClaw 提供了多种失败策略，用于处理健康检查失败后的操作。

1. 基本策略

failure_action: restart

• restart：重启容器
• pause：暂停容器
• ignore：忽略失败，不执行任何操作

2. 高级策略（结合 on_failure）

on_failure:
  - action: restart
    delay: 5s
  - action: pause
    delay: 30s
  - action: ignore

• delay：延迟时间
• 支持多个策略，按顺序执行

3. 示例配置

healthcheck:
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s
  command: ["CMD", "curl", "-f", "http://localhost:5000/health"]

on_failure:
  - action: restart
    delay: 5s
  - action: pause
    delay: 30s
  - action: ignore

六、探活接口优化建议

1. 使用缓存减少接口压力

from flask import Flask, jsonify
from functools import wraps
import time

app = Flask(__name__)

# 缓存探活结果
last_check = time.time()
cache = {}

def cache_health(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        nonlocal last_check
        now = time.time()
        if now - last_check < 5:  # 每5秒更新一次
            return jsonify(cache), 200
        result = func(*args, **kwargs)
        cache.update(result)
        last_check = now
        return result
    return wrapper

@app.route('/health', methods=['GET'])
@cache_health
def health():
    return jsonify({
        "status": "ok",
        "message": "Service is running normally."
    }), 200

2. 使用 Prometheus 暴露探活指标

from prometheus_client import start_http_server, Gauge

app = Flask(__name__)
health_gauge = Gauge('app_health', 'Application health status', ['status'])

@app.route('/health', methods=['GET'])
def health():
    health_gauge.labels(status='ok').set(1)
    return jsonify({
        "status": "ok",
        "message": "Service is running normally."
    }), 200

七、常见问题与解决方案

1. 健康检查失败但服务正常

• 检查探活接口是否返回 200 OK 和 {"status": "ok"}。
• 检查 OpenClaw 的 healthcheck 配置是否正确。
• 检查容器日志是否有异常。

2. 健康检查耗时过长

• 优化探活接口逻辑，减少数据库查询或文件读取。
• 使用缓存或异步探活。
• 调整 timeout 和 interval 参数。

3. 探活接口无法访问

• 检查容器是否启动成功。
• 检查网络配置（如 --network、--publish）。
• 检查探活路径是否正确（如 /health 是否在容器内可访问）。

八、总结

通过合理设计探活接口和配置 OpenClaw 的健康检查策略，可以有效保障服务的高可用性。建议根据服务类型选择合适的探活方式，并结合失败策略进行灵活配置。同时，优化探活接口性能和可监控性，是提升系统稳定性的关键。

九、附录：常用命令与工具

十、结语

健康检查是容器化部署中不可或缺的一环。通过本文的指导，你可以快速为 OpenClaw 容器配置探活接口和失败策略，提升服务的稳定性和可维护性。