FileShare/README.md

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 新增：上下行带宽限速（见 专题）· 站点对外域名、自定义提取码（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 自定义》。

快速开始（docker compose）

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。
• 详见《部署编排》与《存储引擎配置》。

本地开发

前置：Go 1.27.1、Node 20（Postgres 16 仅 Postgres 模式需要）。

# 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/
↳ v3.2 带宽限速（upload_rate / download_rate，管理端改后立即生效）	docs/api/13-bandwidth.md
OpenAPI 3.0 规范 + Swagger UI	站内 /openapi，源文件 docs/openapi.yaml
后端设计契约	server/README.md
前端说明与渲染约定	web/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=不限速）。

完整键表与默认值见《环境变量与配置项》； v3.2 带宽限速专题《带宽限速》； 修改接口见《管理后台 API》（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。 详见《审计日志查询》。

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":…}；错误码语义见《错误码》。

License

GPL-3.0