# 常见问题FAQ

本章节整理了项目开发和部署过程中常见的问题及解决方案，帮助你快速定位和解决问题。

:::tip 温馨提示
遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。
:::

## 1. 端口被占用

**现象**

启动后端服务时报错：

```
OSError: [Errno 98] Address already in use
```

或：

```
ERROR: [Errno 10048] 通常每个套接字地址(协议/网络地址/端口)只允许使用一次
```

**原因**

端口 `8000`（或配置的其他端口）已被其他程序占用。

**解决方案**

```bash
# Windows 查看端口占用
netstat -ano | findstr 8000
# 找到 PID 后终止进程
taskkill /PID <进程ID> /F

# Linux / macOS 查看端口占用
lsof -i :8000
# 终止进程
kill -9 <进程ID>
```

或者使用其他端口启动：

```bash
python manage.py runserver 8080
```

:::tip 温馨提示
前端开发服务器端口冲突同理，修改 `ui/.env.development` 中的 `VITE_PORT` 即可。
:::

## 2. 数据库连接失败

**现象**

启动时报错：

```
pymysql.err.OperationalError: (2003, "Can't connect to MySQL server on '127.0.0.1'")
```

或：

```
django.db.utils.OperationalError: (1045, "Access denied for user 'root'@'localhost'")
```

**排查步骤**

```
1. 检查 MySQL 服务是否已启动
2. 检查 .env 中的 DATABASE_HOST、DATABASE_PORT、DATABASE_USER、DATABASE_PASSWORD 是否正确
3. 检查数据库用户是否有远程连接权限
4. 检查防火墙是否放行了数据库端口
```

**解决方案**

```bash
# 测试数据库连接
mysql -h127.0.0.1 -P3306 -uroot -p

# 如果是权限问题，授权用户
mysql -uroot -p
GRANT ALL PRIVILEGES ON `djangoadmin.django.antdvue`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;
```

:::tip 温馨提示
确认 `.env` 中的 `DATABASE_PASSWORD` 没有多余的空格或引号。密码中的特殊字符可能需要转义。
:::

## 3. Redis 连接失败

**现象**

启动时报错：

```
redis.exceptions.ConnectionError: Error connecting to 127.0.0.1:6379
```

或：

```
redis.exceptions.AuthenticationError: Authentication required
```

**排查步骤**

```
1. 检查 Redis 服务是否已启动
2. 检查 .env 中的 REDIS_HOST、REDIS_PORT、REDIS_PASSWORD 是否正确
3. 检查 Redis 是否设置了密码
```

**解决方案**

```bash
# 测试 Redis 连接
redis-cli -h 127.0.0.1 -p 6379 -a your_password ping

# Windows 启动 Redis 服务
net start Redis

# Linux 启动 Redis 服务
sudo systemctl start redis

# macOS 启动 Redis 服务
brew services start redis
```

:::tip 温馨提示
Redis 用于存储验证码和 JWT 令牌黑名单，是项目正常运行的必需服务。确保 `.env` 中的 `REDIS_PASSWORD` 与 Redis 实际配置的密码一致。
:::

## 4. pip install 安装失败

**现象**

执行 `pip install -r requirements.txt` 时报错：

```
ERROR: Could not find a version that satisfies the requirement xxx
```

或：

```
ERROR: Failed building wheel for xxx
```

**解决方案**

```bash
# 方案一：使用国内镜像源
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

# 方案二：升级 pip 后重试
python -m pip install --upgrade pip
pip install -r requirements.txt

# 方案三：配置全局镜像源
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set global.trusted-host mirrors.aliyun.com
```

:::danger requirements.txt 编码问题
`requirements.txt` 文件为 `UTF-16LE` 编码，部分系统可能无法正确解析。如果 `pip install` 报编码错误，请先将文件转换为 `UTF-8`：

```bash
# Windows (PowerShell)
Get-Content requirements.txt -Encoding Unicode | Set-Content -Encoding UTF8 requirements_utf8.txt
pip install -r requirements_utf8.txt

# Linux / macOS
iconv -f UTF-16LE -t UTF-8 requirements.txt > requirements_utf8.txt
pip install -r requirements_utf8.txt
```
:::

## 5. mysqlclient 安装失败

**现象**

Windows 系统安装 `mysqlclient` 时报错：

```
error: Microsoft Visual C++ 14.0 or greater is required
```

**解决方案**

```bash
# 方案一：安装 Visual C++ Build Tools
# 下载地址：https://visualstudio.microsoft.com/visual-cpp-build-tools/

# 方案二：使用预编译的 wheel 包
# 访问 https://www.lfd.uci.edu/~gohlke/pythonlibs/#mysqlclient
# 下载对应版本的 .whl 文件后安装

# 方案三：使用 pymysql 作为替代（不推荐用于生产）
pip install pymysql
```

## 6. pnpm install 安装失败

**现象**

执行 `pnpm install` 时报错：

```
ERR_PNPM_NO_MATCHING_VERSION
```

或：

```
GET https://registry.npmjs.org/xxx error
```

**解决方案**

```bash
# 方案一：切换淘宝镜像源
pnpm config set registry https://registry.npmmirror.com
pnpm install

# 方案二：清除缓存后重试
pnpm store prune
rm -rf node_modules
pnpm install

# 方案三：使用 --shamefully-hoist 模式
pnpm install --shamefully-hoist
```

:::tip 温馨提示
如果网络环境受限，可以尝试使用 VPN 或配置代理：

```bash
pnpm config set proxy http://127.0.0.1:7890
pnpm config set https-proxy http://127.0.0.1:7890
```
:::

## 7. API 请求返回 404

**现象**

调用接口时返回：

```html
<h1>Page not found (404)</h1>
```

**原因**

可能是请求路径不正确，或后端路由未正确注册。

**排查步骤**

```
1. 检查请求路径是否正确（如 /login/captcha、/example/page）
2. 检查 application/urls.py 中是否注册了对应模块的路由
3. 检查前端代理配置中的后端地址是否正确
```

**解决方案**

```bash
# 测试后端服务是否正常
curl http://127.0.0.1:8000/login/captcha

# 检查前端代理配置
# ui/.env.development
VITE_PROXY=[["/api","http://127.0.0.1:8000/"]]
```

:::tip 温馨提示
前端所有以 `/api` 开头的请求会被代理到后端的 `8000` 端口。例如：
- 前端请求 `http://localhost:8001/api/login/captcha`
- 会被代理到 `http://127.0.0.1:8000/login/captcha`
:::

## 8. 验证码图片不显示

**现象**

登录页面验证码图片区域空白，或显示加载失败图标。

**排查步骤**

```
1. 打开浏览器控制台（F12），查看 Network 标签中的请求状态
2. 检查 /login/captcha 接口是否返回正常
3. 检查 Redis 服务是否正常（验证码存储在 Redis 中）
```

**解决方案**

```bash
# 1. 测试验证码接口
curl http://127.0.0.1:8000/login/captcha

# 2. 测试 Redis 连接
redis-cli -h 127.0.0.1 -p 6379 -a your_password ping
# 应返回 PONG

# 3. 检查 Django 验证码配置是否正常
python manage.py shell
>>> from captcha.models import CaptchaStore
>>> CaptchaStore.objects.count()
```

:::tip 温馨提示
验证码生成依赖 `django-simple-captcha` 库和 `Pillow` 库。如果验证码接口报错，请确认这两个库已正确安装。
:::

## 9. 接口返回权限不足

**现象**

调用接口返回：

```json
{
    "code": 1,
    "data": null,
    "msg": "权限不足",
    "ok": false
}
```

**原因**

当前登录用户没有该接口的访问权限。项目采用 RBAC 权限模型，每个接口对应一个权限字符串（如 `sys:user:list`）。

**解决方案**

```
1. 使用 admin 账号登录（ID=1 的管理员绕过所有权限检查）
2. 检查当前用户的角色是否包含该接口的权限
3. 在系统管理 > 菜单管理中，确认接口对应的权限节点已正确配置
4. 在系统管理 > 角色管理中，确认角色已分配该权限
```

:::tip 温馨提示
`admin` 用户（ID=1）是超级管理员，拥有全部权限，不受权限检查限制。开发调试时建议使用 `admin` 账号。
:::

## 10. 文件上传失败

**现象**

上传文件时返回错误：

```json
{
    "code": 1,
    "data": null,
    "msg": "文件上传失败",
    "ok": false
}
```

**排查步骤**

```
1. 检查上传目录是否存在且有写入权限
2. 检查 .env 中的 DJANGO_UPLOAD_DIR 配置是否正确
3. 检查 .env 中的 DJANGO_FILE_URL 配置是否正确
4. 检查文件大小是否超过 Django 的 FILE_UPLOAD_MAX_MEMORY_SIZE 限制
```

**解决方案**

```bash
# .env 中的上传配置
DJANGO_UPLOAD_DIR="E:\DjangoAdmin_Django_AntdVue\public\uploads"
DJANGO_FILE_URL='http://file.django.antdvue'
```

:::tip 温馨提示
1. 确保 `public/uploads/` 目录存在且有写入权限。
2. 如需上传更大文件，可在 `application/settings.py` 中调整 `FILE_UPLOAD_MAX_MEMORY_SIZE` 和 `DATA_UPLOAD_MAX_MEMORY_SIZE` 配置。
:::

## 快速自检清单

遇到问题时，按以下清单逐项检查：

| 检查项 | 命令 | 期望结果 |
|:----|:----|:----|
| Python 版本 | `python --version` | 3.12+ |
| pip 依赖 | `pip list \| grep django` | Django 6.0+ |
| MySQL 服务 | `mysql -uroot -p -e "SELECT 1"` | 返回 1 |
| Redis 服务 | `redis-cli -h 127.0.0.1 -p 6379 -a 123456 ping` | PONG |
| .env 文件 | 确认 DATABASE_PASSWORD 和 REDIS_PASSWORD 正确 | 非空值 |
| 后端服务 | `curl http://127.0.0.1:8000/login/captcha` | 返回 JSON |
| Node.js 版本 | `node -v` | v18+ |
| pnpm 版本 | `pnpm -v` | 12.x+ |
| 前端服务 | 浏览器访问 `http://localhost:8001` | 显示登录页 |

:::tip 温馨提示
如果以上检查项均正常但仍无法运行，建议查看完整错误日志：

```bash
# 后端日志
python manage.py runserver 2>&1 | tee backend.log

# 前端日志
cd ui && pnpm dev 2>&1 | tee frontend.log
```
:::

## 总结

本章节整理了项目开发中最常见的 10 个问题及其解决方案，涵盖环境配置、服务连接、依赖安装、权限控制和文件上传等方面。遇到问题时，建议先查看终端日志和浏览器控制台的错误信息，结合本章节的排查步骤逐一排除。如果问题仍未解决，可以查阅项目源码或联系开发团队获取支持。