Files

T

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 全绿；二进制端到端冒烟通过

2026-09-05 04:22:41 +08:00

3.2 KiB

Raw Permalink Blame History

错误码

响应结构

{ "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` 字段确认引擎

3.2 KiB Raw Permalink Blame History Unescape Escape

错误码

响应结构

业务状态码

存储哨兵错误映射

错误结果的审计归类

常见排障

3.2 KiB

Raw Permalink Blame History