TermControlAgent/docs/新环境日志问题排查指南.md

# 新环境日志问题排查指南

## 问题描述
在新环境中运行应用程序时，日志输出到控制台但没有创建日志文件记录。

## 快速诊断步骤

### 1. 运行诊断脚本
```bash
python debug_logging.py
```

### 2. 手动测试日志系统
```bash
python -c "from app.utils.structured_log import get_structured_logger, LogLevel; logger = get_structured_logger('test', LogLevel.DEBUG); logger.info('测试日志'); logger.error('测试错误日志')"
```

### 3. 检查logs目录
```bash
# 检查logs目录是否存在
ls -la logs/

# 检查日志文件是否创建
ls -la logs/app.log logs/error.log
```

## 常见问题及解决方案

### 问题1: logs目录不存在
**症状**: 控制台输出日志，但logs目录不存在
**解决方案**:
```python
# 结构化日志系统会自动创建logs目录
# 如果手动创建，确保有写入权限
import os
os.makedirs("logs", exist_ok=True)
```

### 问题2: 权限不足
**症状**: 日志输出到控制台，但无法创建文件
**解决方案**:
```bash
# Linux/Mac: 检查目录权限
ls -la logs/
chmod 755 logs/

# Windows: 以管理员身份运行或检查文件夹权限
# 右键logs文件夹 -> 属性 -> 安全 -> 编辑权限
```

### 问题3: 磁盘空间不足
**症状**: 日志输出到控制台，但文件创建失败
**解决方案**:
```bash
# 检查磁盘空间
df -h  # Linux/Mac
dir    # Windows

# 清理空间或更改日志目录
```

### 问题4: 路径问题
**症状**: 工作目录不正确导致文件创建在错误位置
**解决方案**:
```python
# 确保在正确的目录下运行
import os
print("当前工作目录:", os.getcwd())
print("logs目录绝对路径:", os.path.abspath("logs"))
```

### 问题5: 编码问题
**症状**: 文件创建但内容乱码或无法写入中文
**解决方案**:
```python
# 确保使用UTF-8编码
file_handler = logging.FileHandler("logs/app.log", encoding='utf-8')
```

## 环境检查清单

### ✅ 基础环境
- [ ] Python版本 >= 3.7
- [ ] 工作目录正确
- [ ] 有足够的磁盘空间
- [ ] 有目录写入权限

### ✅ 日志系统
- [ ] 结构化日志模块可以导入
- [ ] 日志记录器可以创建
- [ ] 日志可以输出到控制台
- [ ] logs目录可以创建
- [ ] 日志文件可以写入

### ✅ 文件系统
- [ ] logs目录存在且有写入权限
- [ ] app.log文件可以创建和写入
- [ ] error.log文件可以创建和写入
- [ ] 文件编码为UTF-8

## 调试命令

### 检查环境信息
```bash
# Python版本
python --version

# 当前目录
pwd  # Linux/Mac
cd   # Windows

# 目录权限
ls -la logs/  # Linux/Mac
dir logs      # Windows
```

### 测试文件写入
```bash
# 测试基本文件写入
python -c "with open('logs/test.txt', 'w') as f: f.write('test')"

# 测试日志文件写入
python -c "import logging; logging.basicConfig(filename='logs/test.log'); logging.info('test')"
```

### 检查日志文件内容
```bash
# 查看app.log
tail -f logs/app.log

# 查看error.log
tail -f logs/error.log

# 统计行数
wc -l logs/app.log logs/error.log
```

## 日志系统配置

### 结构化日志配置
```python
from app.utils.structured_log import get_structured_logger, LogLevel

# 创建日志记录器
logger = get_structured_logger("module_name", LogLevel.INFO)

# 记录日志
logger.info("信息日志", extra_param="value")
logger.error("错误日志", error_code=500)
```

### 日志文件结构
```
logs/
├── app.log          # 正常日志（DEBUG、INFO、WARNING）
├── error.log        # 错误日志（ERROR、CRITICAL）
└── *.log           # 其他模块特定日志
```

## 故障排除流程

1. **运行诊断脚本** → 获取详细环境信息
2. **检查基础环境** → 确认Python、目录、权限
3. **测试基础日志** → 验证logging模块功能
4. **测试结构化日志** → 验证自定义日志系统
5. **检查文件权限** → 确认文件系统访问
6. **查看错误信息** → 分析具体错误原因

## 联系支持

如果按照以上步骤仍无法解决问题，请提供：

1. 诊断脚本的完整输出
2. 操作系统和Python版本信息
3. 错误信息和堆栈跟踪
4. 环境配置信息

## 预防措施

1. **定期备份日志配置**
2. **监控磁盘空间使用**
3. **设置日志轮转机制**
4. **定期检查日志文件权限**
5. **在新环境部署前运行诊断脚本**