Go 配置日志怎样隐藏环境变量敏感字段

Go 服务排查配置问题时，最危险的做法是把 os.Environ() 或完整配置结构体直接交给日志。环境变量里往往同时存在数据库密码、云端 Token 和业务开关。更稳妥的方案是“字段白名单负责主路径，日志处理器负责兜底”：先构造只包含可诊断字段的快照，再把明显的敏感键统一替换成占位符。

先把配置日志拆成公开字段和敏感字段

os.Environ() 返回的是一组 key=value 字符串，适合底层读取，不适合作为诊断日志。配置对象也一样：只要未来有人新增了 DB_PASSWORD 字段，原本安全的结构化日志就可能突然泄露密码。配置日志应该回答“服务按什么模式启动、监听哪个端口”，而不是回答“凭据具体是什么”。

如果确实需要知道变量是否存在，使用 os.LookupEnv 取得“值加存在标记”；不要为了判断缺省值而把原值写入日志。

用字段白名单构造可记录的配置快照

把读取环境变量和“可记录字段”放在同一个小函数里，调用方拿到的就是安全快照。下面的示例只保留排查启动状态需要的信息，密码即使存在，也没有进入 PublicConfig。

package main

import (
    "log/slog"
    "os"
    "strconv"
)

type PublicConfig struct {
    AppEnv   string `json:"app_env"`
    Port     int    `json:"port"`
    LogLevel string `json:"log_level"`
}

func publicConfigFromEnv() PublicConfig {
    // 只读取允许出现在日志里的字段，避免把完整环境复制进日志对象。
    get := func(key, fallback string) string {
        value, ok := os.LookupEnv(key)
        if !ok || value == "" {
            return fallback
        }
        return value
    }

    port, err := strconv.Atoi(get("PORT", "8080"))
    if err != nil || port  65535 {
        // 端口只用于诊断展示；非法值回退到约定默认值，不记录原始输入。
        port = 8080
    }
    return PublicConfig{
        AppEnv:   get("APP_ENV", "development"),
        Port:     port,
        LogLevel: get("LOG_LEVEL", "info"),
    }
}

func main() {
    logger := slog.Default()
    cfg := publicConfigFromEnv()
    // 只记录白名单快照；DB_PASSWORD 从未作为字段传入日志。
    logger.Info("configuration loaded", "config", cfg)
}

这段代码的关键不是结构体名称，而是边界：配置读取可以很宽，日志模型必须很窄。后续新增环境变量时，先判断它是否有诊断价值，再决定是否加入白名单。

给 log/slog 增加敏感键脱敏兜底

白名单能解决主路径，但真实项目里还会有临时排障日志。可以给 log/slog 的 HandlerOptions.ReplaceAttr 设置统一规则：遇到明显的敏感键就替换值。它不是白名单的替代品，而是防止误传参数时扩大损失。

package main

import (
    "log/slog"
    "os"
    "strings"
)

var secretKeys = map[string]struct{}{
    "password": {}, "passwd": {}, "token": {}, "secret": {}, "api_key": {},
}

func redactAttr(_ []string, attr slog.Attr) slog.Attr {
    // 只按键名兜底遮蔽；真正的配置日志仍应优先使用字段白名单。
    key := strings.ToLower(attr.Key)
    if _, found := secretKeys[key]; found {
        return slog.String(attr.Key, "[REDACTED]")
    }
    return attr
}

func newLogger() *slog.Logger {
    // ReplaceAttr 在属性写入处理器前改写值，JSON 和文本处理器都能复用。
    handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        ReplaceAttr: redactAttr,
    })
    return slog.New(handler)
}

func main() {
    logger := newLogger()
    // 即使临时日志误传 token，输出也只保留占位符。
    logger.Info("debug config", "app_env", "staging", "token", "[REDACTED]")
}

规则表要覆盖项目真实命名，例如 access_token、client_secret 也可以在进入日志前先归一化，或者在业务层把它们映射为统一键名。不要把脱敏后的值当作可恢复的密文；日志里只应该出现固定占位符。

按空值、默认值和扩展字段做上线前检查

上线前至少检查四件事：第一，代码里没有对 os.Environ() 的直接日志调用；第二，敏感配置没有出现在可序列化的公共快照结构体；第三，脱敏键表覆盖了团队约定的命名；第四，新增环境变量有明确的“可记录/不可记录”结论。LookupEnv 能区分“没有设置”和“设置为空”，但两者都不应该让密码原值进入日志。

生产排障时优先查看 app_env、端口和日志级别；需要核对凭据是否注入，则只输出“已设置”布尔结果。这样既能定位配置装载问题，也不会把日志系统变成第二个密钥存储。

相关问题

只用 ReplaceAttr 能代替白名单吗？

不能。键名规则可能漏掉自定义字段，白名单才是控制日志内容的主边界。

为什么不直接把敏感值截断几位？

截断值仍可能被关联或用于猜测，固定的 [REDACTED] 更容易审计。

如何确认环境变量已注入但不泄露它？

用 _, ok := os.LookupEnv("DB_PASSWORD") 只记录 ok，不要记录返回的字符串。