syncgate 1.3.0
Lightweight multi-storage routing and sync abstraction layer
Requires Python: >=3.10

# SyncGate 🎯

> 轻量级多存储路由与同步抽象层

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-168%2B-green.svg)]()
[![Version](https://img.shields.io/badge/version-v1.1.0-blue.svg)]()

## 🎯 产品定位

**SyncGate** 是轻量级多存储路由与同步抽象层，统一管理本地文件、HTTP 链接和多种云存储。

### 核心功能

1. **🔗 统一路径** - 多种存储一个命令访问
2. **🌳 虚拟文件系统** - 不移动源文件，只管理链接
3. **✅ 链接验证** - 自动验证链接有效性
4. **📊 监控统计** - 跟踪使用情况和健康评分
5. **🔄 批量操作** - 批量创建/删除/验证
6. **⚡ 错误处理** - 重试机制和熔断器
7. **🌐 WebDAV 服务器** - 挂载为网络磁盘
8. **🐳 Docker 部署** - 一键容器化部署

### 支持的存储

| 存储类型 | 状态 | 协议 |
|----------|------|------|
| 本地文件 | ✅ | local:/path/to/file |
| HTTP/HTTPS | ✅ | https://example.com/file |
| AWS S3 | ✅ | s3://bucket/key |
| WebDAV | ✅ | webdav://server.com/path |
| FTP | ✅ | ftp://server.com/path |
| SFTP | ✅ | sftp://user@server.com/path |

## 🚀 快速开始

### 方式一: pip 安装

```bash
pip install syncgate
```

### 方式二: Docker 部署

```bash
# 构建镜像
docker build -t syncgate .

# 运行容器
docker run -p 8080:8080 -v /path/to/virtual:/data syncgate
```

### 方式三: Docker Compose

```bash
docker-compose up -d
```

### 方式四: Kubernetes

```bash
kubectl apply -f k8s/deployment.yaml
# 或使用 Helm
helm install syncgate k8s/helm-chart/
```

### WebDAV 挂载

启动 WebDAV 服务器后，可以挂载为网络磁盘：

```bash
# 启动服务器（无认证）
python3 -m syncgate.webdav_server /path/to/virtual --port 8080

# 启动服务器（带认证）
python3 -m syncgate.webdav_server /path/to/virtual --port 8080 --user admin --pass secret
```

挂载方法：
- **macOS**: `Cmd+K` → `dav://localhost:8080/`
- **Windows**: 此电脑 → 添加网络位置 → `dav://localhost:8080/`
- **Linux**: `mount -t davfs http://localhost:8080/ /mnt/dav`

### Web 管理器

启动 Web 图形管理界面：

```bash
# 启动 Web 管理器
python3 -m syncgate.web --port 8080

# 访问 http://localhost:8080
```

功能：
- 📊 仪表盘 - 实时统计概览
- 🔗 链接管理 - CRUD 操作
- ☁️ 后端状态查看
- 📈 统计图表
- 📥 导入导出
- ⚙️ 设置页面

详细说明: [WEB_GUIDE.md](WEB_GUIDE.md)

### 演示

```bash
python3 demo_complete.py

# 或使用 WebDAV
python3 -m syncgate.webdav_server ./virtual --port 8080
```

输出：
```
🎯 SyncGate Complete Demo
============================================================

📝 Step 1: 创建链接
  ✅ Local:  /docs/notes.txt
  ✅ HTTP:   /online/api.json
  ✅ S3:     /cloud/data.csv

📂 Step 2: 虚拟文件系统结构
virtual/
├── 📁 docs/  → local:/path/to/files
├── 📁 online/ → https://api.example.com
└── 📁 cloud/  → s3://my-bucket/data

🔍 Step 3: 链接验证
  ✅ /docs/notes.txt
  ✅ /online/api.json

✅ 演示完成!
```

### 使用

```bash
# 创建链接
syncgate link /docs/a.txt local:/path/to/file.txt local
syncgate link /online/api.json https://api.example.com/data.json http
syncgate link /cloud/data.csv s3://my-bucket/data/2024.csv s3

# 列出目录
syncgate ls /docs

# 树形结构
syncgate tree /

# 验证链接
syncgate validate /docs/a.txt

# 查看状态
syncgate status /docs/a.txt
```

## 📖 文档

- [Usage](USAGE.md) - 完整使用指南
- [Quick Start](QUICK_START.md) - 5 分钟快速开始
- [Project](PROJECT.md) - 架构设计
- [Changelog](CHANGELOG.md) - 更新日志
- [Web Guide](WEB_GUIDE.md) - Web 管理器使用说明
- [Docker Deployment](DOCKER.md) - Docker 部署指南
- [Kubernetes](k8s/) - K8s 部署配置

## 🔗 相关链接

- GitHub: https://github.com/cyydark/syncgate
- Issues: https://github.com/cyydark/syncgate/issues
- Releases: https://github.com/cyydark/syncgate/releases

## 🛠️ 功能模块

### CLI 命令

| 命令 | 说明 |
|------|------|
| `link` | 创建链接 |
| `unlink` | 删除链接 |
| `ls` | 列出目录 |
| `tree` | 树形结构 |
| `validate` | 验证链接 |
| `status` | 查看状态 |

### REST API

```bash
# 启动 API 服务器
python -m syncgate.api --port 8080
```

| 端点 | 说明 |
|------|------|
| GET /api/stats | 获取统计 |
| GET /api/links | 获取所有链接 |
| POST /api/links | 创建链接 |
| DELETE /api/links/{path} | 删除链接 |

### WebDAV 服务器

```bash
# 启动 WebDAV 服务器
python3 -m syncgate.webdav_server /path/to/virtual --port 8080

# 带认证
python3 -m syncgate.webdav_server /path/to/virtual --port 8080 --user admin --pass secret
```

| 方法 | 说明 |
|------|------|
| GET/HEAD | 读取文件/目录 |
| PUT | 创建/更新文件 |
| DELETE | 删除文件 |
| PROPFIND | 获取属性 |
| MKCOL | 创建目录 |
| MOVE | 移动文件 |
| COPY | 复制文件 |

### 高级功能

```python
from syncgate.batch import BatchOperations
from syncgate.monitor import StatsCollector
from syncgate.error_handler import retry, CircuitBreaker

# 批量操作
batch = BatchOperations(vfs_root="virtual")
batch.batch_create([...])

# 监控统计
stats = StatsCollector(vfs_root="virtual")
stats.record_create("local")
health = stats.get_health_score()

# 错误处理
@retry(max_retries=3, delay=1.0)
def fragile_operation():
    ...
```

### Docker & Kubernetes

```yaml
# docker-compose.yml
services:
  syncgate:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./virtual:/data/virtual
```

```bash
# Kubernetes 部署
kubectl apply -f k8s/deployment.yaml

# Helm 安装
helm install syncgate k8s/helm-chart/
```

## 🧪 测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行性能测试
python3 tests/benchmark_streaming.py
```

**测试覆盖**: 168+ 测试用例

## 📦 部署选项

| 方式 | 命令 | 适用场景 |
|------|------|----------|
| pip | `pip install syncgate` | 本地开发 |
| Docker | `docker build && docker run` | 生产部署 |
| Compose | `docker-compose up -d` | 本地/测试 |
| K8s | `kubectl apply -f k8s/` | Kubernetes |
| Helm | `helm install syncgate k8s/helm-chart/` | K8s 生产 |

## ☁️ 云部署

### AWS ECS / EKS

```yaml
# 使用官方镜像
image: ghcr.io/cyydark/syncgate:latest
```

### Azure Container Apps

```bash
az containerapp create \
  --name syncgate \
  --resource-group mygroup \
  --image ghcr.io/cyydark/syncgate:latest \
  --target-port 8080 \
  --ingress external
```

## 📈 性能

| 场景 | 性能 |
|------|------|
| 初始化 (5000 文件) | 0.04ms |
| 首屏加载 | 2ms (50 条) |
| WebDAV 响应 | <10ms |
| Docker 启动 | <2s |

## 🏗️ 开发

```bash
# 克隆项目
git clone https://github.com/cyydark/syncgate.git
cd syncgate

# 安装开发依赖
pip install -e ".[dev]"

# 运行演示
python3 demo_complete.py

# 运行测试
pytest tests/ -v

# 构建 Docker 镜像
docker build -t syncgate .

# 运行 WebDAV 服务器
python3 -m syncgate.webdav_server ./virtual --port 8080
```

## 🤝 贡献

欢迎提交 Issue 和 PR！

反馈: [GitHub Issues](https://github.com/cyydark/syncgate/issues)

## 📄 许可

MIT License - see [LICENSE](LICENSE)

---

**SyncGate** - 统一管理散落在各处的文件 📁🌐☁️