docs: 重构文档结构，分离学习笔记和 MVP 架构设计

**变更概述：** - 将 MVP 架构设计文档独立到项目根目录 `mvp/` - 整理 `docs/` 为纯学习和分析文档目录 - 按类型分类：learning（学习）、analysis（分析）、reports（报告）、guides（指南） **目录结构：** ``` mvp/ # MVP 架构设计（独立） ├── README.md # 数据库设计总览 ├── architecture/ # 架构文档 │ ├── agent-architecture-mvp.md │ ├── implementation-plan.md │ └── ... └── tables/ # 数据表设计 docs/ # 学习和分析文档 ├── learning/ # 学习笔记（00-08 编号） ├── analysis/ # 分析笔记 + 重构计划 ├── reports/ # 临时报告 └── guides/ # 指南文档 ``` **详细变更：** - docs/README.md → mvp/README.md（数据库设计入口） - docs/architecture/ → mvp/architecture/（架构设计） - docs/tables/ → mvp/tables/（数据表设计） - docs/学习笔记-*.md → docs/learning/07-*.md, 08-*.md - docs/项目学习路径.md → docs/learning/00-*.md - docs/功能分析报告.md → docs/analysis/ - docs/修复报告-*.md → docs/reports/ - docs/日志配置*.md → docs/guides/ 或 docs/reports/ - docs/design/ → docs/analysis/（问题分析和重构计划）
2026-06-23 14:14:51 +08:00
parent caef477cec
commit 60be51f4a5
25 changed files with 339 additions and 606 deletions
@@ -0,0 +1,292 @@
+# 日志配置与分析指南
+
+> 配置日期：2026-05-30  
+> 配置目标：让 Claude 能够分析项目运行日志
+
+---
+
+## 📂 日志文件位置
+
+项目启动后，日志文件会自动生成在 `logs/` 目录：
+
+```
+logs/
+├── application.log              # 所有日志（滚动存储）
+├── application-error.log        # 仅 ERROR 级别日志
+├── aiops.log                    # AI Ops 专用日志
+├── chat.log                     # Chat 对话日志
+├── application-2026-05-30.0.log # 按日期滚动的历史日志
+└── ...
+```
+
+**日志保留策略**：
+- 单个文件最大 **10MB**，超过后自动滚动
+- 保留 **30 天**历史日志（application.log）
+- 保留 **15 天**历史日志（aiops.log、chat.log）
+- 所有日志总大小上限 **1GB**
+
+---
+
+## 🔧 配置详情
+
+### 方式 1：application.yml 配置（已添加）
+
+```yaml
+logging:
+  file:
+    name: logs/application.log
+  level:
+    root: INFO
+    org.example: DEBUG  # 本项目日志级别
+    org.springframework.ai: DEBUG  # Spring AI 日志
+```
+
+### 方式 2：logback-spring.xml 配置（已添加）
+
+位置：`src/main/resources/logback-spring.xml`
+
+**特性**：
+- ✅ 控制台输出（彩色高亮）
+- ✅ 文件输出（application.log）
+- ✅ 错误日志单独文件（application-error.log）
+- ✅ AI Ops 专用日志（aiops.log）
+- ✅ Chat 专用日志（chat.log）
+- ✅ 异步写入（性能优化）
+- ✅ 按日期 + 大小滚动
+- ✅ 第三方库降噪（WARN 级别）
+
+---
+
+## 🔍 如何让 Claude 分析日志
+
+### 1. 查看实时日志
+
+**场景**：分析正在运行的应用行为
+
+```bash
+# 查看最新 50 行日志
+tail -n 50 logs/application.log
+
+# 实时追踪日志（适合调试）
+tail -f logs/application.log
+
+# 只看 ERROR 日志
+tail -f logs/application-error.log
+
+# 只看 AI Ops 相关日志
+tail -f logs/aiops.log
+```
+
+**在 Claude Code 中使用**：
+```
+! tail -n 100 logs/application.log
+```
+输出会直接进入对话，Claude 可以分析。
+
+### 2. 搜索特定日志
+
+**场景**：查找特定错误或关键词
+
+```bash
+# 搜索包含 "OOM" 的日志
+grep "OOM" logs/application.log
+
+# 搜索最近 1 小时的错误日志
+grep "ERROR" logs/application.log | tail -n 100
+
+# 搜索 AI Ops 相关的调用
+grep "AiOpsService" logs/application.log
+```
+
+**Claude Code 内置工具**：
+```
+使用 Grep 工具搜索日志：
+pattern: "ERROR.*OOM"
+path: logs/application.log
+output_mode: "content"
+```
+
+### 3. 分析日志片段
+
+**场景**：重现 Bug 或分析性能问题
+
+1. 重现问题（如触发 AI Ops）
+2. 读取对应时间段的日志
+   ```bash
+   ! grep "2026-05-30 13:" logs/aiops.log
+   ```
+3. Claude 自动分析堆栈跟踪、错误信息、性能指标
+
+---
+
+## 📊 日志级别说明
+
+| 级别 | 用途 | 示例 |
+|------|------|------|
+| **DEBUG** | 详细调试信息 | `ChatService` 调用参数、`AiOpsService` 中间结果 |
+| **INFO** | 关键业务流程 | 请求处理成功、模型切换、Milvus 连接 |
+| **WARN** | 潜在问题 | 重试成功、配置缺失但有默认值 |
+| **ERROR** | 错误需要关注 | OOM、连接失败、模型调用失败 |
+
+---
+
+## 🎯 常见分析场景
+
+### 场景 1：AI Ops 分析耗时
+
+**目标**：分析哪个环节慢
+
+```bash
+! grep "AiOpsService" logs/aiops.log | tail -n 50
+```
+
+**关注日志**：
+```
+2026-05-30 13:00:00.123 [http-nio-9900-exec-1] DEBUG AiOpsService - 开始 AI Ops 分析
+2026-05-30 13:00:01.456 [http-nio-9900-exec-1] DEBUG AiOpsService - Prometheus 告警查询完成，耗时 1233ms
+2026-05-30 13:00:05.789 [http-nio-9900-exec-1] DEBUG AiOpsService - CLS 日志查询完成，耗时 4333ms
+2026-05-30 13:00:56.123 [http-nio-9900-exec-1] DEBUG AiOpsService - LLM 推理完成，耗时 50334ms
+```
+
+### 场景 2：模型调用失败
+
+**目标**：排查 DeepSeek 或 SiliconFlow 调用问题
+
+```bash
+! grep -E "ERROR.*(DeepSeek|SiliconFlow|ChatModel|EmbeddingModel)" logs/application-error.log
+```
+
+**关注日志**：
+```
+2026-05-30 13:00:00.123 [http-nio-9900-exec-1] ERROR ChatService - DeepSeek 调用失败
+org.springframework.ai.retry.RetryException: 重试 3 次后仍失败
+  at DeepSeekChatModel.call(...)
+  Caused by: java.net.SocketTimeoutException: Read timed out
+```
+
+### 场景 3：Milvus 连接问题
+
+**目标**：排查向量数据库问题
+
+```bash
+! grep -E "(MilvusClientFactory|VectorEmbeddingService)" logs/application.log | tail -n 50
+```
+
+**关注日志**：
+```
+2026-05-30 13:00:00.123 [main] INFO MilvusClientFactory - 连接 Milvus: in03-xxx.cloud.zilliz.com:443
+2026-05-30 13:00:01.456 [main] INFO MilvusClientFactory - Collection 'biz' 已存在，跳过创建
+2026-05-30 13:00:01.789 [main] INFO MilvusClientFactory - Collection 'biz' 加载到内存成功
+```
+
+### 场景 4：对话请求完整链路追踪
+
+**目标**：从 HTTP 请求 → Chat 调用 → LLM 响应的完整链路
+
+```bash
+! grep -E "(ChatController|ChatService|DeepSeek)" logs/chat.log | tail -n 100
+```
+
+---
+
+## 🛠️ Claude 分析日志的工作流
+
+### 标准流程
+
+1. **用户报告问题**  
+   例如："AI Ops 分析很慢"
+
+2. **Claude 读取相关日志**  
+   ```
+   Read logs/aiops.log (limit: 100)
+   ```
+
+3. **Claude 分析日志**  
+   - 提取时间戳 → 计算耗时
+   - 提取错误堆栈 → 定位问题代码行
+   - 提取关键参数 → 理解上下文
+
+4. **Claude 给出结论**  
+   "Prometheus 查询耗时 15s（正常 <1s），可能是 Prometheus 服务端慢查询，建议检查 PromQL 复杂度"
+
+### 高级技巧
+
+**多文件关联分析**：
+```
+Read logs/application.log (offset: 1000, limit: 50)  # 找到错误发生时间
+Read logs/aiops.log  # 查看 AI Ops 当时在做什么
+Read logs/chat.log   # 查看是否有并发请求
+```
+
+**时间范围过滤**：
+```
+Grep pattern="2026-05-30 13:0[0-5]" path="logs/application.log"  # 13:00-13:05 的日志
+```
+
+---
+
+## 📝 日志最佳实践
+
+### 开发时
+
+```java
+// ✅ 好的日志
+log.debug("AI Ops 分析开始，告警数量: {}", alerts.size());
+log.info("Prometheus 查询完成，耗时: {}ms，结果数: {}", elapsed, results.size());
+log.error("DeepSeek 调用失败，重试次数: {}", retryCount, exception);
+
+// ❌ 差的日志
+log.debug("开始");  // 没有上下文
+log.info("完成");   // 没有结果
+log.error("失败");  // 没有异常信息
+```
+
+### 关键业务流程必须记录
+
+- **AI Ops 分析**：开始时间、告警数量、各环节耗时、LLM Token 消耗
+- **Chat 对话**：请求 ID、模型名称、响应时间、是否流式
+- **RAG 检索**：查询关键词、Top-K、相似度阈值、命中文档数
+- **模型切换**：从哪个模型切换到哪个模型、原因
+
+---
+
+## 🚀 快速启动与验证
+
+### 1. 启动项目
+```bash
+mvn spring-boot:run
+```
+
+### 2. 验证日志文件生成
+```bash
+ls -lh logs/
+```
+
+应该看到：
+```
+application.log       # 立即生成
+application-error.log # 有错误时生成
+aiops.log            # 触发 AI Ops 后生成
+chat.log             # 发送对话后生成
+```
+
+### 3. 测试日志输出
+
+访问 `http://localhost:9900`，发送一条消息，然后：
+```bash
+! tail -n 20 logs/chat.log
+```
+
+应该看到 `ChatService` 的 DEBUG 日志。
+
+---
+
+## 🔗 相关文件
+
+- **配置文件**：`src/main/resources/logback-spring.xml`
+- **Spring Boot 配置**：`src/main/resources/application.yml`（logging 部分）
+- **忽略规则**：`.gitignore`（logs/ 已忽略）
+
+---
+
+> 💡 **提示**：日志文件不会提交到 Git，只在本地存在。Claude 可以通过 Read/Grep 工具分析日志，帮助你调试问题。