Add client IP logging functionality: Implement `get_client_ip` to retrieve real client IP addresses, enhancing request logging in `before_request`. Update Dockerfile to use Gunicorn with configuration for accurate IP logging. Update VSCode completion for new function.

.vscode/PythonImportHelper-v2-Completion.json

@@ -233,6 +233,15 @@
         "detail": "requests",
         "documentation": {}
     },
+    {
+        "label": "multiprocessing",
+        "kind": 6,
+        "isExtraImport": true,
+        "importPath": "multiprocessing",
+        "description": "multiprocessing",
+        "detail": "multiprocessing",
+        "documentation": {}
+    },
     {
         "label": "OpenSearch",
         "importPath": "opensearchpy",
@@ -266,6 +275,15 @@
         "detail": "app",
         "documentation": {}
     },
+    {
+        "label": "get_client_ip",
+        "kind": 2,
+        "importPath": "app",
+        "description": "app",
+        "peekOfCode": "def get_client_ip():\n    \"\"\"\n    获取客户端真实 IP 地址\n    在代理服务器（如 Hugging Face Spaces）后面时，需要检查代理头部\n    \"\"\"\n    # 按优先级检查各种代理头部\n    headers_to_check = [\n        'X-Forwarded-For',\n        'X-Real-IP',\n        'CF-Connecting-IP',  # Cloudflare",
+        "detail": "app",
+        "documentation": {}
+    },
     {
         "label": "load_book_data",
         "kind": 2,
@@ -397,7 +415,7 @@
         "kind": 2,
         "importPath": "app",
         "description": "app",
-        "peekOfCode": "def before_request():\n    \"\"\"请求前处理\"\"\"\n    # 记录请求信息\n    if request.path.startswith('/api/'):\n        app.logger.info(f\"{request.method} {request.path} - {request.remote_addr}\")\n@app.after_request\ndef after_request(response):\n    \"\"\"请求后处理 - 添加缓存控制\"\"\"\n    # API 端点不缓存\n    if request.path.startswith('/api/'):",
+        "peekOfCode": "def before_request():\n    \"\"\"请求前处理\"\"\"\n    # 获取客户端真实 IP\n    client_ip = get_client_ip()\n    # 记录所有请求信息（包括静态文件）\n    user_agent = request.headers.get('User-Agent', 'Unknown')[:100]  # 限制长度\n    # API 请求记录详细信息\n    if request.path.startswith('/api/'):\n        app.logger.info(\n            f\"[{client_ip}] {request.method} {request.path} \"",
         "detail": "app",
         "documentation": {}
     },
@@ -469,7 +487,7 @@
         "kind": 5,
         "importPath": "app",
         "description": "app",
-        "peekOfCode": "OPENSEARCH_CONFIG = {\n    'host': os.environ.get('OPENSEARCH_HOST', '192.168.3.33'),\n    'port': int(os.environ.get('OPENSEARCH_PORT', 9200)),\n    'use_ssl': os.environ.get('OPENSEARCH_USE_SSL', 'False').lower() == 'true',\n}\n# 全局变量：存储学习数据\nBOOK_DATA = None\ndef load_book_data():\n    \"\"\"加载书籍数据\"\"\"\n    global BOOK_DATA",
+        "peekOfCode": "OPENSEARCH_CONFIG = {\n    'host': os.environ.get('OPENSEARCH_HOST', '192.168.3.33'),\n    'port': int(os.environ.get('OPENSEARCH_PORT', 9200)),\n    'use_ssl': os.environ.get('OPENSEARCH_USE_SSL', 'False').lower() == 'true',\n}\n# 全局变量：存储学习数据\nBOOK_DATA = None\ndef get_client_ip():\n    \"\"\"\n    获取客户端真实 IP 地址",
         "detail": "app",
         "documentation": {}
     },
@@ -478,7 +496,7 @@
         "kind": 5,
         "importPath": "app",
         "description": "app",
-        "peekOfCode": "BOOK_DATA = None\ndef load_book_data():\n    \"\"\"加载书籍数据\"\"\"\n    global BOOK_DATA\n    try:\n        with open('book_10242.json', 'r', encoding='utf-8') as f:\n            BOOK_DATA = json.load(f)\n        app.logger.info(f'✅ 成功加载书籍数据')\n        return True\n    except Exception as e:",
+        "peekOfCode": "BOOK_DATA = None\ndef get_client_ip():\n    \"\"\"\n    获取客户端真实 IP 地址\n    在代理服务器（如 Hugging Face Spaces）后面时，需要检查代理头部\n    \"\"\"\n    # 按优先级检查各种代理头部\n    headers_to_check = [\n        'X-Forwarded-For',\n        'X-Real-IP',",
         "detail": "app",
         "documentation": {}
     },
@@ -617,6 +635,186 @@
         "detail": "download_resources",
         "documentation": {}
     },
+    {
+        "label": "on_starting",
+        "kind": 2,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "def on_starting(server):\n    \"\"\"服务器启动时执行\"\"\"\n    print(\"=\" * 60)\n    print(\"🚀 Gunicorn 服务器启动\")\n    print(f\"📍 绑定地址: {bind}\")\n    print(f\"👷 工作进程数: {workers}\")\n    print(f\"🧵 每进程线程数: {threads}\")\n    print(f\"⏱️  超时时间: {timeout}s\")\n    print(\"=\" * 60)\ndef worker_int(worker):",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "worker_int",
+        "kind": 2,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "def worker_int(worker):\n    \"\"\"工作进程被中断时执行\"\"\"\n    print(f\"⚠️  工作进程 {worker.pid} 被中断\")\ndef worker_abort(worker):\n    \"\"\"工作进程异常退出时执行\"\"\"\n    print(f\"❌ 工作进程 {worker.pid} 异常退出\")\ndef post_worker_init(worker):\n    \"\"\"工作进程初始化后执行\"\"\"\n    print(f\"✅ 工作进程 {worker.pid} 初始化完成\")",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "worker_abort",
+        "kind": 2,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "def worker_abort(worker):\n    \"\"\"工作进程异常退出时执行\"\"\"\n    print(f\"❌ 工作进程 {worker.pid} 异常退出\")\ndef post_worker_init(worker):\n    \"\"\"工作进程初始化后执行\"\"\"\n    print(f\"✅ 工作进程 {worker.pid} 初始化完成\")",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "post_worker_init",
+        "kind": 2,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "def post_worker_init(worker):\n    \"\"\"工作进程初始化后执行\"\"\"\n    print(f\"✅ 工作进程 {worker.pid} 初始化完成\")",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "bind",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "bind = f\"0.0.0.0:{os.environ.get('PORT', 7860)}\"\n# 工作进程数（根据 CPU 核心数自动调整）\nworkers = int(os.environ.get('GUNICORN_WORKERS', multiprocessing.cpu_count() * 2 + 1))\n# 如果资源受限，可以手动设置较小的值\nworkers = min(workers, 4)\n# 工作进程类型\nworker_class = 'sync'\n# 每个工作进程的线程数\nthreads = 2\n# 超时时间（秒）",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "workers",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "workers = int(os.environ.get('GUNICORN_WORKERS', multiprocessing.cpu_count() * 2 + 1))\n# 如果资源受限，可以手动设置较小的值\nworkers = min(workers, 4)\n# 工作进程类型\nworker_class = 'sync'\n# 每个工作进程的线程数\nthreads = 2\n# 超时时间（秒）\ntimeout = 120\n# 保持活动连接的时间",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "workers",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "workers = min(workers, 4)\n# 工作进程类型\nworker_class = 'sync'\n# 每个工作进程的线程数\nthreads = 2\n# 超时时间（秒）\ntimeout = 120\n# 保持活动连接的时间\nkeepalive = 5\n# 最大请求数（处理后重启进程，防止内存泄漏）",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "worker_class",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "worker_class = 'sync'\n# 每个工作进程的线程数\nthreads = 2\n# 超时时间（秒）\ntimeout = 120\n# 保持活动连接的时间\nkeepalive = 5\n# 最大请求数（处理后重启进程，防止内存泄漏）\nmax_requests = 1000\nmax_requests_jitter = 50",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "threads",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "threads = 2\n# 超时时间（秒）\ntimeout = 120\n# 保持活动连接的时间\nkeepalive = 5\n# 最大请求数（处理后重启进程，防止内存泄漏）\nmax_requests = 1000\nmax_requests_jitter = 50\n# 日志配置\naccesslog = '-'  # 输出到 stdout",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "timeout",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "timeout = 120\n# 保持活动连接的时间\nkeepalive = 5\n# 最大请求数（处理后重启进程，防止内存泄漏）\nmax_requests = 1000\nmax_requests_jitter = 50\n# 日志配置\naccesslog = '-'  # 输出到 stdout\nerrorlog = '-'   # 输出到 stderr\nloglevel = 'info'",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "keepalive",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "keepalive = 5\n# 最大请求数（处理后重启进程，防止内存泄漏）\nmax_requests = 1000\nmax_requests_jitter = 50\n# 日志配置\naccesslog = '-'  # 输出到 stdout\nerrorlog = '-'   # 输出到 stderr\nloglevel = 'info'\n# 自定义访问日志格式 - 包含真实客户端 IP\n# %(h)s - 远程地址",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "max_requests",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "max_requests = 1000\nmax_requests_jitter = 50\n# 日志配置\naccesslog = '-'  # 输出到 stdout\nerrorlog = '-'   # 输出到 stderr\nloglevel = 'info'\n# 自定义访问日志格式 - 包含真实客户端 IP\n# %(h)s - 远程地址\n# %({X-Forwarded-For}i)s - X-Forwarded-For 头部（代理后面的真实 IP）\n# %(t)s - 时间",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "max_requests_jitter",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "max_requests_jitter = 50\n# 日志配置\naccesslog = '-'  # 输出到 stdout\nerrorlog = '-'   # 输出到 stderr\nloglevel = 'info'\n# 自定义访问日志格式 - 包含真实客户端 IP\n# %(h)s - 远程地址\n# %({X-Forwarded-For}i)s - X-Forwarded-For 头部（代理后面的真实 IP）\n# %(t)s - 时间\n# %(m)s - 请求方法",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "accesslog",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "accesslog = '-'  # 输出到 stdout\nerrorlog = '-'   # 输出到 stderr\nloglevel = 'info'\n# 自定义访问日志格式 - 包含真实客户端 IP\n# %(h)s - 远程地址\n# %({X-Forwarded-For}i)s - X-Forwarded-For 头部（代理后面的真实 IP）\n# %(t)s - 时间\n# %(m)s - 请求方法\n# %(U)s - URL 路径\n# %(q)s - 查询字符串",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "errorlog",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "errorlog = '-'   # 输出到 stderr\nloglevel = 'info'\n# 自定义访问日志格式 - 包含真实客户端 IP\n# %(h)s - 远程地址\n# %({X-Forwarded-For}i)s - X-Forwarded-For 头部（代理后面的真实 IP）\n# %(t)s - 时间\n# %(m)s - 请求方法\n# %(U)s - URL 路径\n# %(q)s - 查询字符串\n# %(s)s - 状态码",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "loglevel",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "loglevel = 'info'\n# 自定义访问日志格式 - 包含真实客户端 IP\n# %(h)s - 远程地址\n# %({X-Forwarded-For}i)s - X-Forwarded-For 头部（代理后面的真实 IP）\n# %(t)s - 时间\n# %(m)s - 请求方法\n# %(U)s - URL 路径\n# %(q)s - 查询字符串\n# %(s)s - 状态码\n# %(b)s - 响应大小",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "access_log_format",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "access_log_format = (\n    '[%(t)s] '\n    'Client: %({X-Forwarded-For}i)s (Remote: %(h)s) '\n    '%(m)s %(U)s%(q)s '\n    'Status: %(s)s '\n    'Size: %(b)s bytes '\n    'Time: %(D)s μs '\n    'UA: \"%({User-Agent}i)s\"'\n)\n# 进程名称前缀",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "proc_name",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "proc_name = 'english_learning_app'\n# 守护进程（通常设为 False，让容器管理进程）\ndaemon = False\n# 预加载应用（减少内存占用）\npreload_app = True\n# 在请求处理前后执行的钩子\ndef on_starting(server):\n    \"\"\"服务器启动时执行\"\"\"\n    print(\"=\" * 60)\n    print(\"🚀 Gunicorn 服务器启动\")",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "daemon",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "daemon = False\n# 预加载应用（减少内存占用）\npreload_app = True\n# 在请求处理前后执行的钩子\ndef on_starting(server):\n    \"\"\"服务器启动时执行\"\"\"\n    print(\"=\" * 60)\n    print(\"🚀 Gunicorn 服务器启动\")\n    print(f\"📍 绑定地址: {bind}\")\n    print(f\"👷 工作进程数: {workers}\")",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
+    {
+        "label": "preload_app",
+        "kind": 5,
+        "importPath": "gunicorn_config",
+        "description": "gunicorn_config",
+        "peekOfCode": "preload_app = True\n# 在请求处理前后执行的钩子\ndef on_starting(server):\n    \"\"\"服务器启动时执行\"\"\"\n    print(\"=\" * 60)\n    print(\"🚀 Gunicorn 服务器启动\")\n    print(f\"📍 绑定地址: {bind}\")\n    print(f\"👷 工作进程数: {workers}\")\n    print(f\"🧵 每进程线程数: {threads}\")\n    print(f\"⏱️  超时时间: {timeout}s\")",
+        "detail": "gunicorn_config",
+        "documentation": {}
+    },
     {
         "label": "OpenSearchClient",
         "kind": 6,
@@ -661,5 +859,23 @@
         "peekOfCode": "def main():\n    with open('book_10242.json', 'r', encoding='utf-8') as f:\n        data = json.load(f)\n    pages_data = json.loads(data['Data'])\n    # 检查第4页（索引3）和第5页（索引4）\n    for i in [3, 4]:\n        if i < len(pages_data):\n            page = pages_data[i]\n            print(f\"=== 第{page['pageNumber']}页 ===\")\n            print(f\"pageId: {page['pageId']}\")",
         "detail": "quick_check",
         "documentation": {}
+    },
+    {
+        "label": "test_ip_logging",
+        "kind": 2,
+        "importPath": "test_ip_logging",
+        "description": "test_ip_logging",
+        "peekOfCode": "def test_ip_logging():\n    \"\"\"测试 IP 地址记录\"\"\"\n    base_url = \"http://localhost:7860\"\n    print(\"=\" * 60)\n    print(\"🧪 测试客户端 IP 记录功能\")\n    print(\"=\" * 60)\n    # 测试场景\n    test_cases = [\n        {\n            \"name\": \"正常请求（无代理）\",",
+        "detail": "test_ip_logging",
+        "documentation": {}
+    },
+    {
+        "label": "show_example_logs",
+        "kind": 2,
+        "importPath": "test_ip_logging",
+        "description": "test_ip_logging",
+        "peekOfCode": "def show_example_logs():\n    \"\"\"显示日志示例\"\"\"\n    print(\"\\n\" + \"=\" * 60)\n    print(\"📝 日志输出示例\")\n    print(\"=\" * 60)\n    examples = [\n        \"[2025-10-16 18:58:23] INFO in app: [203.0.113.1] GET /api/health | UA: Mozilla/5.0 (Windows NT 10.0)\",\n        \"[2025-10-16 18:58:24] INFO in app: [198.51.100.1] POST /api/search | UA: Mozilla/5.0 (iPhone; CPU iPhone OS)\",\n        \"[2025-10-16 18:58:25] INFO in app: [192.0.2.1] GET /api/book/info | UA: curl/7.68.0\",\n    ]",
+        "detail": "test_ip_logging",
+        "documentation": {}
     }
 ]

Dockerfile

@@ -35,7 +35,8 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
     CMD curl -f http://localhost:7860/api/health || exit 1
 
 # 使用 Gunicorn 启动 Flask 应用（生产环境推荐）
-CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:7860", "--timeout", "120", "--access-logfile", "-", "--error-logfile", "-", "app:app"]
+# 使用配置文件以显示客户端真实 IP
+CMD ["gunicorn", "-c", "gunicorn_config.py", "app:app"]
 
 # 如果想使用 Flask 内置服务器（开发/测试用），使用下面这行：
 # CMD ["python3.12", "app.py"]

IP_LOGGING_GUIDE.md

@@ -0,0 +1,297 @@
+# 📋 客户端 IP 地址日志指南
+
+## ✅ 已完成的功能
+
+现在 Flask 应用已经配置为在日志中记录客户端的真实 IP 地址。
+
+## 🔍 日志格式
+
+### Flask 应用日志
+
+```
+[2025-10-16 18:58:23] INFO in app: [203.0.113.1] GET /api/health | UA: Mozilla/5.0 (Windows NT 10.0)
+                                    ^^^^^^^^^^^^
+                                    客户端真实 IP
+```
+
+**日志包含：**
+- 时间戳
+- 日志级别
+- 客户端 IP 地址
+- HTTP 方法和路径
+- User-Agent（浏览器信息）
+
+### Gunicorn 访问日志
+
+```
+[16/Oct/2025:18:58:23 +0000] Client: 203.0.113.1 (Remote: 172.17.0.1) GET /api/health Status: 200 Size: 123 bytes Time: 5234 μs UA: "Mozilla/5.0..."
+                                     ^^^^^^^^^^^^
+                                     真实客户端 IP
+```
+
+**日志包含：**
+- 时间戳
+- 客户端真实 IP（从 X-Forwarded-For 获取）
+- 远程地址（可能是代理服务器）
+- 请求信息
+- 响应状态码和大小
+- 处理时间
+- User-Agent
+
+## 🎯 IP 获取逻辑
+
+应用会按以下优先级检查 HTTP 头部来获取真实 IP：
+
+1. **X-Forwarded-For** - 最常见的代理头部
+2. **X-Real-IP** - Nginx 等使用
+3. **CF-Connecting-IP** - Cloudflare 使用
+4. **True-Client-IP** - 某些 CDN 使用
+5. **X-Client-IP** - 其他代理使用
+6. **request.remote_addr** - 直连时的 IP
+
+### 代码实现
+
+```python
+def get_client_ip():
+    """获取客户端真实 IP 地址"""
+    headers_to_check = [
+        'X-Forwarded-For',
+        'X-Real-IP',
+        'CF-Connecting-IP',
+        'True-Client-IP',
+        'X-Client-IP',
+    ]
+    
+    for header in headers_to_check:
+        ip = request.headers.get(header)
+        if ip:
+            # X-Forwarded-For 可能包含多个 IP，取第一个
+            return ip.split(',')[0].strip()
+    
+    return request.remote_addr or 'Unknown'
+```
+
+## 📁 日志文件位置
+
+### 本地开发环境
+
+- **控制台输出**: 实时显示
+- **文件日志**: `logs/app.log`（自动滚动，保留10个备份）
+
+### Hugging Face Spaces
+
+- **控制台输出**: Space 页面的 "Logs" 标签
+- **文件日志**: 不持久化（容器重启后丢失）
+
+## 🔍 查看日志
+
+### 查看实时日志（本地）
+
+```bash
+# 启动应用（控制台输出）
+python3.12 app.py
+
+# 或使用 Gunicorn
+gunicorn -c gunicorn_config.py app:app
+
+# 实时监控日志文件
+tail -f logs/app.log
+```
+
+### 查看历史日志
+
+```bash
+# 查看最近 100 条日志
+tail -n 100 logs/app.log
+
+# 搜索特定 IP 的访问记录
+grep "203.0.113.1" logs/app.log
+
+# 统计各 IP 的访问次数
+grep -oP '\[\K[0-9.]+(?=\])' logs/app.log | sort | uniq -c | sort -rn
+```
+
+### Hugging Face Spaces
+
+1. 进入你的 Space 页面
+2. 点击 "Logs" 标签
+3. 查看实时日志输出
+4. 可以搜索特定 IP 或时间段
+
+## 📊 日志分析示例
+
+### 统计最活跃的 IP 地址
+
+```bash
+# 提取所有 IP 并统计
+grep -oP '\[\K[0-9.]+(?=\])' logs/app.log | sort | uniq -c | sort -rn | head -10
+```
+
+输出示例：
+```
+    245 203.0.113.1
+    156 198.51.100.1
+     89 192.0.2.1
+     45 203.0.113.50
+```
+
+### 查看特定 IP 的访问历史
+
+```bash
+grep "\[203.0.113.1\]" logs/app.log
+```
+
+输出示例：
+```
+[2025-10-16 18:58:23] INFO in app: [203.0.113.1] GET /api/health | UA: Mozilla/5.0
+[2025-10-16 18:58:24] INFO in app: [203.0.113.1] GET /api/book/info | UA: Mozilla/5.0
+[2025-10-16 18:58:25] INFO in app: [203.0.113.1] POST /api/search | UA: Mozilla/5.0
+```
+
+### 分析访问时间分布
+
+```bash
+# 按小时统计访问量
+grep -oP '\[.*?\s+\K\d{2}' logs/app.log | sort | uniq -c
+```
+
+### 统计不同浏览器的使用情况
+
+```bash
+grep "UA:" logs/app.log | grep -oP 'UA: \K[^/]+' | sort | uniq -c | sort -rn
+```
+
+## 🧪 测试 IP 记录
+
+### 运行测试脚本
+
+```bash
+# 确保应用正在运行
+python3.12 app.py
+
+# 在另一个终端运行测试
+python3.12 test_ip_logging.py
+```
+
+### 手动测试
+
+```bash
+# 普通请求
+curl http://localhost:7860/api/health
+
+# 模拟代理请求（带 X-Forwarded-For）
+curl -H "X-Forwarded-For: 203.0.113.1" http://localhost:7860/api/health
+
+# 查看日志中记录的 IP
+tail logs/app.log
+```
+
+## 🔒 隐私和安全
+
+### IP 地址处理
+
+- IP 地址仅用于日志记录和调试
+- 不会永久存储在数据库中
+- 日志文件会自动滚动（最多保留10个备份）
+
+### 隐私保护建议
+
+如果需要遵守 GDPR 等隐私法规：
+
+1. **匿名化 IP**: 可以只记录 IP 的前缀
+   ```python
+   # 例如：203.0.113.1 -> 203.0.113.0
+   ip_parts = ip.split('.')
+   anonymized_ip = '.'.join(ip_parts[:3]) + '.0'
+   ```
+
+2. **定期清理日志**: 设置日志保留期限
+   ```python
+   # 在 gunicorn_config.py 中
+   max_log_age_days = 30  # 保留30天
+   ```
+
+3. **限制日志访问**: 确保只有授权人员可以访问日志
+
+## 📈 日志性能影响
+
+### 性能考虑
+
+- IP 获取：几乎无性能影响（只是读取 HTTP 头部）
+- 日志写入：异步处理，不影响请求响应时间
+- 文件大小：每个日志文件最大 10MB，自动滚动
+
+### 优化建议
+
+如果日志量很大：
+
+1. **减少日志级别**（只记录重要信息）
+   ```python
+   app.logger.setLevel(logging.WARNING)  # 只记录警告和错误
+   ```
+
+2. **只记录 API 请求**（跳过静态资源）
+   ```python
+   # 已在 before_request 中实现
+   if request.path.startswith('/api/'):
+       app.logger.info(...)
+   ```
+
+3. **使用日志聚合服务**（如 ELK、Datadog）
+
+## 🛠️ 自定义日志格式
+
+### 修改 Flask 日志格式
+
+编辑 `app.py` 中的 `setup_logging()` 函数：
+
+```python
+file_handler.setFormatter(logging.Formatter(
+    '[%(asctime)s] [%(levelname)s] [IP:%(client_ip)s] %(message)s'
+))
+```
+
+### 修改 Gunicorn 日志格式
+
+编辑 `gunicorn_config.py` 中的 `access_log_format`：
+
+```python
+access_log_format = (
+    '%(h)s - %({X-Forwarded-For}i)s '
+    '[%(t)s] "%(r)s" %(s)s %(b)s '
+    '"%(f)s" "%(a)s"'
+)
+```
+
+## 📚 相关文档
+
+- [Flask 日志文档](https://flask.palletsprojects.com/en/latest/logging/)
+- [Gunicorn 配置文档](https://docs.gunicorn.org/en/stable/settings.html)
+- [HTTP 头部参考](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)
+
+## 🎉 总结
+
+现在您的 Flask 应用已经可以：
+
+✅ 记录客户端真实 IP 地址  
+✅ 支持多种代理环境（Hugging Face Spaces、Cloudflare 等）  
+✅ 提供详细的访问日志  
+✅ 支持日志分析和统计  
+
+查看日志的快速命令：
+```bash
+# 实时监控
+tail -f logs/app.log
+
+# 搜索特定 IP
+grep "203.0.113.1" logs/app.log
+
+# 统计访问量
+grep -c "GET /api/" logs/app.log
+```
+
+---
+
+**最后更新**: 2025-10-16  
+**相关文件**: `app.py`, `gunicorn_config.py`, `test_ip_logging.py`
+

app.py

@@ -70,6 +70,29 @@ OPENSEARCH_CONFIG = {
 # 全局变量：存储学习数据
 BOOK_DATA = None
 
+def get_client_ip():
+    """
+    获取客户端真实 IP 地址
+    在代理服务器（如 Hugging Face Spaces）后面时，需要检查代理头部
+    """
+    # 按优先级检查各种代理头部
+    headers_to_check = [
+        'X-Forwarded-For',
+        'X-Real-IP',
+        'CF-Connecting-IP',  # Cloudflare
+        'True-Client-IP',
+        'X-Client-IP',
+    ]
+    
+    for header in headers_to_check:
+        ip = request.headers.get(header)
+        if ip:
+            # X-Forwarded-For 可能包含多个 IP，取第一个
+            return ip.split(',')[0].strip()
+    
+    # 如果没有代理头部，使用 remote_addr
+    return request.remote_addr or 'Unknown'
+
 def load_book_data():
     """加载书籍数据"""
     global BOOK_DATA
@@ -294,9 +317,25 @@ def internal_error(error):
 @app.before_request
 def before_request():
     """请求前处理"""
-    # 记录请求信息
+    # 获取客户端真实 IP
+    client_ip = get_client_ip()
+    
+    # 记录所有请求信息（包括静态文件）
+    user_agent = request.headers.get('User-Agent', 'Unknown')[:100]  # 限制长度
+    
+    # API 请求记录详细信息
     if request.path.startswith('/api/'):
-        app.logger.info(f"{request.method} {request.path} - {request.remote_addr}")
+        app.logger.info(
+            f"[{client_ip}] {request.method} {request.path} "
+            f"| UA: {user_agent}"
+        )
+    # 静态资源只记录简要信息
+    elif app.debug:
+        app.logger.debug(f"[{client_ip}] {request.method} {request.path}")
+    
+    # 将 IP 存储到 g 对象，方便在其他地方使用
+    from flask import g
+    g.client_ip = client_ip
 
 @app.after_request
 def after_request(response):
@@ -352,7 +391,7 @@ def main():
     print("=" * 60)
     print("🎉 应用已准备就绪!")
     print("=" * 60)
-    
+            
     try:
         # 启动 Flask 应用
         app.run(

gunicorn_config.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Gunicorn 配置文件
+用于在生产环境（如 Hugging Face Spaces）中运行 Flask 应用
+"""
+
+import os
+import multiprocessing
+
+# 服务器绑定
+bind = f"0.0.0.0:{os.environ.get('PORT', 7860)}"
+
+# 工作进程数（根据 CPU 核心数自动调整）
+workers = int(os.environ.get('GUNICORN_WORKERS', multiprocessing.cpu_count() * 2 + 1))
+# 如果资源受限，可以手动设置较小的值
+workers = min(workers, 4)
+
+# 工作进程类型
+worker_class = 'sync'
+
+# 每个工作进程的线程数
+threads = 2
+
+# 超时时间（秒）
+timeout = 120
+
+# 保持活动连接的时间
+keepalive = 5
+
+# 最大请求数（处理后重启进程，防止内存泄漏）
+max_requests = 1000
+max_requests_jitter = 50
+
+# 日志配置
+accesslog = '-'  # 输出到 stdout
+errorlog = '-'   # 输出到 stderr
+loglevel = 'info'
+
+# 自定义访问日志格式 - 包含真实客户端 IP
+# %(h)s - 远程地址
+# %({X-Forwarded-For}i)s - X-Forwarded-For 头部（代理后面的真实 IP）
+# %(t)s - 时间
+# %(m)s - 请求方法
+# %(U)s - URL 路径
+# %(q)s - 查询字符串
+# %(s)s - 状态码
+# %(b)s - 响应大小
+# %(D)s - 请求处理时间（微秒）
+# %({User-Agent}i)s - User-Agent
+
+access_log_format = (
+    '[%(t)s] '
+    'Client: %({X-Forwarded-For}i)s (Remote: %(h)s) '
+    '%(m)s %(U)s%(q)s '
+    'Status: %(s)s '
+    'Size: %(b)s bytes '
+    'Time: %(D)s μs '
+    'UA: "%({User-Agent}i)s"'
+)
+
+# 进程名称前缀
+proc_name = 'english_learning_app'
+
+# 守护进程（通常设为 False，让容器管理进程）
+daemon = False
+
+# 预加载应用（减少内存占用）
+preload_app = True
+
+# 在请求处理前后执行的钩子
+def on_starting(server):
+    """服务器启动时执行"""
+    print("=" * 60)
+    print("🚀 Gunicorn 服务器启动")
+    print(f"📍 绑定地址: {bind}")
+    print(f"👷 工作进程数: {workers}")
+    print(f"🧵 每进程线程数: {threads}")
+    print(f"⏱️  超时时间: {timeout}s")
+    print("=" * 60)
+
+def worker_int(worker):
+    """工作进程被中断时执行"""
+    print(f"⚠️  工作进程 {worker.pid} 被中断")
+
+def worker_abort(worker):
+    """工作进程异常退出时执行"""
+    print(f"❌ 工作进程 {worker.pid} 异常退出")
+
+def post_worker_init(worker):
+    """工作进程初始化后执行"""
+    print(f"✅ 工作进程 {worker.pid} 初始化完成")
+

test_ip_logging.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+测试 IP 地址获取和日志记录功能
+"""
+
+import sys
+import requests
+import json
+
+def test_ip_logging():
+    """测试 IP 地址记录"""
+    base_url = "http://localhost:7860"
+    
+    print("=" * 60)
+    print("🧪 测试客户端 IP 记录功能")
+    print("=" * 60)
+    
+    # 测试场景
+    test_cases = [
+        {
+            "name": "正常请求（无代理）",
+            "headers": {},
+        },
+        {
+            "name": "通过代理请求（X-Forwarded-For）",
+            "headers": {
+                "X-Forwarded-For": "203.0.113.1, 198.51.100.1"
+            },
+        },
+        {
+            "name": "通过代理请求（X-Real-IP）",
+            "headers": {
+                "X-Real-IP": "192.0.2.1"
+            },
+        },
+        {
+            "name": "Cloudflare 代理",
+            "headers": {
+                "CF-Connecting-IP": "198.51.100.50"
+            },
+        },
+    ]
+    
+    for i, test_case in enumerate(test_cases, 1):
+        print(f"\n{i}. {test_case['name']}")
+        print("-" * 40)
+        
+        try:
+            response = requests.get(
+                f"{base_url}/api/health",
+                headers=test_case['headers'],
+                timeout=5
+            )
+            
+            if response.status_code == 200:
+                data = response.json()
+                print(f"  ✅ 状态: {response.status_code}")
+                print(f"  📝 响应: {json.dumps(data, ensure_ascii=False, indent=2)}")
+                print(f"  💡 提示: 查看服务器日志以确认记录的 IP 地址")
+            else:
+                print(f"  ⚠️  状态码: {response.status_code}")
+                
+        except requests.exceptions.ConnectionError:
+            print(f"  ❌ 连接失败 - 请确保应用正在运行")
+            print(f"  💡 启动命令: python3.12 app.py")
+            break
+        except Exception as e:
+            print(f"  ❌ 错误: {e}")
+    
+    print("\n" + "=" * 60)
+    print("📊 测试完成")
+    print("\n💡 查看日志:")
+    print("  - 控制台输出")
+    print("  - logs/app.log 文件")
+    print("\n日志格式示例:")
+    print("  [203.0.113.1] GET /api/health | UA: python-requests/2.31.0")
+    print("=" * 60)
+
+def show_example_logs():
+    """显示日志示例"""
+    print("\n" + "=" * 60)
+    print("📝 日志输出示例")
+    print("=" * 60)
+    
+    examples = [
+        "[2025-10-16 18:58:23] INFO in app: [203.0.113.1] GET /api/health | UA: Mozilla/5.0 (Windows NT 10.0)",
+        "[2025-10-16 18:58:24] INFO in app: [198.51.100.1] POST /api/search | UA: Mozilla/5.0 (iPhone; CPU iPhone OS)",
+        "[2025-10-16 18:58:25] INFO in app: [192.0.2.1] GET /api/book/info | UA: curl/7.68.0",
+    ]
+    
+    print("\nFlask 应用日志:")
+    for example in examples:
+        print(f"  {example}")
+    
+    print("\nGunicorn 访问日志:")
+    print("  [16/Oct/2025:18:58:23 +0000] Client: 203.0.113.1 (Remote: 172.17.0.1)")
+    print("  GET /api/health Status: 200 Size: 123 bytes Time: 5234 μs")
+    print("=" * 60)
+
+if __name__ == '__main__':
+    # 显示日志示例
+    show_example_logs()
+    
+    # 询问是否进行实际测试
+    print("\n是否进行实际测试? (需要应用正在运行)")
+    response = input("输入 'y' 继续，其他键跳过: ")
+    
+    if response.lower() == 'y':
+        test_ip_logging()
+    else:
+        print("\n跳过实际测试")
+        print("\n💡 启动应用后可以运行:")
+        print("  python3.12 test_ip_logging.py")
+