---
title: "系统调用过滤配置"
date: 2026-03-29
lastmod: 2026-03-29
description: "控制是否启用系统调用过滤（seccomp）增强安全性的配置项说明"
tags: ["启动配置", "安全", "系统调用"]
summary: "配置项作用 #  bootstrap.system_call_filter 配置项控制是否启用系统调用过滤（System Call Filter），基于 Linux seccomp（Secure Computing Mode）机制限制进程可以执行的系统调用，从而增强安全性。
配置项类型 #  该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。
默认值 #  true（启用） 是否必需 #  可选配置项
工作原理 #  系统调用过滤通过 seccomp 机制工作：
┌─────────────────────────────────────┐ │ Easysearch 进程 │ └─────────────────────────────────────┘ │ │ 执行系统调用 ▼ ┌─────────────────────────────────────┐ │ seccomp 过滤器 │ │ (启用时：只允许安全的系统调用) │ └─────────────────────────────────────┘ │ ┌─────┴─────┐ │ │ 允许的调用 拒绝的调用 │ │ ▼ ▼ 正常执行 返回 EPERM 安全增强 #  启用系统调用过滤可以防御：
   威胁类型 防御效果     代码注入攻击 阻止执行恶意代码的系统调用   内核漏洞利用 限制可利用的系统调用范围   权限提升 降低攻击面   意外操作 防止执行危险系统调用    允许的系统调用 #  过滤器允许执行必要的安全系统调用："
---


## 配置项作用

`bootstrap.system_call_filter` 配置项控制是否启用系统调用过滤（System Call Filter），基于 Linux seccomp（Secure Computing Mode）机制限制进程可以执行的系统调用，从而增强安全性。

## 配置项类型

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

## 默认值

```
true（启用）
```

## 是否必需

**可选配置项**

## 工作原理

系统调用过滤通过 seccomp 机制工作：

```
┌─────────────────────────────────────┐
│         Easysearch 进程              │
└─────────────────────────────────────┘
            │
            │ 执行系统调用
            ▼
┌─────────────────────────────────────┐
│      seccomp 过滤器                  │
│  (启用时：只允许安全的系统调用)       │
└─────────────────────────────────────┘
            │
      ┌─────┴─────┐
      │           │
  允许的调用    拒绝的调用
      │           │
      ▼           ▼
   正常执行    返回 EPERM
```

## 安全增强

启用系统调用过滤可以防御：

| 威胁类型 | 防御效果 |
|---------|---------|
| 代码注入攻击 | 阻止执行恶意代码的系统调用 |
| 内核漏洞利用 | 限制可利用的系统调用范围 |
| 权限提升 | 降低攻击面 |
| 意外操作 | 防止执行危险系统调用 |

## 允许的系统调用

过滤器允许执行必要的安全系统调用：

- 文件 I/O 操作（read、write、open、close 等）
- 网络操作（socket、connect、bind 等）
- 内存管理（mmap、munmap、mprotect 等）
- 线程管理（clone、set_robust_list 等）
- 时间相关（clock_gettime、gettimeofday 等）

## 使用示例

```yaml
# 默认配置（启用，推荐）
bootstrap.system_call_filter: true

# 禁用（不推荐）
bootstrap.system_call_filter: false
```

## 推荐设置建议

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

**特殊场景禁用：**

```yaml
# 以下场景可能需要禁用：
# 1. 使用不兼容的插件
# 2. 需要执行受限制的系统调用
# 3. 在某些受限容器环境中
bootstrap.system_call_filter: false
```

## 平台支持

| 平台 | 支持状态 | 说明 |
|-----|---------|------|
| Linux | 支持 | 完整支持 seccomp |
| Windows | 不支持 | 配置被忽略 |
| macOS | 不支持 | 配置被忽略 |
| 容器环境 | 取决于配置 | 需要容器支持 seccomp |

## 容器环境注意事项

在某些容器环境中运行时：

**Docker：**
```yaml
# Docker 默认启用 seccomp，通常兼容
docker run -it --cap-add=SYS_ADMIN easysearch

# 使用自定义 seccomp 配置文件
docker run -it --security-opt seccomp=custom-profile.json easysearch
```

**Kubernetes：**
```yaml
# Pod 配置示例
apiVersion: v1
kind: Pod
spec:
  securityContext:
    seccompProfile:
      type: RuntimeDefault  # 或 Unconfined
```

## 验证过滤状态

启动日志会显示系统调用过滤的安装状态：

```
[INFO ][o.e.n.Natives ] installing system call filter
```

如果安装失败，会显示警告：

```
[WARN ][o.e.n.Natives ] unable to install system call filter
```

## 常见问题

**问题 1：过滤安装失败**

```
unable to install syscall filter: Operation not permitted
```

**原因：**
- 容器环境未授予足够权限
- 内核版本过低（需要 3.5+）
- 安全模块（如 AppArmor、SELinux）限制

**解决方案：**
1. 在容器中添加 `--cap-add=SYS_ADMIN` 或 `--privileged`
2. 使用 `--security-opt seccomp=unconfined` 禁用容器 seccomp
3. 或在 Easysearch 中设置 `bootstrap.system_call_filter: false`

**问题 2：插件不兼容**

某些原生插件可能需要被过滤的系统调用，导致运行失败。

**解决方案：**
- 禁用系统调用过滤
- 或联系插件供应商修复兼容性问题

## 与其他安全机制的关系

| 安全机制 | 作用层次 | 与系统调用过滤的关系 |
|---------|---------|-------------------|
| system_call_filter | 系统调用级 | 最细粒度的限制 |
| SELinux | 内核访问控制 | 可协同工作 |
| AppArmor | 程序访问控制 | 可协同工作 |
| capabilities | POSIX 权限 | 需要特定 capability |
| chroot | 文件系统隔离 | 独立的防御层次 |

## 相关配置项

| 配置项 | 作用 | 默认值 |
|-------|------|-------|
| `bootstrap.memory_lock` | 内存锁定 | false |
| `bootstrap.ctrlhandler` | Windows 控制台处理器 | true |

## 注意事项

1. **静态配置**：修改此配置需要重启节点
2. **平台限制**：仅在 Linux 系统上生效
3. **安全权衡**：禁用会降低安全性，仅在必要时禁用
4. **插件兼容**：某些原生插件可能需要禁用此配置
5. **容器环境**：确保容器环境支持 seccomp