日志系统详解

本文档详细介绍服务端的多级日志体系，包括全局系统日志和各业务模块的专用日志。

日志架构概览

服务端采用分层日志设计：

┌─────────────────────────────────────────────────────────┐
│  全局系统日志 (Insts.AddLog)                              │
│  └── 记录：系统启动、客户端连接/断开、登录认证等           │
├─────────────────────────────────────────────────────────┤
│  业务专用日志 (cLogs)                                     │
│  ├── bCalc.cls      → logs/JsonData/                    │
│  ├── bFileManage.cls → logs/FileServer/                 │
│  └── fNotify.frm    → logs/Notify/                      │
└─────────────────────────────────────────────────────────┘

全局系统日志

位置

src-server/Insts.bas

接口定义

Public Sub AddLog(ByVal Msg As String, Optional Level As EnumLogLevel = LvInfo, Optional Title As String)

参数说明

参数	类型	默认值	说明
`Msg`	String	-	日志内容
`Level`	EnumLogLevel	`LvInfo`	日志级别
`Title`	String	`""`	日志标题/分类

日志级别

级别	常量	用途
信息	`LvInfo`	正常操作记录
警告	`LvWarning`	需要注意的非错误事件
危险	`LvDanger`	错误、异常、安全事件

输出目标

文件日志: 通过 VBMAN.Logs 写入 logs/年/月/年月日.txt
界面显示: 实时显示在 Form1.List2 列表框

使用示例

AddLog "系统启动完成", LvInfo, "系统启动"
AddLog "客户端断开，当前在线: 5", LvWarning, "断开"
AddLog "认证失败: 凭证为空", LvDanger, "认证失败"

系统日志记录场景

Form1.frm — 主窗体系统事件

事件	日志级别	记录内容
系统启动	Info	"系统启动中..."、"TCP 服务已启动，端口: 800"、"数据库连接成功"、"路由注册完成"、"系统启动完成"
客户端连接	Info	"新客户端连接请求"、"新客户端连接，当前在线: N"
客户端断开	Warning	"客户端断开，当前在线: N"、"客户端断开连接: [用户名]"

mAuth.cls — 认证中间件

场景	日志级别	记录内容
凭证为空	Danger	"认证失败: 凭证为空 [用户: xxx]"
未绑定用户	Danger	"认证失败: 当前客户端未绑定用户"
凭证验证失败	Danger	"认证失败: 凭证验证失败 [用户: xxx]"

bUser.cls — 用户登录

场景	日志级别	记录内容
用户名不存在	Warning	"登录失败: 用户名不存在 [xxx]"
密码未设置	Warning	"登录失败: 用户密码未设置 [xxx]"
密码错误	Warning	"登录失败: 密码错误 [xxx]"
踢掉旧连接	Warning	"账号在另外一个地方登录，踢掉旧连接: xxx"
登录成功	Info	"用户登录成功: xxx [昵称]"

bNotify.cls — 公告查询

场景	日志级别	记录内容
用户获取公告	Info	"用户获取公告: xxx"

业务专用日志

各业务模块使用独立的 cLogs 实例，日志存储在各自的子目录中，与系统日志分离。

bCalc.cls — 计算参数日志

日志目录: logs/JsonData/

用途: 记录客户端提交的参数数据和服务端修改后的数据，用于数据核对和调试。

Dim LogInst As New cLogs

Private Sub Class_Initialize()
    LogInst.LogSubDir = "JsonData"
    LogInst.HostApp App
End Sub

Public Sub Submit(Inst As cWinsock, Data As cJson)
    ' 记录客户端发来的数据
    LogInst.DataLine Data.Encode(, 2, True), "客户端发来数据"
    
    ' ... 处理数据 ...
    
    ' 记录修改后的数据
    LogInst.DataLine Data.Encode(, 2, True), "服务端修改数据"
    LogInst.Save
End Sub

记录格式: JSON 格式，带缩进便于阅读

bFileManage.cls — 文件传输日志

日志目录: logs/FileServer/

用途: 记录文件上传、下载、归档、删除等操作。

Dim LogInst As New cLogs

Public Sub StartMe(ByVal Port As Long)
    ' ... 启动服务 ...
    LogInst.LogSubDir = "FileServer"
    LogInst.HostApp App
    LogInst.DataLine "文件传输服务已启动，端口: " & Port, "启动"
    LogInst.Save
End Sub

记录场景:

场景	日志级别	记录内容
服务启动/停止	Info	"文件传输服务已启动/停止，端口: xxx"
文件上传归档	Info	"文件已归档 [用户名]: 原文件名 -> 目标路径"
临时文件不存在	Danger	"错误: 临时文件不存在 [用户名]: 路径"
归档失败	Danger	"归档失败 [用户名]: 文件名 - 错误描述"
发送完成	Info	"发送完成 [用户名]: 文件名"
文件下发	Info/Danger	开始发送、文件不存在、发送失败等
文件删除	Warning	"用户删除文件 [用户名]: 文件路径"

fNotify.frm — 公告推送日志

日志目录: logs/Notify/

用途: 记录公告的推送和清空操作。

Dim LogInst As New cLogs

Private Sub Form_Load()
    LogInst.LogSubDir = "Notify"
    LogInst.HostApp App
End Sub

Private Sub Command1_Click()  ' 推送按钮
    ' ... 推送公告 ...
    Dim Content As String
    Content = VBMAN.Json.Decode(VBMAN.Ini("Notify")).Encode(, 2, True)
    LogInst.DataLine(Content, "推送了新公告").Save
End Sub

Private Sub Command2_Click()  ' 清空按钮
    ' ... 清空公告 ...
    LogInst.Data("", "清空了公告", LvDanger).Save
End Sub

记录场景:

场景	日志级别	记录内容
推送公告	Info	完整的公告 JSON 内容，标题"推送了新公告"
清空公告	Danger	空内容，标题"清空了公告"

日志文件结构

logs/
├── 2026/
│   └── 04/
│       └── 20260430.txt          # 系统日志（全局）
├── JsonData/
│   └── 2026/
│       └── 04/
│           └── 20260430.txt      # 计算参数日志
├── FileServer/
│   └── 2026/
│       └── 04/
│           └── 20260430.txt      # 文件传输日志
└── Notify/
    └── 2026/
        └── 04/
            └── 20260430.txt      # 公告操作日志

配置说明

全局日志配置 (Form1.Form_Load)

' 如果 vbman.dll 和 exe 不在同一目录，必须配置 HostApp
VBMAN.Logs.HostApp App

专用日志配置 (各业务模块)

With LogInst
    .LogSubDir = "子目录名"     ' 指定日志子目录
    .HostApp App               ' 配置宿主程序
End With

最佳实践

系统级事件使用全局 AddLog，便于统一监控系统运行状态
业务数据使用专用 cLogs 实例，避免系统日志被大量业务数据淹没
敏感操作（登录失败、密码修改、文件删除等）务必记录，用于安全审计
日志级别选择:
- LvInfo - 正常流程记录
- LvWarning - 需要注意但非错误的事件
- LvDanger - 错误、异常、安全风险事件

日志系统详解 ​

日志架构概览 ​

全局系统日志 ​

位置 ​

接口定义 ​

参数说明 ​

日志级别 ​

输出目标 ​

使用示例 ​

系统日志记录场景 ​

Form1.frm — 主窗体系统事件 ​

mAuth.cls — 认证中间件 ​

bUser.cls — 用户登录 ​

bNotify.cls — 公告查询 ​

业务专用日志 ​

bCalc.cls — 计算参数日志 ​

bFileManage.cls — 文件传输日志 ​

fNotify.frm — 公告推送日志 ​

日志文件结构 ​

配置说明 ​

全局日志配置 (Form1.Form_Load) ​

专用日志配置 (各业务模块) ​

最佳实践 ​