Syslog MCP

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.

syslog search

使用可选过滤器对所有syslog消息进行全文搜索。使用SQLite FTS5和波特词干。

参数

响应

{
  "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 在所有主机上。

参数

响应

结构与 syslog search: { "count": N, "logs": [...] }.

______________________________________________________________________

syslog errors

在时间窗口内汇总所有主机的警告和错误。按主机名和严重性分组，显示计数。使用此功能进行快速健康评估。

参数

严重程度包括： emerg, alert, crit, err, warning.

响应

{
  "summary": [
    { "hostname": "router",  "severity": "err",     "count": 42 },
    { "hostname": "router",  "severity": "warning",  "count": 17 },
    { "hostname": "storage", "severity": "crit",     "count":  3 }
  ]
}

______________________________________________________________________

syslog hosts

列出已发送syslog消息的所有主机，包括第一次/最后一次看到的时间戳和总日志计数。

参数： 无

响应

{
  "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转录会话。

参数

响应

{
  "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": "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

返回数据库统计信息，包括总日志、总主机、覆盖的时间范围、逻辑和物理数据库大小、可用磁盘、配置的阈值、当前写块状态和运行时摄取可观察性。

参数： 无

响应

{
  "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').有效查询表单：

限制： 最多512个字符，最多16个空格分隔的术语。

波特堵塞 手段 connect, connected, connecting，以及 connection 全部与查询匹配 connect.短语查询("...")绕过阻塞并要求精确的令牌顺序。

______________________________________________________________________

日志架构

每个存储的日志条目都有以下字段：

人工智能转录索引

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转录摄入，请安装主机本地 手表服务：

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安装监视器会禁用 较旧的轮询计时器，因此两个助手不会扫描相同的文件。

可选的轮询回退仍然可用：

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 （服务器时钟），这样时钟配置错误的设备就不会导致过早或无限期的日志保留。

严重程度

按严重程度从高到低排序：

设施

kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, authpriv, ftp, ntp, audit, alert, clock, local0–local7.

______________________________________________________________________

安装

单线安装器

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.

有用的安装程序控件：

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

有用的设置命令：

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):

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。

码头工人

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+。

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. 环境变量
2. config.toml （如果存在）
3. 内置默认值

环境变量

MCP服务器

非MCP API

默认情况下，纯JSON API被禁用。启用后，它安装在 /api/* 在同一HTTP侦听器上，需要单独的承载令牌。

Syslog监听器

Docker套接字代理摄取

可选的基于拉取的Docker日志摄取使每个远程主机保持在其正常的Docker日志驱动程序上，并通过只读方式让syslog-mcp读取容器stdout/stderr docker-socket-proxy 端点。这避免了配置Docker的守护进程级syslog驱动程序，并且在syslog-mcp关闭时不会阻止容器启动。

hosts文件使用此形状：

[[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。

存储

容器

config.toml

地方 config.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

______________________________________________________________________

命令模式

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客户端：

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 在每台主机上：

# 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:

[Journal]
ForwardToSyslog=yes

然后如上所述安装并配置rsyslog。

安魂曲

添加 /etc/syslog-ng/conf.d/remote.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:

[boot]
systemd=true

安装rsyslog并使用上面的rsyslog配置。使用syslog-mcp主机的Tailscale IP——WSL有自己的网络命名空间，无法直接访问Docker主机IP。

UniFi云网关

选项A——通过SSH：

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在主机上重定向：

# 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端口：

# 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数据包可能会被内核缓冲区丢弃。

在升级已填充的数据库之前：

1. 使用WAL安全备份 scripts/backup.sh 或 sqlite3 /data/syslog.db ".backup /data/syslog-pre-upgrade.db".
2. 为大型数据库安排一个简短的摄取维护窗口。
3. 启动新版本并监视日志 Migration N: starting ... 和 Migration N: ... created.
4. 保留之前的图像或二进制文件，直到 /health 回报 ok 和 syslog stats 报告了理智的计数。

看 docs/runbooks/deploy.md 对于部署检查表。

______________________________________________________________________

批处理编写器

批处理写入器通过在写入SQLite之前将解析的syslog消息收集到批中来提高吞吐量。

批处理是在单个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：

# /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;
    }
}

______________________________________________________________________

发展

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：

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

生成承载令牌：

just gen-token   # openssl rand -hex 32

______________________________________________________________________

验证

部署后，验证堆栈：

# 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 .

运行完整的测试套件：

just check
just lint
just test

对正在运行的服务器运行实时烟雾测试：

bash scripts/smoke-test.sh

烟雾测试种子UDP和TCP系统日志消息，并验证MCP搜索/尾部结果。Docker摄取覆盖率由Docker套接字代理摄取部分中描述的显式集成路径处理，因为它需要一个与Docker兼容的外部日志端点。

______________________________________________________________________

演出

在典型的家庭实验室规模（1-20台主机，每天数千条消息）：

• 具有WAL模式的SQLite处理并发读写而不争用
• 批处理写入器在普通硬件上每秒可维持数千条消息
• 带有波特词干的FTS5比普通SQL查询增加了最小的开销
• PRAGMA cache_size=-64000 为每个连接分配约64 MB的页面缓存
• PRAGMA synchronous=NORMAL 平衡耐用性和吞吐量
• 连接池（默认值4）满足并发MCP请求而不阻塞

对于更高的摄取率（物联网、高流量网络设备）：

• 增加 SYSLOG_BATCH_SIZE （例如。 500)减少交易开销
• 增加 SYSLOG_FLUSH_INTERVAL （例如。 1000 ms）以扩大批处理窗口
• 增加 SYSLOG_WRITE_CHANNEL_CAPACITY （例如。 100000)吸收爆发
• 增加 SYSLOG_MCP_POOL_SIZE （例如。 8)为了获得更多的读取并发性
• 将数据库放置在SSD或tmpfs支持的卷上

______________________________________________________________________

MCP传输

守护进程在无状态JSON响应模式下通过RMCP Streamable HTTP实现MCP。

• POST /mcp --RMCP可流式HTTP请求/响应端点
• GET /mcp 和 DELETE /mcp — 405 Method Not Allowed 处于无状态模式
• GET /health --未经验证的健康探针
• syslog mcp --用于将MCP服务器作为子进程启动的客户端的仅本地查询stdio MCP模式

什么时候 SYSLOG_MCP_TOKEN 设置， /mcp 要求：

Authorization: Bearer 

/health 始终未经身份验证（Docker健康检查和反向代理探测需要）。

Stdio模式不使用承载身份验证，因为它是本地子进程访问。这确实需要 SYSLOG_MCP_DB_PATH 指向由守护进程填充的同一SQLite数据库：

{
  "mcpServers": {
    "syslog-mcp": {
      "command": "/path/to/syslog",
      "args": ["mcp"],
      "env": {
        "SYSLOG_MCP_DB_PATH": "/data/syslog.db",
        "RUST_LOG": "warn"
      }
    }
  }
}

使用 mcp-remote 而不是直接stdio，因为数据库只能通过正在运行的HTTP守护进程或反向代理访问。

Docker镜像仍然以守护进程为中心，并通过以下方式公开HTTP MCP syslog serve mcp；使用 syslog mcp 在可以读取SQLite数据库以进行直接本地stdio的主机上。

______________________________________________________________________

相关文件

______________________________________________________________________

相关插件

许可证

麻省理工学院