FileCodeBox 部署与使用指南像取快递一样取文件的匿名口令分享服务【免费下载链接】FileCodeBox文件快递柜-匿名口令分享文本文件像拿快递一样取文件FileCodeBox - File Express Cabinet - Anonymous Passcode Sharing Text, Files, Like Taking Express Delivery for Files项目地址: https://gitcode.com/GitHub_Trending/fi/FileCodeBoxFileCodeBox 是一个轻量、现代、可完全自托管的文件分享服务核心体验是上传文件 → 获得口令 → 对方输入口令即可取件全程无需注册账号。本文将以项目英文 READMEreadme_en.md为主线结合仓库源码core/settings.py、core/storage.py、apps/base/views.py 等与官方部署文档docs/guide/getting-started.md完整讲解一键 Docker 部署、三种核心能力即传即取、按需失效、数据自主、分片上传与预签名直传、后台管理以及存储后端原理帮助你快速上手并在生产环境中稳定运行。项目定位为什么叫文件快递柜FileCodeBox 的产品隐喻是快递柜上传者把文件投递进去得到一个取件口令passcode接收者凭口令取件整个过程匿名、无需注册。README 中将其概括为A lightweight, modern, self-hosted file sharing service. No account required—upload, share the passcode, and retrieve.从技术实现上看这个模型由两部分构成分享记录模型apps/base/models.py 中的FileCodes表每条记录以唯一code口令为主键保存prefix/suffix文件名主体与扩展名、size、text文本分享内容、expired_at过期时间与expired_count剩余可领取次数分享接口apps/base/views.py 中的/share/text/与/share/file/上传后返回{code: 口令}取件方通过/share/select/、/share/download等接口凭口令领取。这种投递-口令-取件的流程适合临时文件中转、跨设备传文件、给他人发资料等场景也是项目名文件快递柜的由来。中文版说明见 readme.md。一条命令开始Docker 快速部署官方一键启动命令README 提供了最简启动方式当前仓库 VERSION 记录的版本为 2.6.1docker run -d --restart unless-stopped \ -p 12345:12345 \ -v ./data:/app/data \ -e APP_ENVproduction \ -e LOG_LEVELwarning \ --log-opt max-size10m \ --log-opt max-file3 \ --name filecodebox \ lanol/filecodebox:2.6.1逐项解读参数作用-p 12345:12345将容器内 12345 端口映射到宿主机之后访问http://localhost:12345-v ./data:/app/data挂载数据目录SQLite 数据库与本地存储文件都落在宿主机容器销毁不丢数据-e APP_ENVproduction生产环境模式默认关闭 HTTP 访问日志-e LOG_LEVELwarning日志级别只输出 warning/error 关键日志--log-opt max-size10m / max-file3限制 Docker 日志最多保留 3 个 10MB 文件防止日志撑爆磁盘--restart unless-stopped容器异常退出自动重启启动后访问http://localhost:12345完成首次初始化见下文首次初始化。README 特别提示生产环境务必固定版本号如2.6.1latest标签会跟随最新正式版升级行为不可控。环境变量一览获取配置参考 与 Dockerfile 中定义了完整的运行环境变量变量默认值说明HOST0.0.0.0服务监听地址PORT12345服务端口WORKERS1工作进程数SQLite 部署建议保持单进程APP_ENVproductionDocker运行环境生产环境默认关闭 HTTP 访问日志LOG_LEVELwarningDocker日志级别debug/info/warning/errorACCESS_LOGfalse生产环境是否启用 HTTP 访问日志调试时可设trueFORWARDED_ALLOW_IPS空反向代理场景信任的代理网段如10.0.0.0/8,172.16.0.0/12其中FORWARDED_ALLOW_IPS与安全强相关Dockerfile 的启动命令中它默认为空即只信任直连 IP防止任意客户端伪造X-Forwarded-*头绕过限流与日志记录若前面有反向代理必须显式配置代理网段。Docker Compose 方式仓库自带的 docker-compose.yml 是推荐的生产编排方式使用命名卷持久化数据version: 3 services: file-code-box: image: lanol/filecodebox:2.6.1 volumes: - fcb-data:/app/data:rw restart: unless-stopped ports: - 12345:12345 environment: - APP_ENVproduction - LOG_LEVELwarning - ACCESS_LOGfalse - WORKERS1 logging: driver: json-file options: max-size: 10m max-file: 3 volumes: fcb-data: external: false首次初始化Setup Wizard系统首次启动时尚未初始化会拦截所有请求并引导进入初始化页面。这一点在 main.py 的 HTTP 中间件中有明确实现当is_runtime_initialized()为 False 且访问的不是/setup路径时HTML 请求返回初始化页面API 请求返回 HTTP 428。初始化流程在 apps/base/config.py 的initialize_system中完成核心动作包括设置管理员密码最少 8 位MIN_ADMIN_PASSWORD_LENGTH 8写入站点名称与基础分享配置如上传大小、过期方式白名单、是否开放上传等生成独立的jwt_secret并哈希存储admin_token。简单却足够强大三大核心能力README 用三句话概括 FileCodeBox 的能力边界下面分别结合源码展开。即传即取文本与文件统一分享Files and text in one flow, with drag, paste, batch, and chunked uploads.文本与文件走两条独立接口但共享同一套口令与过期逻辑文本分享POST /share/text/apps/base/views.py表单提交text、expire_value、expire_style文本以 UTF-8 编码后大小上限为222KB超过则提示内容过多建议采用文件形式文件分享POST /share/file/apps/base/views.pyUploadFile上传先经 apps/base/services.py 的validate_file_size校验大小再经 apps/base/file_validation.py 做文件类型与魔数头校验。两者底层都由FileUploadService统一编排容量预留 → 写存储 → 建 FileCodes 记录 → 释放预留见 apps/base/services.py。前端支持拖拽、粘贴、批量与分片上传分片上传的接口细节见下文专门章节。按需失效时间、次数与永久Expire by time or retrieval count, keep forever, and clean up automatically.过期策略由管理员在后台配置白名单expire_style默认[day, hour, minute, forever, count]见 core/settings.py用户在分享时可选择方式语义实现要点day/hour/minute按绝对时间过期expired_at now 时间增量count按领取次数过期expired_count 次数每次取件原子递减forever永久保存expired_at None具体实现在 apps/base/utils.py 的get_expire_info中时间型走expired_at次数型走expired_count默认 -1 表示时间式语义。管理员还可通过max_save_seconds设置最长保存时长上限默认 0 即不限制代码兜底为 7 天超出上限的请求返回 403。自动清理由 apps/base/tasks.py 的delete_expire_files后台任务承担每 10 分钟轮询一次删除expired_at已过或expired_count归零的记录并同步调用存储后端删除实体文件、清理空的share/data目录。FileCodes.is_expired()的判定逻辑apps/base/models.py是取件前检查的依据。此外/share/download接口对次数型文件做了原子扣减apps/base/views.py防止并发取件绕过次数限制。数据自主五种存储后端Local, S3, OneDrive, WebDAV, and OpenDAL storage on infrastructure you control.存储层通过 core/storage.py 的注册表storages抽象支持五种后端由配置项file_storage默认local切换后端键实现类说明localSystemFileStorage本地磁盘默认根目录data带路径穿越防护s3S3FileStorage兼容 S3 协议的对象存储AWS S3 / MinIO / 各类 S3 兼容云onedriveOneDriveFileStorage通过 Microsoft Graph API 读写 OneDrivewebdavWebDAVFileStorage任意 WebDAV 服务器opendalOpenDALFileStorage通过 OpenDAL 统一抽象接入更多存储后端实现统一继承FileStorageInterface约定save_file / delete_file / get_file_url / get_file_response / save_chunk / merge_chunks / clean_chunks / file_exists等接口并返回与 ORM 解耦的StoredFile/StoredDownload数据对象。这意味着上传、取件、过期清理的业务流程与具体存储无关切换后端只需改配置。S3 相关配置项默认值见 core/settings.pys3_endpoint_url自定义端点为空时回退为https://{s3_hostname}s3_region_name默认autos3_signature_version默认s3v2s3_addressing_stylepath/virtual/auto默认autos3_proxy为 1 时强制走服务器中转下载不直接暴露对象存储链接。本地存储的路径由 apps/base/utils.py 的build_file_path生成按share/data/年/月/日/UUID分层存放天然利于过期任务的目录清理。值得留意的是本地后端的_resolve_safe_path会拒绝..路径穿越core/storage.py这是历史安全问题修复后保留的防御层。配合storage_limit默认 0 表示不限可以实现容量配额上传前经 apps/base/quota.py 的reserve_storage做原子预留超限返回 HTTP 507预留记录保存在StorageReservation表中由后台任务定期清理过期预留。配额计算用 SQL 聚合而非全表拉取避免大表场景下的性能退化。分片上传与预签名直传大文件与多云场景分片上传chunk API大文件支持分片上传接口统一挂在/chunk前缀下apps/base/views.pyPOST /chunk/upload/init/声明文件名、总大小、分片大小与整文件哈希服务端校验总大小是否超过upload_size默认 10MB可在后台调大并做容量预留PUT /chunk/upload/chunk/{upload_id}/{chunk_index}逐个上传分片每个分片落盘时计算 SHA-256 哈希并与声明值比对core/storage.py支持断点续传已上传分片直接返回skipped: trueGET /chunk/upload/status/{upload_id}查询已上传分片列表与进度POST /chunk/upload/complete/{upload_id}合并分片按序校验哈希后生成最终文件与分享口令DELETE /chunk/upload/{upload_id}取消上传并清理临时分片。分片会话默认 24 小时内有效chunk_expire_hours见 core/settings.py超时由 apps/base/tasks.py 的clean_incomplete_uploads任务每小时清理一次。存储层对分片合并做了后端级优化本地与 OneDrive 用临时文件流式合并S3 则复用原生 multipart upload APIcore/storage.py避免把整个文件加载进内存。预签名上传presign API预签名上传/presign前缀apps/base/views.py解决大文件绕服务器直传对象存储的需求官方文档见 docs/api/presign-upload.mddirect直传模式仅 S3 后端支持。POST /presign/upload/init返回一个 15 分钟有效的 S3 预签名 PUT URLPRESIGN_SESSION_EXPIRES 900见 apps/base/services.py客户端直接上传到对象存储之后POST /presign/upload/confirm/{upload_id}确认并换取分享口令proxy代理模式其他后端本地、WebDAV、OneDrive、OpenDAL返回PUT /presign/upload/proxy/{upload_id}由服务器转存。会话元数据记录在PresignUploadSession表apps/base/models.py过期会话由 apps/base/tasks.py 每 15 分钟清理一次并回收未完成的直传文件。从分享到管理后台管理README 用一组截图展示了从分享到管理的完整界面分享页、管理仪表盘、管理登录、文件管理与系统设置。仓库 docs/public/screenshots 目录提供了与之一致的界面截图后台管理功能位于 apps/admin 应用views.py/services.py/dependencies.py管理端的安全设计包括管理员认证admin_token以哈希形式存储initialize_system中调用hash_password登录签发 JWTadmin_session_expire默认 30 天core/settings.py 中最小 1 天、最大 365 天并支持trusted_proxies白名单多维度 IP 限流登录、上传、取件、元数据查询四类限流器login_count/login_minute、upload_count/upload_minute、error_count/error_minute在 apps/base/config.py 的_sync_ip_limits中与配置同步。注意限流是进程内状态server_workers 1时各进程独立计数阈值会随 worker 数放大main.py 启动时会给出警告因此文档建议保持单 worker配置热更新每次请求由中间件读取数据库配置带 2 秒 TTL 缓存见 apps/base/config.py后台改设置即时生效无需重启。技术栈与架构一览README 底部标注了核心技术栈FastAPI·Vue 3·SQLite·Docker·S3·WebDAV·Dark Mode。后端FastAPI Tortoise ORM默认 SQLite入口 main.py 注册了分享、分片、预签名、管理四组路由lifespan中启动三个后台任务过期清理、分片清理、预签名会话清理前端Vue 3 构建的多主题2023 / 2024由 Dockerfile 在镜像构建阶段克隆前端仓库编译后打入镜像主题选择配置themes_select默认themes/2024部署Docker 多阶段构建Node 20 构建前端 → Python 3.12 运行后端依赖从带哈希的requirements.lock.txt锁定安装保证可复现构建。继续了解仓库文档导航仓库内提供的中英文文档可深入阅读部署、初始化与升级docs/guide/getting-started.md英文版 docs/en/guide/getting-started.md本地与对象存储配置docs/guide/storage.md限流、会话与访问保护docs/guide/security.md上传方式详解docs/guide/upload.mdAPI 参考docs/api/index.md预签名上传接口docs/api/presign-upload.md发布记录docs/changelog.md许可与使用边界FileCodeBox 基于 LGPL-3.0 许可发布见 LICENSE欢迎提交 Issue 与 Pull Request。README 的免责声明同样适用于所有使用者仅供合法的文件与文本分享场景使用请勿上传、存储或传播违法、侵权或未经授权的内容部署者需自行承担部署安全、数据合规与内容管理责任。由于服务默认对公网开放上传建议部署后立即完成管理员密码初始化并结合限流、反代 IP 白名单与存储配额等机制加固生产实例。【免费下载链接】FileCodeBox文件快递柜-匿名口令分享文本文件像拿快递一样取文件FileCodeBox - File Express Cabinet - Anonymous Passcode Sharing Text, Files, Like Taking Express Delivery for Files项目地址: https://gitcode.com/GitHub_Trending/fi/FileCodeBox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考