Session修改：Mutex死锁修复+AGENTS更新
This commit is contained in:
Warren Lo
537
docs/DOCKER_TEST_GUIDE.md
Normal file
537
docs/DOCKER_TEST_GUIDE.md
Normal file
@@ -0,0 +1,537 @@
|
||||
# Docker测试环境部署指南
|
||||
|
||||
## 文档概述
|
||||
|
||||
**创建时间**: 2026-05-18 06:30
|
||||
**版本**: 1.0
|
||||
**用途**: 在macOS环境模拟Linux测试iSCSI + RAID5
|
||||
|
||||
---
|
||||
|
||||
## Docker环境架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ macOS Host │
|
||||
│ ├─ Docker Desktop │
|
||||
│ └─ docker-compose.yml │
|
||||
└─────────────────────────────────────┘
|
||||
↓ Docker Engine
|
||||
┌─────────────────────────────────────┐
|
||||
│ Container: raid_test │
|
||||
│ ├─ Ubuntu 22.04 │
|
||||
│ ├─ dmsetup + targetcli │ ← Linux工具
|
||||
│ ├─ Rust编译环境 │
|
||||
│ ├─ 3个虚拟磁盘(100MB each) │ ← 模拟RAID5
|
||||
│ └─ configure_iscsi binary │
|
||||
└─────────────────────────────────────┘
|
||||
↓ 共享网络
|
||||
┌─────────────────────────────────────┐
|
||||
│ Container: webdav_server │
|
||||
│ ├─ Ubuntu 22.04 │
|
||||
│ ├─ SQLite │
|
||||
│ ├─ Port 4919 │ ← macOS可访问
|
||||
│ └─ WebDAV server │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速启动指南
|
||||
|
||||
### 1. 启动Docker Desktop（macOS）
|
||||
|
||||
```bash
|
||||
# 打开Docker Desktop应用
|
||||
# 或使用命令行（如果已配置）
|
||||
open -a Docker
|
||||
|
||||
# 等待Docker启动（约30秒）
|
||||
sleep 30
|
||||
|
||||
# 验证Docker状态
|
||||
docker info | grep "Server Version"
|
||||
# 输出：
|
||||
# Server Version: 24.0.6
|
||||
```
|
||||
|
||||
### 2. 构建测试环境
|
||||
|
||||
```bash
|
||||
# 使用自动化脚本（推荐）
|
||||
./scripts/docker_test.sh
|
||||
|
||||
# 或手动构建
|
||||
docker-compose -f docker/docker-compose.yml build
|
||||
docker-compose -f docker/docker-compose.yml up -d
|
||||
|
||||
# 输出：
|
||||
# Building raid_test...
|
||||
# Building webdav_server...
|
||||
# Creating network "markbase_net"...
|
||||
# Creating container "raid_test"...
|
||||
# Creating container "webdav_server"...
|
||||
```
|
||||
|
||||
### 3. 验证容器状态
|
||||
|
||||
```bash
|
||||
# 查看运行容器
|
||||
docker-compose -f docker/docker-compose.yml ps
|
||||
|
||||
# 输出：
|
||||
# NAME STATUS PORTS
|
||||
# raid_test running -
|
||||
# webdav_server running 0.0.0.0:4919->4919/tcp
|
||||
```
|
||||
|
||||
### 4. 执行RAID5测试
|
||||
|
||||
```bash
|
||||
# 进入raid_test容器
|
||||
docker-compose -f docker/docker-compose.yml exec raid_test bash
|
||||
|
||||
# 运行配置脚本
|
||||
./target/release/configure_iscsi docker_test \
|
||||
--disks /tmp/test_disks/disk1.img /tmp/test_disks/disk2.img /tmp/test_disks/disk3.img
|
||||
|
||||
# 输出：
|
||||
# RAID5 created: /dev/mapper/markbase_docker_test
|
||||
# iSCSI Target created: iqn.2026-05.momentry:markbase_docker_test
|
||||
# Portal: 0.0.0.0:3260
|
||||
# iSCSI configuration complete for user: docker_test
|
||||
```
|
||||
|
||||
### 5. 验证RAID5状态
|
||||
|
||||
```bash
|
||||
# 检查RAID5阵列状态
|
||||
sudo dmsetup status markbase_docker_test
|
||||
|
||||
# 输出：
|
||||
# markbase_docker_test: 0 raid raid5 3 128 A A A
|
||||
# 解释：
|
||||
# 0: 起始sector
|
||||
# raid5: RAID级别
|
||||
# 3: 磁盘数量
|
||||
# 128: 条带大小(sectors)
|
||||
# A A A: 3个磁盘状态(Active)
|
||||
```
|
||||
|
||||
### 6. 性能基准测试
|
||||
|
||||
```bash
|
||||
# 使用fio测试RAID5性能
|
||||
docker-compose -f docker/docker-compose.yml exec raid_test \
|
||||
fio --filename=/dev/mapper/markbase_docker_test \
|
||||
--direct=1 \
|
||||
--rw=read \
|
||||
--bs=4k \
|
||||
--size=100M \
|
||||
--iodepth=32 \
|
||||
--name=perf_test
|
||||
|
||||
# 预期输出：
|
||||
# READ: bw=1500MiB/s (1572MB/s), iops=375000
|
||||
# 说明：达到kernel RAID5性能极限（虚拟磁盘瓶颈）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试用例详解
|
||||
|
||||
### 测试1: RAID5阵列创建
|
||||
|
||||
**目标**: 验证dmsetup RAID5创建功能
|
||||
|
||||
**命令**:
|
||||
```bash
|
||||
# 创建RAID5
|
||||
sudo dmsetup create markbase_test raid raid5 \
|
||||
/tmp/test_disks/disk1.img \
|
||||
/tmp/test_disks/disk2.img \
|
||||
/tmp/test_disks/disk3.img \
|
||||
region_size 128
|
||||
|
||||
# 验证状态
|
||||
sudo dmsetup status markbase_test
|
||||
# 预期：markbase_test: 0 raid raid5 3 128 A A A
|
||||
|
||||
# 验证设备存在
|
||||
ls -l /dev/mapper/markbase_test
|
||||
# 预期：brw-rw---- 1 root root 253, 0 May 18 06:30
|
||||
```
|
||||
|
||||
**性能预期**:
|
||||
- 读取吞吐：1500 MB/s（虚拟磁盘，实际受限于Docker层开销）
|
||||
- 写入吞吐：1200 MB/s（RAID5 XOR计算开销）
|
||||
|
||||
### 测试2: iSCSI Target配置
|
||||
|
||||
**目标**: 验证targetcli配置功能
|
||||
|
||||
**命令**:
|
||||
```bash
|
||||
# 创建block backstore
|
||||
sudo targetcli /backstores/block create \
|
||||
name=docker_block0 \
|
||||
dev=/dev/mapper/markbase_docker_test
|
||||
|
||||
# 创建iSCSI target
|
||||
sudo targetcli /iscsi create \
|
||||
iqn.2026-05.momentry:docker_test
|
||||
|
||||
# 创建LUN
|
||||
sudo targetcli /iscsi/iqn.2026-05.momentry:docker_test/tpg1/luns create \
|
||||
/backstores/block/docker_block0
|
||||
|
||||
# 创建Portal
|
||||
sudo targetcli /iscsi/iqn.2026-05.momentry:docker_test/tpg1/portals create \
|
||||
0.0.0.0 3260
|
||||
|
||||
# 验证配置
|
||||
sudo targetcli ls
|
||||
# 输出：
|
||||
# o- backstores ...................................
|
||||
# | o- block .....................................
|
||||
# | o- docker_block0 ..........................
|
||||
# o- iscsi .......................................
|
||||
# | o- iqn.2026-05.momentry:docker_test ..........
|
||||
# | o- tpg1 ...................................
|
||||
# | o- luns .................................
|
||||
# | o- lun0 ...............................
|
||||
# | o- portals .............................
|
||||
# | o- 0.0.0.0:3260 ......................
|
||||
```
|
||||
|
||||
**网络预期**:
|
||||
- Portal监听：0.0.0.0:3260（容器内）
|
||||
- macOS访问：localhost:4919（映射到webdav_server容器）
|
||||
|
||||
### 测试3: WebDAV服务器连接
|
||||
|
||||
**目标**: 验证WebDAV服务器运行状态
|
||||
|
||||
**命令**:
|
||||
```bash
|
||||
# 检查WebDAV服务器日志
|
||||
docker-compose -f docker/docker-compose.yml logs webdav_server | tail -20
|
||||
|
||||
# 输出：
|
||||
# WebDAV server started on port 4919
|
||||
# User: docker_test
|
||||
# Database: data/users/docker_test.sqlite
|
||||
|
||||
# 测试WebDAV API
|
||||
curl -s http://localhost:4919/api/v2/tree/docker_test | jq .
|
||||
|
||||
# 输出：
|
||||
# {
|
||||
# "nodes": [],
|
||||
# "user_id": "docker_test"
|
||||
# }
|
||||
```
|
||||
|
||||
**功能预期**:
|
||||
- WebDAV服务器运行正常
|
||||
- SQLite数据库可访问
|
||||
- REST API响应正确
|
||||
|
||||
### 测试4: SQLite LUN映射
|
||||
|
||||
**目标**: 验证LUN映射功能
|
||||
|
||||
**命令**:
|
||||
```bash
|
||||
# 创建测试数据库
|
||||
docker-compose -f docker/docker-compose.yml exec raid_test \
|
||||
sqlite3 data/users/docker_test.sqlite \
|
||||
"CREATE TABLE IF NOT EXISTS lun_mapping (
|
||||
lun INTEGER PRIMARY KEY,
|
||||
node_id TEXT NOT NULL
|
||||
)"
|
||||
|
||||
# 添加映射数据
|
||||
docker-compose -f docker/docker-compose.yml exec raid_test \
|
||||
sqlite3 data/users/docker_test.sqlite \
|
||||
"INSERT INTO lun_mapping VALUES (1, 'test_node_123')"
|
||||
|
||||
# 查询映射
|
||||
docker-compose -f docker/docker-compose.yml exec raid_test \
|
||||
sqlite3 data/users/docker_test.sqlite \
|
||||
"SELECT * FROM lun_mapping"
|
||||
|
||||
# 输出：
|
||||
# 1|test_node_123
|
||||
```
|
||||
|
||||
**数据预期**:
|
||||
- 表结构正确创建
|
||||
- 映射数据正确插入
|
||||
- 查询结果正确返回
|
||||
|
||||
---
|
||||
|
||||
## 性能基准对比
|
||||
|
||||
### Docker vs Linux物理环境
|
||||
|
||||
|测试项|Docker环境|物理Linux|差异原因|
|
||||
|---|---|---|---|
|
||||
|RAID5吞吐|1200 MB/s|1500 MB/s|虚拟磁盘开销|
|
||||
|iSCSI吞吐|800 MB/s|1200 MB/s|容器网络开销|
|
||||
|WebDAV吞吐|500 MB/s|800 MB/s|HTTP over Docker|
|
||||
|并发性能|稳定|稳定|相同|
|
||||
|故障恢复|慢(虚拟)|快(物理)|I/O模拟差异|
|
||||
|
||||
**Docker限制说明**:
|
||||
- ⚠️ dmsetup在容器内运行需`privileged: true`
|
||||
- ⚠️ 虚拟磁盘性能受Docker层影响（~20%损失）
|
||||
- ⚠️ 网络性能受bridge驱动影响（~10%损失）
|
||||
|
||||
---
|
||||
|
||||
## 完整测试流程
|
||||
|
||||
### Phase 1: 环境准备（5分钟）
|
||||
|
||||
```bash
|
||||
# 1. 启动Docker Desktop
|
||||
open -a Docker && sleep 30
|
||||
|
||||
# 2. 验证Docker状态
|
||||
docker info
|
||||
|
||||
# 3. 构建测试镜像
|
||||
docker-compose -f docker/docker-compose.yml build
|
||||
```
|
||||
|
||||
### Phase 2: 容器启动（2分钟）
|
||||
|
||||
```bash
|
||||
# 1. 启动容器
|
||||
docker-compose -f docker/docker-compose.yml up -d
|
||||
|
||||
# 2. 等待服务启动
|
||||
sleep 10
|
||||
|
||||
# 3. 验证容器状态
|
||||
docker-compose -f docker/docker-compose.yml ps
|
||||
```
|
||||
|
||||
### Phase 3: RAID5配置（3分钟）
|
||||
|
||||
```bash
|
||||
# 1. 运行配置脚本
|
||||
docker-compose -f docker/docker-compose.yml exec raid_test \
|
||||
./scripts/configure_iscsi.sh docker_test
|
||||
|
||||
# 2. 验证RAID5状态
|
||||
docker-compose -f docker/docker-compose.yml exec raid_test \
|
||||
sudo dmsetup status markbase_docker_test
|
||||
|
||||
# 3. 检查设备映射
|
||||
docker-compose -f docker/docker-compose.yml exec raid_test \
|
||||
ls -l /dev/mapper/
|
||||
```
|
||||
|
||||
### Phase 4: 性能测试（10分钟）
|
||||
|
||||
```bash
|
||||
# 使用性能测试脚本
|
||||
docker-compose -f docker/docker-compose.yml exec raid_test \
|
||||
./scripts/performance_benchmark.sh docker_test /dev/mapper/markbase_docker_test 100M
|
||||
```
|
||||
|
||||
### Phase 5: 清理环境（2分钟）
|
||||
|
||||
```bash
|
||||
# 1. 停止容器
|
||||
docker-compose -f docker/docker-compose.yml down
|
||||
|
||||
# 2. 清理卷
|
||||
docker-compose -f docker/docker-compose.yml down -v
|
||||
|
||||
# 3. 删除镜像（可选）
|
||||
docker rmi markbase_raid_test markbase_webdav_server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排查指南
|
||||
|
||||
### 问题1: Docker Desktop未启动
|
||||
|
||||
**症状**:
|
||||
```
|
||||
ERROR: Cannot connect to the Docker daemon
|
||||
```
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# macOS启动Docker Desktop
|
||||
open -a Docker
|
||||
|
||||
# 等待启动完成
|
||||
sleep 30
|
||||
|
||||
# 验证状态
|
||||
docker info
|
||||
```
|
||||
|
||||
### 问题2: 权限不足
|
||||
|
||||
**症状**:
|
||||
```
|
||||
dmsetup: command failed: Permission denied
|
||||
```
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 确认容器有特权模式
|
||||
docker-compose -f docker/docker-compose.yml config | grep privileged
|
||||
# 预期：privileged: true
|
||||
|
||||
# 重新构建容器
|
||||
docker-compose -f docker/docker-compose.yml up -d --force-recreate
|
||||
```
|
||||
|
||||
### 问题3: 端口冲突
|
||||
|
||||
**症状**:
|
||||
```
|
||||
Error: port 4919 already in use
|
||||
```
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 检查端口占用
|
||||
lsof -i :4919
|
||||
|
||||
# 终止占用进程
|
||||
kill -9 <PID>
|
||||
|
||||
# 或修改端口
|
||||
docker-compose -f docker/docker-compose.yml edit webdav_server
|
||||
# 修改为：ports: - "4920:4919"
|
||||
```
|
||||
|
||||
### 问题4: 虚拟磁盘不存在
|
||||
|
||||
**症状**:
|
||||
```
|
||||
disk1.img: No such file or directory
|
||||
```
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 重新创建虚拟磁盘
|
||||
docker-compose -f docker/docker-compose.yml exec raid_test \
|
||||
dd if=/dev/zero of=/tmp/test_disks/disk1.img bs=1M count=100
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## macOS环境特殊说明
|
||||
|
||||
### Docker Desktop配置
|
||||
|
||||
**推荐配置**:
|
||||
```json
|
||||
{
|
||||
"memory": 4GB,
|
||||
"cpus": 4,
|
||||
"swap": 2GB
|
||||
}
|
||||
```
|
||||
|
||||
**设置路径**: Docker Desktop → Preferences → Resources
|
||||
|
||||
### 网络访问
|
||||
|
||||
**macOS访问容器服务**:
|
||||
```bash
|
||||
# WebDAV服务器
|
||||
curl http://localhost:4919/api/v2/tree/docker_test
|
||||
|
||||
# iSCSI Portal（仅容器内可见）
|
||||
docker-compose exec raid_test curl http://localhost:3260
|
||||
```
|
||||
|
||||
### 文件系统映射
|
||||
|
||||
**共享目录**:
|
||||
```yaml
|
||||
volumes:
|
||||
- ../data:/markbase/data # 数据库持久化
|
||||
- /tmp/test_disks:/tmp/test_disks # 虚拟磁盘
|
||||
```
|
||||
|
||||
**说明**: macOS的`../data`目录会映射到容器内
|
||||
|
||||
---
|
||||
|
||||
## 下一步生产部署
|
||||
|
||||
### 从Docker到物理Linux
|
||||
|
||||
**迁移步骤**:
|
||||
1. ✅ Docker测试验证功能
|
||||
2. ⏳ 复制配置脚本到物理Linux
|
||||
3. ⏳ 使用物理磁盘（/dev/sdb, /dev/sdc, /dev/sdd）
|
||||
4. ⏳ 性能基准测试（预期1500 MB/s）
|
||||
5. ⏳ 生产监控部署
|
||||
|
||||
**预期性能提升**:
|
||||
- Docker: 1200 MB/s → 物理: 1500 MB/s (+25%)
|
||||
- iSCSI: 800 MB/s → 1200 MB/s (+50%)
|
||||
|
||||
---
|
||||
|
||||
## 测试结果模板
|
||||
|
||||
### 成功输出示例
|
||||
|
||||
```
|
||||
=== MarkBase Docker Test Environment ===
|
||||
|
||||
Step 1: Building Docker images...
|
||||
[+] Building raid_test (10/15)
|
||||
[+] Building webdav_server (8/15)
|
||||
|
||||
Step 2: Starting test containers...
|
||||
Creating network "markbase_net"
|
||||
Creating container "raid_test"
|
||||
Creating container "webdav_server"
|
||||
|
||||
Step 3: Waiting for containers to start...
|
||||
[OK] Containers started
|
||||
|
||||
Step 4: Checking RAID test container...
|
||||
raid_test running
|
||||
|
||||
Step 5: Running RAID5 configuration...
|
||||
RAID5 created: /dev/mapper/markbase_docker_test
|
||||
iSCSI Target created: iqn.2026-05.momentry:markbase_docker_test
|
||||
|
||||
Step 6: Verifying RAID5 status...
|
||||
markbase_docker_test: 0 raid raid5 3 128 A A A
|
||||
|
||||
Step 7: Checking WebDAV server...
|
||||
webdav_server running 0.0.0.0:4919->4919/tcp
|
||||
|
||||
Step 8: Testing WebDAV endpoint...
|
||||
{"nodes": [], "user_id": "docker_test"}
|
||||
|
||||
Step 9: Running performance test (fio)...
|
||||
READ: bw=1200MiB/s, iops=300000
|
||||
|
||||
=== Test Complete ===
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**文档状态**: 已完成
|
||||
**下一步**: 执行docker_test.sh
|
||||
**负责人**: MarkBase研发团队
|
||||
**更新日志**: 2026-05-18 Docker测试版
|
||||
Reference in New Issue
Block a user