docs/logging-control.md

日志控制指南

本文档介绍如何控制项目的日志输出详细程度和行为。

日志系统概述

项目包含两个主要的日志系统：

1. 启动器日志 (launch_camoufox.py)
2. 主服务器日志 (server.py)

启动器日志控制

日志文件位置

• 文件路径: logs/launch_app.log
• 日志级别: 通常为 INFO
• 内容: 启动和协调过程，以及内部启动的 Camoufox 进程的输出

配置方式

启动器的日志级别在脚本内部通过 setup_launcher_logging(log_level=logging.INFO) 设置。

主服务器日志控制

日志文件位置

• 文件路径: logs/app.log
• 配置模块: logging_utils/setup.py
• 内容: FastAPI 服务器详细运行日志

环境变量控制

主服务器日志主要通过环境变量控制，这些环境变量由 launch_camoufox.py 在启动主服务器之前设置：

SERVER_LOG_LEVEL

控制主服务器日志记录器 (AIStudioProxyServer) 的级别。

• 默认值: INFO
• 可选值: DEBUG, INFO, WARNING, ERROR, CRITICAL

使用示例:

# Linux/macOS
export SERVER_LOG_LEVEL=DEBUG
python launch_camoufox.py --headless

# Windows (cmd)
set SERVER_LOG_LEVEL=DEBUG
python launch_camoufox.py --headless

# Windows (PowerShell)
$env:SERVER_LOG_LEVEL="DEBUG"
python launch_camoufox.py --headless

SERVER_REDIRECT_PRINT

控制主服务器内部的 print() 和 input() 行为。

• 'true': print() 输出重定向到日志系统，input() 可能无响应（无头模式默认）
• 'false': print() 输出到原始终端，input() 在终端等待用户输入（调试模式默认）

DEBUG_LOGS_ENABLED

控制主服务器内部特定功能的详细调试日志点是否激活。

• 默认值: false
• 可选值: true, false

使用示例:

# Linux/macOS
export DEBUG_LOGS_ENABLED=true
python launch_camoufox.py --headless

# Windows (cmd)
set DEBUG_LOGS_ENABLED=true
python launch_camoufox.py --headless

# Windows (PowerShell)
$env:DEBUG_LOGS_ENABLED="true"
python launch_camoufox.py --headless

TRACE_LOGS_ENABLED

控制更深层次的跟踪日志。

• 默认值: false
• 可选值: true, false
• 注意: 通常不需要启用，除非进行深度调试

使用示例:

# Linux/macOS
export TRACE_LOGS_ENABLED=true
python launch_camoufox.py --headless

# Windows (cmd)
set TRACE_LOGS_ENABLED=true
python launch_camoufox.py --headless

# Windows (PowerShell)
$env:TRACE_LOGS_ENABLED="true"
python launch_camoufox.py --headless

组合使用示例

启用详细调试日志

# Linux/macOS
export SERVER_LOG_LEVEL=DEBUG
export DEBUG_LOGS_ENABLED=true
python launch_camoufox.py --headless --server-port 2048

# Windows (PowerShell)
$env:SERVER_LOG_LEVEL="DEBUG"
$env:DEBUG_LOGS_ENABLED="true"
python launch_camoufox.py --headless --server-port 2048

启用最详细的跟踪日志

# Linux/macOS
export SERVER_LOG_LEVEL=DEBUG
export DEBUG_LOGS_ENABLED=true
export TRACE_LOGS_ENABLED=true
python launch_camoufox.py --headless

# Windows (PowerShell)
$env:SERVER_LOG_LEVEL="DEBUG"
$env:DEBUG_LOGS_ENABLED="true"
$env:TRACE_LOGS_ENABLED="true"
python launch_camoufox.py --headless

日志查看方式

文件日志

• logs/app.log: FastAPI 服务器详细日志
• logs/launch_app.log: 启动器日志
• 文件日志通常包含比终端或 Web UI 更详细的信息

Web UI 日志

• Web UI 右侧边栏实时显示来自主服务器的 INFO 及以上级别的日志
• 通过 WebSocket (/ws/logs) 连接获取实时日志
• 包含日志级别、时间戳和消息内容
• 提供清理日志的按钮

终端日志

• 调试模式 (--debug) 下，日志会直接输出到启动的终端
• 无头模式下，终端日志较少，主要信息在日志文件中

日志级别说明

DEBUG

• 最详细的日志信息
• 包含函数调用、变量值、执行流程等
• 用于深度调试和问题排查

INFO

• 一般信息日志
• 包含重要的操作和状态变化
• 日常运行的默认级别

WARNING

• 警告信息
• 表示可能的问题或异常情况
• 不影响正常功能但需要注意

ERROR

• 错误信息
• 表示功能异常或失败
• 需要立即关注和处理

CRITICAL

• 严重错误
• 表示系统级别的严重问题
• 可能导致服务不可用

性能考虑

日志级别对性能的影响

• DEBUG 级别: 会产生大量日志，可能影响性能，仅在调试时使用
• INFO 级别: 平衡了信息量和性能，适合日常运行
• WARNING 及以上: 日志量最少，性能影响最小

日志文件大小管理

• 日志文件会随时间增长，建议定期清理或轮转
• 可以手动删除旧的日志文件
• 考虑使用系统的日志轮转工具（如 logrotate）

故障排除

日志不显示

1. 检查环境变量是否正确设置
2. 确认日志文件路径是否可写
3. 检查 Web UI 的 WebSocket 连接是否正常

日志过多

1. 降低日志级别（如从 DEBUG 改为 INFO）
2. 禁用 DEBUG_LOGS_ENABLED 和 TRACE_LOGS_ENABLED
3. 定期清理日志文件

日志缺失重要信息

1. 提高日志级别（如从 WARNING 改为 INFO 或 DEBUG）
2. 启用 DEBUG_LOGS_ENABLED 获取更多调试信息
3. 检查日志文件而不仅仅是终端输出

最佳实践

日常运行

# 推荐的日常运行配置
export SERVER_LOG_LEVEL=INFO
python launch_camoufox.py --headless

调试问题

# 推荐的调试配置
export SERVER_LOG_LEVEL=DEBUG
export DEBUG_LOGS_ENABLED=true
python launch_camoufox.py --debug

生产环境

# 推荐的生产环境配置
export SERVER_LOG_LEVEL=WARNING
python launch_camoufox.py --headless

下一步

日志控制配置完成后，请参考：

• 故障排除指南
• 高级配置指南