FileShare/README.md

# FileShare

文件快传

数据库**默认 SQLite 零依赖**（modernc.org/sqlite 纯 Go 驱动，数据文件 `./data/fileshare.db`），
可选切换 Postgres（`FCB_DB_DRIVER=postgres` + DSN）；Redis 为**可选**增强（未配置时自动降级为进程内存缓存）。
存储引擎支持 **本地 / S3 / WebDAV**（运行时热切换，健康检查通过才生效；WebDAV 重点优化：流式、Range、重试、连接复用）。
26.9 起支持**上下行带宽限速**（`upload_rate` / `download_rate` 字节/秒，0=不限速，管理端改后立即生效）。

**26.9 新增**：上下行带宽限速（见 [专题](docs/api/13-bandwidth.md)）· 站点对外域名、自定义提取码（26.9）·
本地/S3/WebDAV 存储引擎 26.9 运行时热切换。

| 目录 | 说明 |
|---|---|
| `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`（26.9 起不再使用远程 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/) |
| ↳ **26.9 带宽限速**（`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`（26.9 需求 ⑧） |
| `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` 等）、26.9 展示与通知
（`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`，及 26.9 上限键 `max_save_count`、
`max_file_size`）、限流（`uploadCount/uploadMinute`、`errorCount/errorMinute`、
`loginCount/loginMinute`）、安全（`adminSessionExpire`；`admin_token`/`jwt_secret` 由系统管理）。
26.9 带宽（`upload_rate` / `download_rate`，字节/秒，0=不限速）。

完整键表与默认值见《[环境变量与配置项](docs/api/10-config.md)》；
26.9 带宽限速专题《[带宽限速](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