---
title: "Windows 控制台事件处理器"
date: 2026-02-08
lastmod: 2026-02-08
description: "控制是否在 Windows 系统上注册控制台事件处理器的配置项说明"
tags: ["启动配置", "Windows", "优雅关闭"]
summary: "配置项作用 #  bootstrap.ctrlhandler 配置项控制是否在 Windows 系统上注册控制台事件处理器（Console Ctrl Handler）。该处理器可以捕获 Windows 的控制台关闭事件，实现优雅关闭。
配置项类型 #  该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。
默认值 #  true（启用） 是否必需 #  可选配置项
工作原理 #  当此配置启用时（默认），Easysearch 会在 Windows 系统上注册一个控制台事件处理器：
 事件监听：监听 Windows 控制台控制事件，如关闭窗口事件 优雅关闭：捕获关闭事件后触发优雅关闭流程 清理资源：确保在退出前正确释放资源 数据安全：确保正在进行的操作完成或安全中止  支持的事件 #  处理器主要捕获以下 Windows 控制台事件：
   事件代码 说明     CTRL_CLOSE_EVENT 用户关闭控制台窗口   CTRL_LOGOFF_EVENT 用户注销   CTRL_SHUTDOWN_EVENT 系统关机    使用示例 #  # 默认配置（启用） bootstrap."
---


## 配置项作用

`bootstrap.ctrlhandler` 配置项控制是否在 Windows 系统上注册控制台事件处理器（Console Ctrl Handler）。该处理器可以捕获 Windows 的控制台关闭事件，实现优雅关闭。

## 配置项类型

该配置项为**静态配置**，需要在启动时设置，修改后需要重启节点才能生效。

## 默认值

```
true（启用）
```

## 是否必需

**可选配置项**

## 工作原理

当此配置启用时（默认），Easysearch 会在 Windows 系统上注册一个控制台事件处理器：

1. **事件监听**：监听 Windows 控制台控制事件，如关闭窗口事件
2. **优雅关闭**：捕获关闭事件后触发优雅关闭流程
3. **清理资源**：确保在退出前正确释放资源
4. **数据安全**：确保正在进行的操作完成或安全中止

## 支持的事件

处理器主要捕获以下 Windows 控制台事件：

| 事件代码 | 说明 |
|---------|------|
| CTRL_CLOSE_EVENT | 用户关闭控制台窗口 |
| CTRL_LOGOFF_EVENT | 用户注销 |
| CTRL_SHUTDOWN_EVENT | 系统关机 |

## 使用示例

```yaml
# 默认配置（启用）
bootstrap.ctrlhandler: true

# 禁用控制台处理器
bootstrap.ctrlhandler: false
```

## 推荐设置建议

**Windows 环境建议**：保持默认值 `true`

**特殊场景禁用：**

```yaml
# 作为 Windows 服务运行时，可能需要禁用
bootstrap.ctrlhandler: false
```

## 平台差异

| 平台 | 是否支持此配置 | 说明 |
|-----|--------------|------|
| Windows | 是 | 控制台 Ctrl+Break、关闭窗口等事件 |
| Linux/Unix | 否 | 使用信号机制处理 |
| macOS | 否 | 使用信号机制处理 |

## 优雅关闭流程

```
Windows 控制台关闭事件
        │
        ▼
控制台事件处理器捕获
        │
        ▼
触发优雅关闭流程
        │
        ├──→ 停止接受新请求
        ├──→ 完成正在进行的请求
        ├──→ 持久化未完成的数据
        ├──→ 释放资源（连接、文件句柄等）
        └──→ 退出进程
```

## 相关配置项

| 配置项 | 作用 | 默认值 |
|-------|------|-------|
| `bootstrap.memory_lock` | 锁定内存防止交换 | false |
| `bootstrap.system_call_filter` | 启用系统调用过滤 | true |

## 禁用的后果

如果禁用此配置：

1. **强制终止**：关闭窗口时进程可能被立即终止
2. **数据丢失**：正在进行的操作可能未完成
3. **资源泄漏**：部分资源可能未正确释放
4. **文件损坏**：正在写入的文件可能损坏

## 日志示例

启用后，触发关闭时的日志：

```
[INFO ][o.e.b.Bootstrap ] running graceful exit on windows
```

## 注意事项

1. **静态配置**：修改此配置需要重启节点
2. **Windows 专用**：此配置仅在 Windows 平台生效，其他平台忽略
3. **服务模式**：作为 Windows 服务运行时，服务的生命周期管理可能覆盖此机制
4. **调试场景**：开发调试时可能需要禁用以快速终止进程
5. **与信号处理的关系**：Linux/Unix 系统使用信号（SIGTERM、SIGINT）实现类似功能