Files

T

SKYMirror 00a8c16ab7 26.9：上下行带宽限速 + 品牌更新 + 产品修复

亮点
- 26.9 带宽限速（upload_rate/download_rate，字节/秒，0=不限速；管理端立即生效）
  - middleware/bandwidth.go 时间窗对齐 sleep 算法 + 单元测试（400KB@100KB/s 4.00s 精度）
  - 下载：serveFile 包裹 storage.ReadCloser（统一覆盖 local/webdav/s3 代理下载）
  - 上传：UploadBandwidthMiddleware 包裹 Request.Body（shareFile/chunk/presign proxy）
  - S3 预签名直传不可服务端限速——UI/文档明示
  - 后台 SettingsView 增加 MB/s 友好输入；i18n zh-CN/en-US 双语
- 26.9 文档：新增 docs/api/13-bandwidth.md 专题；10-config 指针；00-overview changelog
  与限流表带宽行；openapi.yaml 三处 schema + description 更新
- README.md / web/README.md / server/README.md / deploy/README.md 全部覆盖

品牌（26.9 收尾）
- 文件快递柜 → 文件快传（前端/后端默认值/文档/产物/运行 KV）
- 「复制取件码」按钮删除；取件码块点击即复制（保持原尺寸）
- 「复制链接」→「复制链接和提取码」（一并复制链接和提取码）

产品修复（26.9）
- 文本分享 Content-Type text/plain + urlencoded body：前端显式声明 urlencoded 头根治；
  后端 bindJSONOrForm 兜底兼容 text/plain + JSON/urlencoded 嗅探
- Docker 部署文档校对到 26.9 现状（热切换 + 端口/卷/健康检查）

2026-09-06 10:20:04 +08:00

5.8 KiB

Raw Blame History

API 概述

文件快传 Go 版（26.9）对外提供一套 REST API，覆盖文本/文件分享、分片上传、预签名直传、管理后台与审计日志查询。

更新日志

v3.2：上下行带宽限速（upload_rate / download_rate，详见《带宽限速》）
v3.1：站点对外域名（site_domain）、自定义提取码（5~8 位）本文档与 server/internal/api/ 实际实现逐一对齐，交互式规范见站内 /openapi（源文件 docs/openapi.yaml）。

Base URL

服务默认监听 :8466，Base URL 为 http://<host>:8466（下文示例统一用 http://localhost:8466）。
业务路由挂根路径（与参考实现一致）：/share/*、/chunk/*、/presign/*、/admin/*、/setup。
仅两个公共接口带 /api/v1 前缀：/api/v1/health、/api/v1/config。

统一响应封装

所有 JSON 接口返回统一结构，HTTP 状态码与 code 一致；失败时 data 缺省：

{ "code": 200, "msg": "ok", "data": { } }

失败示例（404）：

{ "code": 404, "msg": "文件不存在" }

个别端点直接返回原始内容而非 JSON 封装（文档中已单独标注）：

端点	响应形式
`GET /share/select?code=`（文本分享）	`text/plain; charset=utf-8` 正文
`GET /share/select?code=`（文件分享）	文件二进制流（200/206，支持 Range）
`GET /share/download?key=&code=`（文件分享）	文件二进制流（200/206，支持 Range）
`GET /admin/file/download?id=`（文件分享）	文件二进制流
`GET /setup` / `POST /setup`（表单）	HTML 向导/成功页

字段命名约定

接口字段以 snake_case 为主（file_code、size_bytes）。
文件列表与审计日志的行字段同时输出 snake_case 与 camelCase 双份（如 expired_at 与 expiredAt），文档以 snake_case 为准，camelCase 仅为前端兼容保留。

认证

游客接口无需认证；是否允许游客上传由配置 openUpload 控制（关闭时上传类接口要求管理员 Authorization: Bearer <token>，否则 403）。
管理接口（/admin/login 除外）一律要求 Authorization: Bearer <JWT>，无效/缺失返回 401。
详情见《认证与限流》。

限流

按 IP（可信代理场景解析 X-Forwarded-For）维度限流，超限返回 423：

规则	计数时机	默认（次/窗口）	相关配置
`upload`	上传成功后计数	10 次 / 1 分钟	`uploadCount` / `uploadMinute`
`error`	取件失败（404/过期）时计数	10 次 / 1 分钟	`errorCount` / `errorMinute`
`login`	登录失败时计数	5 次 / 15 分钟	`loginCount` / `loginMinute`
`metadata`	每次访问即计数	同 `error`	`errorCount` / `errorMinute`
`bandwidth`	每 Read 块按 `rate` 字节/秒对齐 sleep，0=不限速	0 / 0（不限）	`upload_rate` / `download_rate`

初始化守卫

系统未初始化（未设置管理员密码）时，除 GET|POST /setup 与 GET /api/v1/health 外， 所有接口一律返回 428：

{ "code": 428, "msg": "系统未初始化，请先完成初始化" }

首次部署请先访问 GET /setup 获取 HTML 向导，或直接 POST /setup 完成初始化（见《管理后台 API》初始化章节）。

审计

所有上传/下载端点经审计中间件自动落库（操作时间/IP/UA/设备解析/动作/结果/字节数/耗时/角色），失败与被拒绝的请求同样记录；管理端经 GET /admin/audit/list 查询，详见《审计日志》。

端点总览

模块	端点
公共	`GET /api/v1/health` · `GET /api/v1/config` · `GET /robots.txt`（输出 `robotsText` 配置）
初始化	`GET /setup` · `POST /setup`
文本分享	`POST /share/text`
文件分享	`POST /share/file`
查询与取件	`GET/POST /share/metadata` · `GET /share/select` · `POST /share/select` · `GET /share/download`
分片上传	`POST /chunk/upload/init` · `POST /chunk/upload/{uploadID}/{chunkIndex}` · `GET /chunk/upload/status/{uploadID}` · `POST /chunk/upload/complete/{uploadID}` · `DELETE /chunk/upload/{uploadID}`
预签名直传	`POST /presign/upload/init` · `PUT /presign/upload/proxy/{uploadID}` · `POST /presign/upload/confirm/{uploadID}` · `GET /presign/upload/status/{uploadID}` · `DELETE /presign/upload/{uploadID}`
管理后台	`POST /admin/login` · `GET /admin/verify` · `POST /admin/logout` · `GET /admin/dashboard` · 文件管理 `/admin/file/` · 配置 `/admin/config/` · 密码 `/admin/settings/password`
审计日志	`GET /admin/audit/list`（别名 `/admin/audit/logs`）

专题文档

主题	文档
站点 Logo 自定义	12-logo.md
错误码	11-errors.md
带宽限速（v3.2）	13-bandwidth.md

时间与编码

时间字段一律 RFC 3339（如 2025-06-01T12:00:00+08:00）；管理员会话过期时间为 Unix 秒。
请求体支持 application/json 与 application/x-www-form-urlencoded（上传类为 multipart/form-data），文档示例以 JSON/curl 为主。
CORS：公开接口放开（Bearer 认证，无 Cookie CSRF 面）；管理端 /admin/* 已收紧——携带 Origin 且既不同源也不在 site_domain 白名单时不下发 CORS 头（浏览器拦截跨域读取）。

交互式文档

站内文档页：/docs（渲染本目录 markdown，构建时内嵌）。
Swagger UI：/openapi（渲染 docs/openapi.yaml，构建时内嵌）。
OpenAPI 规范源文件为仓库内 docs/openapi.yaml；如需经后端直接下载，需在部署时把它拷贝进前端静态产物 web/dist/（未拷贝时该路径按 SPA 回退返回页面）。

5.8 KiB Raw Blame History Unescape Escape