markbase/docs/LIBISCSI_DOCKER_TGT_TEST.md

libiscsi Initiator ↔ Docker tgt 测试报告

测试日期: 2026-05-30 15:05
测试环境: macOS 26.5 arm64, M4 Mac mini
测试工具: libiscsi v1.20.3 (Homebrew), tgt (Ubuntu 22.04 Docker)

---

测试架构

macOS (libiscsi userspace)         Colima VM (tgt kernel)
┌─────────────────────┐              ┌─────────────────────┐
│  iscsi-perf         │              │  tgtd daemon        │
│  iscsi-ls           │              │  /lun0.img (256MB)  │
│  iscsi-inq          │              │  Port: 3260         │
│                     │              │                     │
│  TCP: 127.0.0.1     │◄────────────►│                     │
│  (Colima port fwd)  │              │                     │
└─────────────────────┘              └─────────────────────┘
         ▲                                    ▲
         │                                    │
    libiscsi (userspace)                  tgt (Linux kernel)

---

测试结果

✅ 成功项目

测试项	结果	说明
tgt启动	✅	Target ready, LUN 1 (268MB)
libiscsi发现	⚠️	发现target但连接失败（Portal IP问题）
libiscsi SCSI Inquiry	✅	Vendor: IET, Product: VIRTUAL-DISK
libiscsi性能测试	✅	4KB ~ 256KB块大小测试完成

---

性能数据（顺序读取）

块大小	吞吐量	IOPS	说明
4KB	13 MB/s	6,750	小块，高IOPS
64KB	162 MB/s	5,200	中等块
128KB	252 MB/s	4,032	大块
256KB	249 MB/s	1,994	最大块（标准测试）

最佳性能: 128KB块，252 MB/s

---

SCSI Inquiry结果

Peripheral Qualifier: CONNECTED
Peripheral Device Type: DIRECT_ACCESS
Version: SPC-3, iSCSI
Vendor: IET
Product: VIRTUAL-DISK
Revision: 0001

确认: tgt target正确响应SCSI命令

---

性能对比分析

与其他方案对比

方案	块大小	吞吐量	倍数（相对libiscsi）	说明
libiscsi ↔ Docker tgt	256KB	249 MB/s	1.0x (baseline)	真实TCP/IP iSCSI
gotgt native (localhost)	256KB	3275 MB/s	13.2x faster	TCP/IP但无Colima开销
Docker tgt容器内	256KB	19200 MB/s	77.1x faster	本地文件，非真实iSCSI
macOS NVMe本地	256KB	3400 MB/s	13.7x faster	硬件基准

关键发现:

• 真实TCP/IP iSCSI性能：249 MB/s
• Docker容器内测试（19200 MB/s）不代表真实iSCSI性能
• Colima VM开销：端口转发 + virtiofs，导致性能下降

---

为什么libiscsi ↔ Docker tgt慢？

原因分析:

1. TCP/IP协议栈开销 ✅

   • libiscsi → localhost:3260 → Colima VM → tgt
   • TCP握手、PDU解析、确认机制

2. Colima端口转发开销 ✅

   • macOS → Colima VM的网络转发
   • virtiofs或bridge模式

3. tgt kernel开销 ✅

   • Linux kernel SCSI target处理
   • Block I/O调度

4. libiscsi userspace开销 ✅

   • 非kernel initiator，CPU开销更高
   • 无DMA优化

---

为什么gotgt native更快？

gotgt native (3275 MB/s) vs libiscsi ↔ Docker tgt (249 MB/s)

差异: 13.2倍

原因:

1. gotgt在macOS本地运行（无Colima VM）
2. libiscsi → gotgt 直接localhost连接
3. 无端口转发开销
4. gotgt是Go native，性能优化

---

为什么Docker tgt容器内测试不合理？

Docker tgt容器内 (19200 MB/s) 不是真实iSCSI！

原因:

• 容器内直接访问LUN文件（/lun0.img）
• 无TCP/IP传输
• 无SCSI协议解析
• 本地文件系统访问（ext4）

正确的对比:

• 真实iSCSI：249 MB/s（libiscsi ↔ Docker tgt）
• 本地文件：19200 MB/s（容器内文件访问）

结论: 之前测试的19200 MB/s 不代表iSCSI性能

---

libiscsi发现问题

问题: iscsi-ls -s iscsi://127.0.0.1:3260

错误:

Target:iqn.2026-05.momentry:libiscsi-test Portal:172.17.0.2:3260,1
list_luns: iscsi_connect failed. iscsi_service failed with : 
iscsi_service_reconnect_if_loggedin. Can not reconnect right now.

原因:

• tgt返回Portal IP为 172.17.0.2（Docker内部IP）
• libiscsi尝试连接 172.17.0.2:3260（无法从macOS访问）
• 需要配置tgt使用 127.0.0.1 作为Portal

解决方法:

• 配置tgt Portal为 0.0.0.0:3260 或 127.0.0.1:3260
• 或直接使用iscsi-inq/perf（带认证参数）

---

测试命令记录

Step 1: 启动Docker tgt

docker run -d --name iscsi-tgt --privileged -p 3260:3260 ubuntu:22.04 bash -c "
apt-get install -y tgt &&
dd if=/dev/zero of=/lun0.img bs=1M count=256 &&
echo '<target iqn.2026-05.momentry:libiscsi-test>
  backing-store /lun0.img
  incominguser testuser testpass
</target>' > /etc/tgt/targets.conf &&
tgtd &&
sleep 2 &&
tgt-admin -e &&
tail -f /dev/null
"

Step 2: 验证tgt状态

docker exec iscsi-tgt tgtadm --mode target --op show

结果: Target ready, LUN 1 (268MB)

Step 3: libiscsi SCSI Inquiry

iscsi-inq iscsi://testuser:testpass@127.0.0.1:3260/iqn.2026-05.momentry:libiscsi-test/1

结果: Vendor: IET, Product: VIRTUAL-DISK, SPC-3

Step 4: libiscsi性能测试

# 4KB blocks
iscsi-perf -b 4 iscsi://testuser:testpass@127.0.0.1:3260/iqn.2026-05.momentry:libiscsi-test/1
# 结果: 13 MB/s, 6,750 IOPS

# 64KB blocks  
iscsi-perf -b 64 iscsi://testuser:testpass@127.0.0.1:3260/iqn.2026-05.momentry:libiscsi-test/1
# 结果: 162 MB/s, 5,200 IOPS

# 128KB blocks
iscsi-perf -b 128 iscsi://testuser:testpass@127.0.0.1:3260/iqn.2026-05.momentry:libiscsi-test/1
# 结果: 252 MB/s, 4,032 IOPS

# 256KB blocks
iscsi-perf -b 256 iscsi://testuser:testpass@127.0.0.1:3260/iqn.2026-05.momentry:libiscsi-test/1
# 结果: 249 MB/s, 1,994 IOPS

---

关键结论

✅ 成功验证

1. libiscsi initiator成功连接Docker tgt ✅

   • SCSI Inquiry正确响应
   • 性能测试完整运行

2. 真实TCP/IP iSCSI性能: 249 MB/s @ 256KB blocks ✅

   • 这才是真实的iSCSI网络性能
   • 不是容器内的19200 MB/s

3. libiscsi工具验证 ✅

   • iscsi-inq: SCSI Inquiry成功
   • iscsi-perf: 性能测试成功
   • iscsi-ls: Portal IP问题（可解决）

---

⚠️ 重要修正

之前测试的错误理解:

• ❌ Docker tgt容器内19200 MB/s 不是真实iSCSI性能
• ❌ 需要区分"容器内文件访问"vs"真实TCP/IP iSCSI"

正确理解:

测试场景	性能	说明
Docker tgt容器内文件访问	19200 MB/s	本地文件，无网络开销
libiscsi ↔ Docker tgt	249 MB/s	真实TCP/IP iSCSI

---

性能差异原因

19200 vs 249 MB/s（77倍差异）:

1. 容器内文件访问:

   • 直接访问 /lun0.img
   • ext4文件系统
   • 无TCP/IP、无SCSI协议

2. 真实TCP/IP iSCSI:

   • TCP连接建立
   • iSCSI PDU封装/解析
   • SCSI命令处理
   • Colima端口转发

---

后续建议

优化方向

1. 配置tgt Portal IP ⚠️

   • 设置Portal为 0.0.0.0:3260
   • 解决iscsi-ls连接问题

2. 测试gotgt native vs Docker tgt ✅

   • gotgt: 3275 MB/s
   • Docker tgt: 249 MB/s
   • 对比Colima开销

3. 多块大小优化 ✅

   • 128KB块最优（252 MB/s）
   • 调整应用层块大小

4. 测试网络延迟 ⚠️

   • 测试ping延迟
   • 分析Colima端口转发开销

---

文件记录

文件	说明
docs/LIBISCSI_DOCKER_TGT_TEST.md	本测试报告
docs/ISCSI_GOTGT_TEST_REPORT.md	gotgt native测试
docs/ISCSI_PERFORMANCE_COMPARISON.md	之前的对比（需修正）
docker/Dockerfile.iscsi_target	Docker tgt配置

---

测试完成: 2026-05-30 15:05
版本: v1.0
关键发现: 真实TCP/IP iSCSI性能为 249 MB/s，容器内19200 MB/s不代表真实性能。