SKYMirror
7f060dd0e4
Go 1.27.1 (Gin+GORM) + Vue 3 文件快传服务： - 安全审计全部修复（docs/security-audit-2026-09-05.md）： bcrypt 密码哈希与自动升级、presign 直传服务端大小/内容校验、 全局请求体上限、依赖升级（govulncheck 0 命中）、janitor 后台清理、 管理端审计动作落库、/admin CORS 收紧、通知内容白名单净化、 会话默认 7 天、限流缓存故障降级、robots.txt 端点等 - 前端：取件链接复制修复（不再重复拼接提取码）、markdown 净化器加固 - Redis 支持库号（FCB_REDIS_DB / redis://…/db URL） - 文档：docs/api/* 与 openapi.yaml 同步最新行为（robots.txt、 提码 5 位起、chunk 32MiB 上限、admin 审计动作等） 验证：gofmt/go vet/go test 全绿；二进制端到端冒烟通过
63 lines
3.2 KiB
Markdown
63 lines
3.2 KiB
Markdown
# 错误码
|
||
|
||
## 响应结构
|
||
|
||
```json
|
||
{ "code": 404, "msg": "文件不存在" }
|
||
```
|
||
|
||
- `code` 与 HTTP 状态码一致；失败时无 `data` 字段。
|
||
- `msg` 为中文可读信息，可直接展示给用户。
|
||
|
||
## 业务状态码
|
||
|
||
| 状态码 | 语义 | 典型场景 |
|
||
|---|---|---|
|
||
| 200 | 成功 | 全部正常响应 |
|
||
| 400 | 参数/格式错误 | 缺字段、过期策略非法、时间格式错误、分片哈希不匹配、code 冲突、`chunk_size` 超 32MiB 上限、presign 实际大小与声明不符、请求体超过大小上限 |
|
||
| 401 | 未认证 | 管理端令牌缺失/无效；登录密码错误 |
|
||
| 403 | 拒绝 | 类型白名单拒绝、magic bytes 防伪、游客上传未开启、**分片上传未启用**（enableChunk=0）、presign 直传对象超限（服务端删除对象并释放预留）、下载 `key` 鉴权失败、超过大小/时长限制 |
|
||
| 404 | 不存在/已过期 | 取件码不存在、文件已过期、上传会话不存在、`/api/*` 未命中路由 |
|
||
| 409 | 冲突 | 上传容量预留信息不一致 |
|
||
| 416 | Range 越界 | `Range: bytes=…` 超出文件大小 |
|
||
| 423 | 限流 | upload/error/login/metadata 任一规则超限 |
|
||
| 428 | 未初始化 | 系统未初始化时访问除 `/setup`、`/api/v1/health` 外的接口 |
|
||
| 500 | 服务器错误 | 数据库/内部异常 |
|
||
| 501 | 引擎不支持 | 引擎不支持预签名等操作（local/webdav 的 `PresignGetURL/PutURL`） |
|
||
| 503 | 存储不可用 | 存储引擎连接失败/健康检查不通过时的操作 |
|
||
| 507 | 容量超限 | 达到 `storageLimit` 上限（含上传预留判定） |
|
||
|
||
## 存储哨兵错误映射
|
||
|
||
存储层哨兵错误统一映射（支持错误包装链判定）：
|
||
|
||
| 哨兵错误 | HTTP | 响应 msg |
|
||
|---|---|---|
|
||
| `ErrNotFound` | 404 | 文件不存在 |
|
||
| `ErrInvalidPath` | 400 | 非法文件路径 |
|
||
| `ErrUnavailable` | 503 | 存储服务不可用，请稍后再试 |
|
||
| `ErrNotSupported` | 501 | 当前存储引擎不支持该操作 |
|
||
| `ErrRangeNotSatisfiable` | 416 | 请求范围超出文件大小 |
|
||
| `ErrHashMismatch` | 400 | 分片哈希校验失败，请重新上传 |
|
||
|
||
未识别的存储错误归入 500（`存储操作失败: …`）。
|
||
|
||
## 错误结果的审计归类
|
||
|
||
错误响应同时写入审计日志（需求 ③）：
|
||
|
||
- `denied`：401 / 403 / 423 / 429 / 428（拒绝类）。
|
||
- `failed`：其余 4xx / 5xx 及业务显式报错。
|
||
|
||
## 常见排障
|
||
|
||
| 现象 | 原因与处理 |
|
||
|---|---|
|
||
| 全部接口 428 | 未初始化：访问 `GET /setup` 或 `POST /setup` 完成向导 |
|
||
| 上传 403「本站未开启游客上传」 | `openUpload=0`，携带管理员 Bearer 令牌或后台开启 |
|
||
| 上传 423 | 触发 upload 限流，等待窗口或调大 `uploadCount/uploadMinute` |
|
||
| 取件 404「文件已过期」 | 分享过期/次数耗尽；管理员可 `PATCH /admin/file/update` 调整 |
|
||
| 下载 403「下载鉴权失败」 | `key` 窗口令牌过期/伪造：重新 `POST /share/select` 获取新地址 |
|
||
| 预签名 init 返回 proxy | local/webdav 引擎不支持直链，按 proxy 流程走服务端代理上传 |
|
||
| 503 存储服务不可用 | 检查引擎配置与远端服务（S3/WebDAV）连通性；`GET /api/v1/health` 的 `storage` 字段确认引擎 |
|