syncgate 1.3.0

Lightweight multi-storage routing and sync abstraction layer

SyncGate 🎯

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

🎯 产品定位

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://[e-mail]/path

🚀 快速开始

方式一: pip 安装

pip install syncgate

方式二: Docker 部署

# 构建镜像
docker build -t syncgate .

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

方式三: Docker Compose

docker-compose up -d

方式四: Kubernetes

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

WebDAV 挂载

启动 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

挂载方法：

• macOS: Cmd+K → dav://localhost:8080/
• Windows: 此电脑 → 添加网络位置 → dav://localhost:8080/
• Linux: mount -t davfs http://localhost:8080/ /mnt/dav

Web 管理器

启动 Web 图形管理界面：

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

# 访问 http://localhost:8080

功能：

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

详细说明: WEB_GUIDE.md

演示

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

✅ 演示完成!

使用

# 创建链接
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 - 完整使用指南
• Quick Start - 5 分钟快速开始
• Project - 架构设计
• Changelog - 更新日志
• Web Guide - Web 管理器使用说明
• Docker Deployment - Docker 部署指南
• Kubernetes - 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

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

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

WebDAV 服务器

# 启动 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	复制文件

高级功能

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

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

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

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

🧪 测试

# 运行所有测试
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

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

Azure Container Apps

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

🏗️ 开发

# 克隆项目
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

📄 许可

MIT License - see LICENSE

---

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