文件导入
将外部文件批量导入到悦库网盘。支持三种来源：服务器本地目录、FTP 服务器、SMB/CIFS 共享。 导入程序先载入文件信息，然后载入文件实际数据，对于海量文件（数百万或500GB以上级别），可以开启 S3 代理 后导入，文件立即可见可下载，无需等待文件数据实载。
文件元信息导入-性能参考
测试机：CPU i7-13650HX / 固态硬盘 ZHITAI Ti600 2TB / 内存 24G DDR5
| 文件数 | 平均耗时 |
|---|---|
| 100 万 | 2 小时 |
| 500 万 | 16 小时 |
| 1000 万 | 48 小时 |
本地导入
标准导入（先载入文件信息，再载入文件数据）：
opscli import create --from /data/project --to /我的空间/自动化测试/testImport
开启 S3 代理（文件立即可见可下载）：
opscli import create --from /data/project --to /我的空间/自动化测试/testImport --s3proxy
一次导入多个目录（分号分隔，串行执行）：
opscli import create --from "/data/a;/data/b;/data/c" --to /我的空间/自动化测试/testImport
远程导入
FTP 导入：
opscli import create --from ftp://192.168.0.8/share/project --to /我的空间/自动化测试/testImport --username demo --password 123456
FTP 文件名乱码？ 部分旧版 FTP 服务器（Windows IIS FTP、未配置 UTF-8 的 vsftpd）以服务器系统编码（如中文 Windows 下的 GBK）传输文件名，导致导入后中文文件名变乱码。需添加
--ftp-encoding参数指定编码：
opscli import create --from ftp://192.168.0.8/share/project --to /我的空间/testImport \
--username demo --password 123456 --ftp-encoding gbk
--ftp-encoding 可选值 | 适用场景 |
|---|---|
utf-8（默认） | 功能齐全的 FTP 服务器，或老服务器但文件名全为 ASCII |
gbk / gb2312 | 中文 Windows FTP 服务器（未开启 UTF-8） |
big5 | 繁体中文 FTP 服务器 |
shift-jis | 日文 Windows FTP 服务器 |
euc-jp | Linux 上的日文 FTP 服务器 |
euc-kr | 韩文 FTP 服务器 |
windows-1252 | 西欧 Windows FTP 服务器 |
SMB/CIFS 共享导入：
opscli import create --from smb://192.168.0.8/ShareName --to /我的空间/自动化测试/testImport --username demo --password 123456
凭据也可内嵌到 URL：
opscli import create --from smb://demo:123456@192.168.0.8/ShareName --to /我的空间/自动化测试/testImport
如共享允许匿名访问，可省略用户名和密码：
opscli import create --from smb://192.168.0.8/ShareName --to /我的空间/自动化测试/testImport
SMB 默认端口 445。非标准端口在主机名后加
:端口号，例如smb://192.168.0.8:445/ShareName。
## 批量导入
推荐用于重复执行或需要审计的场景。
**1. 准备批量任务文件 `import-batch.json`：**
```json
[
{ "from": "/data/images", "to": "/我的空间/自动化测试/images" },
{ "from": "ftp://192.168.0.8/share/docs", "to": "/我的空间/自动化测试/docs",
"username": "demo", "password": "123456", "ftp_encoding": "gbk" },
{ "from": "smb://192.168.0.8/ShareName", "to": "/我的空间/自动化测试/smb",
"username": "demo", "password": "123456" }
]
2. 执行：
opscli import batch --file /data/tasks/import-batch.json
遇错继续（不中断整批任务）：
opscli import batch --file /data/tasks/import-batch.json --on-error continue
冲突处理
任务级冲突（续传检测）
再次导入同源路径时，检测到未完成的任务，通过 --on-conflict 控制行为：
| 值 | 说明 |
|---|---|
ask（默认） | 交互提示：[c] 续传、[r] 重新开始、[q] 退出（大小写不敏感） |
resume | 自动续传，不提示 |
restart | 自动重新开始，不提示 |
文件级冲突（同名文件）
--overwrite：删除目标中已存在的同名文件/文件夹后导入，不提示
示例：
opscli import create --from /data/project --to /我的空间/testImport --overwrite
查看与管理任务
查看单个任务状态：
opscli import status --taskId 10002
查看最近任务列表：
opscli import list
opscli import list --limit 50
续传中断的任务或补充实载：
# 续传中断的导入
opscli import run --taskId 10002
# 对 --metadata-only(仅导入文件元信息)的任务实载文件数据。
opscli import run --taskId 10002 --realize
取消任务：
opscli import terminate --taskId 10002
删除任务记录：
# 删除单个任务
opscli import delete --taskId 10002
# 删除 30 天前创建的任务
opscli import delete --before-days 30
# 预览将被删除的内容（不实际执行）
opscli import delete --all --dry-run
# 删除所有任务
opscli import delete --all
正在运行的任务会被自动跳过并打印提示，不会强制删除。建议先用
--dry-run确认范围。
S3 代理
S3 代理开启后，文件立即可见可下载，文件通过代理直接从源读取数据，无需等待块实载。
手动开启：
opscli service s3proxy on
导入时自动开启：
opscli import create --from /data/project --to /我的空间/testImport --s3proxy
导入前自动检查 config.json 中 oss.proxy，若为 false 自动设为 true 并执行硬重启，继续导入流程。
常见问题与排障
- 提示"尚未登录"：先执行
opscli login。 - FTP 导入后文件名乱码：FTP 服务器以非 UTF-8 编码（如 GBK）传输文件名，需添加
--ftp-encoding gbk（或对应编码）重新导入。可选值：gbk、gb2312、big5、shift-jis、euc-jp、euc-kr、windows-1252。 - 权限不足：检查目标目录是否有"编辑 / 上传文件 / 上传文件夹"权限。
- 路径不存在：本地导入确认
--from目录真实存在；FTP/SMB 导入确认地址、共享名称和凭证正确；目标目录路径写错也会导致任务无法继续。 - 仓库空间不足：清理目标仓库空间，或更换目标位置，或拆分为多次导入。
运维建议
- 首次导入使用小目录验证流程，确认无误后再做全量导入。
- 大批量导入尽量避开业务高峰期。
- 批量 任务优先使用 JSON 文件，便于保存、复用和审计。
- 海量文件（>10 万）推荐使用
--s3proxy，文件立即可见且可下载，数据后台逐步实载。 - 导入完成后抽查若干文件和目录，确认数量与内容一致。