Webman 的 formFile() 仅负责接收临时文件并返回本地路径，无法解决跨节点一致性、元数据持久化、分布式协议对接及内容校验等问题，故不能单独实现分布式文件管理。
Webman 本身不提供分布式文件管理能力，必须依赖外部存储服务（如 MinIO、RustFS、HDFS）和自定义逻辑来实现高可用。直接用 move_uploaded_file 写本地磁盘或 NFS 共享目录，无法满足跨节点一致性、故障自动转移、秒传、断点续传等核心需求。
为什么不能只靠 Webman 的 formFile() 实现分布式文件管理
formFile() 只负责安全接收单次上传的临时文件，它返回的是一个 UploadFile 实例，其 getRealPath() 指向的是当前 Worker 进程所在机器的临时目录（如 /tmp/phpXXXXXX）。在多 Worker 或多机器部署下：
- 临时文件只存在于本机，其他 Worker 无法访问
- 没有元数据持久化（如文件哈希、分片记录、上传状态），断点续传无法恢复
- 未对接任何分布式存储协议（S3、WebDAV、HDFS API），无法写入远程集群
- 默认不校验文件内容一致性（如 MD5/SHA256），秒传无依据
所以，formFile() 是起点，不是终点 —— 它只解决“怎么拿到文件”，不解决“文件存哪、怎么管、怎么查、怎么恢复”。
MinIO + Webman：最实用的 S3 兼容方案
MinIO 是目前 Webman 生态中最成熟、文档最全的集成对象存储选项，tinywan/storage 扩展已封装好 S3 SDK，适配 Webman 生命周期。
关键配置项必须显式设置，否则会连不上或权限拒绝：
Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。
-
endpoint必须带协议和端口（如http://minio:9000），不能只写域名 -
use_path_style_endpoint设为true，否则 Webman 下某些 S3 SDK 版本会拼错 URL 导致 403 -
bucket需提前在 MinIO 控制台创建，且确保region与 MinIO 配置一致（默认us-east-1） - AccessKey/SecretKey 要通过环境变量注入，避免硬编码在配置文件中
上传示例（非简单 putObject，而是带流式处理和错误回滚）：
use Aws\S3\S3Client;
use Webman\Http\Context;
function uploadToMinIO(Context $c) {
$file = $c->formFile('file');
if (!$file) return $c->json(['code' => 400, 'msg' => 'no file']);
$s3 = new S3Client([
'version' => 'latest',
'region' => 'us-east-1',
'endpoint' => $_ENV['MINIO_ENDPOINT'],
'use_path_style_endpoint' => true,
'credentials' => [
'key' => $_ENV['MINIO_ACCESS_KEY'],
'secret' => $_ENV['MINIO_SECRET_KEY'],
],
]);
$key = 'uploads/' . date('Y/m/d/') . uniqid() . '_' . basename($file->getClientFilename());
try {
$s3->putObject([
'Bucket' => $_ENV['MINIO_BUCKET'],
'Key' => $key,
'Body' => fopen($file->getRealPath(), 'rb'),
'ACL' => 'private',
]);
return $c->json(['code' => 0, 'url' => "https://cdn.example.com/{$key}"]);
} catch (\Exception $e) {
error_log('MinIO upload failed: ' . $e->getMessage());
return $c->json(['code' => 500, 'msg' => 'upload failed']);
}
}
RustFS / HDFS 接入要注意的底层差异
RustFS 和 HDFS 不是 S3 协议，接入时不能复用 MinIO 的配置和 SDK。
- RustFS 提供 REST API，但需手动构造
PUT /object/{bucket}/{object}请求，并处理签名（它用access_key/secret_key做 HMAC-SHA256 签名，不是 AWS v4） - HDFS 必须走 WebHDFS REST 接口（如
POST /webhdfs/v1/path?op=CREATE），上传需两步：先发请求获取重定向地址，再用PUT流式上传；且需开启dfs.webhdfs.enabled=true并配置代理用户权限 - 两者都不支持开箱即用的分片合并逻辑，大文件上传必须在 Webman 层自行实现分片接收、MD5 校验、状态记录（建议用 Redis 存
upload_id → {parts: [...], uploaded: 3}）
也就是说：换存储后端 ≠ 换个配置就行，HTTP 方法、认证方式、错误码语义、重试策略都得重写。
高可用真正依赖的是架构设计，不是框架功能
Webman 的常驻内存和协程只提升单节点吞吐，不解决分布式可靠性问题。真正的高可用来自三层协同：
- 存储层：MinIO 多节点部署（至少 4 节点纠删码）、RustFS 集群模式、HDFS NameNode HA
- 接入层：Webman 多实例 + Nginx 负载均衡，配合健康检查（如
/health返回status: ok） - 元数据层：文件信息（原始名、大小、哈希、归属用户、过期时间）必须存在独立数据库（MySQL/PostgreSQL），不能只存对象存储的 Key
最容易被忽略的一点：所有上传路径生成逻辑（如 uploads/Y/m/d/xxx.jpg）必须是确定性的、可重现的。一旦依赖随机数或本地时间戳，在多实例间就可能产生冲突或不可追溯的路径 —— 这会让后续的清理、审计、CDN 预热全部失效。
