doc: 细化文档

.github/workflows/rust.yml

@@ -2,21 +2,48 @@ name: Rust
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "doc" ]
   pull_request:
     branches: [ "main" ]
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  build:
-
+  check:
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v4
-    - name: Build
-      run: cargo build --verbose
-    - name: Run tests
-      run: cargo test --verbose
+
+    - name: Install protoc
+      run: sudo apt-get update && sudo apt-get install -y protobuf-compiler
+
+    - name: Install Rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rustfmt, clippy
+
+    - name: Cache cargo
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cargo/bin/
+          ~/.cargo/registry/index/
+          ~/.cargo/registry/cache/
+          ~/.cargo/git/db/
+          target/
+        key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+        restore-keys: ${{ runner.os }}-cargo-
+
+    - name: cargo fmt
+      run: cargo fmt --all -- --check
+
+    - name: cargo clippy
+      run: cargo clippy --workspace --all-targets -- -D warnings
+
+    - name: cargo build
+      run: cargo build --workspace --verbose
+
+    - name: cargo test
+      run: cargo test --workspace --verbose

.gitignore

@@ -1,30 +1,8 @@
-# Rust
-/target/
-**/*.rs.bk
-*.pdb
+/target
+**/target
 Cargo.lock
-
-# IDE
-.idea/
-.vscode/
 *.swp
 *.swo
-*~
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Config
-config/config.yaml
-!config/config.yaml.example
-
-# Logs
+.env
 *.log
-logs/
-
-# Cache
-/var/cache/coldstore/
-
-# Test data
-test_data/
+/data

Cargo.toml

@@ -1,69 +1,64 @@
-[package]
-name = "coldstore"
+[workspace]
+resolver = "2"
+members = [
+    "crates/proto",
+    "crates/common",
+    "crates/metadata",
+    "crates/gateway",
+    "crates/scheduler",
+    "crates/cache",
+    "crates/tape",
+]
+
+[workspace.package]
 version = "0.1.0"
 edition = "2021"
-authors = ["Your Name <your.email@example.com>"]
-description = "S3-compatible tape-based cold storage archive system"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/yourusername/coldstore"
 
-[dependencies]
+[workspace.dependencies]
 # Async runtime
-tokio = { version = "1.35", features = ["full"] }
+tokio = { version = "1", features = ["full"] }
+
+# gRPC
+tonic = "0.12"
+tonic-build = "0.12"
+prost = "0.13"
+prost-types = "0.13"
 
-# HTTP server and S3 compatibility
+# HTTP server (Gateway S3 layer)
 axum = "0.7"
 tower = "0.4"
 tower-http = { version = "0.5", features = ["cors", "trace"] }
-http = "1.0"
-hyper = "1.0"
+http = "1"
+hyper = "1"
 
 # Serialization
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
 serde_yaml = "0.9"
 
-# Database and metadata storage
-sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "postgres", "chrono", "uuid"] }
-# etcd-rs = "1.0"  # 暂时注释，等需要时再添加
-
 # Error handling
-anyhow = "1.0"
-thiserror = "1.0"
+anyhow = "1"
+thiserror = "2"
 
 # Logging and observability
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
-tracing-appender = "0.2"
+
+# Time and identity
+chrono = { version = "0.4", features = ["serde"] }
+uuid = { version = "1", features = ["v4", "serde"] }
 
 # Configuration
 config = "0.14"
 
-# Time and date
-chrono = { version = "0.4", features = ["serde"] }
-uuid = { version = "1.6", features = ["v4", "serde"] }
+# Streaming
+tokio-stream = "0.1"
 
-# Checksum and hashing
+# Checksum
 sha2 = "0.10"
-crc32fast = "1.3"
-
-# Cache
-lru = "0.12"
-
-# Tape and storage
-# Note: These may need to be replaced with actual tape library bindings
-# For now, we'll use placeholder dependencies
-
-# Message queue and notifications
-# rabbitmq-stream-client = "0.12"  # Optional: for MQ integration
-
-# Metrics (optional)
-# prometheus = "0.13"
-
-[dev-dependencies]
-tokio-test = "0.4"
-mockall = "0.12"
 
-[[bin]]
-name = "coldstore"
-path = "src/main.rs"
+# Internal crates
+coldstore-proto = { path = "crates/proto" }
+coldstore-common = { path = "crates/common" }

Makefile

@@ -1,133 +1,60 @@
-.PHONY: build fmt clippy run clean test help
+.PHONY: build fmt clippy test clean check help install-hooks lint
 
-# 默认目标
 .DEFAULT_GOAL := help
 
-# 项目名称
-PROJECT := coldstore
-
-# 构建模式（release 或 debug）
 BUILD_MODE ?= release
 
-# 运行参数
-RUN_ARGS ?=
-
-# 构建项目
 build:
-	@echo "构建项目 ($(BUILD_MODE))..."
-	@if [ "$(BUILD_MODE)" = "release" ]; then \
-		cargo build --release; \
-	else \
-		cargo build; \
-	fi
+	@echo "Building all crates ($(BUILD_MODE))..."
+	@if [ "$(BUILD_MODE)" = "release" ]; then cargo build --release; else cargo build; fi
 
-# 快速构建（debug 模式）
 build-debug:
 	@$(MAKE) BUILD_MODE=debug build
 
-# 格式化代码
 fmt:
-	@echo "格式化代码..."
 	@cargo fmt --all
-	@echo "代码格式化完成"
-
-# 检查代码格式
 fmt-check:
-	@echo "检查代码格式..."
 	@cargo fmt --all -- --check
-
-# 运行 Clippy 代码检查
 clippy:
-	@echo "运行 Clippy 代码检查..."
 	@cargo clippy --all-targets --all-features -- -D warnings
-	@echo "Clippy 检查完成"
-
-# 运行 Clippy（允许警告）
-clippy-allow:
-	@echo "运行 Clippy 代码检查（允许警告）..."
-	@cargo clippy --all-targets --all-features
-
-# 运行项目
-run:
-	@echo "运行项目..."
-	@cargo run --release -- $(RUN_ARGS)
-
-# 运行项目（debug 模式）
-run-debug:
-	@echo "运行项目（debug 模式）..."
-	@cargo run -- $(RUN_ARGS)
-
-# 清理构建产物
-clean:
-	@echo "清理构建产物..."
-	@cargo clean
-	@echo "清理完成"
-
-# 运行测试
 test:
-	@echo "运行测试..."
 	@cargo test --all-features
-	@echo "测试完成"
-
-# 运行测试（显示输出）
-test-verbose:
-	@echo "运行测试（显示输出）..."
-	@cargo test --all-features -- --nocapture
-
-# 检查代码（不构建）
 check:
-	@echo "检查代码..."
 	@cargo check --all-targets --all-features
-	@echo "检查完成"
-
-# 完整检查（格式化 + Clippy + 测试）
 check-all: fmt-check clippy test
-	@echo "所有检查完成"
+clean:
+	@cargo clean
 
-# 开发前检查（格式化 + Clippy）
-dev-check: fmt-check clippy
-	@echo "开发检查完成"
+run-metadata:
+	@cargo run -p coldstore-metadata
+run-gateway:
+	@cargo run -p coldstore-gateway
+run-scheduler:
+	@cargo run -p coldstore-scheduler
+run-cache:
+	@cargo run -p coldstore-cache
+run-tape:
+	@cargo run -p coldstore-tape
+
+lint: fmt-check clippy check test
+	@echo "All lint checks passed."
+
+install-hooks:
+	@cp scripts/pre-commit .git/hooks/pre-commit
+	@chmod +x .git/hooks/pre-commit
+	@echo "Pre-commit hook installed."
 
-# 安装开发工具
 install-tools:
-	@echo "安装开发工具..."
 	@rustup component add rustfmt clippy
-	@echo "开发工具安装完成"
+	@echo "protobuf-compiler required: apt install protobuf-compiler"
 
-# 更新依赖
-update:
-	@echo "更新依赖..."
-	@cargo update
-	@echo "依赖更新完成"
+setup: install-tools install-hooks
+	@echo "Development environment ready."
 
-# 显示帮助信息
 help:
-	@echo "ColdStore 项目 Makefile"
-	@echo ""
-	@echo "可用目标："
-	@echo "  build          - 构建项目（release 模式）"
-	@echo "  build-debug    - 构建项目（debug 模式）"
-	@echo "  fmt            - 格式化代码"
-	@echo "  fmt-check      - 检查代码格式"
-	@echo "  clippy         - 运行 Clippy 代码检查（严格模式）"
-	@echo "  clippy-allow   - 运行 Clippy 代码检查（允许警告）"
-	@echo "  run            - 运行项目（release 模式）"
-	@echo "  run-debug      - 运行项目（debug 模式）"
-	@echo "  clean          - 清理构建产物"
-	@echo "  test           - 运行测试"
-	@echo "  test-verbose   - 运行测试（显示输出）"
-	@echo "  check          - 检查代码（不构建）"
-	@echo "  check-all      - 完整检查（格式化 + Clippy + 测试）"
-	@echo "  dev-check      - 开发前检查（格式化 + Clippy）"
-	@echo "  install-tools  - 安装开发工具（rustfmt, clippy）"
-	@echo "  update         - 更新依赖"
-	@echo "  help           - 显示此帮助信息"
+	@echo "ColdStore Workspace Makefile"
 	@echo ""
-	@echo "示例："
-	@echo "  make build              # 构建 release 版本"
-	@echo "  make build-debug        # 构建 debug 版本"
-	@echo "  make fmt                # 格式化代码"
-	@echo "  make clippy             # 运行 Clippy 检查"
-	@echo "  make run                # 运行项目"
-	@echo "  make run RUN_ARGS='--help'  # 带参数运行"
-	@echo "  make check-all          # 运行所有检查"
+	@echo "Build:   build build-debug clean"
+	@echo "Quality: fmt fmt-check clippy test check check-all lint"
+	@echo "Run:     run-metadata run-gateway run-scheduler run-cache run-tape"
+	@echo "Setup:   setup install-tools install-hooks"