6.9 KiB
6.9 KiB
甲辰藏品管理系统 - 完整错误码文档
版本: 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。常见原因：
- 后端服务未启动 - Nginx 返回 502/503 错误页面（HTML）
- API 地址配置错误 - 请求了错误的 URL，返回 404 页面（HTML）
- 网络代理问题 - 防火墙/代理服务器返回拦截页面（HTML）
- 浏览器缓存 - 缓存了旧的错误页面
解决方案
方案 1: 检查后端服务
# 检查后端是否运行
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 配置
# 检查 Nginx 状态
systemctl status nginx
# 检查 Nginx 配置
nginx -t
方案 3: 清除浏览器缓存
- 按
F12打开开发者工具 - 右键点击刷新按钮
- 选择"清空缓存并硬性重新加载"
方案 4: 检查 API 地址
打开浏览器开发者工具 → Network 标签，查看登录请求的 URL：
- 应该是：
http://120.26.133.10:3001/api/auth/login - 如果是其他地址，说明配置有误
🛠️ 调试技巧
1. 查看浏览器控制台
按 F12 打开开发者工具，查看：
- Console - JavaScript 错误
- Network - API 请求详情
2. 查看后端日志
tail -f /tmp/zodiac-backend.log
3. 查看 Nginx 日志
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
4. 测试 API
# 测试登录接口
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