docs: 更新文档

docs/ops-commands.md

@@ -28,6 +28,37 @@ docker exec math_cms_app ps aux | grep -E "nginx|php-fpm"
 
 ## 2. 日志查看
 
+### 快速调试命令
+
+```bash
+# 1. 查看 Laravel 应用日志（最常用）
+docker exec math_cms_app tail -100 storage/logs/laravel.log
+
+# 实时查看
+docker exec math_cms_app tail -f storage/logs/laravel.log
+
+# 2. 查看容器日志（Nginx + PHP-FPM）
+docker logs math_cms_app --tail 100
+
+# 实时查看
+docker logs -f math_cms_app
+
+# 3. 查看 PHP 错误日志
+docker exec math_cms_app tail -100 /var/log/php-fpm/error.log
+
+# 4. 查看 Nginx 错误日志
+docker exec math_cms_app tail -100 /var/log/nginx/error.log
+
+# 5. 筛选特定关键词
+docker exec math_cms_app tail -500 storage/logs/laravel.log | grep -i "error\|exception\|fail"
+
+# 6. 查看今天的日志（如果按日期分割）
+docker exec math_cms_app cat storage/logs/laravel-$(date +%Y-%m-%d).log | tail -100
+
+# 7. 快速排查智能组卷问题
+docker exec math_cms_app tail -200 storage/logs/laravel.log | grep -i "智能\|intelligent\|assemble\|error"
+```
+
 ### Laravel 应用日志
 
 ```bash
@@ -86,25 +117,118 @@ docker exec math_cms_app sh -c "echo '=== Laravel Errors ===' && grep '\.ERROR'
 
 ## 3. 代码更新部署
 
+### 部署模式说明
+
+系统支持两种部署模式：
+
+| 模式 | 说明 | 适用场景 | 耗时 |
+|------|------|---------|------|
+| **Quick** | 代码卷映射，无需重新构建 | 日常代码更新 | 10-30秒 |
+| **Build** | 完整构建 Docker 镜像 | 首次部署、依赖更新、Dockerfile 变更 | 5-10分钟 |
+
+### 服务器与配置文件对应关系
+
+| 服务器类型 | 基础文件 | Mount 文件 |
+|-----------|---------|-----------|
+| 主服务器 | `docker-compose.yml` | `docker-compose.mount.yml` |
+| PDF 服务器 | `docker-compose.pdf.yml` | `docker-compose.pdf.mount.yml` |
+| API 服务器 | `docker-compose.api.yml` | `docker-compose.api.mount.yml` |
+
+### Ansible 自动部署（推荐）
+
 ```bash
-# 1. 拉取最新代码
-git pull
+cd ansible
+
+# 快速部署（默认）
+./deploy.sh              # 所有服务器
+./deploy.sh quick pdf    # 只部署 PDF 服务器
+./deploy.sh quick api    # 只部署 API 服务器
+./deploy.sh quick main   # 只部署主服务器
+
+# 完整构建
+./deploy.sh build        # 所有服务器
+./deploy.sh build pdf    # 只部署 PDF 服务器
+./deploy.sh build api    # 只部署 API 服务器
+./deploy.sh build main   # 只部署主服务器
+
+# 其他命令
+./deploy.sh test         # 测试服务器连接
+./deploy.sh status       # 查看服务器状态
+./deploy.sh help         # 查看帮助
+```
 
-# 2. 重新构建并启动
-docker compose down
-docker compose build --no-cache
-docker compose up -d
+### 手动部署 - 主服务器
 
-# 或一键操作（增量构建）
-docker compose up -d --build
+```bash
+# Build 模式（完整构建）
+docker compose -f docker-compose.yml build
+docker compose -f docker-compose.yml up -d --force-recreate
 
-# 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
+# Quick 模式（代码卷映射）
+docker compose -f docker-compose.yml -f docker-compose.mount.yml up -d --force-recreate
 ```
 
+### 手动部署 - PDF 服务器
+
+```bash
+# Build 模式（完整构建）
+docker compose -f docker-compose.pdf.yml build
+docker compose -f docker-compose.pdf.yml up -d --force-recreate
+
+# Quick 模式（代码卷映射）
+docker compose -f docker-compose.pdf.yml -f docker-compose.pdf.mount.yml up -d --force-recreate
+```
+
+### 手动部署 - API 服务器
+
+```bash
+# Build 模式（完整构建）
+docker compose -f docker-compose.api.yml build
+docker compose -f docker-compose.api.yml up -d --force-recreate
+
+# Quick 模式（代码卷映射）
+docker compose -f docker-compose.api.yml -f docker-compose.api.mount.yml up -d --force-recreate
+```
+
+### 首次部署流程
+
+首次部署必须先 build 创建镜像，之后才能使用 quick 模式：
+
+```bash
+# 1. 拉取代码
+git clone <repo> /srv/www/math_cms
+cd /srv/www/math_cms
+
+# 2. 配置环境
+cp .env.example .env
+# 编辑 .env 配置数据库等
+
+# 3. 构建镜像（以 API 服务器为例）
+docker compose -f docker-compose.api.yml build
+
+# 4. 启动容器（使用 quick 模式）
+docker compose -f docker-compose.api.yml -f docker-compose.api.mount.yml up -d
+```
+
+### 日常更新流程（Quick 模式）
+
+```bash
+# 1. 拉取最新代码
+git fetch origin && git reset --hard origin/main
+
+# 2. 重启容器（以 API 服务器为例）
+docker compose -f docker-compose.api.yml -f docker-compose.api.mount.yml up -d --force-recreate
+
+# 3. 清除缓存
+docker exec math_cms_app php artisan optimize:clear
+```
+
+### 注意事项
+
+1. **Quick 模式前提**：必须先执行过 `build`，镜像里有 vendor、node_modules、public/build
+2. **Queue Worker**：是常驻进程，代码更新后必须重启容器才能生效
+3. **Mount 文件作用**：覆盖 volumes 配置，将宿主机代码映射到容器，但排除 vendor 等目录（用镜像里的）
+
 ## 4. 缓存清理
 
 ```bash