4. 加密SDK日志初始化配置
日志这东西，平时没人关注，一出事它就是唯一的救命稻草。我做过好几个加密SDK项目，几乎每次线上问题都是靠日志定位的。但前提是——你得在初始化阶段就把日志配好。
加密SDK的日志和普通应用日志不太一样。它既要记录密钥生成、签名验签这样敏感的操作，又不能把密钥本身给打出来。你想想看，如果日志里泄露了私钥，那加密还有什么意义？所以初始化配置里有一项特别重要：敏感信息过滤。我们后面会细说。
4.1 日志级别配置
日志级别决定哪些信息能写出来。级别越低，信息越细，对性能影响也越大。我建议线上环境至少开到WARN，开发环境开到DEBUG就够了。
| 级别 | 含义 | 建议场景 |
|---|---|---|
| TRACE | 最细的追踪信息 | 仅临时调试，不上线 |
| DEBUG | 调试信息 | 开发、联调阶段 |
| INFO | 关键运行节点 | 日常记录，比如“初始化完成” |
| WARN | 潜在问题 | 线上默认级别，比如证书即将过期 |
| ERROR | 可恢复的错误 | 业务异常，如签名失败 |
| FATAL | 致命错误，SDK无法继续 | 必须告警的场景 |
举个初始化代码的例子（以Java SDK为例）：
CryptoLoggerConfig config = new CryptoLoggerConfig();
config.setLevel(LogLevel.DEBUG); // 开发环境
config.setLevel(LogLevel.WARN); // 线上环境
sdk.initialize(config);4.2 日志输出目标
输出到哪儿？常见的就三种：控制台、文件、远程日志中心。
- 控制台：开发时用，方便直接看。但生产环境不建议，大量的日志会刷满标准输出，影响容器运行。
- 文件：最主流的方式。要保持文件轮转，不然一天就能撑爆磁盘。
- 远程：通过TCP/UDP发到集中日志平台。适合分布式系统，但要处理好网络抖动。
我曾经遇到一个项目，线上机器磁盘被日志撑爆，导致进程直接挂了。原因就是文件轮转没配，日志每天写100GB，一周后磁盘满了。从那以后我每次都强制要求配置 maxFileSize 和 maxBackupIndex。
配置示例：
FileAppender appender = new FileAppender();
appender.setDirectory("/var/log/sdk");
appender.setMaxFileSize("100MB");
appender.setMaxBackupIndex(5); // 保留最近5个历史文件
config.addAppender(appender);4.3 日志格式与轮转
格式决定了你能从日志里读到什么信息。我个人习惯每行日志至少包含：时间戳、线程名、日志级别、调用链路ID（如果有）、消息。这样方便后续用grep或ELK分析。
| 格式字段 | 说明 | 我推荐 |
|---|---|---|
| %d{yyyy-MM-dd HH:mm:ss.SSS} | 精确到毫秒的时间 | 必须加 |
| %thread | 线程名 | 排查并发问题必备 |
| %-5level | 日志级别，左对齐5位 | 固定宽度好看 |
| %msg%n | 消息+换行 | 基本 |
| %X{traceId} | MDC中的链路ID | 微服务环境下强烈建议 |
轮转策略除了大小和数量，也可以按时间。比如每天零点切分一份新日志。我通常组合使用：按大小触发滚动，同时保留最多7天。
PatternLayout layout = new PatternLayout();
layout.setPattern("%d{ISO8601} [%thread] %-5level %X{traceId} - %msg%n");
appender.setLayout(layout);
TimeBasedRollingPolicy policy = new TimeBasedRollingPolicy();
policy.setFileNamePattern("/var/log/sdk/sdk.%d{yyyy-MM-dd}.log");
policy.setMaxHistory(7);
appender.setRollingPolicy(policy);4.4 敏感信息过滤
加密SDK的日志里最怕什么？明文密钥、密码、证书内容、完整报文。这些东西一旦流出，安全合规就全完了。
过滤策略一般有三种做法：
- 白名单：只允许特定字段输出（例如请求ID、结果码）。
- 黑名单：匹配到敏感关键字就替换成
***。 - 正则替换：比如私钥内容以“-----BEGIN PRIVATE KEY-----”开头，就整段屏蔽。
我个人倾向黑名单+正则组合。初始化时传入一个过滤器列表，依次检查。
Filter filter = new RegexFilter();
filter.addPattern("-----BEGIN.*KEY-----[\s\S]*?-----END.*KEY-----", "[KEY REDACTED]");
filter.addPattern("\"password\":\s*\".+?\"", "\"password\":\"***\"");
config.addFilter(filter);注意：过滤会消耗CPU。我建议只在WARN及以上的日志上应用过滤，对TRACE/DEBUG级别的完整输出单独做脱敏处理，或者直接不把敏感参数传给日志方法。
4.5 初始化流程总图
下面这张图梳理了日志初始化的完整流程。你在实际集成时可以按这个顺序来。
这张图很好理解：先读配置，然后设置级别，接着配输出目标。注意输出目标的配置决定日志写到哪里，轮转和格式是绑定在输出目标上的，所以我把它们画在一起。最后加上过滤，再启动。顺序不能乱——如果你先启动再配过滤，前几条日志可能会泄露敏感信息。