Laravel 不原生支持七牛私有云，因官方驱动及主流扩展包仅适配公有云 API；私有云需手动改造 SDK 并自定义 Flysystem Adapter，注意 API 地址、鉴权、上传逻辑等差异。
直接说结论：Laravel 本身不原生支持七牛云私有云（即企业自建的 Qiniu Private Cloud，非公有云 qiniu.com 域名体系），官方 flysystem-qiniu 驱动和主流扩展包（如 overtrue/laravel-filesystem-qiniu、zgldh/qiniu-laravel-storage）均只适配七牛公有云 API（api.qiniu.com 及配套域名规则）。若你对接的是私有云环境，必须手动重写驱动或改造 SDK。
为什么标准七牛扩展包无法用于私有云
七牛私有云（Qiniu Private Cloud）与公有云在以下关键点不兼容：
- API 地址不同：私有云使用企业内网地址（如
https://qiniu-api.internal.company.com），而非固定https://api.qiniu.com - 鉴权方式差异：部分私有云部署要求自定义 HTTP Header（如
X-Qiniu-Private-Cloud-Sign），不完全遵循公有云的Authorization: QBox ...签名格式 - 上传端点（upload token endpoint）、资源列表接口路径、回调验证逻辑等均可能被定制化，SDK 默认硬编码了公有云路径
-
qiniu/php-sdkv7.x 主线未开放私有云配置入口；其Config类中$host、$upHost等字段虽可设，但底层签名构造器仍强依赖公有云域名白名单校验
如何让 Laravel 支持七牛私有云 —— 替换底层 Flysystem Adapter
最稳妥的做法是绕过现有扩展包，基于 Flysystem v2+（Laravel 9+ 默认）自定义 Adapter。核心是实现一个继承 League\Flysystem\Adapter\AbstractAdapter 的类，并重写 write、read、delete 等方法，调用你改造后的私有云 SDK。
- 先 fork 官方
qiniu/php-sdk，修改src/Config.php，暴露setApiHost()、setUpHost()方法，并允许传入自定义签名生成器 - 新建
app/Filesystems/QiniuPrivateAdapter.php，在write()中使用你定制的 SDK 实例发起 PUT 请求，注意处理返回的200或298（私有云常见成功码） - 在
config/filesystems.php中注册新驱动：'disks' => [ 'qiniu-private' => [ 'driver' => 'custom', 'adapter' => \App\Filesystems\QiniuPrivateAdapter::class, 'access_key' => env('QINIU_PRIVATE_ACCESS_KEY'), 'secret_key' => env('QINIU_PRIVATE_SECRET_KEY'), 'bucket' => env('QINIU_PRIVATE_BUCKET'), 'api_host' => env('QINIU_PRIVATE_API_HOST', 'https://qiniu-api.internal.company.com'), 'up_host' => env('QINIU_PRIVATE_UP_HOST', 'https://qiniu-up.internal.company.com'), ], ] - 不要在
providers里注册任何第三方服务提供者，避免冲突；Laravel 会自动识别'driver' => 'custom'并加载对应 Adapter 类
上传大文件时私有云特有的坑
七牛私有云常禁用分片上传（putFile 自动切片），或要求预签名分片上传地址（类似 S3 presigned URL），而标准 Laravel Storage::disk('qiniu')->put() 会默认走单次上传流程，容易超时或返回 413 Payload Too Large。
- 务必确认私有云是否开启
resumable upload接口；若未开启，所有 >5MB 文件需前端分片 + 后端合并（调用私有云提供的/mkfile接口） - 私有云的
uploadToken有效期往往更短（如 30 秒），且不支持deadline参数扩展；后端生成 token 后必须立即返回给前端，不能缓存 - 若用
fopen($file, 'r')方式上传，私有云可能拒绝非Content-Type: application/octet-stream的请求；需显式设置stream_context_create(['http' => ['header' => "Content-Type: application/octet-stream"]]) - 私有云日志通常不返回标准
x-reqid，调试时要靠X-Request-ID或自定义 trace header，建议在请求头中加X-Trace-ID: {uniqid()}
真正麻烦的不是代码怎么写，而是私有云部署方是否提供了完整、一致、可验证的 OpenAPI Spec。很多企业私有云只给一份 PDF 文档，字段名和实际响应对不上，连 bucket 是叫 space 还是 tenant 都得抓包确认。动手前，先拿到对方环境的真实 cURL 示例和返回体，比看十篇教程都管用。
