# 日志配置

<cite>
**本文引用的文件**
- [cmd/server/main.go](file://cmd/server/main.go)
- [pkg/config/config.go](file://pkg/config/config.go)
- [pkg/logger/logger.go](file://pkg/logger/logger.go)
- [pkg/logger/manager.go](file://pkg/logger/manager.go)
- [internal/middleware/logger.go](file://internal/middleware/logger.go)
- [internal/middleware/recovery.go](file://internal/middleware/recovery.go)
- [go.mod](file://go.mod)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向 CarrotSkin 项目的开发者与运维人员，系统性说明日志系统的配置与使用方式。重点围绕以下配置项展开：log.level、format、output、max_size、max_backups、max_age 和 compress；并结合 LogConfig 结构体与实际代码实现，给出不同日志级别选择策略、JSON 格式与文本格式的适用场景、以及基于大小与天数的日志轮转工作机制。最后提供生产环境监控集成建议与最佳实践。

## 项目结构
日志系统由“配置加载层”“日志工厂层”“全局管理器层”“中间件与业务使用层”四部分组成：
- 配置加载层：从环境变量加载并解析为 Config，其中包含 LogConfig 字段。
- 日志工厂层：根据 LogConfig 构建 zap.Logger。
- 全局管理器层：提供 Init、GetLogger、MustGetLogger 等接口，确保单例与线程安全。
- 中间件与业务使用层：通过中间件注入日志实例，统一记录 HTTP 请求与异常恢复。

```mermaid
graph TB
A["配置加载<br/>pkg/config/config.go"] --> B["日志工厂<br/>pkg/logger/logger.go"]
B --> C["全局管理器<br/>pkg/logger/manager.go"]
C --> D["中间件使用<br/>internal/middleware/logger.go"]
C --> E["恢复中间件<br/>internal/middleware/recovery.go"]
C --> F["应用入口初始化<br/>cmd/server/main.go"]
```

图表来源
- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L1-L69)
- [pkg/logger/manager.go](file://pkg/logger/manager.go#L1-L51)
- [internal/middleware/logger.go](file://internal/middleware/logger.go#L1-L40)
- [internal/middleware/recovery.go](file://internal/middleware/recovery.go#L1-L30)
- [cmd/server/main.go](file://cmd/server/main.go#L1-L124)

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L1-L69)
- [pkg/logger/manager.go](file://pkg/logger/manager.go#L1-L51)
- [cmd/server/main.go](file://cmd/server/main.go#L1-L124)

## 核心组件
- LogConfig 结构体：定义日志系统的核心配置项，来源于环境变量映射。
- New：根据 LogConfig 构建 zap.Logger，支持 JSON/Console 编码器、stdout 或文件输出。
- Init/GetLogger/MustGetLogger：全局单例管理，保证线程安全与幂等初始化。
- 中间件 Logger/Recovery：在请求处理前后记录日志，并在 panic 时记录堆栈与上下文。

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L79-L88)
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L1-L69)
- [pkg/logger/manager.go](file://pkg/logger/manager.go#L1-L51)
- [internal/middleware/logger.go](file://internal/middleware/logger.go#L1-L40)
- [internal/middleware/recovery.go](file://internal/middleware/recovery.go#L1-L30)

## 架构总览
下图展示了从配置到日志输出的关键流程：应用启动时加载配置，初始化日志管理器，随后中间件与业务代码通过全局日志实例进行记录。

```mermaid
sequenceDiagram
participant App as "应用入口<br/>cmd/server/main.go"
participant Cfg as "配置加载<br/>pkg/config/config.go"
participant LMgr as "日志管理器<br/>pkg/logger/manager.go"
participant LNew as "日志工厂<br/>pkg/logger/logger.go"
participant MW as "中间件<br/>internal/middleware/logger.go"
participant Rec as "恢复中间件<br/>internal/middleware/recovery.go"
App->>Cfg : 加载配置
Cfg-->>App : 返回 Config(LogConfig)
App->>LMgr : Init(LogConfig)
LMgr->>LNew : New(LogConfig)
LNew-->>LMgr : 返回 zap.Logger
LMgr-->>App : 初始化完成
App->>MW : 注入日志实例
App->>Rec : 注入日志实例
MW-->>App : 记录请求日志
Rec-->>App : 记录 panic 与堆栈
```

图表来源
- [cmd/server/main.go](file://cmd/server/main.go#L27-L40)
- [pkg/config/config.go](file://pkg/config/config.go#L108-L133)
- [pkg/logger/manager.go](file://pkg/logger/manager.go#L20-L29)
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L14-L68)
- [internal/middleware/logger.go](file://internal/middleware/logger.go#L10-L39)
- [internal/middleware/recovery.go](file://internal/middleware/recovery.go#L11-L29)

## 详细组件分析

### 配置项详解与选择策略
- log.level
  - 取值范围：debug、info、warn、error，默认 info。
  - 选择策略：
    - 开发/调试：debug，便于定位问题。
    - 生产：info，平衡可观测性与性能；仅在需要深入排查时临时提升到 debug。
    - 严重问题：error，聚焦错误事件，避免过多噪声。
- log.format
  - 取值：console、json。
  - 适用场景：
    - console：本地开发终端阅读友好，便于快速定位。
    - json：便于日志收集与结构化分析，适合生产与集中化监控。
- log.output
  - 取值：空/“stdout”表示输出到标准输出；其他路径将自动创建目录并写入文件。
  - 适用场景：
    - 容器化部署：stdout，配合容器日志采集。
    - 传统部署：文件路径，结合日志轮转策略。
- log.max_size、log.max_backups、log.max_age、log.compress
  - 作用：控制日志轮转策略（按大小与天数）与压缩开关。
  - 工作机制（基于大小与天数）：
    - 当单个日志文件达到 max_size（MB）时触发轮转。
    - 最多保留 max_backups 个历史备份文件。
    - 历史文件保留不超过 max_age（天）。
    - compress=true 时对旧文件进行压缩，节省磁盘空间。
  - 注意：当前代码实现中并未直接使用上述字段进行轮转配置，而是采用文件输出与基础写入同步。若需启用基于大小/天数的轮转，可在日志工厂中引入外部轮转库（如 lumberjack）并传入上述参数。

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L79-L88)
- [pkg/config/config.go](file://pkg/config/config.go#L170-L178)
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L43-L60)

### 日志级别选择策略
- debug：用于开发阶段的详细追踪，包含大量上下文信息。
- info：生产环境默认级别，记录关键业务事件与系统状态。
- warn：潜在问题或异常流程，需关注但不影响整体运行。
- error：错误事件，必须处理与上报。

章节来源
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L16-L28)

### JSON 格式与文本格式的适用场景
- JSON：
  - 优点：结构化强，便于日志聚合、检索与告警。
  - 适用：生产环境、集中化日志平台（如 ELK、Loki、Cloud Logging）。
- Console：
  - 优点：人类可读性强，适合本地开发与快速排障。
  - 适用：本地调试、临时诊断。

章节来源
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L30-L41)

### 日志轮转策略（基于大小与天数）
- 当前实现要点：
  - 输出到文件时会自动创建目录并追加写入。
  - 未显式配置基于大小/天数的轮转。
- 建议扩展方案：
  - 引入外部轮转库（如 lumberjack），在 New 中根据 max_size、max_backups、max_age、compress 进行轮转配置。
  - 将轮转配置作为可选参数传入，保持现有接口兼容。

章节来源
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L43-L60)
- [pkg/config/config.go](file://pkg/config/config.go#L79-L88)

### 日志工厂与全局管理器
- New：根据 LogConfig 构建 zap.Logger，设置级别、编码器与输出目标。
- Init/GetLogger/MustGetLogger：提供线程安全的单例初始化与获取能力，避免重复初始化。

```mermaid
classDiagram
class LogConfig {
+string level
+string format
+string output
+int max_size
+int max_backups
+int max_age
+bool compress
}
class LoggerFactory {
+New(cfg LogConfig) *zap.Logger
}
class LogManager {
+Init(cfg LogConfig) error
+GetLogger() (*zap.Logger, error)
+MustGetLogger() *zap.Logger
}
LogConfig --> LoggerFactory : "输入"
LoggerFactory --> LogManager : "被调用"
```

图表来源
- [pkg/config/config.go](file://pkg/config/config.go#L79-L88)
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L14-L68)
- [pkg/logger/manager.go](file://pkg/logger/manager.go#L20-L46)

章节来源
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L14-L68)
- [pkg/logger/manager.go](file://pkg/logger/manager.go#L1-L51)

### 中间件与业务使用
- Logger 中间件：记录每次 HTTP 请求的方法、路径、状态码、耗时、客户端 IP、User-Agent 等。
- Recovery 中间件：捕获 panic 并记录错误、路径、方法、IP 与完整堆栈，返回统一错误响应。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Router as "Gin 路由"
participant MW as "日志中间件"
participant Handler as "业务处理器"
participant Rec as "恢复中间件"
Client->>Router : 发起请求
Router->>MW : 进入日志中间件
MW->>MW : 记录请求开始时间与上下文
MW->>Handler : 继续处理
Handler-->>MW : 返回响应
MW->>MW : 记录状态码、耗时、IP、UA
MW-->>Router : 返回响应
Note over MW : 若发生 panic，由恢复中间件接管
Router->>Rec : 进入恢复中间件
Rec->>Rec : 记录错误与堆栈
Rec-->>Client : 返回 500 错误
```

图表来源
- [internal/middleware/logger.go](file://internal/middleware/logger.go#L10-L39)
- [internal/middleware/recovery.go](file://internal/middleware/recovery.go#L11-L29)
- [cmd/server/main.go](file://cmd/server/main.go#L81-L90)

章节来源
- [internal/middleware/logger.go](file://internal/middleware/logger.go#L1-L40)
- [internal/middleware/recovery.go](file://internal/middleware/recovery.go#L1-L30)
- [cmd/server/main.go](file://cmd/server/main.go#L81-L90)

## 依赖关系分析
- 外部依赖：zap 用于高性能日志记录；viper 用于配置加载；godotenv 用于 .env 支持。
- 内部依赖：配置模块提供 LogConfig；日志模块提供 Init/GetLogger；中间件依赖日志实例。

```mermaid
graph LR
subgraph "外部依赖"
Z["go.uber.org/zap"]
V["github.com/spf13/viper"]
D["github.com/joho/godotenv"]
end
subgraph "内部模块"
CFG["pkg/config/config.go"]
LOGF["pkg/logger/logger.go"]
LOGM["pkg/logger/manager.go"]
MWL["internal/middleware/logger.go"]
MWR["internal/middleware/recovery.go"]
MAIN["cmd/server/main.go"]
end
V --> CFG
D --> CFG
CFG --> LOGM
LOGM --> LOGF
MAIN --> LOGM
MAIN --> MWL
MAIN --> MWR
Z --> LOGF
Z --> MWL
Z --> MWR
```

图表来源
- [go.mod](file://go.mod#L7-L22)
- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L1-L69)
- [pkg/logger/manager.go](file://pkg/logger/manager.go#L1-L51)
- [internal/middleware/logger.go](file://internal/middleware/logger.go#L1-L40)
- [internal/middleware/recovery.go](file://internal/middleware/recovery.go#L1-L30)
- [cmd/server/main.go](file://cmd/server/main.go#L1-L124)

章节来源
- [go.mod](file://go.mod#L7-L22)
- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L1-L69)
- [pkg/logger/manager.go](file://pkg/logger/manager.go#L1-L51)
- [internal/middleware/logger.go](file://internal/middleware/logger.go#L1-L40)
- [internal/middleware/recovery.go](file://internal/middleware/recovery.go#L1-L30)
- [cmd/server/main.go](file://cmd/server/main.go#L1-L124)

## 性能考量
- 使用 zap：具备高性能与零分配特性，适合高并发场景。
- 选择合适的日志级别：生产环境默认 info，避免 debug 的额外开销。
- 输出目标选择：stdout 便于容器日志采集；文件输出需注意磁盘 IO 与轮转策略。
- 压缩与保留策略：合理设置 max_size、max_backups、max_age 与 compress，平衡磁盘占用与检索效率。

## 故障排查指南
- 未初始化日志即使用：
  - 现象：调用 GetLogger 返回错误提示“日志未初始化，请先调用 logger.Init()”。
  - 排查：确认应用入口是否在启动时调用了 logger.Init(cfg.Log)。
- 输出到文件失败：
  - 现象：初始化日志时报错，无法打开文件。
  - 排查：检查 log.output 指定路径是否存在写权限，目录是否可创建。
- panic 未记录：
  - 现象：服务崩溃但无日志记录。
  - 排查：确认已注册 Recovery 中间件并注入了日志实例。
- 日志轮转未生效：
  - 现象：日志文件持续增大。
  - 排查：当前实现未使用 max_size/max_backups/max_age/compress 进行轮转，需扩展轮转逻辑。

章节来源
- [pkg/logger/manager.go](file://pkg/logger/manager.go#L31-L37)
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L43-L60)
- [internal/middleware/recovery.go](file://internal/middleware/recovery.go#L11-L29)
- [cmd/server/main.go](file://cmd/server/main.go#L81-L90)

## 结论
- CarrotSkin 的日志系统以 zap 为核心，通过配置驱动实现灵活的日志级别、编码器与输出目标切换。
- 当前未直接启用基于大小/天数的轮转，建议在日志工厂中引入轮转库并使用 LogConfig 的 max_size、max_backups、max_age、compress 字段。
- 在生产环境中推荐使用 JSON 格式与 stdout 输出，结合集中化日志平台与告警策略，提升可观测性与可维护性。

## 附录

### 配置项一览与默认值
- log.level：默认 info
- log.format：默认 json
- log.output：默认 logs/app.log（文件输出）
- log.max_size：默认 100 MB
- log.max_backups：默认 3
- log.max_age：默认 28 天
- log.compress：默认 true

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L170-L178)

### 环境变量映射
- LOG_LEVEL → log.level
- LOG_FORMAT → log.format
- LOG_OUTPUT → log.output

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L224-L228)

### 配置示例与最佳实践
- 示例一：本地开发（控制台输出，便于阅读）
  - LOG_LEVEL=debug
  - LOG_FORMAT=console
  - LOG_OUTPUT=stdout
- 示例二：生产（结构化日志，集中化采集）
  - LOG_LEVEL=info
  - LOG_FORMAT=json
  - LOG_OUTPUT=stdout
- 示例三：传统服务器（文件输出，配合轮转）
  - LOG_LEVEL=info
  - LOG_FORMAT=json
  - LOG_OUTPUT=/var/log/carrotskin/app.log
  - max_size=100
  - max_backups=3
  - max_age=28
  - compress=true
- 最佳实践：
  - 生产环境统一使用 JSON 格式与 stdout，便于容器日志采集。
  - 严格控制日志级别，避免 debug 在生产长期开启。
  - 对关键路径增加结构化字段（如用户 ID、请求 ID），便于关联追踪。
  - 在中间件中统一记录请求上下文，确保异常时具备足够信息。
  - 如需文件轮转，建议在日志工厂中引入轮转库并使用上述配置项。

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L170-L178)
- [pkg/logger/logger.go](file://pkg/logger/logger.go#L30-L41)
- [internal/middleware/logger.go](file://internal/middleware/logger.go#L30-L37)