文件导入

将外部文件批量导入到悦库网盘。支持三种来源：服务器本地目录、FTP 服务器、SMB/CIFS 共享。

前提：只能在悦库服务器本机运行。目标目录须已存在，且当前账号拥有编辑、上传文件、上传文件夹权限。

常用命令（复制使用）

从本地目录导入：

opscli import create --from /data/project --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。

一次导入多个目录（分号分隔，串行执行）：

opscli import create --from "/data/a;/data/b;/data/c" --to /我的空间/自动化测试/testImport

批量导入（JSON 文件）

推荐用于重复执行或需要审计的场景。

1. 准备批量任务文件 import-batch.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

快速导入（仅元信息）

对于海量文件（数十万至数百万级别），可以先仅导入文件元信息（名称、大小、类型），文件在网盘中立即可见。

# 仅导入文件元信息（名称、大小、类型），不传输文件内容。
# 文件可见可浏览，下载通过 S3 代理从源文件读取。
opscli import create --from /data/project --to /我的空间/自动化测试/testImport --metadata-only

重要：--metadata-only 导入后，文件内容通过 S3 代理直接从源文件读取。源文件必须保持可访问（Docker 部署下 opscli 自动 mount --bind，见下方说明）。

后续补充实载：

# 对已完成元信息导入的任务执行块实载（补充文件内容）
opscli import run --taskId <任务ID> --realize

Docker 部署注意事项

Linux Docker 部署时，S3 代理运行在容器内，无法直接访问宿主机文件系统。opscli 自动处理这一情况：

1. 检测 /opt/ydisks/docker-compose.yml 或 ydisk-server 容器是否存在
2. 自动将本地 --from 路径通过 sudo mount --bind 挂载到 /opt/ydisks/imports/（该目录已挂载进容器）
3. 替换导入路径为容器内可访问的路径，开始导入

用户执行方式不变，opscli 在后台自动完成挂载：

# 用户只需执行（opscli 自动检测 Docker、自动 mount --bind）
opscli import create --from /data/project --to /我的空间/自动化测试/testImport --metadata-only

# 输出示例：
# [挂载] /data/project → /opt/ydisks/imports/project
# [挂载] 请保持挂载状态以供 S3 代理使用，用完执行: sudo umount /opt/ydisks/imports/project

挂载生命周期：

• 普通导入（不带 --metadata-only）：完成后自动 umount，用户无感
• 仅元信息导入（--metadata-only）：挂载保持存活，供 S3 代理下载使用，用户可在不再需要源文件后手动 sudo umount

前提条件：容器 /opt/ydisks 挂载传播必须为 rslave（安装包 v7.3.2+ 已默认配置）。

3. 自动替换导入路径为容器内可访问的路径

# 用户只需执行（opscli 自动处理挂载）
opscli import create --from /data/project --to /我的空间/自动化测试/testImport --metadata-only

非 metadata-only 导入：完成后自动 umount，用户无感。

metadata-only 导入：源文件需保持挂载供 S3 代理下载使用，opscli 会提示手动清理命令：

[挂载] 请保持挂载状态以供 S3 代理使用，用完执行: sudo umount /opt/ydisks/imports/project

前提：容器 /opt/ydisks 挂载传播必须为 rslave（安装包 v7.3.2+ 已默认配置）。

冲突处理

任务级冲突（续传检测）

再次导入同源路径时，检测到未完成的任务，通过 --on-conflict 控制行为：

值	说明
ask（默认）	交互提示：[c] 续传、[r] 重新开始、[q] 退出（大小写不敏感）
resume	自动续传，不提示
restart	自动重新开始，不提示

文件级冲突（同名文件）

导入过程中目标已存在同名文件时：

• 默认逐项交互提示，支持 [R] 重命名（默认）、[O] 覆盖、[S] 跳过
• --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 代理是 --metadata-only 导入后文件可下载的前提。未开启 S3 代理时，仅导入元信息的文件在网盘中可见但无法下载内容；开启后，文件通过代理直接从源读取数据，无需等待块实载。

手动开启：

opscli service s3proxy on

导入时自动开启（--s3proxy）：

opscli import create --from /data/project --to /我的空间/testImport --metadata-only --s3proxy

导入前自动检查 config.json 中 oss.proxy，若为 false 自动设为 true 并执行硬重启，继续导入流程。

退出登录：

opscli logout

常见问题与排障

• 提示"尚未登录"：先执行 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 万）推荐使用 --metadata-only --s3proxy，文件立即可见且可下载，数据后台逐步实载。
• 导入完成后抽查若干文件和目录，确认数量与内容一致。