存储位置管理

概述

ul-disk 支持 4 种后端驱动，通过 FlySystem 3.0 统一抽象。每个存储位置自动生成 MD5 指纹用于 Hamming 路由（类似一致性哈希，但用 Hamming 距离替代环距离）。

驱动类型

Local（本地磁盘）

配置项	说明
`path`	存储根目录（如 `/data/storage`）

Local 后端不能跨节点共享，只本节点访问。

SFTP

配置项	说明
`host`	主机地址
`port`	端口（默认 22）
`username`	用户名
`password`	密码（与密钥二选一）
`privateKey`	私钥路径（与密码二选一）
`root`	根目录

使用 phpseclib V3（已从 V2 迁移）。

FTP

配置项	说明
`host`	主机地址
`port`	端口（默认 21）
`username`	用户名
`password`	密码
`root`	根目录

WebDAV

配置项	说明
`baseUri`	WebDAV 服务地址
`userName`	用户名
`password`	密码
`prefix`	路径前缀

第一参数是 Sabre\DAV\Client（非 Sabre\HTTP\Client）。

Hamming 路由算法

文件写入时，系统按以下步骤选择存储位置：

1. 筛选：status=enable AND (size_limit=0 OR size_limit > size_used)
2. 算距离：gmp_hamdist(chunk_md5 二进制, position.md5 二进制)
3. 排序：Hamming 距离 ASC，同距离 weight DESC
4. 写入：首个可用位置成功即完成

意图：将内容哈希相近的 chunk 倾向放到同一位置，优化跨后端访问局部性。

容量管理

每个位置有 size_limit（0 = 不限）和 size_used（实时累加）
写入前检查容量，满则跳过该位置
原子 UPDATE size_used = size_used + ? 防多副本并发竞争
容量不足时抛出 InsufficientStorageException（507 Insufficient Storage）

位置测速

# 测全部 online 位置（写+读 4MB，更新 priority 权重）
docker exec uldisk-dev-uldisk-1 php think position:benchmark

# 测指定位置
docker exec uldisk-dev-uldisk-1 php think position:benchmark --position=1

配合配置：

storage.priority_mode = auto（默认）：按 Hamming 距离路由
storage.priority_mode = manual：按 priority 权重降序路由（测速后自动更新）

限流

每个位置可配置三维度限流（0 = 不限）：

配置项	说明
`rate_limit_rpm`	每分钟请求数（令牌桶）
`max_concurrent`	最大并发数
`bandwidth_limit_mbps`	带宽上限 Mbps

基于 APCu 共享内存，跨 FPM worker 共享但不跨节点。APCu 不可用时 fail-closed（拒绝不降级）。

后端超时

优先级链：position.config.timeout > storage.position_timeout_default（默认 30s） > 30（硬编兜底）