FileCodeBox：用提取码完成临时文件交付

临时把一份文件交给同事或客户时，注册网盘账号、配置共享目录和管理长期权限往往比传文件本身更费事。FileCodeBox 把交付过程压缩成两个动作：发送者上传文件或文本并拿到提取码，接收者输入提取码取件。文件可以按时间或下载次数失效，服务和数据则由部署者掌握。

这种轻量也意味着边界很明确。FileCodeBox 默认允许匿名上传，更适合临时中转、家庭或小团队使用；公开到互联网之前，必须限制大小、频率和保存期限，并在 HTTPS 反向代理后完成首次初始化。

GitHub 仓库信息

信息	内容
项目标题	FileCodeBox
项目描述	文件快递柜：无需注册即可通过匿名提取码分享文本和文件，让接收者像取快递一样取件。
GitHub 仓库	vastsa/FileCodeBox
官网地址	https://fcb-docs.aiuo.net/
主要开发语言	Python 99.16%、Dockerfile 0.84%
开源许可证	LGPL-3.0
最近代码更新	2026-09-16（GitHub pushed_at，核对日期：2026-09-17）

一次分享能完成什么

FileCodeBox 把文件与文本统一成一条“上传—生成提取码—提取—失效”链路。发送者可以让内容在几分钟、几小时、几天后失效，也可以限定下载次数；接收者不需要账号。对于会议资料、日志片段、一次性交付包，这比维护长期共享空间更直接。

三个机制决定了这套体验：

• 提取码是交付入口：普通提取码通常是 6 位数字，永久分享使用字母数字组合。提取码减少了接收步骤，但不是高强度访问控制；敏感文件仍应先加密。
• 生命周期跟着分享规则走：后台任务会清理过期分享，管理员还能限制最长保存时间。公开服务若保留“永久”选项，存储会从临时中转逐渐变成长久托管。
• 存储后端可以替换：默认文件和 SQLite 数据库都在本地 data/，也可把新文件写入 S3、WebDAV、OneDrive 或 OpenDAL。切换后端不会自动迁移历史文件，变更前要先设计迁移与回退。

FileCodeBox 还有一个容易被低估的用途：把 NAS 目录只读挂载到 /app/data/local 后，管理员可以直接给已有文件生成提取码，不需要先下载再上传。这个“本地分享”只创建引用和分享记录，提取码过期不会删除 NAS 原文件。

适合与不适合的场景

FileCodeBox 适合个人、家庭 NAS、小团队和临时交付站点。部署者愿意维护一个 Web 服务，希望接收者免注册，并且能接受“知道提取码即可访问”的模型时，FileCodeBox 的使用成本很低。

以下需求应考虑其他方案：

• 需要目录同步、协同编辑、版本历史和细粒度成员权限时，Nextcloud 一类协作平台更合适；
• 只在局域网设备间传输文件时，LocalSend 不需要维护服务器；
• 需要长期管理服务器目录而不是临时交付时，文件管理器更直接；
• 需要把文件作为应用基础设施保存时，应直接使用 S3 兼容对象存储，并由业务系统控制授权。

这里的关键判断是：FileCodeBox 不是一个缩小版网盘。项目主动舍弃账号协作和目录组织，换来低摩擦的临时交付。

Docker Compose 部署

下面使用当前稳定版 2.7.0。官方 Compose 已把镜像固定为 lanol/filecodebox:2.7.0，容器端口为 12345，持久数据目录为 /app/data。配置适合单机运行；SQLite 模式下保持一个 worker。

前置条件与工作目录

准备可用的 Docker Engine 和 docker compose 插件，然后在计划长期保留的目录中创建 compose.yaml：

mkdir filecodebox
cd filecodebox

services:
  file-code-box:
    image: lanol/filecodebox:2.7.0
    restart: unless-stopped
    ports:
      - "127.0.0.1:12345:12345"
    volumes:
      - fcb-data:/app/data
    environment:
      APP_ENV: production
      LOG_LEVEL: warning
      ACCESS_LOG: "false"
      WORKERS: "1"
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  fcb-data:

与上游示例相比，这里把宿主机端口固定到 127.0.0.1。本机浏览器可以直接访问；需要局域网访问时，应绑定具体内网地址并用防火墙限制来源；公网入口应交给同机 HTTPS 反向代理。

启动和首次初始化

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100 file-code-box
curl --fail --output /dev/null http://127.0.0.1:12345/

预期结果是 file-code-box 为运行状态，HTTP 请求成功，日志没有持续的数据库初始化错误。第一次打开 http://127.0.0.1:12345 时，系统会显示初始化页面，不会生成默认管理员密码。请在站点暴露给其他人之前完成初始化，并设置至少 16 个字符的独立管理员密码。

初始化后，管理入口位于 /admin。默认首页不显示入口，这只减少被扫描的提示，并不替代身份认证、TLS 或网络限制。

完成第一次有效分享

部署验收不应停在“首页能打开”。用两个浏览器会话走完一条交付链：

1. 在普通页面上传一个无敏感信息的测试文件；
2. 选择按下载次数失效，并设置为 1 次；
3. 记下系统返回的提取码；
4. 在另一个无登录状态的浏览器窗口输入提取码；
5. 下载文件并确认内容正确；
6. 再次使用同一提取码，确认次数用完后无法继续取件。

这个结果同时证明上传、数据库记录、提取、下载计数和失效逻辑可用。若只测试文本分享，还不能证明文件存储路径和反向代理上传限制正确。

验证持久化

再上传一个保留时间较长的测试文件，然后重建容器：

docker compose down
docker compose up -d

重新进入后台，分享记录和文件应仍然存在。命名卷 fcb-data 保存 filecodebox.db、本地对象和运行配置；执行 docker compose down -v 会删除这组本地数据。

请求背后的数据流

Mermaid 流程图

正在准备渲染...

查看源码

flowchart LR
    Sender[发送者] -->|上传文件或文本| API[FastAPI 分享接口]
    API --> Rules[大小、频率与过期规则]
    Rules --> DB[(SQLite: 分享记录与配置)]
    Rules --> Storage{存储适配器}
    Storage --> Local[(data/share)]
    Storage --> Remote[S3 / WebDAV / OneDrive / OpenDAL]
    API -->|返回提取码| Sender
    Receiver[接收者] -->|输入提取码| API
    Cleaner[后台清理任务] --> DB
    Cleaner --> Storage

应用启动时先初始化 SQLite、执行迁移、加载配置，再启动过期文件和未完成分片的清理任务。限流计数保存在进程内，因此 SQLite 默认配置使用 WORKERS=1：增加 worker 会让每个进程各自计数，实际阈值随进程数放大。需要横向扩展时，限流与 SQLite 都要先改造成共享状态，不能只把 worker 数量调大。

管理公开服务

公开服务最先要收紧的不是界面，而是匿名入口的资源边界。在 /admin 的系统设置中至少核对：

配置	公开服务建议	原因
upload_size	与反向代理请求体上限一致	避免代理与应用给出冲突结果
upload_count / upload_minute	按真实访问量压测后设置	限制单 IP 上传滥用
error_count / error_minute	收紧但考虑共享出口	降低提取码暴力尝试
expire_style	移除 forever	避免匿名内容无限累积
max_save_seconds	设置最长保留期	给清理任务明确上限
show_admin_addr	保持 0	不在首页暴露管理入口

反向代理需要终止 TLS，并把 client_max_body_size 等请求体限制设为略高于应用允许的最大文件。真实 IP 只有在代理会清洗客户端提交的转发头、应用又只接受代理直连时才可信；Docker 镜像通过 FORWARDED_ALLOW_IPS 控制 Uvicorn 信任范围，不要把该变量设置成无条件信任所有来源。

匿名提取码适合便利交付，不适合传递未加密的高敏感资料。提取码可被转发，管理员也能访问分享记录；有合规或保密要求时，应先进行客户端加密，并为站点增加独立的身份认证层。

选择存储后端

默认本地存储把文件放在 data/share/data/，SQLite 位于 data/filecodebox.db。这是最容易备份和恢复的单机方案。

数据量增长后可以在管理面板选择 S3、WebDAV、OneDrive 或 OpenDAL。S3 配置需要 endpoint、bucket、region、签名版本和专用凭据；bucket 应提前创建，凭据只授予所需对象权限。若 s3_proxy=0，客户端可能直接访问对象存储地址；若设为 1，下载由 FileCodeBox 中转，带宽压力回到应用服务器。

修改 file_storage 只影响后续读写策略，已有文件不会自动迁移。正确顺序是先备份数据库和旧存储、验证新存储、迁移对象并校验，再切换配置。旧对象全部验收前不要删除原存储。

NAS 的只读分享可以在 Compose 中增加绑定挂载：

services:
  file-code-box:
    volumes:
      - fcb-data:/app/data
      - /srv/nas-share:/app/data/local:ro

把 /srv/nas-share 换成真实宿主机路径。后台“本地分享”会引用文件而不复制；删除分享记录不会删除 NAS 原文件，但删除或移动原文件会让提取码失效。

备份、升级与回滚

使用本地存储时，恢复单元是完整的 fcb-data 卷和当前 compose.yaml。备份前停止上传并停止容器，保证 SQLite、WAL 文件和对象目录处于同一时点；恢复后检查管理员登录、分享列表，并实际提取一个文件。命名卷的通用备份方法见 Docker 备份与恢复数据。

使用外部存储时，还要分别备份数据库和对象存储。数据库保存分享记录、提取码和配置；对象存储保存文件内容，缺少任何一边都不是完整恢复。S3 凭据、WebDAV 密码等敏感配置也在数据库配置中，备份必须加密并限制访问。

升级前阅读目标 Release，固定新镜像 tag，并做一致性备份。应用启动时会自动执行按文件名排序的数据库迁移；因此升级失败后，单独把镜像改回旧 tag 未必足够，还要恢复升级前数据库和对应对象快照。

docker compose pull
docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 file-code-box

升级后重复“管理员登录—上传—提取—过期”验收，并确认原有分享仍可下载。Compose 的版本记录、更新与回退步骤可参考 Docker Compose 服务生命周期。

常见问题

症状	定位	修复与再验证
首次访问一直返回未初始化	查看日志和 /app/data 写权限	修复卷权限，重新打开初始化页并完成密码设置
大文件在代理层被拒绝	比较代理请求体限制与 upload_size	调整两端上限，重新上传同一测试文件
多 worker 后限流变松	检查 WORKERS 和日志警告	SQLite 单机恢复为 1；需要扩展时改用共享限流方案
切换 S3 后旧提取码下载失败	检查记录指向的旧存储和对象是否已迁移	恢复旧存储或完成带校验的迁移，再做提取验收
磁盘持续增长	查看是否允许永久分享、清理任务日志和过期规则	设置最长保存期，确认清理完成后再核对存储量
反向代理后所有请求像来自同一 IP	检查可信代理范围与转发头清洗	只信任真实代理地址，重新验证限流和访问日志

版本与验证说明

这份指南基于 FileCodeBox v2.7.0 和对应源码提交，核对日期为 2026-09-17。官方 Compose、Dockerfile、快速开始、安全、存储和管理文档共同确认了镜像、端口、卷、单 worker、首次初始化和存储后端事实。

本次没有拉取镜像、启动容器或执行备份恢复，只完成官方来源与固定提交的静态核对。读者仍需在目标主机执行文中的 HTTP、上传、提取和持久化验收。

参考资料

• FileCodeBox README
• FileCodeBox 快速开始
• FileCodeBox 配置说明
• FileCodeBox 存储配置
• FileCodeBox 安全设置
• FileCodeBox v2.7.0 Release
• FileCodeBox 许可证