216 lines
4.1 KiB
Markdown
216 lines
4.1 KiB
Markdown
# FTS - 文件传输服务
|
||
|
||
基于Go 1.26.5和Gin框架的现代化文件传输微服务
|
||
|
||
## 特性
|
||
|
||
- 🚀 **现代化架构**: 使用Go 1.26.5最新特性
|
||
- 📁 **多存储支持**: 支持本地存储和MinIO对象存储
|
||
- 🔧 **配置灵活**: 支持YAML配置文件，环境变量覆盖
|
||
- 🏥 **健康检查**: 完整的健康检查和监控端点
|
||
- 🔒 **安全性**: 文件类型检查，大小限制，JWT认证支持
|
||
- 📊 **可观测性**: 完整的日志记录和错误追踪
|
||
- 🐳 **容器化**: Docker和docker-compose开箱即用
|
||
- 🛠️ **开发友好**: 完整的Makefile工具链
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Go 1.26.5
|
||
- PostgreSQL / MySQL (可选)
|
||
- Redis (可选)
|
||
- MinIO (可选，用于对象存储)
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
make deps
|
||
```
|
||
|
||
### 运行服务
|
||
|
||
```bash
|
||
# 开发模式
|
||
make dev
|
||
|
||
# 或构建后运行
|
||
make build
|
||
make run
|
||
```
|
||
|
||
### 使用Docker
|
||
|
||
```bash
|
||
# 启动完整环境（包括数据库、Redis等）
|
||
docker-compose up -d
|
||
|
||
# 仅构建应用镜像
|
||
make docker-build
|
||
```
|
||
|
||
## API文档
|
||
|
||
### 健康检查
|
||
|
||
```http
|
||
GET /health # 详细健康检查
|
||
GET /health/simple # 简单健康检查
|
||
GET /version # 版本信息
|
||
```
|
||
|
||
### 文件操作
|
||
|
||
```http
|
||
POST /fts/upload # 文件上传
|
||
GET /fts/download # 文件下载
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
主要配置文件：`etc/fts_dev.yaml`
|
||
|
||
```yaml
|
||
Service: fts
|
||
Host: 0.0.0.0
|
||
Port: 16290
|
||
|
||
# 数据库配置
|
||
Databases:
|
||
Driver: postgres
|
||
Source:
|
||
- "postgres://user:pass@localhost/fts?sslmode=disable"
|
||
|
||
# 缓存配置
|
||
Cache: redis://localhost:6379/0
|
||
|
||
# 对象存储配置
|
||
MinioOss:
|
||
Site: http://localhost:9000
|
||
Endpoint: localhost:9000
|
||
AccessKeyId: minioadmin
|
||
AccessKeySecret: minioadmin
|
||
UseSSL: false
|
||
|
||
# 本地存储配置
|
||
Local:
|
||
Site: http://localhost:16290
|
||
UploadDir: ./uploads/
|
||
|
||
# FTS特定配置
|
||
FtsConfig:
|
||
InputKey: file
|
||
MaxSize: 5368709120 # 5GB
|
||
Allows:
|
||
- .jpg
|
||
- .png
|
||
- .pdf
|
||
- .doc
|
||
# ... 更多支持的文件类型
|
||
```
|
||
|
||
## 开发工具
|
||
|
||
```bash
|
||
# 查看所有可用命令
|
||
make help
|
||
|
||
# 代码检查
|
||
make lint
|
||
|
||
# 运行测试
|
||
make test
|
||
|
||
# 安全扫描
|
||
make security
|
||
|
||
# 格式化代码
|
||
make fmt
|
||
|
||
# 更新依赖
|
||
make mod-update
|
||
```
|
||
|
||
## 构建和部署
|
||
|
||
```bash
|
||
# 构建所有平台
|
||
make build-all
|
||
|
||
# 构建Linux版本
|
||
make build-linux
|
||
|
||
# 构建Windows版本
|
||
make build-windows
|
||
|
||
# 构建macOS版本
|
||
make build-darwin
|
||
```
|
||
|
||
## 监控和运维
|
||
|
||
### 健康检查端点
|
||
|
||
- `GET /health` - 返回详细的服务状态，包括数据库、Redis、ETCD连接状态
|
||
- `GET /health/simple` - 返回简单的服务状态
|
||
- `HEAD /` - 快速健康检查
|
||
|
||
### 日志记录
|
||
|
||
服务支持结构化日志记录，日志级别可通过配置调整。
|
||
|
||
### 错误处理
|
||
|
||
统一的错误响应格式：
|
||
|
||
```json
|
||
{
|
||
"code": 10001,
|
||
"message": "错误描述",
|
||
"trace_id": "request-trace-id"
|
||
}
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
fts/
|
||
├── cmd/
|
||
│ ├── cli/ # CLI工具
|
||
│ └── main/ # 主服务入口
|
||
├── internal/
|
||
│ ├── config/ # 配置管理
|
||
│ ├── errors/ # 错误定义
|
||
│ ├── health/ # 健康检查
|
||
│ ├── impl/ # 服务实现
|
||
│ ├── logic/ # 业务逻辑
|
||
│ ├── models/ # 数据模型
|
||
│ ├── response/ # 响应处理
|
||
│ └── routers/ # 路由定义
|
||
├── etc/ # 配置文件
|
||
├── scripts/ # 脚本文件
|
||
├── test/ # 测试文件
|
||
├── build/ # 构建输出
|
||
├── Dockerfile # Docker镜像构建
|
||
├── docker-compose.yml # Docker编排
|
||
├── Makefile # 构建工具
|
||
└── README.md # 项目文档
|
||
```
|
||
|
||
## 贡献指南
|
||
|
||
1. Fork 项目
|
||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 打开 Pull Request
|
||
|
||
## 许可证
|
||
|
||
此项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
|
||
|
||
## 联系方式
|
||
|
||
- 项目主页: [GitHub仓库地址]
|
||
- 问题反馈: [Issues页面]
|
||
- 邮箱: [team@example.com] |