196 lines
6.9 KiB
Markdown
196 lines
6.9 KiB
Markdown
# 甲辰藏品管理系统 - 完整错误码文档
|
||
|
||
**版本**: v2.7.3
|
||
**更新时间**: 2026-03-14
|
||
|
||
---
|
||
|
||
## 📖 错误码格式
|
||
|
||
```
|
||
E + 模块 (2 位) + 序号 (3 位)
|
||
```
|
||
|
||
例如：`E00011` = 认证模块 (01) + 第 11 号错误
|
||
|
||
---
|
||
|
||
## 🔢 完整错误码列表
|
||
|
||
### 00-09: 通用错误
|
||
|
||
| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|
||
|--------|------|----------|----------|----------|
|
||
| E00000 | 未知错误 | 0 | 未定义的错误 | 检查日志 |
|
||
| E00001 | 网络连接失败 | 0 | 网络不通、服务未启动 | 检查网络和后端服务 |
|
||
| E00002 | 服务器响应超时 | 0 | 请求超时 | 重试或检查服务器负载 |
|
||
| E00003 | 服务器内部错误 | 500 | 代码异常、数据库错误 | 查看后端日志 |
|
||
|
||
### 10-19: 认证错误
|
||
|
||
| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|
||
|--------|------|----------|----------|----------|
|
||
| E00010 | 未登录或登录已过期 | 401 | Token 失效 | 重新登录 |
|
||
| E00011 | 用户名或密码错误 | 401 | 密码错误、用户名不存在 | 检查账号密码 |
|
||
| E00012 | 验证码错误 | 400 | 验证码输入错误 | 重新输入或刷新验证码 |
|
||
| E00013 | 账号已被禁用 | 403 | 账号被封禁 | 联系管理员 |
|
||
| E00014 | 无权访问此资源 | 403 | 权限不足 | 申请权限或用管理员账号 |
|
||
| E00015 | 令牌无效或已过期 | 401 | Token 过期 | 重新登录 |
|
||
|
||
### 20-29: 登录注册
|
||
|
||
| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|
||
|--------|------|----------|----------|----------|
|
||
| E00020 | 请输入用户名和密码 | 400 | 空表单 | 填写完整信息 |
|
||
| E00021 | 用户名至少 3 个字符 | 400 | 用户名太短 | 使用更长的用户名 |
|
||
| E00022 | 密码至少 6 个字符 | 400 | 密码太短 | 使用更长的密码 |
|
||
| E00023 | 用户名已存在 | 400 | 重复注册 | 更换用户名 |
|
||
| E00024 | 邮箱已被注册 | 400 | 邮箱重复 | 更换邮箱或找回密码 |
|
||
| E00025 | 邮箱格式不正确 | 400 | 邮箱格式错误 | 检查邮箱格式 |
|
||
| E00026 | 手机号格式不正确 | 400 | 手机号格式错误 | 检查手机号格式 |
|
||
|
||
### 30-39: 藏品管理
|
||
|
||
| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|
||
|--------|------|----------|----------|----------|
|
||
| E00030 | 藏品名称不能为空 | 400 | 名称为空 | 填写名称 |
|
||
| E00031 | 藏品名称至少 2 个字符 | 400 | 名称太短 | 使用更长的名称 |
|
||
| E00032 | 藏品分类不能为空 | 400 | 分类为空 | 选择分类 |
|
||
| E00033 | 藏品不存在 | 404 | ID 错误、已删除 | 检查藏品 ID |
|
||
| E00034 | 禁止重复：此冠字号已存在 | 400 | 重复编号 | 使用不同编号 |
|
||
| E00035 | 成本价格必须>=0 | 400 | 负数价格 | 输入正数 |
|
||
| E00036 | 目标价格必须>=0 | 400 | 负数价格 | 输入正数 |
|
||
| E00037 | 发行年份必须是 4 位数字 | 400 | 年份格式错误 | 如：2024 |
|
||
| E00038 | 图片格式不正确 | 400 | 不支持的图片格式 | 使用 JPG/PNG |
|
||
| E00039 | 图片大小不能超过 10MB | 400 | 图片太大 | 压缩图片 |
|
||
|
||
### 40-49: OCR 识别
|
||
|
||
| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|
||
|--------|------|----------|----------|----------|
|
||
| E00040 | 请选择图片文件 | 400 | 未选择图片 | 上传图片 |
|
||
| E00041 | 图片尺寸太小，无法识别 | 400 | 图片分辨率太低 | 使用更清晰的图片 |
|
||
| E00042 | OCR 识别失败，请重试 | 500 | 识别服务异常 | 重试或更换图片 |
|
||
| E00043 | OCR 服务暂时不可用 | 503 | 服务宕机 | 稍后重试 |
|
||
| E00044 | 无法识别图片内容 | 400 | 图片内容不清晰 | 更换清晰的图片 |
|
||
|
||
### 50-59: 用户管理（仅管理员）
|
||
|
||
| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|
||
|--------|------|----------|----------|----------|
|
||
| E00050 | 仅管理员可访问 | 403 | 权限不足 | 使用管理员账号 |
|
||
| E00051 | 用户不存在 | 404 | 用户 ID 错误 | 检查用户 ID |
|
||
| E00052 | 不能删除自己 | 400 | 删除当前用户 | 删除其他用户 |
|
||
| E00053 | 不能修改自己的角色 | 403 | 权限限制 | 让其他管理员修改 |
|
||
|
||
### 60-69: 文件上传
|
||
|
||
| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|
||
|--------|------|----------|----------|----------|
|
||
| E00060 | 文件太大 | 400 | 超过大小限制 | 压缩文件 |
|
||
| E00061 | 不支持的文件格式 | 400 | 格式不支持 | 使用支持的格式 |
|
||
| E00062 | 上传失败 | 500 | 服务器错误 | 重试或联系管理员 |
|
||
|
||
---
|
||
|
||
## 🔍 特殊错误：E00000 + JSON 解析错误
|
||
|
||
### 错误信息示例
|
||
```
|
||
⚠️ E00000: Unexpected token '<', "<html> <h"... is not valid JSON
|
||
```
|
||
|
||
### 原因分析
|
||
这个错误说明**前端期望 JSON 响应，但实际收到的是 HTML**。常见原因：
|
||
|
||
1. **后端服务未启动** - Nginx 返回 502/503 错误页面（HTML）
|
||
2. **API 地址配置错误** - 请求了错误的 URL，返回 404 页面（HTML）
|
||
3. **网络代理问题** - 防火墙/代理服务器返回拦截页面（HTML）
|
||
4. **浏览器缓存** - 缓存了旧的错误页面
|
||
|
||
### 解决方案
|
||
|
||
#### 方案 1: 检查后端服务
|
||
```bash
|
||
# 检查后端是否运行
|
||
ps aux | grep uvicorn
|
||
|
||
# 如果没有，启动后端
|
||
cd /home/admin/.openclaw/workspace/zodiac-collector/backend-fastapi
|
||
uvicorn app.main:app --port 3000 --host 0.0.0.0
|
||
```
|
||
|
||
#### 方案 2: 检查 Nginx 配置
|
||
```bash
|
||
# 检查 Nginx 状态
|
||
systemctl status nginx
|
||
|
||
# 检查 Nginx 配置
|
||
nginx -t
|
||
```
|
||
|
||
#### 方案 3: 清除浏览器缓存
|
||
1. 按 `F12` 打开开发者工具
|
||
2. 右键点击刷新按钮
|
||
3. 选择"**清空缓存并硬性重新加载**"
|
||
|
||
#### 方案 4: 检查 API 地址
|
||
打开浏览器开发者工具 → Network 标签，查看登录请求的 URL：
|
||
- 应该是：`http://120.26.133.10:3001/api/auth/login`
|
||
- 如果是其他地址，说明配置有误
|
||
|
||
---
|
||
|
||
## 🛠️ 调试技巧
|
||
|
||
### 1. 查看浏览器控制台
|
||
按 `F12` 打开开发者工具，查看：
|
||
- **Console** - JavaScript 错误
|
||
- **Network** - API 请求详情
|
||
|
||
### 2. 查看后端日志
|
||
```bash
|
||
tail -f /tmp/zodiac-backend.log
|
||
```
|
||
|
||
### 3. 查看 Nginx 日志
|
||
```bash
|
||
tail -f /var/log/nginx/access.log
|
||
tail -f /var/log/nginx/error.log
|
||
```
|
||
|
||
### 4. 测试 API
|
||
```bash
|
||
# 测试登录接口
|
||
curl -X POST http://localhost:3000/api/auth/login \
|
||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||
-d "username=admin&password=admin123"
|
||
|
||
# 测试藏品列表
|
||
curl http://localhost:3000/api/collections \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
---
|
||
|
||
## 📞 快速诊断流程
|
||
|
||
```
|
||
登录失败
|
||
↓
|
||
1. 打开浏览器 F12 → Network 标签
|
||
↓
|
||
2. 查看登录请求的状态码
|
||
↓
|
||
├── 0 或 (failed) → 网络问题/服务未启动 → 检查后端服务
|
||
├── 401 → 密码错误 → 检查账号密码
|
||
├── 404 → API 地址错误 → 检查 Nginx 配置
|
||
├── 500 → 服务器错误 → 查看后端日志
|
||
└── 502/503 → Nginx 无法连接后端 → 重启后端服务
|
||
```
|
||
|
||
---
|
||
|
||
**文档维护**: 系统自动更新
|
||
**最后更新**: 2026-03-14 10:30
|