配置概览

IEDB 使用 TOML 配置文件

配置文件

主要

生产环境可用以下默认的toml配置文件：

# 服务器配置
[server]
port = 8000

# 日志配置
[log]
level = "info"       # debug, info, warn, error（调试、信息、警告、错误）
format = "console"   # json 或 console（JSON格式或控制台输出）

# 数据库
[database]
# 如未设置则自动检测（推荐）
# max_connections = 28    # 2倍 CPU 核心数
# memory_limit = "8GB"    # 约 50% 系统内存
# thread_count = 14       # CPU 核心数
enable_wal = false

# 存储后端
[storage]
backend = "local"           # local（本地）, s3, minio
local_path = "./data/iedb"

# 数据写入
[ingest]
max_buffer_size = 50000     # 触发刷新的记录数
max_buffer_age_ms = 5000    # 强制刷新的等待时间（毫秒）
# flush_workers = 16        # 异步刷新工作线程数（自动检测）
# flush_queue_size = 64     # 待处理刷新队列大小（自动检测）
# shard_count = 32          # 缓冲区分区数

# 文件合并
[compaction]
enabled = true
hourly_enabled = true
hourly_min_age_hours = 0
hourly_min_files = 5

# 启用认证
[auth]
enabled = true

# 删除操作
[delete]
enabled = true
confirmation_threshold = 10000
max_rows_per_delete = 1000000

# 数据保留策略
[retention]
enabled = true

# 持续查询
[continuous_query]
enabled = true

配置优先级

设置按以下顺序应用（从高到低）：

iedb.toml 文件
内置默认值

存储后端

本地文件系统
S3 对象存储
MinIO

本地文件系统- 默认选项，也是单节点部署的最简单选项。

[storage]
backend = "local"
local_path = "./data/iedb"

关键配置

服务器

基本HTTP服务器设置：

[server]
port = 8000    # HTTP/HTTPS port

TLS/SSL（HTTPS）

原生支持 HTTPS/TLS，无需反向代理：

[server]
port = 443
tls_enabled = true
tls_cert_file = "/etc/letsencrypt/live/example.com/fullchain.pem"
tls_key_file = "/etc/letsencrypt/live/example.com/privkey.pem"

何时使用原生 TLS

原生软件包（deb/rpm）：在简单部署场景下使用原生 TLS。
Docker / Kubernetes：使用反向代理（如 Traefik、Nginx、Ingress）进行 TLS 终止。
开发环境：使用自签名证书进行本地 HTTPS 测试。

启用 TLS 后，自动执行以下操作：

添加Strict-Transport-Security(HSTS) 标头
启动时验证证书和密钥文件

最大有效负载

配置写入接口（msgpack、line 协议）的最大请求有效负载大小：

[server]
# 最大负载大小（同时适用于压缩和未压缩数据）
# 支持单位：B、KB、MB、GB
# 默认值：1GB
max_payload_size = "1GB"

如果您在导入大型数据集时遇到 413 错误，您可以：

增加max_payload_size（例如"2GB"）
将导入操作分批进行（为了保证可靠性，建议这样做）。

数据库

连接池和资源设置：

[database]
# 自动检测：如未设置，IEDB 会自动配置：
#   - max_connections：2倍 CPU 核心数（最小4，最大64）
#   - memory_limit：约50%系统内存
#   - thread_count：CPU 核心数

# 手动覆盖示例：
max_connections = 28      # 连接池大小
memory_limit = "8GB"      # DuckDB 内存限制
thread_count = 14         # 查询执行线程数
enable_wal = false        # DuckDB WAL（非 IEDB WAL）

写入

写入性能的缓冲区和并发设置：

[ingest]
# 刷新到 Parquet 前缓冲的最大记录数
max_buffer_size = 50000

# 强制刷新前的最大等待时间（毫秒）
max_buffer_age_ms = 5000

# 并发设置（如未设置则自动检测）
# flush_workers = 16       # 异步刷新工作线程数（2倍 CPU 核心数，最小8，最大64）
# flush_queue_size = 64    # 待处理刷新队列大小（4倍工作线程数，最小100）
# shard_count = 32         # 缓冲区分区数（用于分散锁竞争）

当满足以下任一条件时，数据将被刷新：

缓冲区达到max_buffer_size记录
缓冲时间超过max_buffer_age_ms

高并发

对于并发客户端数量较多（50 个以上）的部署，增加flush_workers以下参数flush_queue_size：

[ingest]
flush_workers = 32
flush_queue_size = 200
shard_count = 64

压缩

自动文件优化：

[compaction]
enabled = true
hourly_enabled = true
hourly_min_age_hours = 0    # 文件需达到此时长（小时）
hourly_min_files = 5        # 触发合并的最小文件数
daily_enabled = false       # 每日合并层级（可选）
daily_min_age_hours = 24
daily_min_files = 3

验证

基于Token的 API 身份验证：

[auth]
enabled = true              # 启用/禁用认证
db_path = "./data/auth.db"  # Token 数据库
cache_ttl = 30              # Token 缓存有效期（秒）
max_cache_size = 1000       # 最大缓存Token数

删除操作

安全删除并确认：

[delete]
enabled = true
confirmation_threshold = 10000   # 超过此行数需确认后执行
max_rows_per_delete = 1000000    # 单次操作的行数硬限制

保留策略

数据自动过期：

[retention]
enabled = true
db_path = "./data/retention.db"

连续查询

定时自动查询：

[continuous_query]
enabled = true
db_path = "./data/cq.db"

预写式日志（WAL）

可选的健壮性保证：

[wal]
enabled = false              # 激活确保数据0丢失
directory = "./data/wal"
sync_mode = "fdatasync"      # none, fdatasync, fsync
max_size_mb = 500
max_age_seconds = 3600

监控

时间序列指标监控收集：

[metrics]
timeseries_retention_minutes = 60
timeseries_interval_seconds = 10

快速配置示例

生产环境支持本地、S3、MINIO
高可用
高并发

[server]
port = 8000

[log]
level = "debug"
format = "console"

[storage]
backend = "local"
local_path = "./dev_data"

[auth]
enabled = false

[compaction]
enabled = false

最佳实践

1. 文件配置

存储配置信息iedb.toml并进行版本控制（不含密钥）：

[storage]
backend = "s3"
s3_bucket = "iedb"
s3_region = "cn-hangzhou"

2. 自动检测资源

IEDB 会根据您的系统自动检测最佳的引擎设置。只有在您有特殊要求时才需要手动修改：

[database]
# Leave commented for auto-detection
# max_connections = 28
# memory_limit = "8GB"
# thread_count = 14

3. 功能启用

从简单的功能入手，根据需要添加功能：

基本配置（存储+认证）
压缩（用于查询优化）
数据保留策略（用于数据管理）
WAL（零数据丢失保证）

5. 监控配置

配置更改后检查指标：

# 内存占用
curl http://localhost:8000/api/v1/metrics/memory

# 查询性能
curl http://localhost:8000/api/v1/metrics/query-pool

# 压缩情况
curl http://localhost:8000/api/v1/compaction/status

故障排除

配置未加载

# 验证 TOML 语法（可使用任意 TOML 验证工具）
# 检查文件是否存在于预期位置
ls -la iedb.toml

# IEDB 按以下顺序查找 iedb.toml 文件：
# 1. 当前目录
# 2. /etc/iedb/iedb.toml（原生安装）

资源问题

# 通过监控指标调整配置
curl http://localhost:8000/api/v1/metrics/memory

[database]
memory_limit = "4GB"
max_connections = 16

后续步骤

身份验证- 令牌管理
高级功能- 压缩和 WAL

配置文件​

主要​

配置优先级​

存储后端​

关键配置​

服务器​

TLS/SSL（HTTPS）​

最大有效负载​

数据库​

写入​

压缩​

验证​

删除操作​

保留策略​

连续查询​

预写式日志（WAL）​

监控​

快速配置示例​

最佳实践​

1. 文件配置​

2. 自动检测资源​

3. 功能启用​

5. 监控配置​

故障排除​

配置未加载​

资源问题​

后续步骤​