轻量级日志聚合器Shiplog：中小团队分布式日志管理实践

1. 项目概述一个为开发者打造的轻量级日志聚合器如果你是一名后端开发者或者正在维护一个分布式微服务系统那么对“日志”这个词一定又爱又恨。爱的是它是排查线上问题的唯一“时光机”恨的是当服务实例从几个变成几十个日志文件散落在各个服务器上想找一个特定请求的完整链路日志无异于大海捞针。传统的做法是登录每台机器用grep、tail -f命令去翻找效率低下且容易遗漏。而市面上成熟的日志解决方案如 ELKElasticsearch, Logstash, Kibana或 Loki功能强大但架构复杂资源消耗大对于中小型团队或个人项目来说部署和维护成本都太高了。这就是devallibus/shiplog项目诞生的背景。它不是一个功能大而全的企业级平台而是一个定位精准的轻量级、自托管、易于部署的日志聚合与查看工具。你可以把它理解为一个“日志收件箱”。它的核心目标非常明确将分散在各个容器或服务器上的应用日志通过一个简单的方式收集起来并提供一个统一的 Web 界面进行搜索和查看。项目名 “Shiplog” 也很有意思直译是“航海日志”在软件开发中我们的应用就像一艘艘航行的船日志就是它们留下的航行记录这个工具就是用来集中管理这些记录的船长日志。它特别适合哪些场景呢首先是小团队或独立开发者不想在日志系统上投入过多运维精力其次是开发测试环境需要快速搭建一个临时的日志中心来调试问题再者是那些对数据隐私有要求不希望日志上云的项目。Shiplog 用 Golang 编写天生具有跨平台和单文件部署的优势通常一个二进制文件加上一份配置文件就能跑起来几乎没有任何外部依赖这极大地降低了使用门槛。2. 核心架构与设计思路拆解Shiplog 的设计哲学是“简单够用”。它没有试图去解析日志的复杂结构比如 JSON 解析、字段提取也不提供强大的告警或仪表盘功能。它的核心工作流可以概括为收集Collect - 传输Ship - 聚合Aggregate - 查看View。下面我们来拆解这个流程背后的设计考量。2.1 基于“推”模型的日志收集在日志收集领域主要有两种模型“拉”Pull和“推”Push。像 Prometheus 监控指标就是典型的拉模型由中心服务器定期去各个目标抓取数据。而 Shiplog 选择了“推”模型。这意味着运行在各个节点上的应用程序或日志转发 Agent需要主动将日志发送到 Shiplog 服务器。为什么选择“推”模型对于日志这种实时性要求高、数据源分散的场景“推”模型有几个天然优势实时性更好日志一旦产生可以立即被发送延迟更低。对客户端友好客户端应用只需要知道服务器的地址配置简单无需在服务器端维护一个动态的目标列表。适应动态环境在容器化如 Docker、Kubernetes环境中实例的 IP 和生命周期是动态变化的“拉”模型很难跟踪这些变化而“推”模型由每个实例主动上报完美适配。在 Shiplog 中这个“推”的动作者通常是应用本身或者一个轻量的日志转发器比如fluent-bitvector 或者一个简单的 shell 脚本。它们通过 HTTP 接口或者 Syslog 协议将日志行log line发送到 Shiplog 服务端。2.2 存储与索引的轻量化权衡成熟的日志系统如 Elasticsearch其强大之处在于倒排索引可以实现毫秒级的全文检索和复杂的聚合查询。但这一切是以巨大的存储和计算开销为代价的。Shiplog 为了保持轻量做出了不同的权衡。它通常采用文件系统存储。收到的日志按时间例如按小时或按天被追加到不同的日志文件中。索引也非常简单可能只是一个内存中的映射表记录了“某个应用、某个时间段”的日志存储在哪个文件的哪个偏移位置。这种设计的优缺点非常明显优点实现简单零外部依赖不需要数据库读写速度快顺序追加写入资源消耗极低。缺点查询能力弱。复杂的多字段过滤、模糊匹配、范围查询效率不高。它最适合的场景是“按应用名筛选 按时间范围浏览 关键词全文搜索”而这恰恰是日常开发调试中最常用的几种操作。注意这种设计决定了 Shiplog 不适合用于海量日志如每天 TB 级的长期存储和分析。它更偏向于一个“近期日志查看器”专注于解决“快速找到现在或刚才出问题的日志”这个痛点。对于需要长期归档和分析的需求可以定期将 Shiplog 的日志文件备份到对象存储如 S3或导入到更专业的分析系统中。2.3 服务端与客户端的职责分离一个清晰的架构是 Shiplog 易于理解和使用的关键。其架构通常明确分为两部分Shiplog Server服务端这是核心一个常驻进程。它负责暴露接收日志的 APIHTTP endpoint。将接收到的日志写入持久化存储文件。提供 Web UI 服务供用户通过浏览器查询和查看日志。管理简单的索引和日志轮转Log Rotation。Logging Client客户端这不是 Shiplog 项目本身的一部分而是指你的应用程序或一个转发代理。它负责从应用的标准输出stdout/stderr或日志文件中读取内容。将日志内容格式化例如添加应用名、主机名、时间戳等标签。通过 HTTP 或 Syslog 协议发送到 Shiplog Server。这种分离使得 Shiplog Server 非常纯粹和稳定而客户端的选择则非常灵活。你可以用任何你熟悉的语言和工具来发送日志只要符合服务端定义的协议即可。3. 从零开始部署与配置 Shiplog理论讲完了我们动手搭建一个。假设我们有一台 IP 为192.168.1.100的 Linux 服务器作为日志中心上面运行着几个 Docker 容器应用我们希望把这些容器的日志收集起来。3.1 服务端部署获取与运行由于 Shiplog 是 Go 编写的单二进制文件部署异常简单。# 1. 从项目 Release 页面下载最新版本的二进制文件以 Linux amd64 为例 # 假设最新版本是 v0.1.0 wget https://github.com/devallibus/shiplog/releases/download/v0.1.0/shiplog-linux-amd64 -O shiplog # 2. 赋予执行权限 chmod x shiplog # 3. 创建一个配置文件 config.yaml cat config.yaml EOF server: # Web UI 和 API 服务监听的地址和端口 http_addr: :8080 # 接收日志的 HTTP 端点地址通常和 UI 一致或另一个端口 ingest_addr: :8081 storage: # 日志文件存储的根目录 path: ./logs # 日志轮转策略按天切割 rotation: daily # 保留最近多少天的日志 retention_days: 7 logging: # Shiplog 自身日志的级别 level: info EOF # 4. 启动 Shiplog 服务端 ./shiplog -config config.yaml启动后你可以通过浏览器访问http://192.168.1.100:8080打开 Web 界面。而日志接收 API 地址是http://192.168.1.100:8081/ingest。3.2 客户端配置从 Docker 容器发送日志现在我们需要让 Docker 容器的日志发送到 Shiplog。有多种方式这里介绍两种最常用的。方法一使用logging driver推荐用于简单场景Docker 原生支持多种日志驱动。我们可以配置一个支持syslog或fluentd的驱动但需要额外的转发服务。更直接的方式是如果 Shiplog 提供了gelf或特定的驱动可以直接使用。但更通用的方法是使用json-file驱动配合logspout或容器内安装轻量 Agent。方法二使用fluent-bit作为 Sidecar 容器生产环境推荐这是更灵活、功能更强的方式。我们为每个需要收集日志的应用容器搭配一个fluent-bitSidecar 容器。它们共享日志卷volume。# docker-compose.yml 示例 version: 3.8 services: my-app: image: your-application:latest container_name: my-app # 将日志输出到标准输出和错误 # 假设你的应用已经这样做了 # ... volumes: # 将容器内的日志目录或特定文件挂载出来与 fluent-bit 共享 - ./app-logs:/var/log/my-app fluent-bit: image: fluent/fluent-bit:latest container_name: my-app-logger volumes: # 共享应用日志 - ./app-logs:/var/log/my-app:ro # Fluent-bit 配置文件 - ./fluent-bit.conf:/fluent-bit/etc/fluent-bit.conf depends_on: - my-app然后编写fluent-bit.conf配置文件[SERVICE] Flush 5 Daemon Off Log_Level info Parsers_File parsers.conf [INPUT] Name tail Tag my-app.* Path /var/log/my-app/*.log # 解析每行日志可以配置多行日志解析如 Java 异常栈 Parser docker # 记录上次读取的位置避免重启后重复发送 Mem_Buf_Limit 5MB Skip_Long_Lines On Refresh_Interval 10 [FILTER] Name record_modifier Match my-app.* # 为日志记录添加一些元数据标签便于在 Shiplog 中筛选 Record hostname ${HOSTNAME} Record app_name my-awesome-app Record container_name my-app [OUTPUT] Name http Match my-app.* Host 192.168.1.100 Port 8081 URI /ingest Format json_lines # 将日志数据以 JSON 格式发送到 Shiplog # 假设 Shiplog 的接收端点期望 JSON 格式{timestamp: ..., message: ..., tags: {...}} json_date_key timestamp json_date_format iso8601这个配置做了几件事输入INPUT使用tail插件监控共享目录下的日志文件。过滤FILTER使用record_modifier为每条日志添加了hostname、app_name等标签。输出OUTPUT使用http插件将格式化后的 JSON 日志发送到 Shiplog 服务器的/ingest端点。启动服务后fluent-bit就会自动将my-app的日志“推”到 Shiplog 服务器。3.3 Web UI 界面使用与日志查看访问http://192.168.1.100:8080你应该能看到 Shiplog 的界面。界面通常很简洁主要包含以下区域侧边栏或顶部筛选器用于按应用名app_name、主机名hostname、时间范围进行筛选。主日志列表按时间倒序列出所有匹配的日志行。每条日志会显示时间戳、来源应用/主机、以及日志消息本身。搜索框提供全文搜索可以输入关键词在日志消息中查找。假设你的应用打印了一条错误日志“ERROR [2023-10-27 14:30:00] Payment failed for order 12345”。在 Shiplog 的 Web UI 中你可以在筛选器中选择app_namemy-awesome-app。将时间范围设置为今天下午 2:25 到 2:35。在搜索框输入 “Payment failed”。 页面会立即过滤出这条日志你就能快速定位到问题。4. 核心配置详解与高级用法基础的搭建完成了但要让它更贴合你的生产环境还需要深入理解一些核心配置和扩展用法。4.1 服务端配置深度解析让我们回到config.yaml看看每个配置项背后的意义和调优建议。server: http_addr: :8080 # Web UI 端口。如果对外暴露建议改为 0.0.0.0:8080。考虑用 Nginx 反向代理并添加 HTTPS。 ingest_addr: :8081 # 日志接收端口。**强烈建议将此端口置于内部网络不要公开暴露**否则任何人都可以向你写入日志。 # 可以设置 HTTP 基础认证增加一层安全 # auth: # username: admin # password_hash: $2a$10$... # bcrypt 加密后的密码 storage: path: /var/lib/shiplog/logs # 建议改为绝对路径并确保运行用户有读写权限。 rotation: daily # 可选hourly, daily, monthly。根据日志量选择。高频日志可选 hourly。 retention_days: 30 # 保留策略。结合磁盘空间考虑。注意这里是“软”删除只是不显示文件可能还在。需要配套的清理脚本。 # 高级可以设置每个日志文件的最大大小防止单个文件过大 # max_size_mb: 100 # 当日志文件达到 max_size_mb 或 rotation 时间点时进行切割。 index: # 索引配置影响查询速度。Shiplog 的索引通常是内存索引。 # 可以配置索引刷新的时间间隔例如每 10 秒更新一次内存索引。 # refresh_interval: 10s # 可以配置索引哪些字段从日志的 tags 里提取如 app_name, level # fields: [app_name, hostname, level] logging: level: info # Shiplog 自身的日志级别。调试时可设为 debug。实操心得存储路径与权限我遇到过最常见的问题是服务启动失败报“权限不足”。如果使用 Docker 运行 Shiplog需要将宿主机的一个目录挂载到容器内作为storage.path并确保容器内进程的用户通常是 non-root 用户如nobody对该目录有写权限。一个稳妥的做法是# 在宿主机上 sudo mkdir -p /opt/shiplog-data/logs sudo chown -R 65534:65534 /opt/shiplog-data/logs # 65534 通常是 nobody 用户的 ID # 在 Docker 运行命令中 docker run -v /opt/shiplog-data/logs:/logs ... # 在 config.yaml 中 storage: path: /logs4.2 客户端日志的格式化与标签策略日志的价值不仅在于消息本身更在于其附带的上下文Context。在发送到 Shiplog 前为日志添加丰富的标签Tags 或 Labels至关重要。这相当于给每条日志打上了多维度的“索引”。在之前的fluent-bit配置中我们使用了record_modifier过滤器来添加app_name和hostname。在实际生产中你应该添加更多有意义的标签[FILTER] Name record_modifier Match my-app.* # 基础信息 Record app_name payment-service Record service_version v1.2.3 Record pod_name ${K8S_POD_NAME} # 在 Kubernetes 环境中非常有用 Record namespace ${K8S_NAMESPACE} # 环境信息 Record env production Record region us-east-1 # 日志级别需要从日志消息中提取这里假设原日志有 level 字段 # 或者可以通过另一个 filter (如 grep 或 lua) 来解析和添加为什么标签如此重要当你在 Shiplog 的 Web UI 中你可以通过app_namepayment-service AND envproduction这样的条件快速筛选出生产环境支付服务的所有日志。如果没有这些标签你只能面对所有服务的海量日志进行全文搜索效率极低。如何从日志中提取标签这需要客户端配合。最佳实践是你的应用程序在打印日志时就采用结构化的格式如 JSON。例如{timestamp:2023-10-27T14:30:00Z,level:ERROR,message:Payment failed,order_id:12345,user_id:67890,trace_id:abc-xyz}这样fluent-bit可以使用parser插件如json轻松解析出level、order_id、trace_id等字段并将它们作为标签发送给 Shiplog。trace_id对于分布式追踪尤其关键你可以用它来一次性查出同一个请求在所有微服务中的日志。4.3 性能调优与规模考量Shiplog 是轻量级的但并不意味着它不能处理一定量的负载。以下是一些调优点批量发送Batching在客户端如 fluent-bit配置中调整Flush参数。不要每条日志都发一个 HTTP 请求而是积累一小批比如 100 条或等待 5 秒再批量发送。这能大幅减少网络往返开销和服务端连接数。[SERVICE] Flush 5 # 每5秒刷新发送一次 [OUTPUT] Name http ... # 一些输出插件可能支持更细粒度的批量设置服务端并发与限流如果预期日志量很大需要关注 Shiplog 服务的并发处理能力。查看其文档或代码看是否支持配置工作线程数、HTTP 服务器参数等。同时可以在 Shiplog 前面加一个负载均衡器如 Nginx并配置连接数和请求速率限制防止被突发流量打垮。存储 I/O 优化storage.path最好放在高性能的 SSD 磁盘上。如果使用机械硬盘大量的顺序写入也可能成为瓶颈。确保磁盘有足够的 IOPS。内存与索引Shiplog 的内存索引会随着日志量和标签数量的增长而增长。监控服务的内存使用情况。如果发现内存持续增长可能需要调整索引策略如index.fields只索引最关键的几个字段或者缩短日志保留时间retention_days。规模上限的粗略估计 对于一个典型的虚拟机2核4GB如果日志格式简单Shiplog 每天处理几十 GB 的日志、百万级别的日志行数是可行的。但当规模达到每天数百 GB、千万行以上时文件系统的管理和简单索引的查询性能可能会成为瓶颈。这时就需要考虑更专业的方案或者将 Shiplog 作为“实时调试窗口”而将长期存储和深度分析交给 Elasticsearch 等系统。5. 常见问题排查与运维技巧即使设计再简单在实际运行中也会遇到各种问题。下面是我在运维类似系统时积累的一些常见问题排查清单和技巧。5.1 日志接收失败问题排查问题现象客户端显示日志已发送但 Shiplog Web UI 上看不到。排查步骤可能原因与解决方案1. 检查网络连通性在客户端机器上执行curl -X POST http://shiplog-server:8081/ingest -d test。看是否能连接通返回什么 HTTP 状态码。2. 检查服务端状态登录 Shiplog 服务器查看进程是否在运行ps aux3. 验证接收端点确认客户端配置的Host,Port,URI与服务端ingest_addr完全匹配。注意是http还是https。4. 检查客户端配置查看 fluent-bit 或其他客户端的日志。fluent-bit 通常有输出缓冲和重试机制如果持续失败日志里会有错误信息如 “connection refused”, “HTTP 400/500” 等。5. 检查数据格式Shiplog 的接收端点可能对数据格式有要求如必须是 JSON且包含特定字段。用curl模拟发送一条格式正确的日志看是否成功。对比客户端发送的实际数据格式。6. 查看存储权限服务端日志可能显示 “permission denied” 错误。检查storage.path目录的权限确保运行 Shiplog 的用户有写权限。实操心得善用curl进行调试curl是你最好的朋友。当怀疑是数据格式问题时手动构造一条最简单的有效负载进行测试可以快速定位是网络问题、认证问题还是数据问题。# 测试连通性和基本响应 curl -v http://192.168.1.100:8081/health # 模拟发送一条日志假设接收 JSON curl -X POST http://192.168.1.100:8081/ingest \ -H Content-Type: application/json \ -d {timestamp: 2023-10-27T15:00:00Z, message: Test log entry, app: test, level: INFO}5.2 Web UI 查询无结果或缓慢问题现象能收到日志但 UI 上搜索不到或者搜索特别慢。排查步骤可能原因与解决方案1. 检查时间范围Web UI 默认可能只显示最近15分钟或1小时的日志。确保你选择的时间范围覆盖了日志产生的时间。这是最常见的原因。2. 检查筛选条件确认筛选栏里的app_name、hostname等条件是否设置错误或过于严格。尝试清除所有筛选看是否能找到日志。3. 索引未刷新Shiplog 的索引可能是定期刷新的如refresh_interval。刚写入的日志可能不会立即出现在查询结果中。等待几秒或手动触发刷新如果 UI 有按钮。4. 关键词搜索语法确认搜索框的关键词是否正确是否误用了特殊字符。尝试简单的关键词。5. 存储文件损坏极少数情况下日志存储文件可能损坏。检查storage.path目录下的文件是否可读文件大小是否正常增长。6. 性能瓶颈如果日志总量非常大例如保留了30天且查询没有使用任何筛选条件简单的全文扫描可能会很慢。始终养成先按应用和时间筛选再搜索关键词的习惯。5.3 磁盘空间管理与日志轮转Shiplog 的retention_days配置是“逻辑删除”它可能只是在索引中标记过期而物理日志文件仍占据磁盘空间。你需要一个外部进程来清理旧文件。编写一个简单的清理脚本cleanup_old_logs.sh#!/bin/bash LOG_DIR/var/lib/shiplog/logs RETENTION_DAYS7 # 删除超过保留天数的日志文件 find $LOG_DIR -name *.log -type f -mtime $RETENTION_DAYS -delete # 也可以删除空目录 find $LOG_DIR -type d -empty -delete然后通过系统的cron服务如crontab -e每天定时执行一次0 2 * * * /path/to/cleanup_old_logs.sh /dev/null 21这个脚本会在每天凌晨2点运行删除7天前的.log文件。重要提示在删除文件前请确保 Shiplog 服务没有正在写入这些文件。稳妥的做法是在清理前先轮转日志如果 Shiplog 不支持热轮转可能需要重启服务或发送信号。更高级的做法是将旧的日志文件压缩后归档到廉价的对象存储中。5.4 高可用与备份考量作为轻量级工具Shiplog 本身通常不提供集群模式。如果你需要高可用可以考虑以下“土办法”客户端双写配置你的日志客户端如 fluent-bit同时向两个 Shiplog 服务器发送日志。这增加了客户端的复杂性和网络流量但实现了冗余。服务端冷备定期例如每小时将主 Shiplog 服务器的存储目录rsync到备用服务器。备用服务器平时不提供服务主服务器宕机时手动切换 DNS 或负载均衡指向备用服务器。这有数据延迟但实现简单。基于共享存储将storage.path指向一个共享文件系统如 NFS、CephFS。然后部署多个 Shiplog 实例通过负载均衡器将写入请求/ingest定向到同一个实例而读取请求Web UI可以分摊到多个实例。这需要非常小心文件锁和写入冲突除非 Shiplog 明确支持这种模式否则不推荐。对于备份最简单的就是定期将storage.path目录打包压缩传输到另一台机器或云存储中。6. 与其他日志方案的对比与选型建议Shiplog 不是万能的了解它在生态中的位置能帮助你做出正确的技术选型。特性/方案Shiplog (devallibus/shiplog)ELK/EFK StackGrafana Loki系统原生 (journald/syslog)核心定位轻量级、自托管、快速查看企业级全功能日志平台云原生、标签优先、成本优化操作系统级日志管理部署复杂度极低单二进制高多个组件需调优中组件较少依赖对象存储低系统内置资源消耗极低高ES 吃内存低索引小存储省低查询能力弱基础筛选全文搜索极强全文、聚合、可视化强LogQL类似 PromQL弱基础筛选扩展性弱单机为主强可集群化水平扩展强可水平扩展弱单机学习成本极低高中低适合场景开发/测试环境小项目临时调试对运维复杂度敏感大型生产环境需要复杂查询、分析和可视化Kubernetes 环境与 Prometheus/Grafana 生态集成紧密服务器系统日志单个主机管理选型建议选择 Shiplog 如果你是一个小团队或个人开发者你需要一个能快速搭建、立即可用的日志查看工具你的日志量不大日增 GB 级别以内你不需要复杂的查询和告警功能你对运维复杂度有严格限制。考虑 ELK/EFK 如果你的日志是核心业务数据需要深度分析和挖掘你需要强大的全文搜索、聚合统计和精美的仪表盘你的团队有足够的运维能力来维护 Elasticsearch 集群。考虑 Grafana Loki 如果你的基础设施已经全面 Kubernetes 化并且在使用 Prometheus 做监控你希望日志和指标使用相似的查询语言LogQL vs PromQL和同一套可视化工具Grafana你非常关注存储成本希望索引尽可能小。使用系统原生工具如果你只需要查看单台服务器的系统日志你的应用日志直接写入 syslog/journald 即可满足需求。一个实用的混合架构思路在很多中小型生产环境中可以采用Shiplog 长期对象存储的组合。用 Shiplog 作为“热日志”查看窗口保留最近几天的日志提供快速的交互查询。同时配置日志客户端将所有日志也并行发送到云服务商的对象存储如 AWS S3、阿里云 OSS进行廉价长期归档。当需要查询历史日志如合规审计、月度分析时再从对象存储中取出用脚本或临时启动一个 ELK/Loki 实例进行分析。这样既满足了日常运维的敏捷性又控制了成本和复杂度。