fix: 增加调试日志和常用命令

app/Http/Controllers/Api/ExamAnswerAnalysisController.php

@@ -53,6 +53,12 @@ class ExamAnswerAnalysisController extends Controller
             ]);
 
             if ($validator->fails()) {
+                Log::warning('exam-answer-analysis 验证失败', [
+                    'errors' => $validator->errors()->toArray(),
+                    'paper_id' => $request->input('paper_id'),
+                    'student_id' => $request->input('student_id'),
+                    'questions_count' => count($request->input('questions', [])),
+                ]);
                 return response()->json([
                     'success' => false,
                     'error' => 'Validation failed',

docs/ops-commands.md

@@ -21,24 +21,67 @@ docker compose restart pdf-worker
 
 # 查看运行状态
 docker compose ps
+
+# 查看进程状态（nginx + php-fpm）
+docker exec math_cms_app ps aux | grep -E "nginx|php-fpm"
 ```
 
 ## 2. 日志查看
 
+### Laravel 应用日志
+
+```bash
+# 查看最近日志
+docker exec math_cms_app tail -100 storage/logs/laravel.log
+
+# 只看 ERROR 级别
+docker exec math_cms_app grep "\.ERROR" storage/logs/laravel.log | tail -50
+
+# 实时监控日志
+docker exec math_cms_app tail -f storage/logs/laravel.log
+
+# 清空日志
+docker exec math_cms_app truncate -s 0 storage/logs/laravel.log
+
+# 组合：先显示最近 200 行，然后实时监控
+docker exec math_cms_app tail -200f storage/logs/laravel.log
+```
+
+### Nginx 日志
+
 ```bash
-# 查看所有日志（实时）
-docker compose logs -f
+# 访问日志（看请求状态码）
+docker exec math_cms_app tail -100 /var/log/nginx/access.log
 
-# 查看指定服务日志
-docker compose logs -f app          # Web 服务
-docker compose logs -f queue        # 队列服务
-docker compose logs -f pdf-worker   # PDF 生成服务
+# 错误日志
+docker exec math_cms_app tail -50 /var/log/nginx/error.log
+
+# 只看 5xx 错误的请求
+docker exec math_cms_app grep '" 5[0-9][0-9] ' /var/log/nginx/access.log | tail -30
+```
 
-# 查看最近 100 行日志
-docker compose logs --tail=100 app
+### PHP-FPM 日志
 
-# 查看 Laravel 日志
-tail -f storage/logs/laravel.log
+```bash
+# 慢请求日志（超过5秒的请求）
+docker exec math_cms_app cat /var/log/php-fpm-slow.log 2>/dev/null || echo "暂无慢请求"
+```
+
+### 队列日志
+
+```bash
+# 查看队列 Worker 日志
+docker logs math_cms_queue --tail=50
+docker logs math_cms_pdf --tail=50
+
+# 实时监控 PDF 队列
+docker logs -f math_cms_pdf
+```
+
+### 一键查看错误
+
+```bash
+docker exec math_cms_app sh -c "echo '=== Laravel Errors ===' && grep '\.ERROR' storage/logs/laravel.log | tail -10 && echo '=== Nginx 5xx ===' && grep '\" 5[0-9][0-9] ' /var/log/nginx/access.log | tail -5"
 ```
 
 ## 3. 代码更新部署
@@ -52,8 +95,14 @@ docker compose down
 docker compose build --no-cache
 docker compose up -d
 
-# 或一键操作
+# 或一键操作（增量构建）
 docker compose up -d --build
+
+# 3. 热更新（不重新构建，只复制代码）
+docker cp app/ math_cms_app:/app/
+docker cp app/ math_cms_queue:/app/
+docker cp app/ math_cms_pdf:/app/
+docker compose restart app queue pdf-worker
 ```
 
 ## 4. 缓存清理
@@ -66,14 +115,14 @@ docker exec math_cms_app php artisan optimize:clear
 docker compose restart queue pdf-worker
 
 # 清理临时文件
-rm -rf storage/app/temp/*
+docker exec math_cms_app rm -rf storage/app/temp/*
 ```
 
 ## 5. 问题排查
 
 ```bash
 # 查看容器资源使用
-docker stats
+docker stats --no-stream
 
 # 进入容器调试
 docker exec -it math_cms_app sh
@@ -82,13 +131,19 @@ docker exec -it math_cms_app sh
 docker exec math_cms_app php artisan db:show
 
 # 测试 Redis 连接
-docker exec math_cms_app php artisan tinker --execute="Redis::ping()"
+docker exec math_cms_app php artisan tinker --execute="dump(app('redis')->ping());"
 
 # 测试 Chrome（PDF 生成）
-docker exec math_cms_app chromium-browser --version
+docker exec math_cms_pdf chromium-browser --version
 
-# 查看队列状态
-docker exec math_cms_app php artisan queue:monitor
+# 查看失败的队列任务
+docker exec math_cms_app php artisan queue:failed
+
+# 重试失败的任务
+docker exec math_cms_app php artisan queue:retry all
+
+# 查看失败任务详情
+docker exec math_cms_app php artisan tinker --execute="\$job = DB::table('failed_jobs')->latest()->first(); echo \$job->exception ?? 'no failed jobs';"
 ```
 
 ## 6. 紧急处理
@@ -106,6 +161,9 @@ docker exec math_cms_pdf rm -rf /tmp/exam_pdf_*
 
 # 重启 PDF 服务
 docker compose restart pdf-worker
+
+# 修复 storage 权限问题
+docker exec math_cms_app chmod -R 777 /app/storage
 ```
 
 ## 7. 健康检查
@@ -119,6 +177,14 @@ docker compose ps
 
 # 检查容器健康状态
 docker inspect --format='{{.State.Health.Status}}' math_cms_app
+docker inspect --format='{{.State.Health.Status}}' math_cms_queue
+docker inspect --format='{{.State.Health.Status}}' math_cms_pdf
+
+# 检查 PHP-FPM 进程数
+docker exec math_cms_app ps aux | grep php-fpm | wc -l
+
+# 检查 Nginx Worker 数
+docker exec math_cms_app ps aux | grep nginx
 ```
 
 ## 8. 备份与恢复
@@ -156,45 +222,34 @@ docker update --cpus=1 --memory=1g math_cms_pdf
 ## 服务架构
 
 ```
-┌─────────────────────────────────────────────────┐
-│              Docker Compose                     │
-│  ┌─────────────┐ ┌───────────┐ ┌─────────────┐  │
-│  │ math_cms_app│ │math_cms_  │ │math_cms_pdf │  │
-│  │   (Web)     │ │  queue    │ │(PDF Worker) │  │
-│  │   :5019     │ │           │ │ CPU:2 Mem:2G│  │
-│  └─────────────┘ └───────────┘ └─────────────┘  │
-└─────────────────────────────────────────────────┘
-         │               │               │
-         └───────────────┴───────────────┘
-                         │
-          ┌──────────────┴──────────────┐
-          ▼                             ▼
-    ┌──────────┐                  ┌──────────┐
-    │  Redis   │                  │  MySQL   │
-    │ (阿里云)  │                  │ (阿里云)  │
-    └──────────┘                  └──────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│                        Docker Compose                            │
+│  ┌──────────────────┐ ┌───────────────┐ ┌──────────────────────┐ │
+│  │  math_cms_app    │ │ math_cms_queue│ │   math_cms_pdf       │ │
+│  │  (Nginx+PHP-FPM) │ │ (Queue Worker)│ │   (PDF Worker)       │ │
+│  │  :5019 → :8000   │ │ default 队列   │ │   pdf 队列            │
+│  │  并发: 30 worker │ │ CPU:1 Mem:512M│ │   CPU:2 Mem:2G       │ │
+│  └──────────────────┘ └───────────────┘ └──────────────────────┘ │
+└──────────────────────────────────────────────────────────────────┘
+         │                     │                     │
+         └─────────────────────┴─────────────────────┘
+                               │
+            ┌──────────────────┴──────────────────┐
+            ▼                                     ▼
+      ┌──────────┐                          ┌──────────┐
+      │  Redis   │                          │  MySQL   │
+      │ (阿里云)  │                          │ (阿里云)  │
+      └──────────┘                          └──────────┘
 ```
 
-## 联系方式
+### 队列说明
 
-如有问题请联系开发团队。
+| 队列 | 容器 | 处理任务 |
+|------|------|---------|
+| default | math_cms_queue | AI批改、知识点匹配、题目导入等 |
+| pdf | math_cms_pdf | PDF生成（需要Chrome） |
 
-### 常用日志查看
-
-```
-   docker exec math_cms_app grep -A 10 "exam-answer-analysis\|ERROR" storage/logs/laravel.log | tail -50
-
-  tail -200 storage/logs/laravel.log
-
-  # 清空日志
-  docker exec math_cms_app truncate -s 0 storage/logs/laravel.log
-
-  # 实时监控（自动刷新）
-  docker exec math_cms_app tail -f storage/logs/laravel.log
-
-  # 组合：先显示最近 200 行，然后实时监控
-  docker exec math_cms_app tail -200f storage/logs/laravel.log
-```
+---
 
 ## 11. PDF 生成问题排查
 
@@ -204,15 +259,15 @@ docker update --cpus=1 --memory=1g math_cms_pdf
 - 原因：HTML模板中引用了CDN资源（KaTeX CSS/JS），容器内网络请求慢
 - 解决：代码已优化，使用服务端 Node.js KaTeX 预渲染公式
 
-**问题4: 公式显示为原始 LaTeX 文本**
+**问题2: 公式显示为原始 LaTeX 文本**
 - 原因：Chrome headless 的 --print-to-pdf 不等待 JavaScript 执行
 - 解决：使用 Node.js KaTeX 在服务端预渲染公式，生成静态 HTML
 
-**问题2: dbus 连接错误**
+**问题3: dbus 连接错误**
 - 表现：日志中出现 `Failed to connect to the bus` 错误
 - 解决：docker-entrypoint.sh 已配置自动启动 dbus-daemon
 
-**问题3: Chrome 进程积累导致 CPU 满载**
+**问题4: Chrome 进程积累导致 CPU 满载**
 - 原因：PDF生成任务积压，Chrome进程未正常退出
 - 解决：
   ```bash
@@ -226,6 +281,17 @@ docker update --cpus=1 --memory=1g math_cms_pdf
   docker compose restart pdf-worker
   ```
 
+**问题5: 日志为空（权限问题）**
+- 原因：storage 目录权限不正确，php-fpm 无法写入
+- 解决：
+  ```bash
+  docker exec math_cms_app chmod -R 777 /app/storage
+  ```
+
+**问题6: GenerateAnalysisPdfJob 失败**
+- 原因：Job 未指定 pdf 队列，被 default 队列处理（无 Chrome）
+- 解决：代码已修复，Job 使用 `$this->onQueue('pdf')`
+
 ### PDF 生成调试
 
 ```bash
@@ -236,7 +302,7 @@ docker exec math_cms_app grep -i "ExamPdfExportService" storage/logs/laravel.log
 docker exec math_cms_app grep -i "KatexRenderer\|LaTeX.*预渲染" storage/logs/laravel.log | tail -20
 
 # 测试Node.js KaTeX是否正常工作
-docker exec math_cms_app echo '$x^2 + y^2 = z^2$' | node /app/scripts/katex-render.js
+docker exec math_cms_app sh -c "echo '\$x^2 + y^2 = z^2\$' | node /app/scripts/katex-render.mjs"
 
 # 测试Chrome是否正常工作
 docker exec math_cms_pdf chromium-browser --headless --disable-gpu --no-sandbox --print-to-pdf=/tmp/test.pdf https://www.baidu.com
@@ -249,4 +315,31 @@ docker exec math_cms_app node --version
 
 # 检查dbus状态
 docker exec math_cms_pdf pgrep -a dbus
+
+# 查看 PDF 队列处理情况
+docker logs math_cms_pdf --tail=30
+```
+
+---
+
+## 12. 并发问题排查
+
+### 试卷保存失败（题目数量不匹配）
+
+错误信息：`题目插入数量不匹配：预期 20，实际 40`
+
+**原因：** 并发请求导致 Paper ID 碰撞，两个请求插入到同一个 paper_id
+
+**解决：** 已优化 PaperIdGenerator，增加进程ID区分不同 PHP-FPM Worker
+
+**排查命令：**
+```bash
+# 查看相关错误
+docker exec math_cms_app grep "题目插入数量不匹配" storage/logs/laravel.log | tail -10
 ```
+
+---
+
+## 联系方式
+
+如有问题请联系开发团队。