SKYMirror
157db0e9e5
亮点 - v3.2 带宽限速（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 双语 - v3.2 文档：新增 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 全部覆盖 品牌（v3.1 收尾） - 文件快递柜 → 文件快传（前端/后端默认值/文档/产物/运行 KV） - 「复制取件码」按钮删除；取件码块点击即复制（保持原尺寸） - 「复制链接」→「复制链接和提取码」（一并复制链接和提取码） 产品修复（v3.1.1） - 文本分享 Content-Type text/plain + urlencoded body：前端显式声明 urlencoded 头根治； 后端 bindJSONOrForm 兜底兼容 text/plain + JSON/urlencoded 嗅探 - Docker 部署文档校对到 v3.1 现状（热切换 + 端口/卷/健康检查）
155 lines
8.1 KiB
Markdown
155 lines
8.1 KiB
Markdown
# FileShare
|
||
|
||
文件快传
|
||
|
||
数据库**默认 SQLite 零依赖**（modernc.org/sqlite 纯 Go 驱动，数据文件 `./data/fileshare.db`），
|
||
可选切换 Postgres（`FCB_DB_DRIVER=postgres` + DSN）；Redis 为**可选**增强（未配置时自动降级为进程内存缓存）。
|
||
存储引擎支持 **本地 / S3 / WebDAV**（运行时热切换，健康检查通过才生效；WebDAV 重点优化：流式、Range、重试、连接复用）。
|
||
v3.2 起支持**上下行带宽限速**（`upload_rate` / `download_rate` 字节/秒，0=不限速，管理端改后立即生效）。
|
||
|
||
**v3.2 新增**：上下行带宽限速（见 [专题](docs/api/13-bandwidth.md)）· 站点对外域名、自定义提取码（v3.1）·
|
||
本地/S3/WebDAV 存储引擎 v3 运行时热切换。
|
||
|
||
| 目录 | 说明 |
|
||
|---|---|
|
||
| `server/` | Go 后端（API、模型迁移、缓存降级、认证限流、审计、存储引擎） |
|
||
| `web/` | Vue 3 + Vite + TS 前端（分享/取件/管理/审计/设置/`/docs` 文档页/`/openapi` Swagger） |
|
||
| `docs/` | 中文 API 操作文档（`docs/api/*.md`）与 OpenAPI 规范（`docs/openapi.yaml`） |
|
||
| `deploy/` | docker-compose 编排、三阶段 Dockerfile、`.env.example` |
|
||
| `reference/` | 参考原版仓库（只读克隆，目录名 `upstream`） |
|
||
|
||
## 默认 Logo 与自定义
|
||
|
||
- 页面导航 Logo：本地资源 `web/src/assets/brand/logo.svg`
|
||
- favicon / 备用 Logo：本地资源 `web/src/assets/brand/favicon.png`（v2 起不再使用远程 URL 默认值）
|
||
|
||
管理端自定义 Logo 三步：
|
||
|
||
1. 登录后台 `POST /admin/login` 获取 Bearer 令牌；
|
||
2. `PATCH /admin/config/update` 提交 `{"logo_url":"…","favicon_url":"…"}`（或在管理界面「系统设置」页上传/填写 URL）;
|
||
3. 保存即全站生效（前端读取 `GET /api/v1/config` 立即换新，无需重启）。
|
||
|
||
详见《[Logo 自定义](docs/api/12-logo.md)》。
|
||
|
||
## 快速开始（docker compose）
|
||
|
||
```bash
|
||
cd deploy
|
||
cp .env.example .env
|
||
docker compose up -d --build
|
||
# 打开 http://localhost:8466 → 自动跳转 /setup 完成初始化
|
||
```
|
||
|
||
- **数据库双路径**：默认 SQLite 零依赖——`docker compose up -d --build` 即可（无需 postgres profile，
|
||
数据落 `serverdata` 卷 `/app/data/fileshare.db`）；Postgres 模式——`.env` 设
|
||
`FCB_DB_DRIVER=postgres` 与 `FCB_DB_DSN` 后 `docker compose --profile postgres up -d --build`。
|
||
- Redis 可选：`--profile redis` 并在 `.env` 设 `FCB_REDIS_ADDR=redis:6379`；未配置时自动降级为内存缓存。
|
||
- 存储引擎切换：`.env` 改 `FCB_STORAGE_ENGINE=s3|webdav` 并带对应 profile 启动：
|
||
`docker compose --profile minio up -d --build`（含 mc 自动建桶）或 `docker compose --profile webdav up -d --build`。
|
||
- 详见《[部署编排](deploy/README.md)》与《[存储引擎配置](docs/api/09-storage.md)》。
|
||
|
||
## 本地开发
|
||
|
||
前置：Go 1.27.1、Node 20（Postgres 16 仅 Postgres 模式需要）。
|
||
|
||
```bash
|
||
# 1) 后端（:8466）——默认 SQLite 零依赖，无需任何数据库
|
||
cd server
|
||
go run ./cmd/server # 数据落 ./data/fileshare.db；go test ./... 运行单测
|
||
|
||
# 2) 后端 Postgres 模式（可选）
|
||
docker run -d --name fcb-pg -p 5432:5432 \
|
||
-e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=filecodebox postgres:16
|
||
export FCB_DB_DRIVER=postgres
|
||
export FCB_DB_DSN='postgres://postgres:postgres@localhost:5432/filecodebox?sslmode=disable'
|
||
go run ./cmd/server
|
||
|
||
# 3) 前端 dev server（Vite 代理 /api → http://127.0.0.1:8466）
|
||
cd ../web
|
||
npm ci
|
||
npm run dev
|
||
|
||
# 生产构建（go:embed 进二进制）
|
||
npm run build # 产出 web/dist/，构建时按 deploy/Dockerfile 拷入 server/web/dist
|
||
```
|
||
|
||
- 浏览器打开 `http://localhost:5173`（前端 dev）或 `http://localhost:8466`（后端 embed）。
|
||
- 未初始化时除 `/setup` 与 `/api/v1/health` 外一律 428；首次访问按向导完成初始化。
|
||
|
||
## 文档
|
||
|
||
| 内容 | 入口 |
|
||
|---|---|
|
||
| API 操作文档（概述/认证/分享/分片/预签名/管理后台/审计/存储/配置/错误码/Logo/
|
||
**带宽限速**） | 站内 `/docs`，源文件 [docs/api/](docs/api/) |
|
||
| ↳ **v3.2 带宽限速**（`upload_rate` / `download_rate`，管理端改后立即生效） | [docs/api/13-bandwidth.md](docs/api/13-bandwidth.md) |
|
||
| OpenAPI 3.0 规范 + Swagger UI | 站内 `/openapi`，源文件 `docs/openapi.yaml` |
|
||
| 后端设计契约 | [server/README.md](server/README.md) |
|
||
| 前端说明与渲染约定 | [web/README.md](web/README.md) |
|
||
| 部署编排 | [deploy/README.md](deploy/README.md) |
|
||
|
||
## 全量配置
|
||
|
||
### 进程环境变量（`FCB_*`）
|
||
|
||
| 变量 | 必需 | 默认 | 说明 |
|
||
|---|---|---|---|
|
||
| `FCB_DB_DRIVER` | ❌ | `sqlite` | 数据库驱动：`sqlite` \| `postgres`（v2 需求 ⑧） |
|
||
| `FCB_DB_DSN` | 视驱动 | - | postgres：连接串（**必需**）；sqlite：文件路径（可空，默认 `./data/fileshare.db`） |
|
||
| `FCB_REDIS_ADDR` | ❌ | 空 | 为空时缓存降级为内存实现；支持 `redis://[:password@]host:port[/db]` / `rediss://` URL 形式 |
|
||
| `FCB_REDIS_DB` | ❌ | `0` | Redis 逻辑库号 0-15（URL 显式 `/N` 时以 URL 为准） |
|
||
| `FCB_LISTEN` | ❌ | `:8466` | 监听地址 |
|
||
| `FCB_STORAGE_ENGINE` | ❌ | `local` | `local` / `s3` / `webdav` |
|
||
| `FCB_TRUSTED_PROXIES` | ❌ | 空 | 可信代理 CIDR（逗号分隔），生产必读（限流/审计 IP 依据） |
|
||
| `FCB_ADMIN_PASSWORD` | ❌ | 空 | 设置后首次启动自动初始化管理员（≥8 位），消除 `/setup` 被抢占窗口；初始化后建议移除 |
|
||
|
||
### 引擎环境变量（种子注入，重启生效）
|
||
|
||
| 变量 | 引擎 |
|
||
|---|---|
|
||
| `FCB_LOCAL_STORAGE_PATH`（容器内默认 `/app/data`） | local |
|
||
| `FCB_STORAGE_PATH` | 全部（存储相对路径前缀） |
|
||
| `FCB_S3_ACCESS_KEY_ID` / `FCB_S3_SECRET_ACCESS_KEY` / `FCB_AWS_SESSION_TOKEN` | s3 |
|
||
| `FCB_S3_BUCKET_NAME` / `FCB_S3_ENDPOINT_URL` / `FCB_S3_REGION_NAME` / `FCB_S3_ADDRESSING_STYLE` | s3 |
|
||
| `FCB_WEBDAV_URL` / `FCB_WEBDAV_USERNAME` / `FCB_WEBDAV_PASSWORD` / `FCB_WEBDAV_ROOT_PATH` | webdav |
|
||
|
||
### 运行时配置（settings KV，管理端可改）
|
||
|
||
站点信息（`site_name`、`logo_url`、`favicon_url`、`page_explain` 等）、v2 展示与通知
|
||
（`background_url`、`footer_text`、`footer_beian`、`notify_enabled`、`notify_title/content`）、
|
||
上传策略（`openUpload`、`enableChunk`、`uploadSize`、`allowed_file_types`、`expireStyle`、
|
||
`code_generate_type`、`max_save_seconds`、`storageLimit`，及 v2 上限键 `max_save_count`、
|
||
`max_file_size`）、限流（`uploadCount/uploadMinute`、`errorCount/errorMinute`、
|
||
`loginCount/loginMinute`）、安全（`adminSessionExpire`；`admin_token`/`jwt_secret` 由系统管理）。
|
||
v3.2 带宽（`upload_rate` / `download_rate`，字节/秒，0=不限速）。
|
||
|
||
完整键表与默认值见《[环境变量与配置项](docs/api/10-config.md)》；
|
||
v3.2 带宽限速专题《[带宽限速](docs/api/13-bandwidth.md)》；
|
||
修改接口见《[管理后台 API](docs/api/07-admin.md)》（`PATCH /admin/config/update`，改密自动轮换 jwt_secret）。
|
||
|
||
## 审计日志
|
||
|
||
所有上传/下载端点自动落库：操作时间、IP、UA、设备解析（OS/浏览器/类型）、动作
|
||
（`upload`/`download`）、结果（`success`/`denied`/`failed`）、字节数（文件总大小 + 实际传输，
|
||
Range 只计实际区间）、耗时、角色（`admin`/`guest`）。管理端查询：
|
||
`GET /admin/audit/list?page&size&action&result&ip&start_time&end_time`。
|
||
详见《[审计日志查询](docs/api/08-audit.md)》。
|
||
|
||
## API 速览
|
||
|
||
| 模块 | 代表端点 |
|
||
|---|---|
|
||
| 公共 | `GET /api/v1/health` · `GET /api/v1/config` |
|
||
| 初始化 | `GET /setup` · `POST /setup` |
|
||
| 分享 | `POST /share/text` · `POST /share/file` · `GET /share/metadata?code=` · `GET/POST /share/select` · `GET /share/download` |
|
||
| 分片上传 | `POST /chunk/upload/init` → `POST /chunk/upload/{id}/{index}` → `POST /chunk/upload/complete/{id}` |
|
||
| 预签名直传 | `POST /presign/upload/init`（S3=direct，local/webdav=proxy） |
|
||
| 管理后台 | `POST /admin/login` · `/admin/file/*` · `PATCH /admin/config/update` |
|
||
| 审计 | `GET /admin/audit/list`（别名 `/admin/audit/logs`） |
|
||
|
||
统一响应 `{"code":200,"msg":"ok","data":…}`；错误码语义见《[错误码](docs/api/11-errors.md)》。
|
||
|
||
## License
|
||
|
||
GPL-3.0
|