FileCodeBox（文件快递柜）完整部署方案

环境：Linux（CentOS Stream / openEuler）+ Docker + Docker Compose；镜像：lanol/filecodebox:latest；数据持久化：本地目录；数据库：内置 SQLite；可选择裸端口访问 / Nginx 反向代理域名 + HTTPS

一、前置依赖

1. 检查环境

# 查看 docker、compose
docker -v
docker compose version

如果没有安装：

# 安装 docker（yum）
yum install -y docker-ce docker-ce-cli containerd.io
systemctl enable --now docker


# 如果系统自带 compose 插件缺失
yum install -y docker-compose-plugin

防火墙放行（如果不用 Nginx，直接开放 12345；反向代理则放行 80/443）

# firewalld
firewall-cmd --add-port=12345/tcp --permanent
firewall-cmd --reload

SELinux（可选，避免挂载权限报错）

setenforce 0
# 永久关闭：修改 /etc/selinux/config，SELINUX=disabled

二、部署目录规划

统一路径：/opt/my-app/external/filecodebox

mkdir -p /opt/my-app/external/filecodebox
cd /opt/my-app/external/filecodebox

创建 docker-compose.yml，下面是生产完整版，直接覆盖使用：

version: '3.8'
services:
  filecodebox:
    image: lanol/filecodebox:latest
    container_name: filecodebox
    restart: always
    ports:
      - "12345:12345"
    volumes:
      - ./data:/app/data
    environment:
      # 务必修改为高强度密码
      - ADMIN_PASSWORD=ChangeMe@2026
      - HOST=0.0.0.0
      - PORT=12345
      - WORKERS=2
      - APP_ENV=production
      - LOG_LEVEL=warning
      - ACCESS_LOG=false
      # 如果使用 Nginx 反向代理，填入代理网段
      - FORWARDED_ALLOW_IPS=172.21.0.0/16,127.0.0.1
    logging:
      driver: json-file
      options:
        max-size: 100m
        max-file: "3"

参数说明

• WORKERS：CPU 不高保持 1～2；机器性能好可上调
• FORWARDED_ALLOW_IPS：反向代理必须配置，否则获取不到真实客户端 IP
• ADMIN_PASSWORD：后台登录密码，部署第一件事修改

三、启动服务

# 在 yml 所在目录
cd /opt/my-app/external/filecodebox


# 拉取镜像并后台启动
docker compose pull
docker compose up -d


# 查看状态
docker ps | grep filecodebox


# 查看日志
docker compose logs -f

访问：

• 裸 IP：http://你的服务器IP:12345
• 后台地址：http://IP:12345/admin，使用上面设置的 ADMIN_PASSWORD 登录

四、Nginx 反向代理方案（推荐，域名 + HTTPS）

假定域名：box.example.com，Nginx 使用 docker / 宿主机 Nginx 均可。

Nginx 配置片段

server {
    listen 80;
    server_name box.example.com;
    return 301 https://$host$request_uri;
}


server {
    listen 443 ssl;
    server_name box.example.com;


    ssl_certificate     /etc/nginx/ssl/box.example.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/box.example.com/privkey.pem;


    location / {
        proxy_pass [http://127.0.0.1:12345](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;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

如果 Nginx 也是容器部署，把 FORWARDED_ALLOW_IPS 改成 Nginx 所在网络网段。

五、后台配置（网页端）

登录 /admin，常用设置（全部存入 SQLite，无需改 yml）

• ✅ 站点名称、页面简介
• ✅ 单文件最大上传大小
• ✅ 文件/口令默认过期时间
• ✅ 是否允许匿名上传
• ✅ 是否开启上传验证码
• ✅ 存储引擎：本地 / S3 对象存储
• ✅ 自动清理过期口令与文件

文件本地存放路径：/opt/my-app/external/filecodebox/data/local 数据库：/opt/my-app/external/filecodebox/data/filecodebox.db

六、备份方案

停机备份（安全，推荐定时任务）

备份脚本：/opt/my-app/external/filecodebox/backup.sh

#!/bin/bash
set -e


APP_DIR="/opt/my-app/external/filecodebox"
BACKUP_ROOT="/backup/filecodebox"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
RETENTION_DAYS=7


mkdir -p "${BACKUP_ROOT}"


cd "${APP_DIR}"
docker compose down


# 打包 data
tar -zcf "${BACKUP_ROOT}/filecodebox-data-${TIMESTAMP}.tar.gz" ./data


# 启动
docker compose up -d


# 删除超过保留天数的备份
find "${BACKUP_ROOT}" -name "filecodebox-data-*.tar.gz" -type f -mtime +${RETENTION_DAYS} -delete

赋予权限：

chmod +x /opt/my-app/external/filecodebox/backup.sh

定时任务，每天凌晨 2 点备份：

crontab -e
# 添加一行
0 2 * * * /opt/my-app/external/filecodebox/backup.sh >> /var/log/filecodebox-backup.log 2>&1

如果业务允许风险，也可以不停机直接打包 data，但 WAL 模式下存在极小概率数据库不一致。

七、迁移方案（迁移到另一台服务器）

1. 在源服务器执行一次完整备份

2. 在目标服务器按照本方案部署，启动一次然后 down

3. 将备份包解压，覆盖目标机器 data 目录

4. 在目标目录执行：

   docker compose up -d    

所有口令、上传文件、后台配置、管理员密码完全保留。

八、升级方案

cd /opt/my-app/external/filecodebox
docker compose pull
docker compose down
docker compose up -d

升级前强烈建议先跑一次备份；该项目一般向前兼容 SQLite，极少出现破坏性变更。

九、运维常用命令汇总

# 重启
docker compose restart


# 停止
docker compose down


# 实时日志
docker compose logs -f


# 进入容器
docker exec -it filecodebox bash


# 查看数据库（宿主机安装 sqlite3）
sqlite3 ./data/filecodebox.db

十、安全建议

1. 必须修改默认 admin 密码，不要使用简单密码；
2. 如果公网暴露，优先 HTTPS + 关闭裸端口；
3. 不要把 ADMIN_PASSWORD 明文提交到版本库；
4. 定期备份；
5. 如果不需要匿名上传，后台关闭匿名上传；
6. 如果前端 Nginx，可增加 rate limit，防止刷上传；
7. data 目录做好权限，不要给全局可读。

十一、故障快速排查

• 访问不通：检查端口、防火墙、容器是否正常运行；
• 拿不到真实 IP：核对 FORWARDED_ALLOW_IPS；
• 上传报错：检查磁盘空间、data 目录读写权限；
• 数据库异常：停止服务，执行 sqlite3 filecodebox.db "VACUUM;"