Go Gateway

外观

📝 日志配置指南 ​

📖 简介 ​

日志系统是应用程序的重要组成部分，它帮助我们追踪系统运行状态、排查问题和监控性能。本指南将帮助您了解如何在 Go Gateway 中配置和使用日志功能。

为什么需要日志？

  • 问题排查和调试
  • 系统运行状态监控
  • 安全审计和追踪
  • 性能分析和优化

⚙️ 基础配置 ​

日志级别配置 ​

yaml
log:
  level: debug  # 日志级别
  max-size: 100  # 日志文件最大大小（MB）
  max-backups: 100  # 最大保留的旧日志文件数量
  max-age: 100  # 最大保留天数
  async: false  # 是否异步写入日志

配置参数说明

参数名类型说明默认值是否必填
levelString日志级别，可选值：debug/info/warn/errorinfo否
max-sizeInteger单个日志文件最大大小，单位：MB100否
max-backupsInteger最大保留的旧日志文件数量100否
max-ageInteger日志文件最大保留天数100否
asyncBoolean是否异步写入日志false否

敏感信息脱敏配置 ​

🛡️ 自动脱敏机制

系统内置自动脱敏机制。当你使用 log.Ctx(ctx) 获取的 Logger 输出日志时，底层会通过 sensitiveWriteCore 自动对消息内容和字段值进行脱敏处理，无需手动调用任何脱敏函数。所有经过 Ctx() 输出的日志数据都会自动经过脱敏流程。

脱敏配置分为三种机制，各司其职：

机制配置项作用范围说明
字段名匹配field-rulesJSON 字段键、URL query 参数名根据字段名精确匹配脱敏
正则内容匹配content-rules非结构化文本、未命中 field-rules 的字段值基于正则模式匹配脱敏
长度截断max-length所有字符串值超长字段自动截断

1. 字段级脱敏（field-rules） ​

根据字段名匹配，适用于结构化日志中通过 *w 方法输出的键值对数据（如 Infow("登录", "password", pwd) 中的字段名 password）以及 JSON 请求/响应体中的字段。

yaml
log:
  sensitive:
    field-rules:
      - field-names:           # 需要脱敏的字段名列表（大小写不敏感）
          - password
          - passwd
          - token
        type: password         # 脱敏类型，使用预设策略
      - field-names:
          - authorization
        mask:                  # 自定义掩码策略（会覆盖 type 的预设策略）
          strategy: replace    # 掩码策略：border/replace/prefix/suffix
          mask-char: "*"       # 掩码字符，默认 "*"
    max-length: 100

field-rules 配置参数说明

参数名类型说明默认值是否必填
field-namesArray[String]需要脱敏的字段名列表（大小写不敏感）-是
typeString脱敏类型，详见下方脱敏类型表格-与 mask 二选一
mask.strategyString自定义掩码策略：border（前后保留）、replace（全替换）、prefix（前缀保留）、suffix（后缀保留）由 type 决定否
mask.prefix-keepInteger前缀保留字符数（strategy=border 或 prefix 时有效）由 type 决定否
mask.suffix-keepInteger后缀保留字符数（strategy=border 或 suffix 时有效）由 type 决定否
mask.mask-charString掩码替换字符*否

2. 内容级脱敏（content-rules） ​

基于正则表达式匹配，用于脱敏非结构化文本日志（如 Debugf("xxx", ...) 输出的消息体）中的敏感内容。

⚠️ 重要说明

content-rules 不仅作用于消息体（message），还会对所有未命中 field-rules 的字符串字段值进行正则扫描。因此不要将通用正则（如 ip）放入 content-rules，否则会导致类似 Host、URL 等字段值中的 IP 地址也被误脱敏。这类场景应使用 field-rules 按字段名精确控制。

yaml
log:
  sensitive:
    content-rules:
      - type: mobile           # 匹配手机号格式（基于预设正则：1[3-9]\d{9}）
      - type: idcard           # 匹配身份证号格式（基于预设正则：\d{17}[\dXx]）
      - type: bankcard         # 匹配银行卡号格式（基于预设正则：\d{16,19}）
      - type: email            # 匹配邮箱格式
      - type: creditcode       # 匹配统一社会信用代码格式
      - type: qq               # 匹配QQ号格式（基于预设正则：[1-9]\d{4,10}）

content-rules 配置参数说明

参数名类型说明默认值是否必填
typeString脱敏类型，使用内置预设正则和掩码策略-是
patternString自定义正则表达式（覆盖预设），留空则使用 type 对应预设-否
mask.strategyString自定义掩码策略，覆盖 type 预设由 type 决定否

content-rules 可用的预设正则

类型预设正则说明
mobile1[3-9]\d{9}中国大陆手机号
idcard\d{17}[\dXx]中国大陆身份证号
bankcard\d{16,19}银行卡号
email标准邮箱正则邮箱地址
creditcode[0-9A-HJ-NPQRTUWXY]{2}\d{6}[0-9A-HJ-NPQRTUWXY]{10}统一社会信用代码
qq[1-9]\d{4,10}QQ号

以下类型没有预设 contentPattern，放入 content-rules 将不生效，请使用 field-rules 替代： password、name、address、passport、militaryid、businesslicense、carnumber、wechatid

3. 长度截断（max-length） ​

超过指定长度的字符串值会被自动截断，末尾追加 ...，防止日志过大。

yaml
log:
  sensitive:
    max-length: 100  # 单个参数值最大字符长度，超过则截断

脱敏类型支持 ​

系统内置以下脱敏类型，每种类型都有预设的掩码策略和正则模式：

脱敏类型预设掩码策略预设掩码参数示例（原文 → 脱敏后）有 contentPattern
mobileborder前3后413812348888 → 138****8888✅
idcardborder前6后4110101199001011234 → 110101********1234✅
bankcardborder前4后46222021234561234 → 6222********1234✅
emailborder前3后0test@example.com → tes***@example.com✅
passwordreplace—mypassword → **********❌
nameborder前1后1张三丰 → 张*丰❌
addressborder前6后0北京市海淀区中关村大街1号 → 北京市海淀区******❌
ipborder前2后0192.168.1.100 → 19***✅
creditcodeborder前8后291110108MA01ABCD1X → 91110108********D1X✅
passportborder前4后4E12345678 → E123****5678❌
militaryidborder前4后4军12345678 → 军123****5678❌
businesslicenseborder前6后491110108MA01ABCD1X → 911101*******D1X❌
carnumberborder前3后2京A12345 → 京A1***45❌
wechatidprefix前3wxid_abcdef → wxi********❌
qqprefix前41234567890 → 1234******✅

掩码策略说明

策略说明相关参数
border保留前后字符，中间用掩码字符替换prefix-keep、suffix-keep
replace全部用掩码字符替换—
prefix保留前 N 个字符，其余替换prefix-keep
suffix保留后 N 个字符，其余替换suffix-keep

注意事项

  • 确保敏感字段配置完整，覆盖所有可能的字段名变体（如 password/passwd/pwd）
  • content-rules 中的 ip 类型会误伤 Host/URL 等技术字段中的 IP 地址，建议通过 field-rules 精确控制
  • 没有预设 contentPattern 的类型（如 password、name）放入 content-rules 不会生效
  • 定期检查脱敏规则是否满足安全要求
  • 注意日志文件的安全存储

请求和响应日志配置 ​

日志级别说明

请求和响应日志仅在日志级别为 debug 时生效。如需启用，请确保配置：

yaml
log:
  level: debug
yaml
log:
  request:  # 请求日志配置
    enabled: true  # 是否启用请求日志
    urls:  # 允许记录请求日志的URL列表
      - /api/**
      - /web/**
    forbid-urls:  # 禁止记录请求日志的URL列表
      - /api/health
      - /api/metrics
  response:  # 响应日志配置
    enabled: true  # 是否启用响应日志
    urls:  # 允许记录响应日志的URL列表
      - /api/**
      - /web/**
    forbid-urls:  # 禁止记录响应日志的URL列表
      - /api/health
      - /api/metrics

请求和响应配置参数说明

参数名类型说明默认值是否必填
request.enabledBoolean是否启用请求日志false否
request.urlsArray允许记录请求日志的URL列表-否
request.forbid-urlsArray禁止记录请求日志的URL列表-否
response.enabledBoolean是否启用响应日志false否
response.urlsArray允许记录响应日志的URL列表-否
response.forbid-urlsArray禁止记录响应日志的URL列表-否

📋 完整配置示例 ​

基础配置示例 ​

yaml
log:
  level: info  # 生产环境推荐使用info级别
  max-size: 50  # 50MB文件切割
  max-backups: 30  # 保留30个备份文件
  max-age: 7  # 保留7天

开发环境配置 ​

yaml
log:
  level: debug  # 开发环境使用debug级别
  max-size: 10  # 10MB文件切割（开发环境较小）
  max-backups: 5  # 保留5个备份文件
  max-age: 3  # 保留3天

  # 脱敏配置
  sensitive:
    field-rules:
      - field-names:
          - password
          - token
        type: password
      - field-names:
          - mobile
          - phone
        type: mobile
    content-rules:
      - type: mobile
      - type: idcard
      - type: email
    max-length: 100

  # 请求响应日志（仅debug级别生效）
  request:
    enabled: true
    urls:
      - /api/**
      - /test/**
    forbid-urls:
      - /api/health
      - /api/ping

  response:
    enabled: true
    urls:
      - /api/**
      - /test/**
    forbid-urls:
      - /api/health
      - /api/ping

生产环境配置 ​

yaml
log:
  level: warn  # 生产环境只记录警告和错误
  max-size: 100  # 100MB文件切割
  max-backups: 50  # 保留50个备份文件
  max-age: 30  # 保留30天

  # 全面的敏感信息脱敏
  sensitive:
    field-rules:
      # 密码/凭证类
      - field-names:
          - password
          - passwd
          - oldPassword
          - newPassword
          - confirmPassword
          - token
          - accessToken
          - refreshToken
          - secret
          - apiKey
          - signKey
          - jwtToken
          - authorization
        mask:
          strategy: replace
          mask-char: "*"

      # 手机号
      - field-names:
          - mobile
          - telephone
          - phoneNumber
        type: mobile

      # 身份证号
      - field-names:
          - idCard
          - identityNo
        type: idcard

      # 银行卡
      - field-names:
          - bankCard
          - cardNo
        type: bankcard

      # 邮箱
      - field-names:
          - email
        type: email

      # 姓名
      - field-names:
          - name
          - realName
          - nickName
        type: name

      # 地址
      - field-names:
          - address
          - addr
        type: address

      # IP地址（按字段名精确匹配，不放入 content-rules）
      - field-names:
          - ip
          - clientIp
          - remoteAddr
        type: ip

    # 内容级脱敏（非结构化文本中的敏感信息）
    content-rules:
      - type: mobile
      - type: idcard
      - type: bankcard
      - type: email
      - type: creditcode
      - type: qq

    max-length: 200

  # 生产环境建议关闭请求响应日志
  request:
    enabled: false

  response:
    enabled: false

不同业务场景配置 ​

金融系统日志配置 ​

yaml
log:
  level: warn  # 金融系统高安全要求
  max-size: 50  # 较小的文件便于管理
  max-backups: 100  # 长期保留
  max-age: 90  # 保留90天（合规要求）

  sensitive:
    field-rules:
      # 金融敏感信息
      - field-names:
          - accountNumber
          - bankCard
          - cardNo
          - creditCard
        type: bankcard

      # 身份信息
      - field-names:
          - idCard
          - passport
          - socialSecurity
        type: idcard

      # 交易密码
      - field-names:
          - tradePassword
          - paymentPassword
          - transactionPwd
        type: password

      # 金额信息
      - field-names:
          - amount
          - balance
        type: address

    max-length: 100  # 严格限制长度

医疗系统日志配置 ​

yaml
log:
  level: info
  max-size: 100
  max-backups: 50
  max-age: 365  # 医疗数据长期保存

  sensitive:
    field-rules:
      # 患者信息
      - field-names:
          - patientName
          - patientId
          - medicalRecordNo
        type: name

      # 身份证件
      - field-names:
          - idCard
          - passport
          - insuranceNumber
        type: idcard

      # 联系方式
      - field-names:
          - phone
          - emergencyContact
          - familyPhone
        type: mobile

      # 医疗隐私字段
      - field-names:
          - diagnosis
          - medicalHistory
          - prescription
        type: address

    max-length: 300

电商系统日志配置 ​

yaml
log:
  level: info
  max-size: 200
  max-backups: 20
  max-age: 30

  sensitive:
    field-rules:
      # 用户信息
      - field-names:
          - realName
          - recipientName
          - consignee
        type: name

      # 联系方式
      - field-names:
          - phone
          - mobile
          - contactPhone
        type: mobile

      # 收货地址
      - field-names:
          - shippingAddress
          - deliveryAddress
          - address
        type: address

      # 支付信息
      - field-names:
          - bankCard
          - paymentAccount
          - alipayAccount
        type: bankcard

    content-rules:
      - type: mobile
      - type: email

    max-length: 200

  # 电商系统可能需要记录用户行为（调试时）
  request:
    enabled: false
    urls:
      - /api/order/**
      - /api/payment/**
    forbid-urls:
      - /api/product/list  # 商品列表接口访问频繁
      - /api/category/**   # 分类接口访问频繁

URL匹配规则

  • 支持通配符匹配，如 /api/**
  • 支持精确匹配，如 /api/health
  • 支持多个URL配置，使用数组形式
  • 优先级：forbid-urls > urls

注意事项

  • 请求和响应日志可能包含敏感信息，请确保配置了适当的脱敏规则
  • 日志系统已内置自动脱敏，使用 Ctx() 输出的日志会自动脱敏，无需手动调用脱敏函数
  • content-rules 会影响所有未命中 field-rules 的字段值，谨慎添加范围过广的正则规则
  • 建议只记录必要的URL，避免日志量过大
  • 对于高频访问的接口，建议配置到 forbid-urls 中
  • 定期检查日志内容，确保没有敏感信息泄露

🆘 技术支持 ​

如果遇到问题：

  1. 检查日志配置文件
  2. 查看系统日志
  3. 分析错误信息
  4. 联系技术支持团队

重要提示

  • 定期备份重要日志
  • 确保日志存储安全
  • 遵守数据保护规范
  • 及时处理异常日志

Copyright © 2017-2026 wueasy.com