# mini-seaweedfs

**Repository Path**: MuMuNan/mini-seaweedfs

## Basic Information

- **Project Name**: mini-seaweedfs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mini-seaweedfs

`mini-seaweedfs` 是 SeaweedFS 的「代码路径蒸馏」学习项目。

它不是 SeaweedFS 的复刻，也不是通用对象存储系统，而是把 SeaweedFS 真实源码中最重要的几条主代码路径用更小、更清晰、更易读的方式重新实现。

详细背景见 [`CLAUDE.md`](CLAUDE.md)。

## 当前进度（第一批 P0–P4）

第一批五条主路径已完成端到端打通：

| 路径 | 内容 | 状态 |
| ---- | ---- | ---- |
| P0 | 服务启动入口（master / volume / filer） | ✅ |
| P1 | Volume Server 注册到 Master | ✅ |
| P4 | Needle append / index / read | ✅ |
| P2 | 小文件写入路径（client → filer → master → volume） | ✅ |
| P3 | 小文件读取路径（client → filer → master → volume） | ✅ |

蒸馏目标对照见 [`docs/seaweedfs-reading-map.md`](docs/seaweedfs-reading-map.md)，逐条路径设计见 `docs/p0-startup.md` / `docs/p1-registration.md` / `docs/p2-write.md` / `docs/p3-read.md` / `docs/p4-needle.md`，整体计划见 [`docs/plan.md`](docs/plan.md)。

## 项目结构

```text
cmd/
  mini-master/    # master 启动入口（对应 weed/command/master.go）
  mini-volume/    # volume 启动入口（对应 weed/command/volume.go）
  mini-filer/     # filer 启动入口（对应 weed/command/filer.go）
  mini-client/    # CLI 客户端（put / get）

internal/
  master/         # registry + assigner + /dir/lookup
  volume/         # store + needle + index + write/read handler
  filer/          # path → fileId 内存元数据 + write/read handler
  proto/          # fileId 模型

test/
  integration/    # 同进程集成测试（httptest）
  e2e/            # 端到端子进程测试（go run）

scripts/
  demo-put-get.sh # 一键演示 put → get 闭环
```

## 演示

要求：本机 `go` 工具链、空闲端口 `9333 / 8080 / 8888`、可写目录 `/tmp/mini-volume`。

### 一键脚本

```bash
bash scripts/demo-put-get.sh
# 期望输出：hello seaweedfs
```

脚本会启动 master / volume / filer 三个服务，put 一个本地文件，get 回内容，最后清理子进程。

### 手动步骤

打开四个终端：

```bash
# terminal 1: master
go run ./cmd/mini-master --listen=:9333

# terminal 2: volume
go run ./cmd/mini-volume \
  --listen=:8080 \
  --master=http://localhost:9333 \
  --dir=/tmp/mini-volume \
  --volume=1 \
  --ip=localhost

# terminal 3: filer
go run ./cmd/mini-filer --listen=:8888 --master=http://localhost:9333

# terminal 4: client
echo "hello seaweedfs" > /tmp/hello.txt
go run ./cmd/mini-client put /tmp/hello.txt /hello.txt
go run ./cmd/mini-client get /hello.txt
# 期望输出：hello seaweedfs
```

### 直接走 HTTP

mini-client 是个薄壳，主路径全部在 filer 上：

```bash
curl --data-binary @/tmp/hello.txt http://localhost:8888/hello.txt
curl http://localhost:8888/hello.txt
```

## 测试

```bash
go test ./...                 # 全量
go test -race ./internal/...  # L1/L2 单元 + handler，带 race 检测
go test ./test/integration    # L3 同进程集成
go test ./test/e2e            # L4 端到端子进程
```

测试规范见 [`docs/test-policy.md`](docs/test-policy.md)。

## 不做什么

参见 `CLAUDE.md` §12 与 `docs/plan.md` §4。第一批不实现：副本 / EC / TTL / compaction / S3 gateway / FUSE / chunk manifest / cookie / 多 filer 后端 / raft / 认证 / 监控。

后续批次只蒸馏 SeaweedFS 真实存在的主路径（P5 filer 元数据 → P6 删除/Compaction → P7 S3 gateway），不引入「通用云系统看起来需要」的组件。