数据迁移与 SDK

批量导入（import:from-fs）

将本地文件系统目录批量导入到 ul-disk。

命令用法

# 基础导入：递归扫描源目录 → writeFile 流式上传
docker exec uldisk-dev-uldisk-1 php think import:from-fs \
    --source=/data/import \
    --position=1

# 导入到指定子目录
docker exec uldisk-dev-uldisk-1 php think import:from-fs \
    --source=/data/import \
    --position=1 \
    --target=/photos

# 限制并发 / 间隔
docker exec uldisk-dev-uldisk-1 php think import:from-fs \
    --source=/data/import \
    --position=1 \
    --sleep=100

参数

行为

• 递归扫描源目录，保持目录结构
• 每个文件经完整 pipeline（加密/压缩/去重）
• 跳过已存在同 MD5 文件（自动去重）
• 输出统计：imported=N skipped=M failed=K

批量导出（export:to-fs）

将 ul-disk 中的文件导出到本地文件系统。

命令用法

# 导出全部文件
docker exec uldisk-dev-uldisk-1 php think export:to-fs \
    --target=/data/export

# 导出指定目录
docker exec uldisk-dev-uldisk-1 php think export:to-fs \
    --target=/data/export \
    --path=/photos

# 导出单个文件
docker exec uldisk-dev-uldisk-1 php think export:to-fs \
    --target=/data/export \
    --path=/photos/cat.jpg

参数

行为

• 递归读取 storage_path 文件树
• 每个文件 readFile 流式读取 + 本地 copy
• 只读不删远端（安全导出，不影响 ul-disk 数据）
• 保持目录结构
• 输出统计：exported=N failed=K

数据再平衡

position:rebalance

扫描超载位置（size_used > size_limit）→ 入队迁移任务到其他可用位置。

php think position:rebalance              # 执行
php think position:rebalance --dry-run    # 预览
php think position:rebalance --limit=100  # 限制数量

position:evacuate

撤空指定位置（下线维护场景）。

php think position:evacuate --position=3
php think position:evacuate --position=3 --dry-run

仅入队不物理 IO，实际迁移由 Worker Pool 异步完成。

PHP SDK

项目自带 SDK（sdk/ 目录），可在应用中集成。

安装

cd sdk
composer install

使用示例

<?php
require 'vendor/autoload.php';

use Uldisk\Client;

$client = new Client([
    'base_url'    => 'http://localhost:8002',
    'access_key'  => 'ULDSK-XXXX-XXXX',
    'secret_key'  => '<secret>',
]);

// 上传文件
$client->upload('/path/to/local.txt', 'remote/path.txt');

// 下载文件
$client->download('remote/path.txt', '/path/to/local.txt');

// 删除文件
$client->delete('remote/path.txt');

// 列出文件
$files = $client->list('/');

SDK 目录结构

sdk/
├── composer.json
├── README.md
├── src/
│   ├── Client.php        # 主客户端
│   └── Exceptions.php    # 异常定义
└── examples/
    └── upload.php        # 上传示例

认证

SDK 使用 S3 SigV4 签名（与 aws-cli / boto3 相同），需要在管理后台生成 Access Key。

迁移策略建议

从本地磁盘迁移到 ul-disk

# 1. 导入本地文件
php think import:from-fs --source=/old-data --position=1

# 2. 验证数据完整性
php think selfheal:verify

# 3. 确认无误后删除旧数据

从其他存储迁移到 ul-disk

# 1. 导出到本地临时目录（从旧系统）
# 2. 导入到 ul-disk
php think import:from-fs --source=/tmp/old-storage --position=1

# 3. 或者直接使用 WebDAV/S3 协议迁移
rclone copy old-remote: uldisk: --transfers=4