mirror of
https://github.com/huge-dream/django-vue3-admin.git
synced 2026-09-26 14:23:46 +00:00
lewis_yan
7a8b4ff7d5
Document known issues with Celery on Windows PowerShell (billiard multiprocessing incompatibility) and recommend using Git Bash instead.
296 lines
7.1 KiB
Markdown
296 lines
7.1 KiB
Markdown
# 脚本文档
|
||
|
||
PIS 项目跨平台服务管理脚本。
|
||
|
||
## 概述
|
||
|
||
| 脚本 | Windows (PowerShell) | Unix/Linux/macOS (Bash) |
|
||
|------|---------------------|------------------------|
|
||
| 启动后端 | `start-backend.ps1` | `start-backend.sh` |
|
||
| 启动前端 | `start-frontend.ps1` | `start-frontend.sh` |
|
||
| 启动 Celery | `start-celery.ps1` | `start-celery.sh` |
|
||
| 停止所有 | `stop-all.ps1` | `stop-all.sh` |
|
||
| 停止 Celery | `stop-celery.ps1` | `stop-celery.sh` |
|
||
| 查看日志 | `view-logs.ps1` | `view-logs.sh` |
|
||
| 检查状态 | `check-status.ps1` | `check-status.sh` |
|
||
|
||
## 快速开始
|
||
|
||
### Windows (PowerShell)
|
||
|
||
```powershell
|
||
# 启动所有服务
|
||
.\make.ps1 dev
|
||
|
||
# 停止所有服务
|
||
.\make.ps1 stop
|
||
|
||
# 查看日志
|
||
.\make.ps1 logs
|
||
|
||
# 检查状态
|
||
.\make.ps1 status
|
||
```
|
||
|
||
### Unix/Linux/macOS (Bash)
|
||
|
||
```bash
|
||
# 启动所有服务
|
||
make dev
|
||
|
||
# 停止所有服务
|
||
make stop
|
||
|
||
# 查看日志
|
||
make logs
|
||
|
||
# 检查状态
|
||
make status
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### make.ps1 命令 (Windows PowerShell)
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `.\make.ps1 help` | 显示所有可用命令 |
|
||
| `.\make.ps1 dev` | 启动开发环境（前端 + 后端 + Celery） |
|
||
| `.\make.ps1 dev-backend` | 仅启动后端 |
|
||
| `.\make.ps1 dev-frontend` | 仅启动前端 |
|
||
| `.\make.ps1 dev-celery` | 仅启动 Celery |
|
||
| `.\make.ps1 stop` | 停止所有服务 |
|
||
| `.\make.ps1 restart` | 重启所有服务 |
|
||
| `.\make.ps1 restart-celery` | 仅重启 Celery |
|
||
| `.\make.ps1 logs` | 查看所有日志 |
|
||
| `.\make.ps1 logs-backend` | 查看后端日志 |
|
||
| `.\make.ps1 logs-frontend` | 查看前端日志 |
|
||
| `.\make.ps1 logs-celery` | 查看 Celery 日志 |
|
||
| `.\make.ps1 status` | 检查服务状态 |
|
||
| `.\make.ps1 clean-logs` | 清理日志文件 |
|
||
| `.\make.ps1 clean-pids` | 清理 PID 文件 |
|
||
|
||
### make 命令 (Unix/Linux/macOS Bash)
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `make help` | 显示所有可用命令 |
|
||
| `make dev` | 启动开发环境（前端 + 后端 + Celery） |
|
||
| `make dev-backend` | 仅启动后端 |
|
||
| `make dev-frontend` | 仅启动前端 |
|
||
| `make dev-celery` | 仅启动 Celery |
|
||
| `make stop` | 停止所有服务 |
|
||
| `make restart` | 重启所有服务 |
|
||
| `make restart-celery` | 仅重启 Celery |
|
||
| `make logs` | 查看所有日志 |
|
||
| `make logs-backend` | 查看后端日志 |
|
||
| `make logs-frontend` | 查看前端日志 |
|
||
| `make logs-celery` | 查看 Celery 日志 |
|
||
| `make status` | 检查服务状态 |
|
||
| `make clean-logs` | 清理日志文件 |
|
||
| `make clean-pids` | 清理 PID 文件 |
|
||
|
||
## 直接调用脚本
|
||
|
||
### Windows PowerShell
|
||
|
||
```powershell
|
||
# 启动后端
|
||
.\scripts\start-backend.ps1 [dev|prod]
|
||
|
||
# 启动前端
|
||
.\scripts\start-frontend.ps1 [dev|prod]
|
||
|
||
# 启动 Celery
|
||
.\scripts\start-celery.ps1 [dev|prod]
|
||
|
||
# 停止所有服务
|
||
.\scripts\stop-all.ps1
|
||
|
||
# 仅停止 Celery
|
||
.\scripts\stop-celery.ps1
|
||
|
||
# 查看日志
|
||
.\scripts\view-logs.ps1 [backend|frontend|celery|all]
|
||
|
||
# 检查状态
|
||
.\scripts\check-status.ps1
|
||
```
|
||
|
||
### Unix/Linux/macOS Bash
|
||
|
||
```bash
|
||
# 启动后端
|
||
./scripts/start-backend.sh [dev|prod]
|
||
|
||
# 启动前端
|
||
./scripts/start-frontend.sh [dev|prod]
|
||
|
||
# 启动 Celery
|
||
./scripts/start-celery.sh [dev|prod]
|
||
|
||
# 停止所有服务
|
||
./scripts/stop-all.sh
|
||
|
||
# 仅停止 Celery
|
||
./scripts/stop-celery.sh
|
||
|
||
# 查看日志
|
||
./scripts/view-logs.sh [backend|frontend|celery|all]
|
||
|
||
# 检查状态
|
||
./scripts/check-status.sh
|
||
```
|
||
|
||
## 环境参数
|
||
|
||
- `dev`（默认）：开发模式，带热重载
|
||
- `prod`：生产模式，使用优化构建
|
||
|
||
### Windows PowerShell
|
||
```powershell
|
||
.\make.ps1 dev -ENV prod
|
||
```
|
||
|
||
### Unix/Linux/macOS
|
||
```bash
|
||
ENV=prod make dev
|
||
```
|
||
|
||
## 端口
|
||
|
||
| 服务 | 端口 |
|
||
|------|------|
|
||
| 后端 (Django) | 8000 |
|
||
| 前端 (Vue) | 8080 |
|
||
|
||
## 日志文件
|
||
|
||
日志存储在 `backend/logs/`：
|
||
|
||
- `backend.log` - 后端应用日志
|
||
- `frontend.log` - 前端应用日志
|
||
- `celery_worker.log` - Celery Worker 日志
|
||
- `celery_beat.log` - Celery Beat 调度器日志
|
||
|
||
## PID 文件
|
||
|
||
PID 文件存储在 `.pids/`：
|
||
|
||
- `backend.pid`
|
||
- `frontend.pid`
|
||
- `celery_worker.pid`
|
||
- `celery_beat.pid`
|
||
|
||
## 跨平台兼容性
|
||
|
||
### Windows PowerShell
|
||
- 支持 Windows PowerShell 5.1 及 PowerShell 7+
|
||
- 使用 `System.Net.Sockets.TcpClient` 检查端口
|
||
- 使用 WMI 查询检测进程（兼容 PS 5.1 和 PS 7+）
|
||
- 所有输出使用英文（避免编码问题）
|
||
|
||
### Unix/Linux/macOS
|
||
- 需要 Bash 4.0+
|
||
- 使用 `nc`（netcat）检查端口（如果可用）
|
||
- 使用 `pgrep` 和 `pkill` 管理进程
|
||
- 输出使用中文
|
||
|
||
### Windows PowerShell Celery 已知问题
|
||
|
||
**Celery 在 Windows PowerShell 上有已知的兼容性问题。**
|
||
|
||
问题原因：PowerShell 的 `Start-Process` 与 Celery 的多进程池（billiard）不兼容，导致以下错误：
|
||
- `PermissionError: [WinError 5] 拒绝访问`
|
||
- `OSError: [WinError 6] 句柄无效`
|
||
|
||
**推荐解决方案：使用 Git Bash**
|
||
|
||
在 Windows 上，推荐使用 Git Bash 运行 Celery 脚本：
|
||
|
||
```bash
|
||
# 启动 Celery (推荐)
|
||
bash scripts/start-celery.sh
|
||
|
||
# 停止 Celery
|
||
bash scripts/stop-celery.sh
|
||
```
|
||
|
||
Git Bash 使用 `nohup` 和 `&` 后台运行，与 Celery 的多进程机制完全兼容。
|
||
|
||
**如需使用 PowerShell：**
|
||
|
||
可以尝试使用 `--pool solo` 参数（单进程模式）：
|
||
|
||
```powershell
|
||
.\scripts\start-celery.ps1
|
||
```
|
||
|
||
但这可能会影响 Celery 的性能和稳定性。
|
||
|
||
## 依赖要求
|
||
|
||
### 后端
|
||
- Python 3.10+
|
||
- Django 4.2.14
|
||
- uvicorn（开发）或 gunicorn（生产）
|
||
- Celery + Redis broker
|
||
|
||
### 前端
|
||
- Node.js 18+
|
||
- Yarn 或 npm
|
||
|
||
### Celery
|
||
- Redis 服务运行中
|
||
- django-celery-beat
|
||
|
||
## 故障排除
|
||
|
||
### 后端无法启动
|
||
1. 检查端口 8000 是否被占用
|
||
2. 检查 Python 依赖是否安装
|
||
3. 检查 Django 配置：确保 `backend/conf/env.py` 已配置
|
||
|
||
### 前端无法启动
|
||
1. 检查 Node.js 是否安装
|
||
2. 安装依赖：`cd web && yarn install`
|
||
3. 检查端口 8080 是否被占用
|
||
|
||
### Celery 无法启动
|
||
1. 检查 Redis 是否运行
|
||
2. 执行数据库迁移：`python manage.py migrate`
|
||
3. 查看 Celery 日志
|
||
4. **Windows 用户**：如果使用 PowerShell 启动失败，请改用 Git Bash：
|
||
```bash
|
||
bash scripts/start-celery.sh
|
||
```
|
||
这是 Windows 上的已知问题，PowerShell 的进程管理机制与 Celery 不兼容。
|
||
|
||
### 编码问题
|
||
如果 PowerShell 显示乱码，确保使用 UTF-8 with BOM 编码保存的脚本文件。
|
||
|
||
## 脚本架构
|
||
|
||
```
|
||
scripts/
|
||
├── start-backend.ps1/.sh # 启动 Django 后端服务
|
||
├── start-frontend.ps1/.sh # 启动 Vue 前端开发服务器
|
||
├── start-celery.ps1/.sh # 启动 Celery worker 和 beat
|
||
├── stop-all.ps1/.sh # 停止所有服务
|
||
├── stop-celery.ps1/.sh # 仅停止 Celery 服务
|
||
├── view-logs.ps1/.sh # 查看和跟踪日志文件
|
||
├── check-status.ps1/.sh # 检查服务运行状态
|
||
├── Makefile # Unix/Linux/macOS 编排
|
||
└── make.ps1 # Windows PowerShell 编排
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- 所有脚本都是幂等的 - 多次运行是安全的
|
||
- 脚本会检测服务是否已运行，已运行则跳过启动
|
||
- 使用 PID 文件实现优雅关闭
|
||
- 停止时会清理残留进程
|
||
- PowerShell 脚本输出使用英文，避免编码问题
|
||
- Bash 脚本输出使用中文
|
||
- **Windows 用户**：建议使用 Git Bash 运行 Celery 脚本，以避免进程兼容性问题
|