math_cms/docs/pdf-worker-deployment.md

PDF Worker 分布式部署清单

架构

                         ┌─────────────┐
                         │   Redis     │
                         │  (pdf队列)   │
                         └──────┬──────┘
            ┌──────────────────┼──────────────────┐
            ▼                  ▼                  ▼
     ┌───────────┐      ┌───────────┐      ┌───────────┐
     │  主服务器   │      │ PDF机器1  │      │ PDF机器2  │
     └───────────┘      └───────────┘      └───────────┘
            │                  │                  │
            └──────────────────┼──────────────────┘
                               ▼
                        ┌─────────────┐
                        │   MySQL     │
                        └─────────────┘

---

一、PDF 机器需要的软件

• Docker
• Docker Compose
• Git

---

二、部署步骤

2.1 Clone 代码

mkdir -p /srv/www/math_cms
cd /srv/www/math_cms
git clone https://git.yunzhixue.cn/yms/math_cms.git .

2.2 拷贝 .env

从主服务器拷贝 .env 文件到 /srv/www/math_cms/.env

.env 中的 APP_URL=http://app:8000 保持不变，PDF worker 会调用本机的 app 容器

2.3 启动服务

docker-compose.pdf.yml 已在项目根目录，clone 后直接可用

cd /srv/www/math_cms
docker compose -f docker-compose.pdf.yml up -d

---

三、验证

3.1 检查容器状态

docker compose -f docker-compose.pdf.yml ps

预期输出：5 个容器都是 Up 状态

3.2 检查数据库连接

docker exec pdf_worker_1 php artisan db:show

3.3 检查 Redis 连接

docker exec pdf_worker_1 php artisan tinker --execute="dump(Redis::ping());"

3.4 检查队列消费

# 查看队列长度
docker exec pdf_worker_1 php artisan tinker --execute="echo Redis::llen('queues:pdf');"

# 查看 worker 日志
docker compose -f docker-compose.pdf.yml logs -f pdf-worker-1

3.5 端到端测试

在主服务器触发一个 PDF 生成，观察 PDF 机器日志是否有消费记录。

---

四、日常运维

# 查看状态
docker compose -f docker-compose.pdf.yml ps

# 查看日志
docker compose -f docker-compose.pdf.yml logs -f

# 重启
docker compose -f docker-compose.pdf.yml restart

# 停止
docker compose -f docker-compose.pdf.yml down --timeout 120

---

五、更新代码

cd /srv/www/math_cms
git pull origin main
docker compose -f docker-compose.pdf.yml restart

---

六、故障排查

# 查看失败任务
docker exec pdf_worker_1 php artisan queue:failed

# 重试失败任务
docker exec pdf_worker_1 php artisan queue:retry all

# 查看 Laravel 日志
tail -f storage/logs/laravel.log