SKYMirror
84df9996cb
CI 测试 / go vet + go test (push) Successful in 49s
- 全项目版本号统一：v3.x 迭代号（26.9/26.9/26.9/26.9 及裸 v2/v3）→ 26.9， 覆盖 Go 注释 / 文档 / openapi.yaml / README×4 / 前端源码（80+ 处） - v31_test.go 更名 custom_code_test.go；TestV2AccessorDefaults → TestKVAccessorDefaults - docs/api/00-overview.md 更新日志合并为单条 26.9 条目（修复错位拼接） - .goreleaser.yaml 头部注释与实际一致（Pro 2.18.1 / GITEA_TOKEN / semver tag 要求） - CI：release-image.yml → ci.yml，仅保留 vet+test 门禁； 镜像发布移交 GoReleaser Pro（原 build-push 的 tag 校验与 26.9 版本方案冲突，历史 9 次失败） - 前端重建：server/web/dist 与 web-embed 同步（docs 文案嵌入更新）
117 lines
5.8 KiB
Markdown
117 lines
5.8 KiB
Markdown
# API 概述
|
||
|
||
文件快传 Go 版（26.9）对外提供一套 REST API，覆盖文本/文件分享、分片上传、
|
||
预签名直传、管理后台与审计日志查询。
|
||
|
||
## 更新日志
|
||
|
||
- **26.9**：上下行带宽限速（`upload_rate` / `download_rate`，详见《[带宽限速](13-bandwidth.md)》）、
|
||
站点对外域名（`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` 缺省：
|
||
|
||
```json
|
||
{ "code": 200, "msg": "ok", "data": { } }
|
||
```
|
||
|
||
失败示例（404）：
|
||
|
||
```json
|
||
{ "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**：
|
||
|
||
```json
|
||
{ "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](12-logo.md) |
|
||
| 错误码 | [11-errors.md](11-errors.md) |
|
||
| 带宽限速（26.9） | [13-bandwidth.md](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 回退返回页面）。
|