Syslog MCP
Rust syslog接收器和MCP服务器用于家庭实验室日志智能。通过UDP和TCP摄取syslog,将其存储在具有FTS5全文索引的SQLite中,并向MCP客户端公开基于操作的日志搜索、清点、关联、状态和分析工具。
概述```
┌─────────────────────────────────┐
rsyslog/syslog-ng ─▶ UDP :1514 / TCP :1514 │
network devices ─▶ ┌──────────────────────────┐ │
│ │ parse → batch writer │ │
│ │ SQLite + FTS5 (WAL mode) │ │
│ └──────────────────────────┘ │
Claude / MCP ◀──── ▶ RMCP HTTP :3100/mcp │
local MCP client ◀──▶ syslog mcp query process │
└─────────────────────────────────┘
守护进程在单个端口上监听UDP和TCP syslog(默认 `1514`).所有入站消息都经过解析、批处理,并使用全文索引写入SQLite。MCP HTTP服务器在单独的端口上运行(默认 `3100`)并在无状态JSON响应模式下使用RMCP Streamable HTTP。仅本地stdio MCP客户端可以启动 `syslog mcp`,一个仅查询的MCP进程,在不启动syslog侦听器或HTTP服务器的情况下读取相同的SQLite数据库。
______________________________________________________________________
## 工具
一个MCP工具, `syslog`,暴露。使用所需 `action` 论点运行 `search`, `tail`, `errors`, `hosts`, `sessions`, `search_sessions`, `abuse`, `ai_correlate`, `usage_blocks`, `project_context`, `list_ai_tools`, `list_ai_projects`, `correlate`, `stats`, `status`, `apps`, `source_ips`, `timeline`, `patterns`, `context`, `get`, `ingest_rate`, `silent_hosts`, `clock_skew`, `anomalies`, `compare`, `compose_status`, `compose_doctor`,或 `help`.
有关完整的特定于操作的参数参考,请参阅 `docs/mcp/SCHEMA.md`.
|行动|目的|
| --- | --- |
| `search` |带过滤器的全文搜索|
| `tail` |最近的日志条目|
| `errors` |按主机和严重性列出的错误/警告摘要|
| `hosts` |首次/最后一次看到的主机注册表|
| `sessions` |按项目划分的AI转录会话|
| `search_sessions` |分组会话搜索排名|
| `abuse` |具有相同会话上下文的AI记录中的滥用点击|
| `ai_correlate` |AI转录锚与非AI日志交叉引用|
| `usage_blocks` |5小时UTC窗口中的AI活动|
| `project_context` |一个AI项目路径的总结|
| `list_ai_tools` |具有计数功能的独特AI工具|
| `list_ai_projects` |具有计数的不同AI项目|
| `correlate` |时间窗口中的跨主机事件相关性|
| `stats` |数据库统计信息和存储健康状况|
| `status` |轻量级运行时和数据库健康状况|
| `apps` |具有日志和主机计数的不同应用程序名称|
| `source_ips` |具有主机名细分的不同源标识符|
| `timeline` |随着时间的推移,按桶计数|
| `patterns` |近乎重复的消息模板集群|
| `context` |围绕日志id或时间戳的日志|
| `get` |按id列出一个日志条目,包括原始帧|
| `ingest_rate` |最近的摄取吞吐量和写入块状态|
| `silent_hosts` |last_seen早于阈值的主机|
| `clock_skew` |每台主机接收_时间戳分布为负|
| `anomalies` |最近与基线体积/误差比较|
| `compare` |两个时间范围的并排比较|
| `compose_status` |编辑只读编写部署诊断|
| `compose_doctor` |Compose部署健康诊断的别名|
| `help` |所有操作的Markdown引用|
### `syslog search`
使用可选过滤器对所有syslog消息进行全文搜索。使用SQLite FTS5和波特词干。
**参数**
|参数|类型|必填|默认|说明|
|-----------|------|----------|---------|-------------|
| `query` |string | no |--|FTS5搜索查询(请参见 FTS5查询语法) |
| `hostname` |string | no |--|主机名完全匹配。使用 `syslog` 随着 `action: "hosts"` 列举。 |
| `source_ip` |string | no |--|确切的源标识符。Syslog条目使用经过验证的网络发件人地址(`IP:port`)OTLP行使用经过验证的对等IP;Docker摄取流行使用 `docker://host/container/stream`;Docker生命周期事件行使用 `docker-event://host/container/action`. |
| `severity` |string | no |--|以下之一: `emerg alert crit err warning notice info debug` |
| `app_name` |string | no |--|应用程序名称,例如。 `sshd`, `dockerd`, `kernel` |
| `from` |string | no |--|时间范围的开始(ISO 8601/RFC 3339,例如。 `2025-01-15T00:00:00Z`) |
| `to` |string | no |--|时间范围结束(ISO 8601)|
| `limit` |integer |否|100|最大结果(硬上限:1000)|
**响应**```json
{
"count": 3,
"logs": [
{
"id": 12345,
"timestamp": "2025-01-15T14:30:00Z",
"hostname": "router",
"facility": "kern",
"severity": "err",
"app_name": "kernel",
"process_id": null,
"message": "kernel panic: unable to mount root",
"received_at": "2025-01-15T14:30:01.123Z",
"source_ip": "10.0.0.1:51234"
}
]
}
例子```
query: "kernel panic" # implicit AND: both terms must appear
query: "OOM AND killer" # explicit AND
query: "sshd OR pam" # boolean OR
query: "failed NOT sudo" # boolean NOT
query: '"connection refused"' # exact phrase (bypasses stemming)
query: "error" # prefix wildcard
query: "restart" # matches restart, restarted, restarting
______________________________________________________________________
### `syslog tail`
返回N个最近的日志条目。相当于 `tail -f` 在所有主机上。
**参数**
|参数|类型|必填|默认|说明|
|-----------|------|----------|---------|-------------|
| `hostname` |string | no |--|筛选到特定主机|
| `source_ip` |string |no|--|筛选到精确的源标识符。Syslog条目使用经过验证的网络发件人地址(`IP:port`)OTLP行使用经过验证的对等IP;Docker摄取流行使用 `docker://host/container/stream`;Docker生命周期事件行使用 `docker-event://host/container/action`. |
| `app_name` |string | no |--|筛选到特定应用程序|
| `n` |integer |否|50|最近输入的条目数(硬上限:500)|
**响应**
结构与 `syslog search`: `{ "count": N, "logs": [...] }`.
______________________________________________________________________
### `syslog errors`
在时间窗口内汇总所有主机的警告和错误。按主机名和严重性分组,显示计数。使用此功能进行快速健康评估。
**参数**
|参数|类型|必填|默认|说明|
|-----------|------|----------|---------|-------------|
| `from` |string | no | all time |时间范围的开始(ISO 8601)|
| `to` |string | no | now |时间范围结束(ISO 8601)|
严重程度包括: `emerg`, `alert`, `crit`, `err`, `warning`.
**响应**```json
{
"summary": [
{ "hostname": "router", "severity": "err", "count": 42 },
{ "hostname": "router", "severity": "warning", "count": 17 },
{ "hostname": "storage", "severity": "crit", "count": 3 }
]
}
syslog hosts
列出已发送syslog消息的所有主机,包括第一次/最后一次看到的时间戳和总日志计数。
参数: 无
响应```json
{
"hosts": [
{
"hostname": "router",
"first_seen": "2025-01-01T00:00:00.000Z",
"last_seen": "2025-01-15T14:30:00.000Z",
"log_count": 18432
}
]
}
______________________________________________________________________
### `syslog sessions`
列出按项目、工具、会话和主机分组的AI转录会话。
**参数**
|参数|类型|必填|默认|说明|
|-----------|------|----------|---------|-------------|
| `project` |string | no |--|精确的项目路径,例如。 `/home/jmagar/workspace/syslog-mcp` |
| `tool` |string | no |--|AI工具筛选器: `claude`, `codex`,或 `gemini` |
| `hostname` |string | no |--|限制为一个主机|
| `from` |string | no |--|时间范围的开始(ISO 8601)|
| `to` |string | no |--|时间范围结束(ISO 8601)|
| `limit` |integer |否|100|最大会话数(硬上限:1000)|
**响应**```json
{
"count": 1,
"sessions": [
{
"project": "/home/jmagar/workspace/syslog-mcp",
"tool": "codex",
"session_id": "019e1506-dc81-7881-9926-4d6d4efda1ac",
"hostname": "dookie",
"first_seen": "2026-05-11T03:13:51.745Z",
"last_seen": "2026-05-11T04:10:00.000Z",
"event_count": 42
}
]
}
syslog correlate
在参考时间戳周围的±N分钟窗口内跨多个主机搜索相关事件。可用于调试级联故障。结果按主机分组并按时间排序。
参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
reference_time |
字符串 | 是 | -- | 中心时间戳(ISO 8601,例如。 2025-01-15T14:30:00Z) |
window_minutes |
integer | 否 | 5 | 前后分钟 reference_time (最多60个) |
severity_min |
string | 否 | warning |
包括的最低严重程度。 warning 回报 warning/err/crit/alert/emerg. debug 归还一切。 |
hostname |
string | no | -- | 将相关性限制为一个主机 |
source_ip |
string | no | -- | 将相关性限制为精确的源标识符。Syslog条目使用经过验证的网络发件人地址(IP:port)OTLP行使用经过验证的对等IP;Docker摄取流行使用 docker://host/container/stream;Docker生命周期事件行使用 docker-event://host/container/action. |
query |
string | no | -- | FTS5查询以缩小结果范围 |
limit |
integer | 否 | 500 | 最大总事件数(硬上限:999) |
响应```json
{
"reference_time": "2025-01-15T14:30:00Z",
"window_minutes": 5,
"window_from": "2025-01-15T14:25:00+00:00",
"window_to": "2025-01-15T14:35:00+00:00",
"severity_min": "warning",
"total_events": 12,
"truncated": false,
"hosts_count": 3,
"hosts": [
{
"hostname": "router",
"event_count": 7,
"events": [...]
}
]
}
**关于时钟偏移的注意事项:** `syslog correlate` 使用 `timestamp` syslog消息中的字段,反映发送设备的时钟。如果设备时钟偏斜,事件可能会落在相关性窗口之外。看 时间同步.
______________________________________________________________________
### `syslog stats`
返回数据库统计信息,包括总日志、总主机、覆盖的时间范围、逻辑和物理数据库大小、可用磁盘、配置的阈值、当前写块状态和运行时摄取可观察性。
**参数:** 无
**响应**```json
{
"total_logs": 284917,
"total_hosts": 12,
"oldest_log": "2024-10-15T00:00:01Z",
"newest_log": "2025-01-15T14:30:00Z",
"logical_db_size_mb": "312.45",
"physical_db_size_mb": "328.00",
"free_disk_mb": "14200.00",
"max_db_size_mb": 1024,
"min_free_disk_mb": 512,
"write_blocked": false,
"runtime_observability": {
"syslog_udp_packets_received": 280000,
"syslog_tcp_connections_active": 3,
"ingest_entries_enqueued": 284917,
"ingest_queue_depth": 0,
"ingest_queue_capacity": 10000,
"ingest_queue_utilization_pct": "0.00",
"writer_batches_flushed": 2850,
"writer_logs_written": 284917,
"writer_flush_failures": 0,
"writer_logs_retained": 0,
"writer_logs_discarded": 0,
"writer_storage_blocked": false,
"last_ingest_at": "2025-01-15T14:30:05.123Z",
"last_write_at": "2025-01-15T14:30:05.400Z",
"last_error_at": null
},
"otlp": {
"logs_received": 42,
"decode_errors": 0
}
}
write_blocked: true 意味着存储预算已超出,新的日志接收已暂停。看 存储预算执行.
syslog status
返回轻量级的运行时状态,无需进行更繁重的数据库统计查询。将其用于需要当前队列深度、背压、写入器故障/丢弃状态、侦听器计数器和上次活动时间戳的仪表板和医生检查。
参数: 无
syslog help
返回此工具集中所有工具的markdown文档。
参数: 无
FTS5查询语法
这 syslog search 和 syslog correlate 操作使用SQLite FTS5和波特词干(tokenize='porter unicode61').有效查询表单:
| 语法 | 示例 | 匹配 |
|---|---|---|
| 单期 | panic |
任何包含“恐慌”或变体的消息 |
| 波特堵塞 | restart |
重启,重新启动,重新启动 |
| AND(默认) | disk error 或 disk AND error |
两个术语都存在 |
| 或 | sshd OR pam |
任一学期都有 |
| 不是 | failed NOT sudo |
“failed”存在,“sudo”不存在 |
| 短语 | "connection refused" |
按顺序排列的确切短语 |
| 前缀通配符 | error* |
任何以“error”开头的单词 |
| 分组 | (kernel OR oom) AND panic |
分组布尔逻辑 |
限制: 最多512个字符,最多16个空格分隔的术语。
波特堵塞 手段 connect, connected, connecting,以及 connection 全部与查询匹配 connect.短语查询("...")绕过阻塞并要求精确的令牌顺序。
日志架构
每个存储的日志条目都有以下字段:
字段 · 类型 · 描述
id · integer · 主键自动递增
timestamp · text · 消息时间戳(RFC 3339,UTC)。来自syslog消息头。
hostname · text · 系统日志消息中的主机名(用户控制,未验证)
facility · text · null · Syslog设施名称(见下面的设施)
severity · text · 系统日志严重性级别名称
app_name · text · null · 系统日志消息中的应用程序/进程名称
process_id · 系统日志消息中的text · null · PID
message · text · 日志消息正文(FTS5索引)
received_at · text · 服务器端接收时间戳(RFC 3339,UTC)。用于保留。
source_ip · text · 源标识符。Syslog条目使用确切的网络发件人地址(IP:port)从数据包/连接对等端捕获。OTLP行使用对等IP,不使用临时源端口。Docker摄取流行使用 docker://host/container/stream;Docker生命周期事件行使用 docker-event://host/container/action.
ai_tool · text · null · AI工具名称(例如。 claude, codex)
ai_project · text · null · AI项目路径
ai_session_id · text · null · AI会话唯一标识符
ai_transcript_path · text · null · 源转录文件的完整路径
metadata_json · text · null · 特定于源的JSON元数据。系统日志行包括解析器/源出处;OTLP行包括资源/日志属性以及跟踪/span id;Docker行包括主机/容器/映像/组合/操作详细信息;转录行包括源类型、文件路径、行号、记录键和擦除状态。
人工智能转录索引
syslog ai index 扫描默认的本地转录根
~/.claude/projects 和 ~/.codex/sessions; syslog ai index --path PATH
可以扫描已知的转录目录或一个显式目录 .jsonl 文件,以及
syslog ai add --file FILE 导入一个文件。递归扫描仅限于
~/.claude/projects, ~/.codex/sessions或他们的孩子;广泛的根源
作为 /, $HOME,当前的repo根在行走前被拒绝。这
扫描程序跳过符号链接,计数不受支持的非-.jsonl 未解析的文件
并以有界SQLite块的形式逐行流式传输转录文件。使用
--force 在解析器更改后从头开始重新导入转录路径,
--since RFC3339 仅扫描最近修改的文件,以及
syslog ai checkpoints --errors 加 syslog ai errors 检查结构化
扫描仪故障。
对于实时本地Claude/Codex转录摄入,请安装主机本地
手表服务:```bash
syslog setup ai-watch-service install
syslog setup ai-watch-service check
syslog setup ai-watch-service remove
观察器在Docker之外运行,因为它需要主机访问
`~/.claude/projects` 和 `~/.codex/sessions`。它写入配置的实时
SQLite数据库和委托每一个稳定的变化 `.jsonl` 文件到同一扫描仪
使用的路径 `syslog ai add --file FILE`安装监视器会禁用
较旧的轮询计时器,因此两个助手不会扫描相同的文件。
可选的轮询回退仍然可用:```bash
syslog setup ai-index-timer install
syslog setup ai-index-timer check
syslog setup ai-index-timer remove
这两个助手都故意不在Docker容器内。Docker Compose
仅拥有服务器/查询运行时。
导入的AI转录消息会被清除已知的凭据/令牌模式
在存储和FTS索引之前。这些行仍然住在主楼 logs 桌子,
因此,原始行为,如 search, tail, context,以及 get 可以返回
删除成绩单文本和本地 ai_transcript_path 秒内的值
成绩单上写着。擦洗是最好的努力,而不是合规界限。如果
存储护栏无法恢复足够的空间,提交前索引失败
额外的块。
重要提示:
hostname 取自syslog消息体,任何LAN设备都可以通过UDP将其设置为任意值。对于系统日志条目, source_ip 是唯一值得信赖的网络标识符。对于Docker摄取条目, source_ip 标识配置的Docker摄取主机/容器/流,并且只有在配置的Docker套接字代理端点和网络路径可信的情况下才应被信任。 metadata_json 保留用于调试和关联的源代码特定上下文,但它不是授权边界。保留截止值使用 received_at (服务器时钟),这样时钟配置错误的设备就不会导致过早或无限期的日志保留。
严重程度
按严重程度从高到低排序:
| 级别 | 数字 | 含义 |
|---|---|---|
emerg |
0 | 系统不可用 |
alert |
1 | 必须立即采取行动 |
crit |
2 | 临界条件 |
err |
3 | 错误条件 |
warning |
4 | 警告条件 |
notice |
5 | 正常但重要的情况 |
info |
6 | 信息性消息 |
debug |
7 | 调试级别消息 |
设施
kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, authpriv, ftp, ntp, audit, alert, clock, local0–local7.
安装
单线安装器```bash
curl -fsSL https://raw.githubusercontent.com/jmagar/syslog-mcp/main/install.sh | sh
安装程序将主机 `syslog` 二进制in `~/.local/bin` 然后跑
`syslog setup`安装程序是幂等的,并拥有共享主机布局:
- `~/.syslog-mcp/.env` --secrets、ports、组合插值、运行时值
- `~/.syslog-mcp/compose/docker-compose.yml` --Docker编写部署资产
- `~/.syslog-mcp/data/syslog.db` --SQLite数据库和WAL/SHM Sidecar
安装程序写入 `COMPOSE_PROJECT_NAME=syslog-jmagar-lab` 如此直接
`docker compose` 命令在 `~/.syslog-mcp/compose` 以相同的规范为目标
集装箱作为 `syslog compose`.
有用的安装程序控件:```bash
SYSLOG_INSTALL_DRY_RUN=1 ./install.sh
SYSLOG_INSTALL_PREFIX=/opt/syslog-mcp ./install.sh
SYSLOG_VERSION=0.25.2 ./install.sh
SYSLOG_INSTALL_SKIP_SETUP=1 ./install.sh
有用的设置命令:```bash
syslog setup # first-run or normal repair
syslog setup check # inspect only; does not mutate files or start services
syslog setup repair # repair env/assets and restart the Docker stack
syslog setup ai-watch-service install # host-local real-time transcript watcher
syslog doctor binary # check host/container binary freshness
### Claude Code插件(推荐)
作为Claude Code插件安装。该插件自动处理部署——您可以在服务器模式(此机器承载syslog接收器+MCP服务器)和客户端模式(连接到远程服务器)之间进行选择。
**安装时提示** (通过 `userConfig`):
|字段|必填|默认|备注|
|-------|----------|---------|-------|
| `is_server` |是的| `true` |服务器模式承载接收器;客户端模式连接到远程服务器|
| `server_url` |没有| `http://localhost:3100` |服务器模式:保留默认值。客户端模式:远程主机URL(例如。 `http://shart:3100`) |
| `api_token` |yes|--|插件MCP客户端使用的承载令牌。服务器模式:这将成为服务器强制执行的令牌,除非 `no_auth=true`客户端模式:来自服务器管理员的令牌。存储在系统钥匙链中。 |
| `syslog_host` / `syslog_port` |没有| `0.0.0.0` / `1514` |Syslog侦听器绑定(服务器模式)|
| `mcp_host` / `mcp_port` |没有| `0.0.0.0` / `3100` |MCP HTTP服务器绑定(服务器模式)|
| `data_dir` |没有| `~/.syslog-mcp/data` |可选SQLite目录覆盖;默认共享设置数据在插件缓存外保留|
| `max_db_size_mb` |没有| `8192` |DB大小上限;超过时删除最旧的日志|
| `retention_days` |没有| `90` | `0` =永远保存|
| `batch_size` |没有| `100` |每个SQLite批解析的消息数|
| `write_channel_capacity` |没有| `10000` |侦听器背压前的内部解析消息队列容量|
| `docker_ingest_enabled` |没有| `false` |从远程提取容器日志 `docker-socket-proxy` 端点|
| `fleet_hosts` |没有|--|舰队主机的SSH别名。用于Docker摄取(启用后,每个都变成 `http://:2375`)以及 `syslog-deploy-dropins` 技能|
**SessionStart钩子自动化** (在服务器模式下):
- 确保主机 `syslog` 二进制已打开 `PATH`;安装程序默认为 `~/.local/bin`
- 将插件userConfig导出为 `SYSLOG_*` / `SYSLOG_MCP_*` 环境价值观
- 跑 `syslog setup repair`,单行安装程序使用的设置路径相同
- 维修以下共享资产 `~/.syslog-mcp` 并删除过时的用户级别 `syslog-mcp.service` 旧插件版本留下的单元/插件
- 所有幂等性——在每个会话上都可以安全运行
**捆绑技能**:
- `syslog-dr` --健康检查涵盖MCP、服务状态、系统日志端口、舰队投递和实时日志流;tails服务记录故障
- `syslog-deploy-dropins` --基于SSH的一次性rsyslog直接部署到中的每台主机 `fleet_hosts`
- `syslog-redeploy` --在配置或插件更改后重新运行插件设置
- `syslog-logs` --Docker编写服务日志跟踪
- `syslog-version-check` --检查正在运行的Docker容器是否与本地Compose镜像匹配;添加 `--pull` 先拉取,否则只检查本地映像缓存
该插件通过相同的方式使用Docker Compose部署服务器 `syslog setup`
路径作为单行安装程序。您仍然可以在本地构建和运行二进制文件
用于开发,但自动化部署仅限于Compose。
### 码头工人```bash
git clone https://github.com/jmagar/syslog-mcp
cd syslog-mcp
cp .env.example .env
# Edit .env — set SYSLOG_MCP_TOKEN at minimum
docker compose up -d
容器绑定:
UDP :1514和TCP :1514用于系统日志摄取TCP :3100用于MCP HTTP API
本地建设
需要Rust 1.86+。```bash
cargo build --release
./target/release/syslog serve mcp
______________________________________________________________________
## 认证
syslog-mcp支持两种身份验证模式,可通过以下方式选择 `SYSLOG_MCP_AUTH_MODE`.
**仅限不记名(默认)** --set `SYSLOG_MCP_TOKEN` 以及一切 `/mcp` 请求必须将该令牌表示为 `Authorization: Bearer `。未装载OAuth路由。
**网关保护无身份验证** --set `NO_AUTH=true` 仅当上游网关或反向代理在流量到达syslog-mcp之前强制执行身份验证时。这有意禁用服务本地MCP身份验证,即使在非环回绑定上也是如此。
**OAuth(谷歌)** --set `SYSLOG_MCP_AUTH_MODE=oauth`,OAuth提供程序环境变量和分配的管理员电子邮件。用户通过谷歌进行身份验证后,服务器会发出RS256 JWT。承载令牌和OAuth JWT可以共存(OAuth模式默认禁用静态令牌;set `SYSLOG_MCP_AUTH_DISABLE_STATIC_TOKEN_WITH_OAUTH=false` 或 `disable_static_token_with_oauth = false` 在 `config.toml` 用于玻璃破碎通道)。
两种模式都离开 `/health` 未经身份验证,因此健康探测器始终有效。
看 docs/OAUTH.md 有关完整的设置说明、架构图和操作员常见问题解答。
______________________________________________________________________
## 配置
配置按优先级顺序从三个来源加载(最高获胜):
1. 环境变量
1. `config.toml` (如果存在)
1. 内置默认值
### 环境变量
#### MCP服务器
|变量|必填|默认|描述|
|----------|----------|---------|-------------|
| `SYSLOG_MCP_TOKEN` |否|--|不记名代币 `/mcp`.忽略禁用身份验证。 |
| `SYSLOG_MCP_HOST` |没有| `0.0.0.0` |绑定MCP HTTP服务器的主机|
| `SYSLOG_MCP_PORT` |没有| `3100` |绑定MCP HTTP服务器的端口|
| `SYSLOG_MCP_ALLOWED_HOSTS` |否|--|RMCP主机验证接受额外逗号分隔的主机头值|
| `SYSLOG_MCP_ALLOWED_ORIGINS` |否|--|RMCP Origin验证接受额外逗号分隔的浏览器源|
#### 非MCP API
默认情况下,纯JSON API被禁用。启用后,它安装在 `/api/*` 在同一HTTP侦听器上,需要单独的承载令牌。
|变量|必填|默认|描述|
|----------|----------|---------|-------------|
| `SYSLOG_API_ENABLED` |没有| `false` |启用非MCP JSON API|
| `SYSLOG_API_TOKEN` |是的,启用时|--|承载令牌 `/api/*` 路线|
#### Syslog监听器
|变量|必填|默认|描述|
|----------|----------|---------|-------------|
| `SYSLOG_HOST` |没有| `0.0.0.0` |为UDP+TCP系统日志侦听器绑定主机|
| `SYSLOG_PORT` |没有| `1514` |UDP+TCP系统日志侦听器的绑定端口|
| `SYSLOG_HOST_PORT` |没有| `1514` |Docker Compose主机端口发布到容器端口 `1514` |
| `SYSLOG_MAX_MESSAGE_SIZE` |没有| `8192` |每个UDP数据报或换行符分隔的TCP帧的最大字节数。超大换行符分隔的TCP帧被丢弃,连接保持打开状态;超大的未端接框架被丢弃,连接被关闭。 |
| `SYSLOG_MAX_TCP_CONNECTIONS` |没有| `1024` |最大同时TCP syslog连接数|
| `SYSLOG_TCP_IDLE_TIMEOUT_SECS` |没有| `300` |关闭非活动连接前每次TCP读取的空闲超时|
| `SYSLOG_BATCH_SIZE` |没有| `100` |每批写入的消息数|
| `SYSLOG_FLUSH_INTERVAL` |没有| `500` |批量刷新间隔(毫秒)|
| `SYSLOG_WRITE_CHANNEL_CAPACITY` |没有| `10000` |内部解析消息队列容量|
#### Docker套接字代理摄取
可选的基于拉取的Docker日志摄取使每个远程主机保持在其正常的Docker日志驱动程序上,并通过只读方式让syslog-mcp读取容器stdout/stderr `docker-socket-proxy` 端点。这避免了配置Docker的守护进程级syslog驱动程序,并且在syslog-mcp关闭时不会阻止容器启动。
|变量|必填|默认|描述|
|----------|----------|---------|-------------|
| `SYSLOG_DOCKER_INGEST_ENABLED` |没有| `false` |启用远程Docker日志摄取|
| `SYSLOG_DOCKER_HOSTS` |两个|--|逗号分隔的主机名之一;每个变成 `http://:2375` 随着 `allow_insecure_http = true`.优先于 `SYSLOG_DOCKER_HOSTS_FILE`. |
| `SYSLOG_DOCKER_HOSTS_FILE` |两个|--|路径之一,指向具有 `[[hosts]]` 阵列(在每个主机需要时使用 `base_url` 或TLS)。如果文件不存在,则会记录一条警告,并且不会加载任何主机——容器不会崩溃。通过以下方式装载文件 `SYSLOG_MCP_CONFIG_VOLUME`. |
| `SYSLOG_DOCKER_RECONNECT_INITIAL_MS` |没有| `1000` |主机流故障后的初始重新连接延迟|
| `SYSLOG_DOCKER_RECONNECT_MAX_MS` |没有| `30000` |重复故障后的最大重新连接延迟|
hosts文件使用此形状:```toml
[[hosts]]
name = "edge-host-a"
base_url = "http://edge-host-a:2375"
allow_insecure_http = true
[[hosts]]
name = "app-host-b"
base_url = "http://app-host-b:2375"
allow_insecure_http = true
docker套接字代理端只需要对容器、事件、ping和版本端点进行读取访问: CONTAINERS=1, EVENTS=1, PING=1, VERSION=1, POST=0. CONTAINERS=1 将更广泛的只读Docker容器API暴露给任何可以访问代理的对象,因此仅将其绑定到受信任的专用网络上,将其防火墙连接到syslog-mcp,或将其置于经过身份验证的TLS之后。平原 http:// 端点需要 allow_insecure_http = true 在hosts文件中,这样这个信任决定是明确的。
Docker摄取不是默认冒烟测试的一部分,因为它需要一个与Docker套接字代理兼容的实时端点和容器日志流。对于集成测试,请使用以下命令运行syslog-mcp SYSLOG_DOCKER_INGEST_ENABLED=true 针对一次性docker套接字代理或模拟的docker HTTP夹具,从短期容器中发出一个唯一的行,然后用 syslog search 或 mcporter call ... action=search.容器stdout/stderr行使用 source_ip=docker:////.容器生命周期行用于以下操作 create, start, restart, die, stop, destroy, rename, oom,以及 health_status:* 使用 source_ip=docker-event:////, facility=docker,并保留原始Docker事件JSON。
存储
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
SYSLOG_MCP_DB_PATH |
没有 | /data/syslog.db |
SQLite数据库路径 |
SYSLOG_MCP_POOL_SIZE |
没有 | 4 |
SQLite连接池大小 |
SYSLOG_MCP_RETENTION_DAYS |
没有 | 90 |
保留日志的天数。 0 =永远保存。 |
SYSLOG_MCP_MAX_DB_SIZE_MB |
没有 | 1024 |
写阻塞的逻辑数据库大小触发器。 0 =禁用。 |
SYSLOG_MCP_RECOVERY_DB_SIZE_MB |
没有 | 900 |
在DB大小触发后清理目标。必须小于最大值 |
SYSLOG_MCP_MIN_FREE_DISK_MB |
没有 | 512 |
用于写阻塞的空闲磁盘触发器。 0 =禁用。 |
SYSLOG_MCP_RECOVERY_FREE_DISK_MB |
没有 | 768 |
释放磁盘触发后清理目标。必须大于min |
SYSLOG_MCP_CLEANUP_INTERVAL_SECS |
没有 | 60 |
存储预算执行间隔。最小 5. |
SYSLOG_MCP_CLEANUP_CHUNK_SIZE |
没有 | 2000 |
每个执行块删除的行 |
容器
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
SYSLOG_UID |
没有 | 1000 |
数据卷所有权的容器用户ID |
SYSLOG_GID |
没有 | 1000 |
数据卷所有权的容器组ID |
SYSLOG_MCP_DATA_VOLUME |
没有 | syslog-mcp-data |
Docker卷名或绑定挂载路径 |
SYSLOG_MCP_CONFIG_VOLUME |
没有 | ./config |
可选文件的只读配置挂载,例如 docker-hosts.toml |
DOCKER_NETWORK |
没有 | syslog-mcp |
Docker网络名称(必须存在) |
RUST_LOG |
没有 | info |
日志级别(trace, debug, info, warn, error) |
TZ |
没有 | UTC |
集装箱时区 |
config.toml
地方 config.toml 在二进制文件旁边(或工作目录中)。环境变量覆盖此处设置的值。```toml
[syslog]
host = "0.0.0.0"
port = 1514
max_message_size = 8192
max_tcp_connections = 512
tcp_idle_timeout_secs = 300
[storage]
db_path = "data/syslog.db"
pool_size = 4
retention_days = 90 # 0 = keep forever
wal_mode = true
max_db_size_mb = 1024
recovery_db_size_mb = 900
min_free_disk_mb = 512
recovery_free_disk_mb = 768
cleanup_interval_secs = 60
[mcp]
host = "0.0.0.0"
port = 3100
server_name = "syslog-mcp"
api_token = "your-secret-token"
[docker_ingest]
enabled = false
reconnect_initial_ms = 1000
reconnect_max_ms = 30000
[[docker_ingest.hosts]]
name = "edge-host-a"
base_url = "http://edge-host-a:2375"
allow_insecure_http = true
______________________________________________________________________
## 命令模式```bash
syslog serve mcp # UDP/TCP syslog ingest plus HTTP MCP on /mcp
syslog mcp # query-only MCP stdio transport
syslog setup # install/repair shared ~/.syslog-mcp Docker Compose setup
syslog stats # query the SQLite DB directly from the CLI
syslog db status # inspect SQLite maintenance state
syslog db backup # create a WAL-safe SQLite backup
syslog compose doctor # diagnose live Compose/listener ownership
syslog compose status --json # inspect canonical syslog-mcp container/project
这两种模式都使用相同的配置和环境变量加载器。 syslog mcp 用于可以读取的本地子进程MCP客户端 SYSLOG_MCP_DB_PATH;它不绑定网络端口或运行保留/存储清理作业。
直接CLI使用与MCP工具相同的共享服务层,因此结果和验证与MCP操作相匹配,而不需要MCP客户端:```bash
syslog search 'error AND nginx' --hostname proxy --limit 10
syslog tail -n 20 --app-name kernel
syslog errors --from 2026-01-01T00:00:00Z
syslog hosts
syslog correlate --reference-time 2026-01-01T12:00:00Z --window-minutes 10 --severity-min warning
syslog stats --json
syslog db integrity # run PRAGMA integrity_check
syslog db checkpoint --mode full
syslog db vacuum --pages 1000
syslog compose pull # pull image for resolved Compose project
syslog compose up # run docker compose up -d for resolved service
syslog compose restart # restart resolved service
syslog compose logs --tail 20 # bounded compose logs
`syslog compose` 命令在变异之前解析活的Compose所有者。他们拒绝模糊的cwd回退、过时的Compose标签、听众冲突和破坏性 `down` 没有 `--yes`.
看 docs/CLI.md 获取完整的直接CLI参考,包括标志、JSON输出以及CLI命令如何映射到MCP操作。
______________________________________________________________________
## Syslog转发器设置
服务器监听端口 `1514` 默认情况下。配置发件人以转发到此端口。如果设备无法使用非特权端口,请参阅 暴露端口514.
### rsyslog
创建 `/etc/rsyslog.d/99-remote.conf` 在每台主机上:```conf
# TCP (reliable, recommended for persistent connections)
*.* @@SYSLOG_SERVER:1514
# UDP (lower overhead, no delivery guarantee)
# *.* @SYSLOG_SERVER:1514
重新启动: sudo systemctl restart rsyslog
对于运行没有rsyslog的纯日志的主机,首先在中启用转发 /etc/systemd/journald.conf:```ini
[Journal]
ForwardToSyslog=yes
然后如上所述安装并配置rsyslog。
### 安魂曲
添加 `/etc/syslog-ng/conf.d/remote.conf`:```conf
destination d_remote_tcp {
network("SYSLOG_SERVER"
port(1514)
transport("tcp")
);
};
destination d_remote_udp {
network("SYSLOG_SERVER"
port(1514)
transport("udp")
);
};
log {
source(s_src);
destination(d_remote_tcp);
};
重新启动: sudo systemctl restart syslog-ng
WSL2(系统启用)
在中启用systemd /etc/wsl.conf:```ini
[boot]
systemd=true
安装rsyslog并使用上面的rsyslog配置。使用syslog-mcp主机的Tailscale IP——WSL有自己的网络命名空间,无法直接访问Docker主机IP。
### UniFi云网关
选项A——通过SSH:```bash
ssh admin@
# Create /etc/rsyslog.d/remote.conf (persists on newer firmware):
echo "*.* @SYSLOG_SERVER:1514" | sudo tee /etc/rsyslog.d/remote.conf
sudo systemctl restart rsyslog
选项B——通过用户界面(固件更新后仍然有效):
设置→ 系统→ 高级→ 远程系统日志服务器。设置主机和端口 1514.
路由器和设备(仅UDP设备)
将syslog服务器地址设置为 SYSLOG_SERVER 港口到 1514 在设备的syslog设置中。大多数消费者路由器和网络设备在诊断或日志设置下都会公开此信息。
暴露端口514
Syslog的特权端口514需要root或 CAP_NET_BIND_SERVICE.推荐的方法是使用iptables在主机上重定向:```bash
Redirect UDP and TCP 514 → 1514 on the host
sudo iptables -t nat -A PREROUTING -p udp --dport 514 -j REDIRECT --to-port 1514
sudo iptables -t nat -A PREROUTING -p tcp --dport 514 -j REDIRECT --to-port 1514
Persist across reboots (Debian/Ubuntu)
sudo apt install iptables-persistent
sudo netfilter-persistent save
对于Docker Compose,设置 `SYSLOG_HOST_PORT=514` 发布主机端口 `514` 而集装箱继续绑定非特权端口 `1514`.在Unraid上,映射主机端口 `514` 集装箱码头 `1514` 适用于Docker模板中的UDP和TCP(`514:1514/udp` 和 `514:1514/tcp`).
### 防火墙规则
打开Docker主机防火墙上的syslog端口:```bash
# ufw
sudo ufw allow 1514/udp
sudo ufw allow 1514/tcp
# firewalld
sudo firewall-cmd --permanent --add-port=1514/udp
sudo firewall-cmd --permanent --add-port=1514/tcp
sudo firewall-cmd --reload
保留政策
日志保留用于 SYSLOG_MCP_RETENTION_DAYS 天数(默认值 90).设为 0 永远保存日志。
保留作业继续运行 SYSLOG_MCP_CLEANUP_INTERVAL_SECS (默认60秒)。它以10000行为一组删除日志,释放组块之间的写锁,以便继续摄取。保留截止使用 received_at (服务器端摄入时间戳),而不是 timestamp 在消息中。这可以防止时钟配置错误的设备导致过早或无限期保留。
在大量删除后,将运行增量FTS5合并以回收索引空间,而无需长时间的写锁持续时间。
存储预算执行
两个独立的防护装置可防止磁盘耗尽:
DB大小保护 (SYSLOG_MCP_MAX_DB_SIZE_MB,默认1024 MB)
当逻辑SQLite数据库大小超过 max_db_size_mb,最旧的日志将以块的形式删除 SYSLOG_MCP_CLEANUP_CHUNK_SIZE 行,直到大小降至以下 recovery_db_size_mb.
免费磁盘保护 (SYSLOG_MCP_MIN_FREE_DISK_MB,默认512 MB)
当可用磁盘降至以下时 min_free_disk_mb,删除最旧的日志,直到可用磁盘超过 recovery_free_disk_mb.
写阻塞行为
如果强制执行无法释放足够的空间(例如,数据库为空,但存储仍超出限制),批处理写入器将进入写阻止状态。新的日志消息累积在内存缓冲区中(SYSLOG_WRITE_CHANNEL_CAPACITY,默认10000条消息)。当空间恢复时,自动写入恢复。这 write_blocked 领域 syslog stats 反映了当前的状态。
通过将触发器设置为禁用任一防护装置 0 (还将恢复目标设置为 0).
大量SQLite迁移
大多数架构设置在启动过程中会自动运行。大量迁移,例如在已填充的数百万行上创建新索引 logs 表,可以在syslog监听器和 /health 可用。在该窗口期间,TCP发送方可能会备份,UDP数据包可能会被内核缓冲区丢弃。
在升级已填充的数据库之前:
- 使用WAL安全备份
scripts/backup.sh或sqlite3 /data/syslog.db ".backup /data/syslog-pre-upgrade.db". - 为大型数据库安排一个简短的摄取维护窗口。
- 启动新版本并监视日志
Migration N: starting ...和Migration N: ... created. - 保留之前的图像或二进制文件,直到
/health回报ok和syslog stats报告了理智的计数。
看 docs/runbooks/deploy.md 对于部署检查表。
批处理编写器
批处理写入器通过在写入SQLite之前将解析的syslog消息收集到批中来提高吞吐量。
| 变量 | 默认值 | 描述 |
|---|---|---|
SYSLOG_BATCH_SIZE |
100 |
当这么多邮件排队时写入 |
SYSLOG_FLUSH_INTERVAL |
500 ms |
即使批处理未满,也每N毫秒写入一次 |
SYSLOG_WRITE_CHANNEL_CAPACITY |
10000 |
侦听器背压前解析的消息队列容量 |
批处理是在单个SQLite事务中编写的。如果数据库繁忙(锁定),写入器将以指数回退(25ms、100ms、250ms)重试最多3次。插入失败的批处理将保留在内存中,并在下一个刷新周期重试。如果保留的批增长超过1000个条目,则将其丢弃以防止无限内存增长。
内部写入通道最多可容纳 SYSLOG_WRITE_CHANNEL_CAPACITY 解析的消息。当通道已满时,记录背压,并进一步UDP/TCP接收块,直到空间可用。
多主机部署
将多个主机指向同一syslog-mcp实例。每个发件人的 hostname 字段(来自syslog消息)被记录并索引。使用 syslog hosts 查看所有发件人。筛选依据 hostname 在 syslog search 和 syslog tail.使用 syslog correlate 在一个时间窗口内跨主机查找相关事件。
对于大型车队,请考虑:
- 增加
SYSLOG_MCP_POOL_SIZE(默认值4)用于更高的读取并发性 - 增加
SYSLOG_BATCH_SIZE和SYSLOG_FLUSH_INTERVAL减少写入开销 - 设置
SYSLOG_MCP_RETENTION_DAYS平衡历史深度与磁盘成本
时间同步
所有时间戳都以UTC存储。 syslog correlate 使用 timestamp syslog消息中的字段,反映发送设备的时钟。时钟漂移的设备将使其事件相对于相关窗口发生偏移。在所有发送器上运行NTP以尽量减少偏斜。 received_at (服务器端摄取时间)不受发送方时钟漂移的影响,用于保留。
HTTPS/反向代理
添加一个SWAG代理conf以通过TLS公开MCP API:```nginx
/config/nginx/proxy-confs/syslog-mcp.subdomain.conf
server {
listen 443 ssl;
server_name syslog-mcp.*;
include /config/nginx/ssl.conf;
location / {
include /config/nginx/proxy.conf;
include /config/nginx/resolver.conf;
RMCP Streamable HTTP in stateless JSON-response mode.
Clients use POST /mcp; GET/DELETE /mcp are not supported.
proxy_http_version 1.1;
set $upstream_app syslog-mcp;
set $upstream_port 3100;
set $upstream_proto http;
proxy_pass $upstream_proto://$upstream_app:$upstream_port;
}
}
______________________________________________________________________
## 发展```bash
just dev # cargo run -- serve mcp
just check # cargo check
just lint # cargo clippy -- -D warnings
just fmt # cargo fmt
just test # cargo test
just build # cargo build
just release # cargo build --release
Docker:```bash
just up # docker compose up -d
just logs # docker compose logs -f
just down # docker compose down
just restart # docker compose restart
syslog compose doctor
syslog compose status --json
syslog compose logs --tail 20
生成承载令牌:```bash
just gen-token # openssl rand -hex 32
验证
部署后,验证堆栈:```bash
Health probe (no auth required)
curl -sf http://localhost:3100/health | jq .
→ {"status":"ok"}
Send a test message from any Linux host
logger -n SYSLOG_SERVER -P 1514 --tcp "test from $(hostname)"
Tail recent logs via MCP (replace token if auth is enabled)
curl -s -X POST http://localhost:3100/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "syslog",
"arguments": {"action": "tail", "n": 10}
}
}' | jq .
DB stats
curl -s -X POST http://localhost:3100/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {"name": "syslog", "arguments": {"action": "stats"}}
}' | jq .result.content[0].text | jq -r . | jq .
运行完整的测试套件:```bash
just check
just lint
just test
对正在运行的服务器运行实时烟雾测试:bash
bash scripts/smoke-test.sh
…(正文过长,页面只展示前面部分,完整内容见仓库)
