file_transfer 主要用于实现 BMC 与外部系统之间的文件传输能力

组件概述 ​

组件是什么、解决什么问题 ​

file_transfer 是独立部署的文件传输服务组件（部署服务 file_transfer.service），对外提供资源树功能接口 bmc.kepler.Managers.FileTransfer，解决 BMC 与远端服务器/存储之间的文件交换问题：

• 上传/下载：将 BMC 本地文件上传到远端（SFTP/SCP/HTTPS/SMB/CIFS/NFS），或将远端文件下载到 BMC 本地（/tmp 目录）。
• 文件系统挂载/解挂：将远端 NFS/CIFS 共享目录挂载到 BMC 本地挂载点，便于直接读写共享文件。
• 连通性检测：检测远端 SFTP/NFS 服务器是否可达，供上层（如升级、日志导出）预检网络。

组件通过 curl 或 mount 完成实际传输，传输过程异步执行并以**任务（TaskService）**形式向调用方回报进度与结果。

核心功能 ​

术语解释 ​

外部系统交互边界 ​

说明：file_transfer 为纯北向服务组件，不依赖其他 BMC 组件的数据源；调用方通过 D-Bus 资源树接口调用，实际网络传输发生在组件内部线程。

对外接口 ​

资源协作接口 ​

• FileTransfer

  • Path: /bmc/kepler/Managers/1/FileTransfer

  • Interface: bmc.kepler.Managers.FileTransfer

属性：

方法：

传输文件 StartTransfer ​

用于文件的上传和下载，通过 file:// 所在的字符串判断当前操作是上传还是下载：file:// 在 src_url 中则为上传，反之为下载。方法内部创建任务（TaskService）并异步执行传输，立即返回任务 ID。

输入：

• context（a{ss}）：调用上下文（调用者信息）
• src_url（string）：源地址，协议格式为 协议://用户名:密码@IP地址/路径，例如 sftp://username:password@ipaddr/xxx
• target_url（string）：目标地址，本地地址使用 file:///tmp/xxx 形式
• max_length（uint32）：文件大小上限（字节），仅下载有效，上传的大小/敏感信息检查由调用方完成
• uid（uint32）：文件属主 UID，仅下载有效
• gid（uint32）：文件属组 GID，仅下载有效
• permission（uint32）：文件权限，仅下载有效

输出：

• task_id（uint32）：传输任务标识，用于查询任务状态

示例：

使用 sftp 协议下载一个长度小于 1000 字节的 xxx 文件到 /tmp 目录下，用户/用户组为 root，权限为 640：

StartTransfer(ctx, "sftp://username:password@ipaddr/xxx", "file:///tmp/xxx", 1000(max_length), 0(uid), 0(gid), 640(permission))

异常与触发条件：

首发版本： file_transfer 1.140.1（bmcsdk 25.x）

应用场景与限制条件：

• 典型场景：升级包/日志/配置文件在 BMC 与远端服务器之间上传下载。
• 限制条件：
  • 本地路径必须在 /tmp（或 /data/sp/）下，非 /tmp 路径需评审后以白名单形式管理；
  • 下载大小受 max_length 与 /tmp 剩余空间双重限制，且单文件硬上限 500MB（0x1F400000）；
  • 任务最多 32 个，任务存活最长 40 分钟，超时后对象销毁、进度强制置 100；
  • 下载完成后文件属主/属组/权限由 uid/gid/permission 设置；上传的大小/敏感信息检查由调用方完成。

调试示例：

# 1) 查询资源树对象与属性
busctl --user introspect bmc.kepler.file_transfer /bmc/kepler/Managers/1/FileTransfer
busctl --user get-property bmc.kepler.file_transfer /bmc/kepler/Managers/1/FileTransfer \
    bmc.kepler.Managers.FileTransfer HttpsTransferCertVerification
# 相应: b true

# 2) 调用 StartTransfer（sftp 下载 /xxx 到 /tmp/xxx，长度<1000，root:root，权限 640）
busctl --user call bmc.kepler.file_transfer /bmc/kepler/Managers/1/FileTransfer \
    bmc.kepler.Managers.FileTransfer StartTransfer a{ss}ssuuuu 0 \
    'sftp://username:password@ipaddr/xxx' 'file:///tmp/xxx' 1000 0 0 640
# 相应: u 3    （u 为任务 ID）

# 3) 查询传输任务状态（State: Completed/Exception，Progress，Parameters 含 ErrorCode）
busctl --user get-property bmc.kepler.file_transfer \
    /bmc/kepler/Managers/1/FileTransfer/TaskService/Tasks/3 \
    bmc.kepler.Tasks.TaskService State
# 相应: s "Completed"

挂载文件系统 Mount ​

用于挂载文件系统，只支持 NFS 和 CIFS 协议。

输入：

• context（a{ss}）：调用上下文（调用者信息）
• Src（string）：服务端地址，例如 nfs://nfsaddr/NFSShare/
• MountPoint（string）：本地挂载点，例如 /tmp/nfs

输出：

• Result（int32）：挂载结果，0 表示成功，非 0 表示失败

示例：

使用 nfs 协议，将 nfs 服务器上的 NFSShare 目录挂载到 /tmp/nfs 目录：

Mount(ctx, "nfs://nfsaddr/NFSShare/", "/tmp/nfs")

异常与触发条件：

首发版本： file_transfer 1.140.1（bmcsdk 25.x）

应用场景与限制条件：

• 典型场景：将远端 NFS/CIFS 共享目录挂载到 BMC 本地挂载点，直接读写共享文件。
• 限制条件：
  • 仅支持 nfs、cifs 协议；CIFS 挂载内部会转换为 //IP/共享名 形式并通过 smb 协议访问；
  • 挂载前会先 ping 远端 IP（3 次），ping 不通直接失败；
  • 密码等挂载参数存在特殊字符（,;$|&><\!` 及换行）时拒绝挂载；
  • 挂载点需提前创建且可写，挂载成功后由调用方负责解挂。

调试示例：

# nfs 挂载
busctl --user call bmc.kepler.file_transfer /bmc/kepler/Managers/1/FileTransfer \
    bmc.kepler.Managers.FileTransfer Mount a{ss}ss 0 'nfs://nfsaddr/NFSShare/' '/tmp/nfs'
# 相应: i 0    （0 表示成功）

# cifs 挂载
busctl --user call bmc.kepler.file_transfer /bmc/kepler/Managers/1/FileTransfer \
    bmc.kepler.Managers.FileTransfer Mount a{ss}ss 0 'cifs://user:pass@ip/Share/' '/tmp/cifs'
# 相应: i 0

# 查看当前挂载情况
mount | grep /tmp/nfs

解挂文件系统 Umount ​

用于解挂文件系统。

输入：

• context（a{ss}）：调用上下文（调用者信息）
• MountPoint（string）：挂载点，例如 /tmp/nfs

输出：

• Result（int32）：解挂结果，0 表示成功，非 0 表示失败

示例：

解挂挂载点为 /tmp/nfs 的文件系统：

Umount(ctx, "/tmp/nfs")

异常与触发条件：

首发版本： file_transfer 1.140.1（bmcsdk 25.x）

应用场景与限制条件：

• 典型场景：传输/挂载完成后释放挂载点，避免遗留挂载影响后续操作。
• 限制条件：挂载点必须已挂载；挂载点被占用（busy）时解挂失败，需先释放占用进程。

调试示例：

busctl --user call bmc.kepler.file_transfer /bmc/kepler/Managers/1/FileTransfer \
    bmc.kepler.Managers.FileTransfer Umount a{ss}s 0 '/tmp/nfs'
# 相应: i 0

检测远端连通性 TestConnection ​

检测远端服务器网络连通性。当前支持 SFTP、NFS 协议，其他协议不支持。方法内部创建任务异步执行检测，立即返回任务 ID，检测结果（成功/失败）通过任务状态上报。

输入：

• context（a{ss}）：调用上下文（调用者信息）
• Protocol（string）：协议类型，支持 sftp、nfs
• Address（string）：服务器地址
• Port（uint16）：端口号
• UserName（string）：用户名
• Password（string）：密码，敏感信息

输出：

• TaskId（uint32）：连通性检测任务标识，用于查询任务状态

异常与触发条件：

首发版本： file_transfer 1.140.1（bmcsdk 25.x）

应用场景与限制条件：

• 典型场景：升级、日志导出等业务在发起前预检远端 SFTP/NFS 服务器可达性。
• 限制条件：仅支持 sftp、nfs 协议；sftp 依赖 curl（连接超时 15s、操作超时 30s）；nfs 通过挂载共享根目录再解挂验证；检测结果为异步，需通过任务状态（Completed/Exception）判断。

调试示例：

# sftp 连通性检测
busctl --user call bmc.kepler.file_transfer /bmc/kepler/Managers/1/FileTransfer \
    bmc.kepler.Managers.FileTransfer TestConnection a{ss}ssqss 0 sftp 192.168.1.10 22 user pass
# 相应: u 5    （任务 ID）

# 查询检测结果
busctl --user get-property bmc.kepler.file_transfer \
    /bmc/kepler/Managers/1/FileTransfer/TaskService/Tasks/5 \
    bmc.kepler.Tasks.TaskService State
# 相应: s "Completed"

IPMI接口 ​

不涉及

配置介绍 ​

数字证书 ​

证书存放在 /data/trust/cert/ca/ 目录下，可能有 .crt、.crl、.0、.r0 四种后缀，其中 .0 和 .crt 功能一致（CA 证书），.r0 和 .crl 功能一致（证书吊销列表），目前同时兼容两种版本。

资源树属性 HttpsTransferCertVerification 决定了进行文件传输时是否对上传下载的 url 进行证书校验：true 时用证书目录中的证书校验服务器身份，false 时不校验。

组件扩展案例 ​

扩展能力概述 ​

file_transfer 的扩展能力体现在 HTTPS 服务器 CA 证书信任管理：通过向证书目录投放证书（.crt/.0 及吊销列表 .crl/.0）即可扩展可信任的 HTTPS 文件服务器，无需改动组件代码。

扩展点说明 ​

二次开发指导 ​

步骤一：投放证书 ​

将需要信任的 HTTPS 文件服务器根证书拷贝到 /data/trust/cert/ca/ 目录下，文件名为证书标识，后缀 .crt 或 .0（例如 myserver.crt）。

cp myserver.crt /data/trust/cert/ca/

步骤二：使能证书校验 ​

确认资源树属性 HttpsTransferCertVerification 为 true（默认值）：

busctl --user get-property bmc.kepler.file_transfer /bmc/kepler/Managers/1/FileTransfer \
    bmc.kepler.Managers.FileTransfer HttpsTransferCertVerification
# 相应: b true

若为 false，可通过资源树写操作或 Redfish 使能：

busctl --user set-property bmc.kepler.file_transfer /bmc/kepler/Managers/1/FileTransfer \
    bmc.kepler.Managers.FileTransfer HttpsTransferCertVerification b true

验证方法 ​

注意事项 ​

1. 证书文件权限需保证 file_transfer 进程（root）可读；
2. 同名证书同时存在 .crt 与 .0 时按目录扫描顺序生效，建议只保留一种后缀；
3. 关闭证书校验（HttpsTransferCertVerification=false）存在安全风险，生产环境不建议；
4. 修改证书后无需重启服务，下次传输自动读取；
5. 吊销列表（.crl/.r0）存在时一并参与校验。

问题定界指南 ​

典型问题定界 ​

错误码速查表 ​

传输/挂载/连通性任务失败时，任务对象的 Parameters 会携带 {"ErrorCode": -xxx}，MessageId 为 FileTransferErrorDesc，MessageArgs 为错误描述。

调试方法 ​

file_transfer 使用 libmc4c 日志框架，日志默认打到 syslog/journald（服务 file_transfer.service），可用 journalctl -u file_transfer.service -f 实时查看。复现方法：调用 StartTransfer/Mount/TestConnection 后，在任务对象上查看 State/Parameters/MessageArgs，结合日志关键字定位。

日志说明 ​

一键日志收集 ​

一键日志收集（AppDump/日志导出）涉及 file_transfer 的日志文件如下：

关键日志信息 ​

FAQ ​

Q1：HTTPS 传输失败，任务错误码 -122，日志提示证书校验失败？ ​

一句话答案： 远端 HTTPS 服务器证书不在信任列表中，检查 /data/trust/cert/ca/ 证书或临时关闭证书校验。

根因： HttpsTransferCertVerification 为 true 时，组件用证书目录中的证书逐一校验证书链，失败返回 -122（CURL_PEER_SSL_VERIFY_FAILED）。

解决方案： ① 将远端服务器根证书导入 /data/trust/cert/ca/；② 或临时置 HttpsTransferCertVerification=false 关闭校验（生产环境不建议）。

适用版本： file_transfer 1.140.1 及以上。

Q2：下载报错 -103，提示文件超长？ ​

一句话答案： 待下载文件超过 max_length 或 /tmp 空间不足。

根因： 组件先比较文件大小与 max_length，再比较 max_length 与 /tmp 剩余空间，取小者；同时存在 500MB 硬上限。

解决方案： 调大 max_length、清理 /tmp 或拆分文件。

适用版本： 全版本。

Q3：为什么 tftp 协议不支持？ ​

一句话答案： 当前版本禁用 tftp，仅支持 https/sftp/scp/smb/cifs/nfs。

根因： 源码中对 tftp 协议直接返回 SFTP NOT supportted，仅保留协议枚举未实现功能。

解决方案： 使用 sftp 或 https 替代。

适用版本： file_transfer 1.140.1。

Q4：任务查询不到或进度一直为 100？ ​

一句话答案： 任务最多 32 个、存活 40 分钟，超时销毁；进度 100 表示已结束。

根因： 任务完成/销毁后对象不在位；进度 100 是任务结束（含失败）后的终态。

解决方案： 传输结束后尽快查询任务结果；失败时通过任务 Parameters 的 ErrorCode 定位。

适用版本： 全版本。