【实用的开源工具】FileCodeBox：用提取码分享文件和文本，像快递柜一样简单

「实用的开源工具」系列：我只收集值得用的开源项目，写清楚它能做什么、怎么部署、有哪些坑，并在文末标明出处。内容整理自官方文档，核对日期 2026-10-30，具体版本以官方为准。

项目信息卡

它能做什么

图：上传页面。来自 FileCodeBox 官方仓库，截的是作者的演示站，图里的“最大 20MB”是演示站的设置，默认值是 10MB。

图：管理后台仪表盘。来自 FileCodeBox 官方仓库，数字是作者演示站的数据，不是默认状态。

• 提取码取件：上传后生成口令，把口令发给对方，对方在网页里输入就能下载，不用装 App，不用注册。
• 文件和文本都能分享：不只是文件，一段文字也能用提取码发出去。
• 自动失效：可以按时间、按下载次数过期，也可以永久保存，过期内容自动清理。
• 多种上传方式：拖拽、粘贴、批量、分片上传（分片需要管理员开启）。
• 多种存储：本地、S3、OneDrive、WebDAV、OpenDAL。
• 后台管理：查看文件列表、系统信息、活动记录和配置。

典型用法：给客户发交付包、临时中转一个大文件，不想走网盘也不想暴露账号。

部署

建目录 /opt/filecodebox，写 compose.yaml（基于官方示例，我把端口绑定到本机，并固定了版本号）：

services:
  file-code-box:
    image: lanol/filecodebox:2.8.5
    restart: unless-stopped
    volumes:
      - fcb-data:/app/data:rw
    ports:
      - "127.0.0.1:12345:12345"
    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:
    external: false

启动：

cd /opt/filecodebox
docker compose up -d

官方建议生产环境固定版本号（上面是 2.8.5），latest 指向最新正式版。WORKERS=1 是官方在环境变量表里的建议：用 SQLite 时保持单进程。

第一次访问：设置管理员密码

官方安全文档的说法是：FileCodeBox 首次启动时不会生成默认管理员密码，要在浏览器里打开站点，按初始化页面自己设置。

1. 打开首页，完成初始化，设置管理员密码。
2. 管理后台的地址是 /#/admin，用刚才设的密码登录。
3. 首页默认不显示管理入口（show_admin_addr 默认为 0），公开服务建议保持这样。

Nginx 反向代理

官方安全文档建议让 Nginx 的请求体大小和上传限制保持一致，并传递真实 IP：

server {
    listen 443 ssl http2;
    server_name file.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:12345;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

几个要调的配置

这些在后台“系统设置”里改，名字和默认值取自官方安全文档与上传文档：

踩坑清单

1. 没有默认密码，也别指望能找回。 第一次访问的人可以设置管理员密码，所以部署后要马上自己打开并完成初始化，不要把还没初始化的站点晾在公网上。
2. admin_token 是哈希存储的。 官方提醒不要往数据库里直接写明文，否则管理员登录会失效。改密码走后台页面。
3. 默认只能传 10MB。 超过会返回 403，提示大小超限。要同时改 upload_size 和 Nginx 的 client_max_body_size，两个都要放大，少改一个都会失败。
4. 经过 Cloudflare 时，大文件可能被拦。 据我所知，Cloudflare 免费套餐对单次请求体有大小限制（我没有重新核对当前数值，请以 Cloudflare 官方文档为准）。上传大文件时，可以开分片上传，或者给文件站用不走代理的域名。
5. 速率限制依赖真实 IP。 官方说明是按 X-Real-IP、X-Forwarded-For、直连 IP 的顺序取。如果前面还有 Cloudflare，上面 Nginx 示例里的 $remote_addr 会是 Cloudflare 的地址，所有访客可能被当成同几个 IP，限流和锁定会互相误伤。需要自己配置 Nginx 的真实 IP 模块，或者改用 CF-Connecting-IP，配完要测试。
6. 默认的错误次数限制偏松。 官方文档提醒，默认配置允许每个 IP 一分钟内出错 10 次，公开服务可以收紧，但要避免误伤共用出口的用户。
7. 别开 forever，也别不设过期。 公开的文件站，最后总会变成别人的免费网盘。过期策略和最长保存时间一定要设。
8. 多进程会出问题。 官方建议 SQLite 部署保持 WORKERS=1，不要为了“更快”调大。
9. 备份的是 fcb-data 这个卷。 数据库和文件都在里面。升级前先备份，并固定版本号。
10. 内容合规要自己负责。 官方 README 写明项目仅供合法的文件与文本分享场景使用，部署和内容管理的责任在使用者。对外开放前，想清楚谁能传、传了什么你能不能管。
11. Docker 发布的端口会绕过 ufw 之类的防火墙。 所以我绑定到了 127.0.0.1。

出处

• FileCodeBox 官方仓库（Docker 命令、许可证、功能）
• 官方 Compose 文件
• 官方文档：快速开始
• 官方文档：安全设置
• 官方文档：文件上传