246 lines
5.0 KiB
Markdown
246 lines
5.0 KiB
Markdown
# GoalfyMax Admin
|
||
|
||
基于 Go 语言开发的管理后台系统基础架构，提供数据模型、存储层、服务层等核心组件。
|
||
|
||
## 🚀 项目特性
|
||
|
||
- **数据模型**: 完整的用户、角色、菜单等数据模型
|
||
- **存储层**: 统一的数据访问接口
|
||
- **服务层**: 业务逻辑封装
|
||
- **工具包**: 加密、JWT、日志等工具函数
|
||
- **配置管理**: 灵活的配置管理
|
||
- **数据库支持**: MySQL数据库支持
|
||
|
||
## 🏗️ 项目架构
|
||
|
||
```
|
||
goalfymax-admin/
|
||
├── cmd/ # 应用程序入口
|
||
│ └── server/ # 主服务
|
||
│ └── main.go # 主程序入口
|
||
├── internal/ # 内部包
|
||
│ ├── config/ # 配置管理
|
||
│ ├── models/ # 数据模型
|
||
│ ├── services/ # 业务服务层
|
||
│ └── storage/ # 数据访问层
|
||
├── pkg/ # 公共包
|
||
│ └── utils/ # 工具函数
|
||
└── etc/ # 配置文件
|
||
```
|
||
|
||
## 📋 技术栈
|
||
|
||
- **语言**: Go 1.25+
|
||
- **数据库**: MySQL 8.0+
|
||
- **ORM**: GORM
|
||
- **配置**: Viper + YAML
|
||
- **日志**: Zap
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Go 1.25+
|
||
- MySQL 8.0+
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd goalfymax-admin
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
go mod download
|
||
```
|
||
|
||
### 3. 配置数据库
|
||
|
||
创建数据库：
|
||
|
||
```sql
|
||
CREATE DATABASE goalfymax_admin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||
```
|
||
|
||
### 4. 配置文件
|
||
|
||
编辑 `etc/config.yaml`：
|
||
|
||
```yaml
|
||
server:
|
||
addr: "0.0.0.0"
|
||
port: 8080
|
||
|
||
database:
|
||
dsn: "root:password@tcp(127.0.0.1:3306)/goalfymax_admin?charset=utf8mb4&parseTime=True&loc=Local"
|
||
maxIdleConns: 10
|
||
maxOpenConns: 100
|
||
|
||
log:
|
||
level: "info"
|
||
format: "json"
|
||
output: "stdout"
|
||
```
|
||
|
||
### 5. 运行项目
|
||
|
||
```bash
|
||
# 开发模式
|
||
go run main.go
|
||
|
||
# 或指定配置文件
|
||
go run main.go -config etc/config.yaml
|
||
```
|
||
|
||
### 6. 运行项目
|
||
|
||
```bash
|
||
# 运行项目
|
||
go run cmd/server/main.go
|
||
|
||
# 或指定配置文件
|
||
go run cmd/server/main.go -config etc/config.yaml
|
||
```
|
||
|
||
### 7. 访问服务
|
||
|
||
- **API服务**: http://localhost:8084
|
||
- **健康检查**: http://localhost:8084/health
|
||
- **配额历史**: http://localhost:8084/api/quotas/history
|
||
|
||
## 🔧 CORS 配置
|
||
|
||
项目已配置CORS支持，允许以下域名跨域访问：
|
||
- `http://localhost:5173` (Vite开发服务器)
|
||
- `http://localhost:5174` (Vite开发服务器)
|
||
- `http://localhost:3000` (其他前端服务)
|
||
|
||
支持的HTTP方法：GET, POST, PUT, DELETE, OPTIONS
|
||
|
||
## 📖 API 接口
|
||
|
||
### 配额历史接口
|
||
|
||
#### 获取配额历史数据
|
||
|
||
```bash
|
||
POST /api/quotas/history
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"start_date": "2024-01-01",
|
||
"end_date": "2024-01-31",
|
||
"user_id": "user123",
|
||
"api_group": "openai",
|
||
"project_id": "project456",
|
||
"period": "daily",
|
||
"group_by": ["user_id", "api_group"]
|
||
}
|
||
```
|
||
|
||
**请求参数：**
|
||
- `start_date` (必填): 开始日期，格式 YYYY-MM-DD
|
||
- `end_date` (必填): 结束日期，格式 YYYY-MM-DD
|
||
- `user_id` (可选): 用户ID过滤
|
||
- `api_group` (可选): API组过滤
|
||
- `project_id` (可选): 项目ID过滤
|
||
- `period` (可选): 周期类型，daily 或 monthly，默认 daily
|
||
- `group_by` (可选): 分组维度，默认 ["user_id"]
|
||
|
||
**注意：** 此接口会转发请求到 goalfy-ai-gateway 的 `/aigateway-admin/api/quotas/history` 接口。
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"user_id": "user123",
|
||
"api_group": "openai",
|
||
"project_id": "project456",
|
||
"day": "2024-01-01",
|
||
"account": "account1",
|
||
"model": "gpt-4",
|
||
"quota_used": 1.5,
|
||
"created_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 配额服务健康检查
|
||
|
||
```bash
|
||
GET /api/quotas/health
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"status": "ok",
|
||
"service": "quota"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 项目结构说明
|
||
|
||
- `internal/config/`: 配置管理
|
||
- `internal/models/`: 数据模型定义
|
||
- `internal/services/`: 业务逻辑层
|
||
- `internal/storage/`: 数据访问层
|
||
- `pkg/utils/`: 工具函数
|
||
|
||
### 添加新功能
|
||
|
||
1. 在 `internal/models/` 中定义数据模型
|
||
2. 在 `internal/storage/` 中实现数据访问
|
||
3. 在 `internal/services/` 中实现业务逻辑
|
||
|
||
### 数据库迁移
|
||
|
||
项目启动时会自动执行数据库迁移，创建必要的表结构。
|
||
|
||
## 📊 监控和日志
|
||
|
||
### 日志
|
||
|
||
系统使用结构化日志，支持不同级别的日志输出：
|
||
|
||
```bash
|
||
# 查看实时日志
|
||
tail -f logs/app.log
|
||
|
||
# 按级别过滤
|
||
grep "ERROR" logs/app.log
|
||
```
|
||
|
||
## 🤝 贡献指南
|
||
|
||
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 许可证。
|
||
|
||
## 🆘 支持
|
||
|
||
如果您遇到问题或有疑问，请：
|
||
|
||
1. 查看 [文档](docs/)
|
||
2. 搜索 [Issues](https://github.com/your-org/goalfymax-admin/issues)
|
||
3. 创建新的 Issue
|