FileCodeBox文件快递柜部署
FileCodeBox + 阿里 ESA + Caddy 部署与排错笔记
一、 架构设计与流量拓扑
为了在 1核 1G 内存 的低配云服务器上实现高可用、高安全性且不爆内存的“文件/文本快递柜”服务，整体网络与流量拓扑设计如下：
[ 用户 / 浏览器 ]
│
│ 第一段：HTTPS (443 端口) ➔ 全程 TLS 加密，安全绿锁
▼
[ 阿里云 ESA 边缘节点 ]
│
│ 第二段：HTTP (80 端口) + Range 分片优化回源
▼
[ Caddy 反向代理 (源站) ]
│
│ 第三段：容器内网回源 (127.0.0.1:12345)
▼
[ FileCodeBox 容器 (Podman) ]
二、 阿里云 ESA (边缘安全加速) 配置指南
1. 核心回源参数设置
在阿里云 ESA 域名配置的“回源配置”模块中，主要改回源 HOST Range 分片和按以下规则设置各配置项：
| 配置项 | 推荐设置 | 作用与原理 |
|---|---|---|
| 回源 HOST | 跟随请求 HOST | 将客户端请求的域名完整透传给 Caddy，确保 Caddy 能准确识别并匹配虚拟主机。 |
| 回源协议和端口 | HTTP / 80端口 | 实现 SSL 卸载。将 TLS 握手交给 ESA 节点，减轻源站 1G 内存服务器计算负担，彻底规避 525 等 TLS 握手错误。 |
| 回源 SNI | 默认 / 不配置 | 由于回源协议已设为 HTTP 80 端口，TLS SNI 标头不生效，保持默认即可。 |
| DNS 记录 (源站改写) | 保持默认 | 填入云服务器实际的公网 IP 地址，指向源站。 |
| Range 分片 | 开启（建议 2MB - 4MB） | 优化大文件传输，匹配 FileCodeBox 的切片机制，减轻源站瞬时内存与带宽压力。注意： 须按后缀排除 .css / .js 等静态资源，防止样式切片异常导致网页崩塌。 |
| 回源超时时间 | 30s - 60s | 避免大文件切片传输时源站响应较慢导致频繁触发 504 回源超时。 |
| 回源 301/302 跟随 | 关闭 (Disable) | 保持默认关闭，防止源站返回重定向指令时触发非必要的重定向死循环。 |
三、 Caddy 反向代理配置
Caddy 用于接收 ESA 节点回源的 HTTP 请求，并附带客户端真实 IP 标头转发至本地 FileCodeBox 服务。
1. Caddyfile 配置文件
yourdomain.com {
# 监听纯 HTTP 80 端口，前端 SSL 由阿里 ESA 处理
reverse_proxy 127.0.0.1:12345 {
# 正确透传真实 IP，防止 FileCodeBox 触发频控/密码锁死
header_up Host {host}
header_up X-Real-IP {remote_host}
header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme}
}
}
2. 生效命令
caddy reload
四、 后端存储方案分析与选择
FileCodeBox 支持多种底层存储方式，不同方式的技术特点与选型建议如下：
1. 存储方案对比
| 存储类型 | 核心技术原理 | 优点 | 缺点 / 风险 | 适用的场景 |
|---|---|---|---|---|
| 本地存储 (Local) | 保存在容器映射目录 /opt/filecodebox/data | 零配置、传输延迟最低 | 易爆盘，需强依赖后台过期清理策略 | 个人小文件、剪贴板文本传输 |
| S3 对象存储 | 通过标准 S3 API 存入云端 Bucket（如 R2/OSS/七牛） | 扩展性强，配合预签名 URL 不占用服务器硬盘 | 部分厂商会按下载流量计费（须注意扣费陷阱） | 长期文件分享、大文件存储 |
| WebDAV 存储 | 基于 HTTP 扩展协议读写远程网盘/NAS | 可复用现网盘/NAS 资源，无需额外花钱 | 受限于网盘提供方的 API 频率限制 | 挂载已有网盘、私有云存储 |
2. S3 / 免费云存储选型策略
- 七牛云 (Kodo)： 国内节点速度快，提供永久 10GB 存储 + 10GB/月 流量。前提： 域名必须完成工信部备案。
- Cloudflare R2： 全球免出站流量费，提供 10GB 免费存储。配合阿里 ESA 边缘节点缓存，可实现国内高速访问且无欠费风险。
- 阿里云 OSS / 腾讯云 COS： 谨防免费额度陷阱。此类服务仅免存储费，外网下载流量按量计费，不建议公开分享使用。
3. 通过 Alist 扩展网盘为 WebDAV 后端
若需复用阿里云盘、百度网盘等资源，可通过挂载轻量级 Alist 容器实现：
部署 Alist 容器：
mkdir -p /opt/alist/data podman run -d --name=alist --restart=always -p 5244:5244 -v /opt/alist/data:/opt/alist/data xhofe/alist:latest获取初始密码：
podman exec -it alist ./alist admin- FileCodeBox 对接 WebDAV 参数配置：
- WebDAV 地址：
[http://127.0.0.1:5244/dav](http://127.0.0.1:5244/dav)（走本地环回网络，速度最快） - 根路径：
/netdisk（须与 Alist 中的存储挂载路径一致） - 账号/密码： Alist 后台设定的管理员凭据
五、 故障排查与运维指南
故障 1：页面样式崩塌，所有元素缩在屏幕左上角
- 故障原因： ESA 开启了针对静态资源（
.css/.js）的 Range 分片，导致响应头为206 Partial Content，CSS 资源加载不完整。 - 排查与解决：
- 在阿里 ESA 中将 Range 分片规则调整为仅对大文件（如大于 5MB）生效，排除静态资源。
- 浏览器按
F12，长按刷新按钮选择“清除缓存并硬性重新加载”。
故障 2：管理员输入密码无法登录 / 右上角弹出报错
- 故障原因： 未正确传递
X-Forwarded-For真实 IP 头，所有请求均显示为内网代理 IP（如10.89.0.x），触发了 FileCodeBox 的安全限流锁死。 - 排查与解决：
- 检查 Caddyfile 中是否配置了
header_up X-Forwarded-For {remote_host}。 强制重置管理员密码：
podman exec -it filecodebox python3 main.py --reset-password
故障 3：本地存储空间防爆配置
- 排查与解决：
- 登录后台
/#/admin，进入【系统设置】->【上传限制】，设定“单文件最大限制”（如 50MB）。 - 进入【安全/清理设置】，开启默认“24小时过期”及“最大下载次数限制”，确保系统按时物理销毁过期文件。