基于Webman构建高可用的分布式文件管理系统-php教程-PHP中文网

webman 的 formfile() 仅负责接收临时文件并返回本地路径，无法解决跨节点一致性、元数据持久化、分布式协议对接及内容校验等问题，故不能单独实现分布式文件管理。

基于webman构建高可用的分布式文件管理系统

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

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 方法、认证方式、错误码语义、重试策略都得重写。