# LogLite

**Repository Path**: helmsmen-network/log-lite

## Basic Information

- **Project Name**: LogLite
- **Description**: 免费、自由、小巧、快速解决 Syslog 日志接收服务器，目的是解决交换机路由器的日志信息。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-21
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Syslog UDP服务器 原理逻辑+使用文档

# 第一部分：原理逻辑文档

## 1. 文档概述

本文档详细拆解Syslog UDP服务器的核心原理、运行逻辑及各模块交互流程，帮助理解服务器如何接收、处理、存储日志，以及日志压缩、过期清理等功能的实现机制。该服务器基于Python开发，采用UDP协议接收Syslog日志，支持IP白名单校验、按规则存储日志、自动压缩和定时清理，具备高可用性和并发处理能力。

## 2. 核心设计理念

服务器设计遵循「解耦、高效、可靠」三大原则，核心目标是：接收指定IP的UDP日志消息，按规范存储，同时通过自动化管理（压缩、清理）减少磁盘占用，确保核心功能（日志接收）不被辅助操作（清理、压缩）阻塞。

关键设计思路：

- 模块解耦：将配置读取、日志处理、IP校验、请求接收等功能拆分独立模块，便于维护和扩展；

- 并发安全：通过全局文件锁解决多线程写入/压缩日志的冲突问题；

- 后台异步：日志清理操作放入独立守护线程，与日志接收流程分离，避免阻塞；

- 容错性：所有配置读取、文件操作、IP解析均增加异常处理，避免单一错误导致服务器崩溃。

## 3. 整体运行流程

服务器启动后，按以下固定流程运行，全程自动化，无需人工干预（除启动/停止操作）：

1. 初始化阶段：加载配置文件 → 初始化日志系统 → 检查并创建日志目录；

2. 准备阶段：启动日志清理后台线程 → 配置UDP服务器 → 注册信号处理（优雅退出）；

3. 运行阶段：监听UDP端口 → 接收客户端请求 → 校验IP白名单 → 解码日志 → 存储日志 → 检查并压缩超大日志；

4. 退出阶段：接收退出信号（Ctrl+C或kill命令） → 关闭服务器 → 清理线程 → 正常退出。

## 4. 各核心模块原理拆解

### 4.1 配置读取模块（load_config函数）

核心功能：读取并解析config.ini配置文件，提供统一的配置字典供其他模块调用，同时处理配置注释和默认值，避免配置缺失导致报错。

关键逻辑：

- 使用configparser模块读取配置文件，指定UTF-8编码，避免中文乱码；

- 通过get_clean_config_value函数清理配置值，去除#后的注释和首尾空格（如处理max_log_size=10485760 # 10MB）；

- 为所有配置项设置默认值（如host默认0.0.0.0、port默认514），即使config.ini缺失对应项，服务器也能正常启动；

- 将IP白名单字符串分割为列表，过滤空值，便于后续IP校验。

### 4.2 日志系统模块（setup_logging函数）

核心功能：实现「控制台+文件」双输出日志，支持日志轮转，确保服务器运行状态和日志接收情况可追溯。

关键逻辑：

- 日志级别：支持DEBUG（调试模式，输出详细信息）和INFO（正常模式，输出核心信息），通过命令行参数--debug切换；

- 控制台输出：实时打印服务器运行状态（如启动成功、接收日志、清理日志），便于实时监控；

- 文件输出：将日志写入server.log文件，采用RotatingFileHandler实现日志轮转，当文件达到max_log_size（10MB）时，自动生成备份文件（server.log.1、server.log.2...），最多保留backup_count（5）个备份；

- 日志格式：统一为「时间 - 级别 - 内容」，包含具体时间戳，便于问题排查。

### 4.3 IP白名单校验模块（is_ip_allowed函数）

核心功能：校验发送日志的客户端IP是否在允许的白名单内，拒绝非法IP的请求，保障服务器安全。

关键逻辑：

- 支持两种白名单格式：单个IP（如127.0.0.1）和网段（如192.168.1.0/24），适配不同场景；

- 使用ipaddress模块解析IP和网段，将客户端IP转换为IP对象，遍历白名单中的每个IP/网段，判断客户端IP是否在允许范围内；

- 容错处理：若白名单中存在无效IP/网段（如格式错误），仅记录警告，不影响整体运行；若客户端IP格式无效，拒绝请求并记录错误。

### 4.4 UDP请求处理模块（SyslogUDPHandler类）

核心功能：处理客户端发送的UDP日志请求，是服务器接收和处理日志的核心模块，继承自socketserver.BaseRequestHandler，重写handle方法实现具体逻辑。

关键逻辑（按执行顺序）：

1. 获取请求数据：从UDP请求中提取日志数据和客户端IP，记录数据长度（便于调试）；

2. IP校验：调用is_ip_allowed函数校验客户端IP，拒绝非法IP；

3. 日志解码：优先使用UTF-8解码日志数据（标准Syslog编码），若解码失败，尝试GBK编码（兼容部分国产设备），仍失败则记录错误并放弃处理；

4. 日志存储：按「日志根目录/日期/客户端IP/客户端IP.log」的路径存储日志，日期格式为YYYY-MM-DD（如2026-01-21），确保日志分类清晰，便于查找；

5. 并发安全：写入日志时使用全局文件锁（file_lock），避免多线程同时写入同一个文件导致文件损坏；

6. 日志压缩：写入日志后，检查文件大小，若超过max_log_size（10MB），调用compress_log_file函数压缩日志。

### 4.5 日志压缩模块（compress_log_file函数）

核心功能：将超过指定大小的日志文件压缩为.gz格式，减少磁盘占用，压缩后删除原始日志文件。

关键逻辑：

- 并发安全：使用全局文件锁，确保同一时间只有一个线程执行压缩操作，避免压缩过程中文件被修改；

- 压缩规则：压缩后的文件名为「原始文件名.gz」（如192.168.1.100.log → 192.168.1.100.log.gz），采用gzip模块，压缩级别为compress_level（9，最高压缩率）；

- 容错处理：检查原始文件是否存在，避免压缩不存在的文件；检查压缩文件是否已存在，避免重复压缩；压缩失败时记录错误，不影响服务器运行。

### 4.6 日志清理模块（clean_expired_logs、start_cleanup_worker函数）

核心功能：定时清理超过保留天数的日志文件（包括原始.log文件和压缩后的.gz文件），防止磁盘被日志占满。

关键逻辑：

- 清理触发方式：通过start_cleanup_worker函数启动后台守护线程，线程内循环执行clean_expired_logs函数，循环间隔为clean_interval（3600秒/1小时）；

- 清理规则：计算当前时间与文件最后修改时间的差值，若超过log_retention_days（7天），则删除该文件；

- 遍历范围：使用Path.rglob方法遍历日志根目录下所有子目录的.log和.log.gz文件，确保所有过期日志都能被清理；

- 守护线程特性：后台线程不阻塞主程序运行，主程序退出时，线程自动终止，无需手动清理。

### 4.7 服务器核心模块（ThreadedUDPServer类、主程序入口）

核心功能：启动UDP服务器，监听指定端口，处理并发请求，支持优雅退出。

关键逻辑：

- 多线程处理：继承socketserver.ThreadingMixIn，实现多线程并发处理UDP请求，每个请求分配一个独立线程，支持同时接收多个客户端的日志；

- 端口复用：设置allow_reuse_address = True，避免服务器重启时出现「端口被占用」的错误；

- 优雅退出：通过setup_signal_handler函数注册SIGINT（Ctrl+C）和SIGTERM（kill命令）信号处理，接收退出信号后，关闭服务器、清理资源，避免日志丢失；

- 主程序流程：解析命令行参数 → 加载配置 → 初始化日志 → 创建服务器 → 启动后台清理线程 → 监听请求，全程包含异常处理，确保服务器稳定运行。

## 5. 关键参数关联逻辑

服务器的核心配置参数（来自config.ini）相互关联，共同决定日志管理和服务器运行效果，关联关系如下：

- max_log_size（10MB） ↔ compress_log_file：日志文件达到该大小，触发自动压缩；

- log_retention_days（7天） ↔ clean_expired_logs：超过该天数的日志，被定时清理；

- clean_interval（3600秒） ↔ start_cleanup_worker：决定日志清理的频率，与日志产生量匹配；

- allowed_ips ↔ is_ip_allowed：白名单IP/网段决定哪些客户端可以发送日志；

- max_threads（10） ↔ ThreadedUDPServer：限制最大并发线程数，避免高并发导致服务器资源耗尽。

## 6. 异常处理机制

服务器在关键流程中均增加了异常处理，确保单一模块出错不影响整体运行，主要异常场景及处理方式：

- 配置文件加载失败：打印错误信息，直接退出服务器；

- 日志目录创建失败：记录错误信息，退出服务器（无法存储日志，服务器无运行意义）；

- IP解析/校验失败：记录警告/错误信息，放弃处理当前请求，继续监听其他请求；

- 日志写入/压缩失败：记录错误信息，放弃当前日志处理，继续运行；

- 服务器启动失败：记录错误信息，退出服务器；

- 运行中异常：记录错误信息，关闭服务器并清理资源，正常退出。

# 第二部分：使用文档

## 1. 文档概述

本文档详细介绍Syslog UDP服务器的安装、配置、启动、使用及问题排查方法，适用于运维人员和开发人员，无需掌握核心原理，按步骤操作即可完成服务器的部署和使用。

适用环境：Python 3.7及以上版本（兼容Windows、Linux、MacOS）。

## 2. 前置准备

### 2.1 环境要求

- Python版本：3.7+（推荐3.8-3.11，稳定性最优）；

- 依赖模块：无第三方依赖（所有模块均为Python标准库，无需额外安装）；

- 系统权限：
       

    - Linux/MacOS：若使用默认端口514（特权端口），需使用sudo权限启动；

    - Windows：无需特殊权限，直接启动即可。

- 网络要求：服务器监听的端口（默认514）需开放，客户端能通过UDP协议访问该端口；若开启防火墙，需放行对应端口的UDP流量。

### 2.2 文件准备

将以下两个文件放在同一目录下（建议创建单独的服务器目录，如syslog-server）：

1. 服务器代码文件：syslog_server.py（复制前文完整带注释代码，保存为.py文件）；

2. 配置文件：config.ini（复制前文配套配置，保存为.ini文件）。

## 3. 配置文件详解（config.ini）

配置文件是服务器的核心，所有运行参数均可通过修改该文件调整，无需改动代码。文件分为4个配置节，每个配置项均有详细注释，以下是关键配置项说明（可直接使用默认配置，按需修改）：

### 3.1 [Server] 服务器配置

|配置项|默认值|说明|修改建议|
|---|---|---|---|
|host|0.0.0.0|服务器监听地址，0.0.0.0表示监听所有网卡，允许外部客户端访问；若设为127.0.0.1，仅允许本地客户端访问。|对外提供服务时保留默认值，仅本地测试可设为127.0.0.1。|
|port|514|UDP监听端口，默认Syslog协议端口，若端口被占用，可修改为其他端口（如5140）。|端口被占用时修改，修改后需确保客户端发送日志的端口与该端口一致。|
|max_threads|10|最大并发线程数，限制同时处理的UDP请求数量，避免高并发导致资源耗尽。|日志量小时保留默认值，日志量大（每分钟数百条）可改为20-50。|
### 3.2 [Storage] 存储配置

|配置项|默认值|说明|修改建议|
|---|---|---|---|
|log_dir|./syslog_logs|日志根目录，相对路径（当前目录下创建syslog_logs文件夹），也可设置为绝对路径（如Linux的/var/log/syslog，Windows的D:\syslog_logs）。|需确保服务器有该目录的读写权限，建议设置为绝对路径，便于查找日志。|
### 3.3 [Whitelist] IP白名单配置

|配置项|默认值|说明|修改建议|
|---|---|---|---|
|allowed_ips|127.0.0.1, 192.168.1.0/24|允许发送日志的客户端IP/网段，逗号分隔，支持单个IP（如192.168.1.100）和网段（如192.168.0.0/16）。|根据实际客户端IP修改，删除默认的192.168.1.0/24，添加实际需要的IP/网段；本地测试保留127.0.0.1。|
### 3.4 [Logging] 日志管理配置（核心）

|配置项|默认值|说明|修改建议|
|---|---|---|---|
|max_log_size|10485760|单日志文件最大大小（字节），默认10MB（10485760字节），超过该大小自动压缩。|日志量小时保留默认值，日志量大可改为20971520（20MB）。|
|backup_count|5|服务器主日志（server.log）的备份数量，超过该数量会自动删除最旧的备份。|保留默认值即可，需更多备份可改为10。|
|log_retention_days|7|日志保留天数，超过该天数的.log和.log.gz文件会被定时清理。|根据业务需求修改，需长期保留日志可改为30（天），无需长期保留可改为3（天）。|
|clean_interval|3600|日志清理间隔（秒），默认3600秒（1小时），每隔该时间清理一次过期日志。|日志量小改为86400（24小时），日志量大改为1800（30分钟）。|
|compress_level|9|日志压缩级别（1-9），9压缩率最高、速度最慢，1压缩率最低、速度最快。|追求磁盘节省保留默认值，追求压缩速度可改为3-5。|
## 4. 服务器启动与停止

### 4.1 启动步骤

启动前请确认：配置文件config.ini已正确修改（尤其是IP白名单和端口），Python环境已准备就绪，日志目录有读写权限。

启动命令（打开终端/命令提示符，进入服务器所在目录）：

#### 4.1.1 正常模式（推荐）

```bash

python syslog_server.py
```

启动成功提示（控制台输出）：

```text

日志系统初始化完成
日志目录已准备好：./syslog_logs
Syslog UDP服务器启动成功（0.0.0.0:514）
IP白名单：['127.0.0.1', '192.168.1.0/24']
信号处理已初始化，按Ctrl+C可优雅退出服务器
日志清理后台线程启动成功（清理间隔：3600秒，保留天数：7天）
```

#### 4.1.2 调试模式（排查问题时使用）

调试模式会输出更详细的信息（如配置加载详情、每个请求的处理过程），便于排查启动或运行中的问题。

```bash

python syslog_server.py --debug
```

#### 4.1.3 Linux/MacOS 特权端口启动（使用514端口时）

Linux/MacOS中，514端口属于特权端口，普通用户无法直接使用，需加sudo权限：

```bash

sudo python syslog_server.py
```

### 4.2 停止步骤

服务器支持优雅退出，停止时会清理资源，避免日志丢失，两种停止方式：

- 方式1（推荐）：在启动服务器的终端/命令提示符中，按Ctrl+C组合键，服务器会打印退出提示，正常停止；

- 方式2（Linux/MacOS）：若服务器在后台运行，先通过ps命令查找进程ID，再用kill命令停止（替换[pid]为实际进程ID）：
        `# 查找进程ID
ps -ef | grep syslog_server.py
# 停止服务器（优雅退出）
kill [pid]
# 强制停止（仅当优雅退出失败时使用）
kill -9 [pid]`

停止成功提示（控制台输出）：

```text

接收到退出信号（2），开始优雅关闭服务器...
服务器已成功关闭
```

## 5. 日志查看与管理

### 5.1 日志存储路径

服务器日志分为两类，存储路径不同，便于区分和管理：

1. 服务器运行日志：存储在log_dir配置的目录下，文件名为server.log（主日志）和server.log.1~server.log.5（备份日志），记录服务器启动、停止、接收日志、清理日志等运行状态；

2. 客户端日志：按「log_dir/日期/客户端IP/客户端IP.log」存储，例如：
        `./syslog_logs/2026-01-21/192.168.1.100/192.168.1.100.log`日志文件超过10MB后，会自动压缩为.gz格式（如192.168.1.100.log.gz）。

### 5.2 日志查看方法

#### 5.2.1 实时查看服务器运行日志（Linux/MacOS）

```bash

tail -f ./syslog_logs/server.log
```

#### 5.2.2 查看客户端日志

- Windows：直接打开对应.log或.log.gz文件（.gz文件需解压后查看）；

- Linux/MacOS：使用cat、less命令查看.log文件，使用zcat、zgrep命令查看.gz压缩文件：
        `# 查看未压缩的日志
cat ./syslog_logs/2026-01-21/192.168.1.100/192.168.1.100.log
# 查看压缩的日志
zcat ./syslog_logs/2026-01-21/192.168.1.100/192.168.1.100.log.gz`

### 5.3 手动清理日志（可选）

服务器会自动定时清理过期日志，若需手动清理，直接删除对应日志文件即可，不会影响服务器运行。

Linux/MacOS 手动清理示例（删除所有30天前的日志）：

```bash

find ./syslog_logs -name "*.log" -mtime +30 -delete
find ./syslog_logs -name "*.log.gz" -mtime +30 -delete
```

## 6. 客户端日志发送测试

服务器启动后，可通过以下方法测试是否能正常接收日志（以本地测试为例，客户端IP为127.0.0.1，需在白名单中）。

### 6.1 Python 客户端测试（推荐）

创建test_client.py文件，复制以下代码，运行后发送测试日志：

```python

import socket

# 服务器地址和端口（与config.ini中的host、port一致）
SERVER_HOST = '127.0.0.1'
SERVER_PORT = 514

# 创建UDP socket
udp_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# 测试日志消息
test_message = "This is a test syslog message from 127.0.0.1"

# 发送日志（UDP协议，无需建立连接）
udp_socket.sendto(test_message.encode('utf-8'), (SERVER_HOST, SERVER_PORT))

print(f"测试日志已发送：{test_message}")
udp_socket.close()
```

运行测试脚本：

```bash

python test_client.py
```

查看服务器控制台，若出现以下提示，说明接收成功：

```text

接收日志（127.0.0.1）：This is a test syslog message from 127.0.0.1
日志写入成功：./syslog_logs/2026-01-21/127.0.0.1/127.0.0.1.log
```

### 6.2 Linux/MacOS 终端测试

使用logger命令发送日志（需确保logger命令支持UDP协议）：

```bash

logger -n 127.0.0.1 -P 514 "Test syslog from Linux terminal"
```

### 6.3 Windows 命令行测试

使用PowerShell发送UDP消息：

```powershell

$udpClient = New-Object System.Net.Sockets.UdpClient
$udpClient.Connect("127.0.0.1", 514)
$message = [System.Text.Encoding]::UTF8.GetBytes("Test syslog from Windows PowerShell")
$udpClient.Send($message, $message.Length)
$udpClient.Close()
```

## 7. 常见问题排查

下表列出服务器运行中可能出现的常见问题、原因及解决方法，优先查看服务器运行日志（server.log），可快速定位问题。

|问题现象|可能原因|解决方法|
|---|---|---|
|启动失败，提示「Address already in use」|配置的port端口被其他程序占用。|1. 关闭占用该端口的程序；2. 修改config.ini中的port为其他未占用端口（如5140）。|
|Linux/MacOS 启动失败，提示「Permission denied」|使用了514等特权端口，未加sudo权限。|使用sudo命令启动：sudo python syslog_server.py。|
|客户端发送日志，服务器无响应，控制台无提示|1. 客户端IP未在白名单中；2. 服务器host配置错误；3. 网络不通，端口未开放；4. 客户端发送端口与服务器port不一致。|1. 检查config.ini的allowed_ips，添加客户端IP；2. 确认host为0.0.0.0；3. 检查防火墙，放行服务器UDP端口；4. 确认客户端发送端口与服务器port一致。|
|服务器提示「Access denied for IP: xxx」|客户端IP未在白名单中，被拒绝访问。|修改config.ini的allowed_ips，添加该客户端IP或所在网段。|
|日志写入失败，提示「Permission denied」|服务器无日志目录（log_dir）的读写权限。|1. 修改日志目录权限（Linux/MacOS：chmod 777 ./syslog_logs）；2. 更换日志目录为有读写权限的路径。|
|日志未被压缩，超过10MB仍为.log文件|1. max_log_size配置错误；2. 日志文件路径错误。|1. 检查config.ini的max_log_size，确保为10485760（10MB）；2. 检查日志存储路径，确认文件存在且大小超过阈值。|
|过期日志未被清理|1. clean_interval间隔过长；2. log_retention_days配置错误；3. 日志文件最后修改时间异常。|1. 缩短clean_interval（如改为1800）；2. 确认log_retention_days配置正确；3. 手动删除异常日志文件。|
|日志显示乱码|客户端日志编码不是UTF-8或GBK，解码失败。|修改syslog_server.py中日志解码逻辑，添加对应编码（如GB2312）。|
## 8. 注意事项

- 服务器采用UDP协议，UDP是无连接、不可靠协议，若网络不稳定，可能会丢失少量日志，适合对日志可靠性要求不高的场景；

- 日志压缩和解压会消耗一定的CPU资源，压缩级别越高，CPU消耗越大，可根据服务器配置调整compress_level；

- 长期运行建议使用后台运行方式（Linux/MacOS：nohup python syslog_server.py &），避免终端关闭导致服务器停止；

- 定期检查日志目录占用空间，若磁盘空间不足，可缩短log_retention_days或增大clean_interval；

- 修改config.ini配置后，需重启服务器才能生效。

## 9. 扩展建议

- 日志备份：可将压缩后的日志文件同步到远程存储（如FTP、云存储），防止本地磁盘损坏导致日志丢失；

- 监控告警：添加磁盘空间监控，当日志目录占用超过阈值时，发送告警信息；

- 日志分析：结合ELK等日志分析工具，对接收的日志进行可视化分析和检索；

- 多端口支持：修改代码，支持同时监听多个UDP端口，适配不同客户端的日志发送需求。
> （注：文档部分内容可能由 AI 生成）