SKYMirror
6f1a925833
- 数据库默认文件 filecodebox.db → fileshare.db（config.go 默认值与全部文档/编排同步）
- Go module filecodebox → fileshare（全部 import 同步，build/vet/test 全绿）
- 应用版本 APP_VERSION 2.5.6 → 26.9（health 接口已验证返回 26.9）
- deploy 编排统一：compose 项目名、Postgres 默认凭据、minio 桶名、env 注释
- JWT issuer、存储临时目录前缀、web 包名同步 fileshare
- CI：镜像 tag 以 APP_VERSION 为唯一版本源，main/tag 推送即发布
${VER} + latest；tag 触发时校验 tag 名与 APP_VERSION 一致，防错版
- 本地开发库文件已改名 fileshare.db（含 -shm/-wal 清理）
147 lines
7.5 KiB
Markdown
147 lines
7.5 KiB
Markdown
# FileShare
|
||
|
||
文件快传
|
||
|
||
数据库**默认 SQLite 零依赖**（modernc.org/sqlite 纯 Go 驱动，数据文件 `./data/fileshare.db`），
|
||
可选切换 Postgres（`FCB_DB_DRIVER=postgres` + DSN）；Redis 为**可选**增强（未配置时自动降级为进程内存缓存）。
|
||
存储引擎支持 **本地 / S3 / WebDAV**（运行时热切换，健康检查通过才生效；WebDAV 重点优化：流式、Range、重试、连接复用）。
|
||
|
||
| 目录 | 说明 |
|
||
|---|---|
|
||
| `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/*.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` 由系统管理）。
|
||
|
||
完整键表与默认值见《[环境变量与配置项](docs/api/10-config.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
|