yujun/goalfylearning-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
goalfylearning-admin/ARCHITECTURE.md

3429 lines
88 KiB
Markdown
Raw Permalink Blame History

# GoalfyMax Admin 后端管理系统 - 架构文档
## 目录
- [项目概述](#项目概述)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [架构设计](#架构设计)
- [核心功能模块](#核心功能模块)
- [数据库设计](#数据库设计)
- [API接口说明](#api接口说明)
- [认证与权限](#认证与权限)
- [中间件系统](#中间件系统)
- [服务层设计](#服务层设计)
- [配置管理](#配置管理)
- [部署方案](#部署方案)
- [开发指南](#开发指南)
---
## 项目概述
GoalfyMax Admin 是一个企业级的后端管理系统,基于 Go 语言开发,采用分层架构设计。系统提供了完整的用户管理、权限控制、财务管理、邀请码系统等功能,支持 SSO 单点登录和 RBAC 权限控制。
go run cmd/server/main.go --env dev
### 主要特性
- **企业级架构**: 严格的三层架构,职责分离明确
- **SSO单点登录**: 基于 OAuth2/OIDC 协议的认证系统
- **RBAC权限控制**: 灵活的角色-页面权限管理
- **完整的审计日志**: 记录所有数据变更操作
- **多数据库支持**: MySQL + PostgreSQL + Redis
- **容器化部署**: Docker + Kubernetes 生产就绪
- **国际化支持**: 中英文邮件模板
- **可扩展性**: 模块化设计,易于扩展
### 代码规模
- **总代码量**: 约 1.5 万行 Go 代码
- **服务层**: 20 个 Service,共 7305 行代码
- **API层**: 18 个 Handler
- **存储层**: 17 个 Storage
- **数据模型**: 15 个 Model
---
## 技术栈
### 核心框架
| 技术 | 版本 | 用途 |
|------|------|------|
| Go | 1.25+ | 编程语言 |
| Gin | v1.11.0 | Web 框架 |
| GORM | v1.30.1 | ORM 框架 |
### 数据库
| 数据库 | 用途 |
|--------|------|
| MySQL | 主数据库 |
| PostgreSQL | MCP 配置存储 |
| Redis v9.16.0 | 缓存和会话管理 |
### 认证与安全
| 技术 | 版本 | 用途 |
|------|------|------|
| JWT | v5.3.0 | Token 管理 |
| OAuth2 | - | SSO 单点登录 |
| PKCE | - | OAuth2 安全增强 |
### 基础设施
| 组件 | 版本 | 用途 |
|------|------|------|
| Viper | v1.20.1 | 配置管理 |
| Zap | v1.27.0 | 结构化日志 |
| CORS | v1.7.0 | 跨域支持 |
| AWS SDK | v2 | S3 对象存储 |
### 其他依赖
- **UUID v1.6.0**: 唯一标识符生成
- **Decimal v1.3.1**: 精确数值计算
- **Email v4.0**: 邮件发送
---
## 项目结构
```
goalfylearning-admin/
├── cmd/
│ └── server/
│ └── main.go # 应用程序入口
├── internal/ # 内部私有代码
│ ├── api/ # API 层
│ │ ├── handlers/ # HTTP 处理器 (18个)
│ │ │ ├── user_handler.go
│ │ │ ├── goalfymax_user_handler.go
│ │ │ ├── sso_handler.go
│ │ │ ├── rbac_handler.go
│ │ │ ├── role_handler.go
│ │ │ ├── page_handler.go
│ │ │ ├── invite_code_handler.go
│ │ │ ├── invite_code_application_handler.go
│ │ │ ├── user_level_config_handler.go
│ │ │ ├── finance_handler.go
│ │ │ ├── quota_handler.go
│ │ │ ├── message_push_handler.go
│ │ │ ├── user_feedback_handler.go
│ │ │ ├── audit_log_handler.go
│ │ │ ├── system_config_handler.go
│ │ │ ├── user_project_quota_handler.go
│ │ │ ├── vendor_model_pricing_handler.go
│ │ │ ├── vm_pricing_handler.go
│ │ │ └── mcp_provider_handler.go
│ │ ├── middlewares/ # 中间件
│ │ │ ├── logging.go # 请求日志
│ │ │ └── api_log_middleware.go # API 调用日志
│ │ └── routes/
│ │ └── routes.go # 路由配置
│ ├── config/
│ │ └── config.go # 配置结构定义
│ ├── jobs/ # 定时任务
│ │ ├── mcp_usage_job.go # MCP 使用余额同步
│ │ └── model_token_job.go # 模型 Token 余额同步
│ ├── models/ # 数据模型 (15个)
│ │ ├── common.go # 基础模型
│ │ ├── user.go
│ │ ├── goalfymax_user.go
│ │ ├── user_level_config.go
│ │ ├── invite_code.go
│ │ ├── invite_code_application.go
│ │ ├── rbac.go
│ │ ├── audit_log.go
│ │ ├── balance_operation_log.go
│ │ ├── message_push.go
│ │ ├── quota_models.go
│ │ ├── user_feedback.go
│ │ ├── user_project_quota.go
│ │ ├── sso.go
│ │ ├── request.go
│ │ └── response.go
│ ├── notifier/
│ │ └── notifier.go # 钉钉通知服务
│ ├── oss/
│ │ └── s3.go # S3 对象存储
│ ├── services/ # 业务逻辑层 (20个,7305行)
│ │ ├── user_service.go
│ │ ├── goalfymax_user_service.go
│ │ ├── sso_service.go
│ │ ├── sso_admin_service.go
│ │ ├── rbac_service.go
│ │ ├── role_service.go
│ │ ├── page_service.go
│ │ ├── invite_code_service.go
│ │ ├── invite_code_application_service.go
│ │ ├── user_level_config_service.go
│ │ ├── finance_service.go
│ │ ├── quota_service.go
│ │ ├── message_push_service.go
│ │ ├── user_feedback_service.go
│ │ ├── audit_log_service.go
│ │ ├── system_config_service.go
│ │ ├── user_project_quota_service.go
│ │ ├── email_service.go
│ │ ├── gateway_client.go
│ │ └── log_service.go
│ └── storage/ # 数据访问层 (17个)
│ ├── database.go # 数据库初始化
│ ├── postgres.go # PostgreSQL 连接
│ ├── user_storage.go
│ ├── goalfymax_user_storage.go
│ ├── rbac_storage.go
│ ├── role_storage.go
│ ├── page_storage.go
│ ├── invite_code.go
│ ├── user_level_config_storage.go
│ ├── audit_log_storage.go
│ ├── balance_operation_log_storage.go
│ ├── message_push_storage.go
│ ├── user_feedback_storage.go
│ ├── system_config_storage.go
│ ├── user_project_quota_storage.go
│ ├── sso_storage.go
│ └── log_storage.go
├── pkg/ # 公共可复用包
│ ├── middleware/
│ │ ├── auth.go # 认证中间件
│ │ ├── rbac.go # 权限中间件
│ │ └── sso_client.go # SSO 客户端
│ ├── redis/
│ │ └── redis.go # Redis 客户端
│ └── utils/
│ ├── crypto.go # 加密工具
│ ├── jwt.go # JWT 工具
│ ├── logger.go # 日志工具
│ ├── response.go # 响应封装
│ └── validator.go # 验证工具
├── etc/ # 配置文件
│ ├── config.yaml # 开发配置
│ └── config-prod.yaml # 生产配置
├── k8s/ # Kubernetes 部署配置
│ ├── deployment.yaml
│ ├── service.yaml
│ └── configmap.yaml
├── docs/ # 文档
│ ├── deployment_and_testing.md
│ ├── email_templates_preview.html
│ └── *.html # 邮件模板
├── migrations/ # 数据库迁移脚本
│ ├── 20250129_add_client_id_to_invite_codes.sql
│ ├── 20250131_add_invite_code_applications_table.sql
│ └── 20250204_add_language_to_invite_code_applications.sql
├── scripts/ # 脚本工具
│ ├── start.sh
│ ├── stop.sh
│ ├── status.sh
│ ├── migrate.sh
│ ├── invite_code_api.py
│ └── test_*.sh
├── test/ # 测试文件
│ ├── test_email.go
│ ├── send_test_email.go
│ └── preview_email.go
├── Dockerfile # Docker 构建文件
├── build.sh # 构建脚本
├── build-and-push.sh # 构建并推送到 ECR
├── go.mod # Go 模块定义
└── go.sum # 依赖校验
```
---
## 架构设计
### 整体架构
系统采用**分层架构**设计,从上到下分为:
```
┌─────────────────────────────────────────────┐
│ HTTP Client (前端) │
└─────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Gin Router & Middlewares │
│ (认证、权限、日志、CORS、错误处理) │
└─────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Handler Layer (API层) │
│ (参数验证、请求解析、响应封装) │
└─────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Service Layer (业务逻辑层) │
│ (业务规则、事务处理、外部服务调用) │
└─────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Storage Layer (数据访问层) │
│ (数据库操作、缓存操作) │
└─────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Database (MySQL/PostgreSQL/Redis) │
└─────────────────────────────────────────────┘
```
### 架构特点
1. **严格的层次分离**
- Handler 只负责 HTTP 请求处理
- Service 封装所有业务逻辑
- Storage 封装所有数据访问
2. **依赖注入**
- Service 依赖 Storage 接口
- Handler 依赖 Service 接口
- 便于单元测试和模块替换
3. **统一错误处理**
- 使用 `utils.ErrorResponse` 统一错误响应
- 使用 `utils.SuccessResponse` 统一成功响应
4. **中间件链**
- 认证 -> 权限 -> 日志 -> 业务处理
### 数据流向
```
Request → Middleware Chain → Handler → Service → Storage → Database
↓
External API
↓
Redis Cache
```
### 外部依赖
系统依赖以下外部服务:
- **SSO Server**: passport.goalfy.ai (OAuth2/OIDC 认证)
- **AI Gateway**: 44.247.156.94:8080 (配额查询、网关服务)
- **SMTP Server**: smtp.mxhichina.com (邮件发送)
- **DingTalk**: 钉钉机器人 (告警通知)
- **AWS S3**: 对象存储
---
## 核心功能模块
### 1. 用户管理系统
**位置**: `internal/api/handlers/user_handler.go`, `internal/services/user_service.go`
**功能**:
- 用户 CRUD 操作
- 用户状态管理 (启用/禁用)
- 角色分配
- 权限查询
- 系统角色变更
**API 路由**: `/api/admin/users/*`
**主要接口**:
- `GET /api/admin/users` - 用户列表 (支持分页、搜索)
- `POST /api/admin/users` - 创建用户
- `PUT /api/admin/users/:id` - 更新用户
- `DELETE /api/admin/users/:id` - 删除用户
- `PUT /api/admin/users/:id/status` - 更新状态
- `PUT /api/admin/users/:id/roles` - 更新角色
- `POST /api/admin/users/change-system-role` - 变更系统角色
---
### 2. GoalfyMax 用户管理
**位置**: `internal/models/goalfymax_user.go`, `internal/services/goalfymax_user_service.go`
**核心字段**:
```go
type GoalfyMaxUser struct {
BaseModel
UserID uint `json:"user_id" gorm:"uniqueIndex;not null"` // SSO 用户 ID
Username string `json:"username"`
Email string `json:"email"`
Nickname string `json:"nickname"`
Avatar string `json:"avatar"`
UserLevelCode string `json:"user_level_code"` // 用户等级代码
IsBanned bool `json:"is_banned" gorm:"default:false"` // 是否封禁
BanReason string `json:"ban_reason"` // 封禁原因
BannedAt *time.Time `json:"banned_at"` // 封禁时间
BannedBy *uint `json:"banned_by"` // 封禁操作人
GoalfyHubPermission int `json:"goalfy_hub_permission" gorm:"default:0"` // Hub权限 (0/1)
Version int `json:"version" gorm:"default:1"` // 版本 (1:用户版 2:观察版 3:双版)
Balance float64 `json:"balance" gorm:"-"` // 余额(从Redis查询,不存数据库)
}
```
**功能**:
- 用户创建、编辑、删除
- 封禁/解封操作
- 余额增减操作
- 版本管理 (用户版/观察版/双版)
- Hub 权限管理
**API 路由**: `/api/admin/goalfymax-users/*`
**余额操作**:
- 余额存储在 Redis: `goalfymax:user:balance:{user_id}`
- 支持增加余额和扣减余额
- 自动记录余额操作日志 (balance_operation_logs 表)
---
### 3. SSO 单点登录系统
**位置**: `internal/services/sso_service.go`, `pkg/middleware/auth.go`
**认证流程**:
```
1. 前端请求登录
↓
2. 后端生成 PKCE state 和 code_verifier
↓
3. 返回 SSO 授权 URL
↓
4. 用户在 SSO 服务器登录
↓
5. SSO 重定向到回调 URL (带 code 和 state)
↓
6. 后端验证 state,使用 code_verifier 交换 token
↓
7. 获取 access_token, refresh_token, id_token
↓
8. 调用 SSO userinfo 接口获取用户信息
↓
9. 自动创建/更新本地用户
↓
10. 返回 token 给前端
```
**特性**:
- **OAuth2/OpenID Connect** 协议
- **PKCE** 安全增强 (防止授权码拦截攻击)
- **自动用户创建**: 首次登录自动创建本地用户记录
- **在线用户管理**: 内存存储在线用户会话
- **批量登出**: 支持批量踢出用户
- **Token 刷新**: 自动刷新过期的 access_token
**API 路由**: `/api/sso/*`
**配置** (etc/config.yaml):
```yaml
sso:
sso_server_url: "https://passport.goalfy.ai"
client_id: "xv5Xesd4ry1_I3hP3xYXNw"
redirect_uri: "http://localhost:3003"
scope: "openid profile email"
resource_aud: "api://admin"
```
**关键代码**:
- 认证中间件: `pkg/middleware/auth.go:84-159` (RequireAuth)
- 自动用户创建: `pkg/middleware/auth.go:230-290` (findOrCreateUser)
---
### 4. RBAC 权限系统
**位置**: `internal/models/rbac.go`, `pkg/middleware/rbac.go`
**权限模型**:
```
User (用户)
↓ (role_id)
Role (角色)
↓ (role_page_permissions)
Page (页面/菜单)
```
**数据表**:
- `admin_users`: 用户表 (包含 role_id 外键)
- `admin_roles`: 角色表 (如: 超级管理员、普通管理员)
- `admin_pages`: 页面/菜单表 (如: /users, /roles)
- `admin_role_page_permissions`: 角色-页面关联表
**核心模型**:
```go
type Role struct {
BaseModel
Name string `json:"name" gorm:"uniqueIndex;size:100;not null"`
Level int `json:"level" gorm:"default:1"` // 角色级别 (1-5)
Description string `json:"description" gorm:"size:255"`
IsDefault bool `json:"is_default" gorm:"default:false"` // 是否默认角色
}
type Page struct {
BaseModel
Name string `json:"name" gorm:"size:100;not null"`
Path string `json:"path" gorm:"uniqueIndex;size:255;not null"` // 页面路径
Icon string `json:"icon" gorm:"size:100"`
SortOrder int `json:"sort_order" gorm:"default:0"`
IsActive bool `json:"is_active" gorm:"default:true"`
}
type RolePagePermission struct {
BaseModel
RoleID uint `json:"role_id" gorm:"not null;index:idx_role_page"`
PageID uint `json:"page_id" gorm:"not null;index:idx_role_page"`
}
```
**功能**:
- 页面权限检查
- 角色权限管理
- 用户可访问页面查询
- 权限继承 (通过角色级别)
**API 路由**: `/api/admin/rbac/*`
**权限检查中间件**:
```go
// 检查用户是否有访问某个页面的权限
rbacMiddleware.RequirePagePermission("/users")
```
**使用示例**:
```go
// routes.go
users := admin.Group("/users")
users.Use(rbacMiddleware.RequirePagePermission("/users"))
{
users.GET("", userHandler.List)
users.POST("", userHandler.Create)
}
```
---
### 5. 用户等级配置系统
**位置**: `internal/models/user_level_config.go`, `internal/services/user_level_config_service.go`
**配置内容**:
```go
type UserLevelConfig struct {
BaseModel
LevelName string `json:"level_name" gorm:"size:100;not null"`
LevelCode string `json:"level_code" gorm:"uniqueIndex;size:50;not null"` // 等级代码
ProjectLimit int `json:"project_limit" gorm:"default:0"` // 项目数限制
CoderVMLimit int `json:"coder_vm_limit" gorm:"default:0"` // Coder VM上限
BrowserVMLimit int `json:"browser_vm_limit" gorm:"default:0"` // Browser VM上限
ProcessLimit int `json:"process_limit" gorm:"default:0"` // 进程上限
Description string `json:"description" gorm:"size:255"`
SortOrder int `json:"sort_order" gorm:"default:0"`
Status int `json:"status" gorm:"default:1"` // 1:启用 0:禁用
}
```
**默认等级** (storage/database.go:181-206):
| 等级代码 | 等级名称 | 项目限制 | Coder VM | Browser VM | 进程上限 |
|---------|---------|---------|----------|------------|---------|
| normal | 普通用户 | 2 | 0 | 0 | 0 |
| vip | VIP用户 | 10 | 0 | 0 | 0 |
| internal| 内部用户 | 0 (无限) | 0 | 0 | 0 |
**功能**:
- 等级配置 CRUD
- 等级启用/禁用
- 排序管理
- 与 GoalfyMax 用户关联
**API 路由**: `/api/admin/user-level-configs/*`
---
### 6. 邀请码系统
**位置**: `internal/models/invite_code.go`, `internal/services/invite_code_service.go`
**核心模型**:
```go
type InviteCode struct {
BaseModel
Code string `json:"code" gorm:"uniqueIndex;size:50;not null"` // 邀请码
IsUsed bool `json:"is_used" gorm:"default:false"` // 是否已使用
ClientID *string `json:"client_id" gorm:"size:255"` // 客户端ID
Email string `json:"email" gorm:"size:255"` // 关联邮箱
ExpiresAt *time.Time `json:"expires_at"` // 过期时间
UserLevelID uint `json:"user_level_id"` // 用户等级ID
UserLevel *UserLevelConfig `json:"user_level,omitempty" gorm:"foreignKey:UserLevelID"`
}
```
**功能**:
- 邀请码生成 (支持批量生成)
- 过期时间管理
- 使用状态追踪
- 邮箱关联
- 用户等级绑定
- 邀请码验证 (检查是否过期、是否已使用)
**申请审批流程**:
```
1. 用户在官网提交申请 (公开接口)
↓
2. 管理员查看待审批列表
↓
3. 审批通过
├─ 自动生成邀请码
├─ 关联申请邮箱
└─ 发送邮件通知 (中英文)
或
3. 审批拒绝
└─ 发送拒绝邮件 (中英文)
```
**API 路由**:
- 管理端: `/api/admin/invite-codes/*`
- 公开接口: `/api/public/invite-code/apply`
**统计功能**:
- 总邀请码数
- 已使用数量
- 未使用数量
- 过期数量
---
### 7. 邀请码申请系统
**位置**: `internal/models/invite_code_application.go`, `internal/services/invite_code_application_service.go`
**核心模型**:
```go
type InviteCodeApplication struct {
BaseModel
Email string `json:"email" gorm:"size:255;not null;index"` // 申请人邮箱
Purpose string `json:"purpose" gorm:"type:text"` // 申请目的
Language string `json:"language" gorm:"size:10;default:'zh'"` // 语言 (zh/en)
Status string `json:"status" gorm:"size:20;default:'pending'"` // pending/approved/rejected
ReviewedBy *uint `json:"reviewed_by"` // 审核人ID
ReviewedAt *time.Time `json:"reviewed_at"` // 审核时间
RejectReason string `json:"reject_reason" gorm:"type:text"` // 拒绝原因
InviteCodeID *uint `json:"invite_code_id"` // 关联的邀请码ID
}
```
**功能**:
- 公开申请接口 (官网接入)
- 申请列表查询 (支持状态筛选)
- 待处理数量统计
- 审批通过 (自动生成邀请码并发邮件)
- 审批拒绝 (发送拒绝邮件)
- 批量审批 (批量通过/拒绝)
**API 路由**: `/api/admin/invite-applications/*`
**邮件模板**:
- 通过模板: `docs/email_preview_approval.html` (中文), `docs/email_preview_en.html` (英文)
- 拒绝模板: `docs/email_preview_rejection.html` (中文)
**审批逻辑** (invite_code_application_service.go):
**通过审批**:
```go
1. 验证申请状态 (必须是 pending)
2. 生成邀请码
- 关联申请邮箱
- 设置默认用户等级 (normal)
- 设置过期时间 (30天)
3. 更新申请状态为 approved
4. 记录审核人和审核时间
5. 发送邮件通知 (根据语言选择模板)
6. 在事务中完成所有操作
```
**拒绝审批**:
```go
1. 验证申请状态 (必须是 pending)
2. 更新申请状态为 rejected
3. 记录拒绝原因、审核人和审核时间
4. 发送拒绝邮件 (根据语言选择模板)
5. 在事务中完成所有操作
```
---
### 8. 财务管理系统
**位置**: `internal/api/handlers/finance_handler.go`, `internal/services/finance_service.go`
**功能模块**:
#### 8.1 使用记录查询
- **Sandbox 使用记录**: 查询用户的 Sandbox 使用历史
- **Token 使用统计**: 模型 Token 消耗统计
- **MCP 使用记录**: MCP 服务使用记录
- **交易日志**: 所有交易流水
- **支付记录**: 支付订单和退款记录
#### 8.2 MCP 账户管理
- **余额管理**: 各 MCP Provider 的账户余额
- **充值记录**: MCP 账户充值历史
- **余额调整**: 增加或减少账户余额
#### 8.3 模型账户管理
- **余额查询**: 各模型供应商的账户余额
- **使用统计**: Token 消耗统计
**API 路由**: `/api/finance/*`
**主要接口**:
- `GET /api/finance/sandbox-records` - Sandbox 记录
- `GET /api/finance/token-usages` - Token 使用
- `GET /api/finance/mcp-usages` - MCP 使用
- `GET /api/finance/transaction-logs` - 交易日志
- `GET /api/finance/payment-records` - 支付记录
- `POST /api/finance/payment-records/refund` - 退款
- `GET /api/finance/mcp-account-balances` - MCP 余额
- `POST /api/finance/mcp-account-balances` - 创建余额
- `PUT /api/finance/mcp-account-balances/:provider_id` - 调整余额
---
### 9. 配额管理系统
**位置**: `internal/services/quota_service.go`, `internal/api/handlers/quota_handler.go`
**功能**:
#### 9.1 配额历史查询
- 转发到 AI Gateway
- 查询用户的配额使用历史
#### 9.2 配额规则管理
- 配额规则 CRUD
- 规则启用/禁用
#### 9.3 用户项目配额
- 用户项目配额查询
- 配额创建和更新
**API 路由**: `/api/quotas/*`
**主要接口**:
- `POST /api/quotas/history` - 配额历史 (转发到 Gateway)
- `GET /api/quotas/health` - 健康检查
- `GET /api/quotas/rules` - 规则列表
- `POST /api/quotas/rules` - 创建规则
- `PUT /api/quotas/rules/:id` - 更新规则
- `DELETE /api/quotas/rules/:id` - 删除规则
- `GET /api/quotas/user-project` - 用户项目配额
- `POST /api/quotas/user-project` - 创建配额
---
### 10. 消息推送系统
**位置**: `internal/services/message_push_service.go`, `internal/api/handlers/message_push_handler.go`
**功能**:
- 向 GoalfyMax 后端发送消息推送
- 推送日志记录
- 用户搜索
**API 路由**: `/api/admin/message-push/*`
---
### 11. 用户反馈系统
**位置**: `internal/api/handlers/user_feedback_handler.go`, `internal/services/user_feedback_service.go`
**功能**:
- 反馈列表查询
- 标记已处理
- 反馈统计信息
**API 路由**: `/api/admin/user-feedback/*`
---
### 12. 审计日志系统
**位置**: `internal/models/audit_log.go`, `internal/services/audit_log_service.go`
**核心模型**:
```go
type AuditLog struct {
BaseModel
UserID uint `json:"user_id" gorm:"index;not null"`
OperationType string `json:"operation_type" gorm:"size:50;not null"` // create/update/delete
TargetTable string `json:"target_table" gorm:"size:100;not null"` // 目标表名
TargetID uint `json:"target_id" gorm:"index"` // 目标记录ID
OldValue string `json:"old_value" gorm:"type:text"` // 修改前的值(JSON)
NewValue string `json:"new_value" gorm:"type:text"` // 修改后的值(JSON)
IP string `json:"ip" gorm:"size:50"`
UserAgent string `json:"user_agent" gorm:"size:255"`
}
```
**功能**:
- 记录所有数据修改操作
- 记录 API 调用日志
- 变更前后值对比
- IP 和 UserAgent 追踪
**自动日志记录**:
- 通过中间件自动记录 POST/PUT/DELETE 请求
- 中间件位置: `internal/api/middlewares/api_log_middleware.go`
---
### 13. 定时任务系统
**位置**: `internal/jobs/`
#### 13.1 MCP Usage Balance Job
**文件**: `internal/jobs/mcp_usage_job.go`
**功能**:
- 定时同步 MCP 使用余额
- 从外部服务获取余额数据
- 更新到本地数据库
**配置**:
```yaml
jobs:
mcp_usage_balance:
enabled: true
run_on_startup: true
delay_minutes: 5
```
**执行频率**: 每小时
#### 13.2 Model Token Balance Job
**文件**: `internal/jobs/model_token_job.go`
**功能**:
- 定时同步模型 Token 余额
- 统计 Token 使用情况
- 更新余额数据
**配置**:
```yaml
jobs:
model_token_balance:
enabled: true
run_on_startup: true
delay_minutes: 5
```
**执行频率**: 每小时
---
## 数据库设计
### 数据库架构
系统使用**三个数据库**:
1. **MySQL**: 主数据库,存储所有业务数据
2. **PostgreSQL**: MCP 配置和相关数据
3. **Redis**: 缓存、会话、余额等临时数据
### 核心数据表
#### 1. BaseModel (所有表的基础)
```go
type BaseModel struct {
ID uint `json:"id" gorm:"primarykey"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
DeletedAt gorm.DeletedAt `json:"deleted_at,omitempty" gorm:"index"`
}
```
**特点**:
- 自动管理 ID、创建时间、更新时间
- 支持软删除 (DeletedAt)
---
#### 2. admin_users (管理员用户表)
```go
type User struct {
BaseModel
Username string `json:"username" gorm:"uniqueIndex;size:100;not null"`
Email string `json:"email" gorm:"uniqueIndex;size:255"`
Nickname string `json:"nickname" gorm:"size:100"`
Avatar string `json:"avatar" gorm:"size:500"`
Status int `json:"status" gorm:"default:1"` // 1:正常 0:禁用
SSOProvider string `json:"sso_provider" gorm:"size:50"`
RoleID *uint `json:"role_id" gorm:"index"`
Role *Role `json:"role,omitempty" gorm:"foreignKey:RoleID"`
LastLoginAt *time.Time `json:"last_login_at"`
LoginCount int `json:"login_count" gorm:"default:0"`
}
```
**索引**:
- `uniqueIndex`: username, email
- `index`: role_id, deleted_at
**说明**:
- 管理后台的用户表
- 通过 SSO 登录自动创建
- 关联角色表实现权限控制
---
#### 3. admin_goalfymax_users (GoalfyMax 用户表)
```go
type GoalfyMaxUser struct {
BaseModel
UserID uint `json:"user_id" gorm:"uniqueIndex;not null"`
Username string `json:"username" gorm:"size:100"`
Email string `json:"email" gorm:"size:255"`
Nickname string `json:"nickname" gorm:"size:100"`
Avatar string `json:"avatar" gorm:"size:500"`
UserLevelCode string `json:"user_level_code" gorm:"size:50"`
IsBanned bool `json:"is_banned" gorm:"default:false"`
BanReason string `json:"ban_reason" gorm:"type:text"`
BannedAt *time.Time `json:"banned_at"`
BannedBy *uint `json:"banned_by"`
GoalfyHubPermission int `json:"goalfy_hub_permission" gorm:"default:0"`
Version int `json:"version" gorm:"default:1"`
Balance float64 `json:"balance" gorm:"-"` // 虚拟字段,从Redis查询
}
```
**索引**:
- `uniqueIndex`: user_id
- `index`: deleted_at
**说明**:
- GoalfyMax 产品的用户表
- user_id 关联 SSO 系统的用户 ID
- Balance 字段不存数据库,从 Redis 实时查询
**余额存储** (Redis):
```
key: goalfymax:user:balance:{user_id}
value: float64 (余额)
```
---
#### 4. admin_user_level_configs (用户等级配置表)
```go
type UserLevelConfig struct {
BaseModel
LevelName string `json:"level_name" gorm:"size:100;not null"`
LevelCode string `json:"level_code" gorm:"uniqueIndex;size:50;not null"`
ProjectLimit int `json:"project_limit" gorm:"default:0"`
CoderVMLimit int `json:"coder_vm_limit" gorm:"default:0"`
BrowserVMLimit int `json:"browser_vm_limit" gorm:"default:0"`
ProcessLimit int `json:"process_limit" gorm:"default:0"`
Description string `json:"description" gorm:"size:255"`
SortOrder int `json:"sort_order" gorm:"default:0"`
Status int `json:"status" gorm:"default:1"` // 1:启用 0:禁用
}
```
**索引**:
- `uniqueIndex`: level_code
- `index`: deleted_at
**默认数据**:
| level_code | level_name | project_limit |
|------------|-----------|---------------|
| normal | 普通用户 | 2 |
| vip | VIP用户 | 10 |
| internal | 内部用户 | 0 (无限) |
---
#### 5. admin_invite_codes (邀请码表)
```go
type InviteCode struct {
BaseModel
Code string `json:"code" gorm:"uniqueIndex;size:50;not null"`
IsUsed bool `json:"is_used" gorm:"default:false"`
ClientID *string `json:"client_id" gorm:"size:255"`
Email string `json:"email" gorm:"size:255"`
ExpiresAt *time.Time `json:"expires_at"`
UserLevelID uint `json:"user_level_id"`
UserLevel *UserLevelConfig `json:"user_level,omitempty" gorm:"foreignKey:UserLevelID"`
}
```
**索引**:
- `uniqueIndex`: code
- `index`: deleted_at
---
#### 6. admin_invite_code_applications (邀请码申请表)
**SQL 迁移**: `migrations/20250131_add_invite_code_applications_table.sql`
```sql
CREATE TABLE admin_invite_code_applications (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
email VARCHAR(255) NOT NULL,
purpose TEXT,
language VARCHAR(10) DEFAULT 'zh',
status VARCHAR(20) DEFAULT 'pending', -- pending/approved/rejected
reviewed_by BIGINT,
reviewed_at TIMESTAMP NULL,
reject_reason TEXT,
invite_code_id BIGINT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
deleted_at TIMESTAMP NULL,
INDEX idx_email (email),
INDEX idx_status (status),
INDEX idx_deleted_at (deleted_at)
);
```
---
#### 7. admin_roles (角色表)
```go
type Role struct {
BaseModel
Name string `json:"name" gorm:"uniqueIndex;size:100;not null"`
Level int `json:"level" gorm:"default:1"`
Description string `json:"description" gorm:"size:255"`
IsDefault bool `json:"is_default" gorm:"default:false"`
}
```
**索引**:
- `uniqueIndex`: name
- `index`: deleted_at
---
#### 8. admin_pages (页面/菜单表)
```go
type Page struct {
BaseModel
Name string `json:"name" gorm:"size:100;not null"`
Path string `json:"path" gorm:"uniqueIndex;size:255;not null"`
Icon string `json:"icon" gorm:"size:100"`
SortOrder int `json:"sort_order" gorm:"default:0"`
IsActive bool `json:"is_active" gorm:"default:true"`
}
```
**索引**:
- `uniqueIndex`: path
- `index`: deleted_at
---
#### 9. admin_role_page_permissions (角色-页面权限关联表)
```go
type RolePagePermission struct {
BaseModel
RoleID uint `json:"role_id" gorm:"not null;index:idx_role_page"`
PageID uint `json:"page_id" gorm:"not null;index:idx_role_page"`
}
```
**索引**:
- `index`: idx_role_page (role_id, page_id 组合索引)
- `index`: deleted_at
---
#### 10. admin_audit_logs (审计日志表)
```go
type AuditLog struct {
BaseModel
UserID uint `json:"user_id" gorm:"index;not null"`
OperationType string `json:"operation_type" gorm:"size:50;not null"`
TargetTable string `json:"target_table" gorm:"size:100;not null"`
TargetID uint `json:"target_id" gorm:"index"`
OldValue string `json:"old_value" gorm:"type:text"`
NewValue string `json:"new_value" gorm:"type:text"`
IP string `json:"ip" gorm:"size:50"`
UserAgent string `json:"user_agent" gorm:"size:255"`
}
```
**索引**:
- `index`: user_id, target_id, deleted_at
---
#### 11. admin_balance_operation_logs (余额操作日志表)
```go
type BalanceOperationLog struct {
BaseModel
UserID uint `json:"user_id" gorm:"index;not null"`
OperationType string `json:"operation_type" gorm:"size:50;not null"` // add/deduct
Amount float64 `json:"amount" gorm:"type:decimal(20,2);not null"`
BalanceBefore float64 `json:"balance_before" gorm:"type:decimal(20,2)"`
BalanceAfter float64 `json:"balance_after" gorm:"type:decimal(20,2)"`
OperatorID uint `json:"operator_id" gorm:"index"`
Remark string `json:"remark" gorm:"type:text"`
}
```
**索引**:
- `index`: user_id, operator_id, deleted_at
---
### 数据库初始化
**位置**: `internal/storage/database.go`
#### 自动迁移 (database.go:119-165)
```go
func (d *Database) autoMigrate() error {
return d.DB.AutoMigrate(
&models.User{},
&models.Role{},
&models.Page{},
&models.RolePagePermission{},
&models.UserLevelConfig{},
&models.InviteCode{},
&models.AuditLog{},
&models.BalanceOperationLog{},
&models.GoalfyMaxUser{},
// ... 其他模型
)
}
```
#### 初始化默认数据 (database.go:167-260)
**默认角色**:
- 超级管理员 (level: 5)
- 普通管理员 (level: 3)
- 观察者 (level: 1)
**默认用户等级**:
- normal (普通用户): 2个项目
- vip (VIP用户): 10个项目
- internal (内部用户): 无限制
**默认页面**:
- /dashboard (仪表盘)
- /users (用户管理)
- /roles (角色管理)
- /pages (页面管理)
- /invite-codes (邀请码管理)
- /user-level-configs (用户等级配置)
---
### SQL 迁移脚本
**位置**: `migrations/`
1. **20250129_add_client_id_to_invite_codes.sql**
- 添加 client_id 字段到 invite_codes 表
2. **20250131_add_invite_code_applications_table.sql**
- 创建邀请码申请表
3. **20250204_add_language_to_invite_code_applications.sql**
- 添加 language 字段到申请表
**执行迁移**:
```bash
./scripts/migrate.sh
```
---
## API 接口说明
### 接口规范
#### 请求格式
**认证**:
```
Authorization: Bearer {access_token}
```
**请求体** (POST/PUT):
```json
{
"field1": "value1",
"field2": "value2"
}
```
#### 响应格式
**成功响应**:
```json
{
"code": 200,
"message": "success",
"data": {
// 响应数据
}
}
```
**错误响应**:
```json
{
"code": 400,
"message": "错误信息"
}
```
**分页响应**:
```json
{
"code": 200,
"message": "success",
"data": {
"list": [...],
"total": 100,
"page": 1,
"page_size": 20
}
}
```
---
### API 路由列表
#### 公开接口 (无需认证)
```
POST /api/public/invite-code/apply # 提交邀请码申请
```
---
#### SSO 认证接口
```
POST /api/sso/login # SSO 登录
POST /api/sso/callback # SSO 回调
POST /api/sso/refresh # 刷新令牌
POST /api/sso/logout # 登出
GET /api/sso/userinfo # 获取用户信息
GET /api/sso/online-users # 在线用户列表
GET /api/sso/online-count # 在线用户数量
POST /api/sso/batch-logout # 批量登出
```
---
#### 用户管理 (需认证)
```
GET /api/admin/users # 用户列表
POST /api/admin/users # 创建用户
GET /api/admin/users/:id # 用户详情
PUT /api/admin/users/:id # 更新用户
DELETE /api/admin/users/:id # 删除用户
PUT /api/admin/users/:id/status # 更新状态
PUT /api/admin/users/:id/roles # 更新角色
GET /api/admin/users/:id/roles # 获取角色
GET /api/admin/users/:id/permissions # 获取权限
GET /api/admin/users/check-role/:user_id # 检查系统角色
POST /api/admin/users/change-system-role # 变更系统角色
```
---
#### GoalfyMax 用户管理 (需认证)
```
GET /api/admin/goalfymax-users # 用户列表
POST /api/admin/goalfymax-users # 新增用户
GET /api/admin/goalfymax-users/:id # 用户详情
PUT /api/admin/goalfymax-users/:id # 编辑用户
DELETE /api/admin/goalfymax-users/:id # 删除用户
POST /api/admin/goalfymax-users/:id/ban # 封禁用户
POST /api/admin/goalfymax-users/:id/unban # 解封用户
POST /api/admin/goalfymax-users/:id/add-balance # 增加余额
POST /api/admin/goalfymax-users/:id/deduct-balance # 减少余额
```
---
#### 角色管理 (需认证)
```
GET /api/admin/roles # 角色列表
POST /api/admin/roles # 创建角色
GET /api/admin/roles/:id # 角色详情
PUT /api/admin/roles/:id # 更新角色
DELETE /api/admin/roles/:id # 删除角色
PUT /api/admin/roles/:id/status # 更新状态
PUT /api/admin/roles/:id/permissions # 更新权限
GET /api/admin/roles/:id/permissions # 获取权限
```
---
#### 页面管理 (需认证)
```
GET /api/admin/pages # 页面列表
POST /api/admin/pages # 创建页面
GET /api/admin/pages/:id # 页面详情
PUT /api/admin/pages/:id # 更新页面
DELETE /api/admin/pages/:id # 删除页面
```
---
#### RBAC 权限管理 (需认证)
```
POST /api/admin/rbac/role-page-permissions # 分配角色页面权限
DELETE /api/admin/rbac/roles/:id/page-permissions # 移除角色页面权限
GET /api/admin/rbac/roles/:id/page-permissions # 获取角色页面权限
GET /api/admin/rbac/users/:id/permissions # 获取用户权限
GET /api/admin/rbac/check-page-permission # 检查页面权限
GET /api/admin/rbac/users/:id/accessible-pages # 获取用户可访问页面
```
---
#### 用户等级配置 (需认证)
```
GET /api/admin/user-level-configs # 等级列表
GET /api/admin/user-level-configs/all # 获取所有(不分页)
POST /api/admin/user-level-configs # 创建等级
GET /api/admin/user-level-configs/:id # 等级详情
PUT /api/admin/user-level-configs/:id # 更新等级
DELETE /api/admin/user-level-configs/:id # 删除等级
PUT /api/admin/user-level-configs/:id/status # 更新状态
```
---
#### 邀请码管理 (需认证)
```
GET /api/admin/invite-codes # 邀请码列表
POST /api/admin/invite-codes # 创建邀请码
GET /api/admin/invite-codes/client-options # 客户端选项
GET /api/admin/invite-codes/statistics # 统计信息
GET /api/admin/invite-codes/:id # 邀请码详情
PUT /api/admin/invite-codes/:id # 更新邀请码
DELETE /api/admin/invite-codes/:id # 删除邀请码
POST /api/admin/invite-codes/mark-used # 标记为已使用
POST /api/admin/invite-codes/validate # 验证有效性
```
---
#### 邀请码申请管理 (需认证)
```
GET /api/admin/invite-applications # 申请列表
GET /api/admin/invite-applications/statistics # 统计信息
GET /api/admin/invite-applications/pending-count # 待处理数量
POST /api/admin/invite-applications/approve # 审批通过
POST /api/admin/invite-applications/reject # 审批拒绝
POST /api/admin/invite-applications/batch-approve # 批量通过
POST /api/admin/invite-applications/batch-reject # 批量拒绝
```
---
#### 财务管理 (需认证)
```
GET /api/finance/sandbox-records # Sandbox 记录
GET /api/finance/token-usages # Token 使用
GET /api/finance/mcp-usages # MCP 使用
GET /api/finance/transaction-logs # 交易日志
GET /api/finance/payment-records # 支付记录
POST /api/finance/payment-records/refund # 退款
GET /api/finance/mcp-account-recharge-records # MCP 充值记录
POST /api/finance/mcp-account-recharge-records # 创建充值
GET /api/finance/mcp-account-balances # MCP 余额
POST /api/finance/mcp-account-balances # 创建余额
PUT /api/finance/mcp-account-balances/:provider_id # 调整余额
GET /api/finance/model-account-balances # 模型余额
```
---
#### 配额管理 (需认证)
```
POST /api/quotas/history # 配额历史
GET /api/quotas/health # 健康检查
GET /api/quotas/rules # 规则列表
POST /api/quotas/rules # 创建规则
PUT /api/quotas/rules/:id # 更新规则
DELETE /api/quotas/rules/:id # 删除规则
GET /api/quotas/user-project # 用户项目配额
POST /api/quotas/user-project # 创建配额
```
---
#### 消息推送 (需认证)
```
POST /api/admin/message-push/send # 发送消息
GET /api/admin/message-push/logs # 推送日志
POST /api/admin/message-push/search # 用户搜索
```
---
#### 用户反馈 (需认证)
```
GET /api/admin/user-feedback # 反馈列表
PUT /api/admin/user-feedback/:id/process # 标记已处理
GET /api/admin/user-feedback/statistics # 统计信息
```
---
#### 审计日志 (需认证)
```
GET /api/admin/audit-logs # 审计日志列表
```
---
### CORS 配置
**允许的源** (routes.go:37-44):
- http://localhost:5173
- http://localhost:5174
- http://localhost:3000
- http://localhost:3003
- http://localhost:3004
**允许的方法**:
- GET, POST, PUT, DELETE, OPTIONS, PATCH
**允许的头**:
- Origin, Content-Type, Accept, Authorization, X-Requested-With, Cookie
---
## 认证与权限
### SSO 单点登录
#### OAuth2/OIDC 流程
```
┌─────────┐ ┌──────────┐
│ 前端 │ │ SSO 服务器│
└────┬────┘ └─────┬────┘
│ │
│ 1. 请求登录 │
├──────────────────────────────────────────► │
│ │
│ 2. 返回授权 URL (带 state, code_challenge) │
│◄──────────────────────────────────────────┤
│ │
│ 3. 跳转到 SSO 登录页面 │
├────────────────────────────────────────────►
│ │
│ 4. 用户登录授权 │
│ │
│ 5. 回调 (带 code 和 state) │
│◄────────────────────────────────────────────┤
│ │
│ 6. 交换 token (使用 code_verifier) │
├──────────────────────────────────────────► │
│ │
│ 7. 返回 access_token, refresh_token, id_token│
│◄──────────────────────────────────────────┤
│ │
│ 8. 获取用户信息 │
├──────────────────────────────────────────► │
│ │
│ 9. 返回用户信息 (email, name, etc.) │
│◄──────────────────────────────────────────┤
│ │
```
#### PKCE 安全增强
**什么是 PKCE?**
PKCE (Proof Key for Code Exchange) 是 OAuth2 的安全扩展,用于防止授权码拦截攻击。
**流程**:
1. **生成 code_verifier** (随机字符串)
```go
codeVerifier := generateRandomString(128)
```
2. **计算 code_challenge**
```go
hash := sha256.Sum256([]byte(codeVerifier))
codeChallenge := base64.RawURLEncoding.EncodeToString(hash[:])
```
3. **授权请求携带 code_challenge**
```
GET /authorize?
client_id=xxx
&redirect_uri=xxx
&code_challenge=xxx
&code_challenge_method=S256
```
4. **Token 交换时携带 code_verifier**
```
POST /token
{
"code": "xxx",
"code_verifier": "xxx"
}
```
5. **服务器验证**
```
hash(code_verifier) == code_challenge
```
#### 自动用户创建
**位置**: `pkg/middleware/auth.go:230-290`
**逻辑**:
```go
func findOrCreateUser(ssoUserID, username, email string, db *gorm.DB) (*models.User, error) {
var user models.User
// 1. 查找现有用户
err := db.Where("username = ?", username).First(&user).Error
if err == gorm.ErrRecordNotFound {
// 2. 用户不存在,创建新用户
user = models.User{
Username: username,
Email: email,
Nickname: username,
Status: 1, // 默认启用
SSOProvider: "goalfy-sso",
LoginCount: 1,
LastLoginAt: &now,
}
if err := db.Create(&user).Error; err != nil {
return nil, err
}
} else {
// 3. 用户已存在,更新登录信息
updates := map[string]interface{}{
"login_count": user.LoginCount + 1,
"last_login_at": &now,
}
// 同步 SSO 的姓名和邮箱
if user.Email != email {
updates["email"] = email
}
db.Model(&user).Updates(updates)
}
return &user, nil
}
```
**特性**:
- 首次登录自动创建用户
- 每次登录更新登录时间和次数
- 自动同步 SSO 的邮箱信息
- 默认启用状态
---
### RBAC 权限系统
#### 权限模型
```
User (用户)
↓ (role_id)
Role (角色)
↓ (role_page_permissions 中间表)
Page (页面/菜单)
```
#### 权限检查流程
**中间件**: `pkg/middleware/rbac.go:31-70`
```go
func RequirePagePermission(pagePath string) gin.HandlerFunc {
return func(c *gin.Context) {
// 1. 从 Context 获取 user_id
userID, exists := c.Get("user_id")
if !exists {
c.JSON(401, gin.H{"error": "Unauthorized"})
c.Abort()
return
}
// 2. 调用 Storage 检查权限
hasPermission, err := storage.CheckUserRolePagePermission(userID, pagePath)
if err != nil {
c.JSON(500, gin.H{"error": "Failed to check permission"})
c.Abort()
return
}
// 3. 验证权限
if !hasPermission {
c.JSON(403, gin.H{"error": "Forbidden: No permission to access this page"})
c.Abort()
return
}
// 4. 继续处理请求
c.Next()
}
}
```
#### 权限查询 SQL
**位置**: `internal/storage/rbac_storage.go`
```sql
SELECT COUNT(*) > 0
FROM admin_users u
JOIN admin_roles r ON u.role_id = r.id
JOIN admin_role_page_permissions rpp ON r.id = rpp.role_id
JOIN admin_pages p ON rpp.page_id = p.id
WHERE u.id = ? AND p.path = ?
AND u.deleted_at IS NULL
AND r.deleted_at IS NULL
AND rpp.deleted_at IS NULL
AND p.deleted_at IS NULL
```
#### 使用示例
**在路由中使用**:
```go
// routes.go
users := admin.Group("/users")
users.Use(rbacMiddleware.RequirePagePermission("/users"))
{
users.GET("", userHandler.List) // 需要 /users 权限
users.POST("", userHandler.Create) // 需要 /users 权限
users.PUT("/:id", userHandler.Update) // 需要 /users 权限
}
```
**灵活的权限粒度**:
```go
// 整个路由组共享权限
usersGroup.Use(rbacMiddleware.RequirePagePermission("/users"))
// 或者单个路由单独设置权限
users.GET("",
rbacMiddleware.RequirePagePermission("/users/view"),
userHandler.List,
)
```
---
### 会话管理
#### MemorySessionManager
**位置**: `pkg/middleware/auth.go:24-58`
**数据结构**:
```go
type Session struct {
UserID uint
Username string
AccessToken string
ExpiresAt time.Time
}
type MemorySessionManager struct {
sessions map[string]*Session // key: access_token
mu sync.RWMutex
}
```
**功能**:
1. **创建会话**
```go
func (m *MemorySessionManager) Create(session *Session) {
m.mu.Lock()
defer m.mu.Unlock()
m.sessions[session.AccessToken] = session
}
```
2. **获取会话**
```go
func (m *MemorySessionManager) Get(accessToken string) (*Session, bool) {
m.mu.RLock()
defer m.mu.RUnlock()
session, exists := m.sessions[accessToken]
if !exists {
return nil, false
}
// 检查是否过期
if time.Now().After(session.ExpiresAt) {
return nil, false
}
return session, true
}
```
3. **删除会话 (登出)**
```go
func (m *MemorySessionManager) Delete(accessToken string) {
m.mu.Lock()
defer m.mu.Unlock()
delete(m.sessions, accessToken)
}
```
4. **获取所有在线用户**
```go
func (m *MemorySessionManager) GetAllSessions() []*Session {
m.mu.RLock()
defer m.mu.RUnlock()
var sessions []*Session
now := time.Now()
for _, session := range m.sessions {
if now.Before(session.ExpiresAt) {
sessions = append(sessions, session)
}
}
return sessions
}
```
**特点**:
- 内存存储,重启丢失
- 线程安全 (使用 RWMutex)
- 自动过期检查
- 支持批量登出
---
## 中间件系统
### 中间件链
```
Request
↓
CORS Middleware
↓
Logging Middleware
↓
Auth Middleware (RequireAuth)
↓
RBAC Middleware (RequirePagePermission)
↓
API Log Middleware
↓
Handler
↓
Response
```
---
### 1. 认证中间件
**位置**: `pkg/middleware/auth.go`
#### RequireAuth() (第84-159行)
**功能**: 验证用户身份
**流程**:
```go
func (m *AuthMiddleware) RequireAuth() gin.HandlerFunc {
return func(c *gin.Context) {
// 1. 从 Header 或 Query 获取 Token
token := c.GetHeader("Authorization")
if token == "" {
token = c.Query("token")
}
if token == "" {
c.JSON(401, gin.H{"error": "Missing token"})
c.Abort()
return
}
// 移除 "Bearer " 前缀
token = strings.TrimPrefix(token, "Bearer ")
// 2. 调用 SSO 服务验证 Token
userInfo, err := m.ssoService.ValidateToken(token)
if err != nil {
c.JSON(401, gin.H{"error": "Invalid token"})
c.Abort()
return
}
// 3. 解析用户 ID
userID := parseUserID(userInfo)
if userID == 0 {
c.JSON(401, gin.H{"error": "Invalid user ID"})
c.Abort()
return
}
// 4. 查找或创建本地用户
user, err := findOrCreateUser(userID, userInfo.Username, userInfo.Email, m.db)
if err != nil {
c.JSON(500, gin.H{"error": "Failed to get user"})
c.Abort()
return
}
// 5. 将用户信息存入 Context
c.Set("user_id", user.ID)
c.Set("username", user.Username)
c.Set("user", user)
c.Next()
}
}
```
**Token 获取方式**:
- **Header**: `Authorization: Bearer {token}`
- **Query**: `?token={token}`
---
### 2. RBAC 权限中间件
**位置**: `pkg/middleware/rbac.go`
#### RequirePagePermission(pagePath) (第31-70行)
**功能**: 检查用户是否有访问某个页面的权限
```go
func RequirePagePermission(pagePath string) gin.HandlerFunc {
return func(c *gin.Context) {
// 1. 从 Context 获取 user_id (由 AuthMiddleware 设置)
userID, exists := c.Get("user_id")
if !exists {
c.JSON(401, gin.H{"error": "Unauthorized"})
c.Abort()
return
}
// 2. 调用 Storage 检查权限
hasPermission, err := storage.CheckUserRolePagePermission(userID.(uint), pagePath)
if err != nil {
c.JSON(500, gin.H{"error": "Failed to check permission"})
c.Abort()
return
}
// 3. 验证权限
if !hasPermission {
c.JSON(403, gin.H{"error": "Forbidden: No permission"})
c.Abort()
return
}
c.Next()
}
}
```
#### RequireRole(roleName) (第73-126行)
**功能**: 检查用户是否具有特定角色
```go
func RequireRole(roleName string) gin.HandlerFunc {
return func(c *gin.Context) {
userID, _ := c.Get("user_id")
// 查询用户角色
var user models.User
db.Preload("Role").First(&user, userID)
// 检查角色
if user.Role == nil || user.Role.Name != roleName {
c.JSON(403, gin.H{"error": "Insufficient role"})
c.Abort()
return
}
c.Next()
}
}
```
---
### 3. 日志中间件
#### RequestLogMiddleware
**位置**: `internal/api/middlewares/logging.go`
**功能**: 记录所有 HTTP 请求
```go
func RequestLogMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
startTime := time.Now()
// 处理请求
c.Next()
// 计算耗时
duration := time.Since(startTime)
// 记录日志
logger.Info("HTTP Request",
zap.String("method", c.Request.Method),
zap.String("path", c.Request.URL.Path),
zap.Int("status", c.Writer.Status()),
zap.Duration("duration", duration),
zap.String("client_ip", c.ClientIP()),
)
}
}
```
**日志输出示例**:
```
2025-01-15T10:30:45.123Z INFO HTTP Request
method: GET
path: /api/admin/users
status: 200
duration: 45ms
client_ip: 192.168.1.100
```
---
#### APILogMiddleware
**位置**: `internal/api/middlewares/api_log_middleware.go`
**功能**: 记录数据修改接口的详细信息
```go
func APILogMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
// 只记录 POST/PUT/DELETE 请求
if !shouldLogRequest(c.Request.Method) {
c.Next()
return
}
// 读取请求体
bodyBytes, _ := ioutil.ReadAll(c.Request.Body)
c.Request.Body = ioutil.NopCloser(bytes.NewBuffer(bodyBytes))
// 创建响应写入器
blw := &bodyLogWriter{body: bytes.NewBufferString(""), ResponseWriter: c.Writer}
c.Writer = blw
// 处理请求
c.Next()
// 记录日志
logger.Info("API Call",
zap.String("method", c.Request.Method),
zap.String("path", c.Request.URL.Path),
zap.String("request_body", string(bodyBytes)),
zap.String("response_body", blw.body.String()),
zap.Int("status", c.Writer.Status()),
)
}
}
```
**日志包含**:
- 请求方法和路径
- 请求体 (JSON)
- 响应体 (JSON)
- 状态码
---
### 4. CORS 中间件
**位置**: `internal/api/routes/routes.go:37-44`
```go
config := cors.Config{
AllowOrigins: []string{
"http://localhost:5173",
"http://localhost:5174",
"http://localhost:3000",
"http://localhost:3003",
"http://localhost:3004",
},
AllowMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"},
AllowHeaders: []string{"Origin", "Content-Type", "Accept", "Authorization", "X-Requested-With", "Cookie"},
AllowCredentials: true,
}
router.Use(cors.New(config))
```
---
## 服务层设计
### 服务层职责
Service Layer 负责:
- **业务逻辑封装**: 所有业务规则都在 Service 中实现
- **事务管理**: 跨表操作的事务控制
- **外部服务调用**: 调用 SSO、Gateway、Email 等外部服务
- **数据转换**: 将 Storage 层的数据转换为业务对象
- **错误处理**: 统一的错误处理和日志记录
---
### 核心服务
#### 1. SSO 服务
**位置**: `internal/services/sso_service.go`
**主要方法**:
```go
type SSOService struct {
config *config.SSOConfig
db *gorm.DB
}
// Login 生成 SSO 授权 URL
func (s *SSOService) Login() (string, error)
// HandleCallback 处理 SSO 回调,交换 token
func (s *SSOService) HandleCallback(code, state string) (*TokenResponse, error)
// RefreshToken 刷新访问令牌
func (s *SSOService) RefreshToken(refreshToken string) (*TokenResponse, error)
// ValidateToken 验证 token 有效性
func (s *SSOService) ValidateToken(accessToken string) (*UserInfo, error)
// Logout 用户登出
func (s *SSOService) Logout(accessToken string) error
// GetOnlineUsers 获取在线用户列表
func (s *SSOService) GetOnlineUsers() []*Session
```
---
#### 2. 用户服务
**位置**: `internal/services/user_service.go`
**主要方法**:
```go
type UserService struct {
storage *storage.UserStorage
}
// List 用户列表(分页+搜索)
func (s *UserService) List(page, pageSize int, search string) ([]models.User, int64, error)
// Create 创建用户
func (s *UserService) Create(user *models.User) error
// Update 更新用户
func (s *UserService) Update(id uint, user *models.User) error
// Delete 删除用户(软删除)
func (s *UserService) Delete(id uint) error
// UpdateStatus 更新状态
func (s *UserService) UpdateStatus(id uint, status int) error
// UpdateRoles 更新用户角色
func (s *UserService) UpdateRoles(userID uint, roleIDs []uint) error
// GetPermissions 获取用户权限
func (s *UserService) GetPermissions(userID uint) ([]string, error)
// ChangeUserSystemRole 变更用户系统角色
func (s *UserService) ChangeUserSystemRole(userID uint, newRoleID uint) error
```
---
#### 3. GoalfyMax 用户服务
**位置**: `internal/services/goalfymax_user_service.go`
**主要方法**:
```go
type GoalfyMaxUserService struct {
storage *storage.GoalfyMaxUserStorage
balanceLogStorage *storage.BalanceOperationLogStorage
redis *redis.Client
}
// Create 创建用户
func (s *GoalfyMaxUserService) Create(user *models.GoalfyMaxUser) error
// Update 更新用户
func (s *GoalfyMaxUserService) Update(id uint, user *models.GoalfyMaxUser) error
// Delete 删除用户
func (s *GoalfyMaxUserService) Delete(id uint) error
// Ban 封禁用户
func (s *GoalfyMaxUserService) Ban(id uint, reason string, bannedBy uint) error
// Unban 解封用户
func (s *GoalfyMaxUserService) Unban(id uint) error
// AddBalance 增加余额
func (s *GoalfyMaxUserService) AddBalance(id uint, amount float64, operatorID uint, remark string) error
// DeductBalance 扣减余额
func (s *GoalfyMaxUserService) DeductBalance(id uint, amount float64, operatorID uint, remark string) error
```
**余额操作逻辑**:
```go
func (s *GoalfyMaxUserService) AddBalance(id, amount, operatorID, remark) error {
// 1. 开启事务
tx := s.storage.BeginTx()
defer tx.Rollback()
// 2. 查询用户
user, err := s.storage.GetByID(tx, id)
// 3. 从 Redis 获取当前余额
balanceKey := fmt.Sprintf("goalfymax:user:balance:%d", id)
currentBalance := redis.Get(balanceKey).Float64()
// 4. 计算新余额
newBalance := currentBalance + amount
// 5. 更新 Redis 余额
redis.Set(balanceKey, newBalance, 0)
// 6. 记录余额操作日志
log := &models.BalanceOperationLog{
UserID: id,
OperationType: "add",
Amount: amount,
BalanceBefore: currentBalance,
BalanceAfter: newBalance,
OperatorID: operatorID,
Remark: remark,
}
s.balanceLogStorage.Create(tx, log)
// 7. 提交事务
tx.Commit()
return nil
}
```
---
#### 4. 邀请码服务
**位置**: `internal/services/invite_code_service.go`
**主要方法**:
```go
type InviteCodeService struct {
storage *storage.InviteCodeStorage
}
// CreateInviteCode 创建邀请码(支持批量)
func (s *InviteCodeService) CreateInviteCode(req *CreateInviteCodeRequest) ([]models.InviteCode, error)
// ValidateInviteCode 验证邀请码有效性
func (s *InviteCodeService) ValidateInviteCode(code string) (bool, error)
// MarkAsUsed 标记邀请码为已使用
func (s *InviteCodeService) MarkAsUsed(code string, clientID string) error
// GetStatistics 获取邀请码统计
func (s *InviteCodeService) GetStatistics() (*InviteCodeStatistics, error)
```
---
#### 5. 邀请码申请服务
**位置**: `internal/services/invite_code_application_service.go`
**主要方法**:
```go
type InviteCodeApplicationService struct {
storage *storage.InviteCodeApplicationStorage
inviteCodeService *InviteCodeService
emailService *EmailService
}
// SubmitApplication 提交申请(公开接口)
func (s *InviteCodeApplicationService) SubmitApplication(req *SubmitApplicationRequest) error
// ApproveApplication 审批通过
func (s *InviteCodeApplicationService) ApproveApplication(id uint, reviewerID uint) error
// RejectApplication 审批拒绝
func (s *InviteCodeApplicationService) RejectApplication(id uint, reviewerID uint, reason string) error
// BatchApprove 批量审批通过
func (s *InviteCodeApplicationService) BatchApprove(ids []uint, reviewerID uint) error
// BatchReject 批量审批拒绝
func (s *InviteCodeApplicationService) BatchReject(ids []uint, reviewerID uint, reason string) error
```
**审批通过逻辑**:
```go
func (s *InviteCodeApplicationService) ApproveApplication(id, reviewerID) error {
// 1. 开启事务
tx := s.storage.BeginTx()
defer tx.Rollback()
// 2. 查询申请
app, err := s.storage.GetByID(tx, id)
if app.Status != "pending" {
return errors.New("申请状态不是待审批")
}
// 3. 生成邀请码
inviteCode, err := s.inviteCodeService.CreateInviteCode(tx, &CreateInviteCodeRequest{
Email: app.Email,
UserLevelID: defaultLevelID, // normal
ExpiresAt: time.Now().Add(30 * 24 * time.Hour), // 30天
Count: 1,
})
// 4. 更新申请状态
app.Status = "approved"
app.ReviewedBy = &reviewerID
now := time.Now()
app.ReviewedAt = &now
app.InviteCodeID = &inviteCode.ID
s.storage.Update(tx, app)
// 5. 提交事务
tx.Commit()
// 6. 发送邮件通知
s.emailService.SendApprovalEmail(app.Email, inviteCode.Code, app.Language)
return nil
}
```
---
#### 6. 邮件服务
**位置**: `internal/services/email_service.go`
**主要方法**:
```go
type EmailService struct {
config *config.EmailConfig
}
// SendApprovalEmail 发送审批通过邮件
func (s *EmailService) SendApprovalEmail(email, code, language string) error
// SendRejectionEmail 发送审批拒绝邮件
func (s *EmailService) SendRejectionEmail(email, reason, language string) error
```
**邮件模板**:
**中文通过模板** (docs/email_preview_approval.html):
```html
<h2>您的邀请码申请已通过!</h2>
<p>您的邀请码是: <strong>{{code}}</strong></p>
<p>有效期: 30天</p>
<a href="https://passport.goalfy.ai/invite/{{code}}">立即使用</a>
```
**英文通过模板** (docs/email_preview_en.html):
```html
<h2>Your invite code application has been approved!</h2>
<p>Your invite code is: <strong>{{code}}</strong></p>
<p>Valid for: 30 days</p>
<a href="https://passport.goalfy.ai/invite/{{code}}">Use Now</a>
```
**中文拒绝模板** (docs/email_preview_rejection.html):
```html
<h2>您的邀请码申请未通过</h2>
<p>拒绝原因: {{reason}}</p>
<p>您可以重新申请或联系我们的客服。</p>
```
---
#### 7. 财务服务
**位置**: `internal/services/finance_service.go`
**主要方法**:
```go
type FinanceService struct {
db *gorm.DB
}
// GetSandboxRecords 获取 Sandbox 使用记录
func (s *FinanceService) GetSandboxRecords(req *SandboxRecordRequest) ([]SandboxRecord, int64, error)
// GetTokenUsages 获取 Token 使用统计
func (s *FinanceService) GetTokenUsages(req *TokenUsageRequest) ([]TokenUsage, int64, error)
// GetMCPUsages 获取 MCP 使用记录
func (s *FinanceService) GetMCPUsages(req *MCPUsageRequest) ([]MCPUsage, int64, error)
// GetMCPAccountBalances 获取 MCP 账户余额
func (s *FinanceService) GetMCPAccountBalances() ([]MCPAccountBalance, error)
// AdjustMCPBalance 调整 MCP 账户余额
func (s *FinanceService) AdjustMCPBalance(providerID uint, amount float64, operatorID uint, remark string) error
// RefundPayment 退款
func (s *FinanceService) RefundPayment(paymentID uint, amount float64, reason string) error
```
---
#### 8. 配额服务
**位置**: `internal/services/quota_service.go`
**主要方法**:
```go
type QuotaService struct {
gatewayClient *GatewayClient
storage *storage.QuotaStorage
}
// GetQuotaHistory 获取配额历史(转发到 Gateway)
func (s *QuotaService) GetQuotaHistory(req *QuotaHistoryRequest) (*QuotaHistoryResponse, error)
// CreateQuotaRule 创建配额规则
func (s *QuotaService) CreateQuotaRule(rule *models.QuotaRule) error
// UpdateQuotaRule 更新配额规则
func (s *QuotaService) UpdateQuotaRule(id uint, rule *models.QuotaRule) error
// DeleteQuotaRule 删除配额规则
func (s *QuotaService) DeleteQuotaRule(id uint) error
```
---
#### 9. 网关客户端
**位置**: `internal/services/gateway_client.go`
**功能**: 转发请求到 AI Gateway
```go
type GatewayClient struct {
baseURL string
httpClient *http.Client
authToken string
}
// Login 登录 Gateway 获取 token
func (c *GatewayClient) Login() error
// ForwardRequest 转发请求到 Gateway
func (c *GatewayClient) ForwardRequest(method, path string, body interface{}) ([]byte, error)
```
**配置**:
```yaml
gateway:
base_url: "http://44.247.156.94:8080"
timeout: 30
auth:
login_url: "/api/auth/login"
key: "your-key"
```
---
#### 10. 审计日志服务
**位置**: `internal/services/audit_log_service.go`
**主要方法**:
```go
type AuditLogService struct {
storage *storage.AuditLogStorage
}
// CreateLog 创建审计日志
func (s *AuditLogService) CreateLog(log *models.AuditLog) error
// ListLogs 查询审计日志(分页)
func (s *AuditLogService) ListLogs(req *ListAuditLogsRequest) ([]models.AuditLog, int64, error)
```
**日志记录示例**:
```go
// 更新用户时记录日志
func (s *UserService) Update(id uint, newUser *models.User) error {
// 1. 查询旧值
oldUser, _ := s.storage.GetByID(id)
// 2. 更新用户
s.storage.Update(id, newUser)
// 3. 记录审计日志
s.auditLogService.CreateLog(&models.AuditLog{
UserID: currentUserID,
OperationType: "update",
TargetTable: "admin_users",
TargetID: id,
OldValue: toJSON(oldUser),
NewValue: toJSON(newUser),
IP: clientIP,
UserAgent: userAgent,
})
return nil
}
```
---
## 配置管理
### 配置文件位置
- **开发环境**: `etc/config.yaml`
- **生产环境**: `etc/config-prod.yaml`
### 配置加载
**位置**: `internal/config/config.go`
```go
type Config struct {
Server ServerConfig `mapstructure:"server"`
Database DatabaseConfig `mapstructure:"database"`
Redis RedisConfig `mapstructure:"redis"`
PostgreSQL PostgreSQLConfig `mapstructure:"postgresql"`
SSO SSOConfig `mapstructure:"sso"`
Gateway GatewayConfig `mapstructure:"gateway"`
OSS OSSConfig `mapstructure:"oss"`
Email EmailConfig `mapstructure:"email"`
Alert AlertConfig `mapstructure:"alert"`
Jobs JobsConfig `mapstructure:"jobs"`
}
func LoadConfig(env string) (*Config, error) {
viper.SetConfigName(fmt.Sprintf("config-%s", env))
viper.SetConfigType("yaml")
viper.AddConfigPath("./etc")
if err := viper.ReadInConfig(); err != nil {
return nil, err
}
var config Config
if err := viper.Unmarshal(&config); err != nil {
return nil, err
}
return &config, nil
}
```
---
### 配置示例
#### 完整配置文件 (config.yaml)
```yaml
# 服务器配置
server:
addr: "0.0.0.0"
port: 8087
# MySQL 数据库配置
database:
dsn: "root:password@tcp(localhost:3306)/goalfymax_admin?charset=utf8mb4&parseTime=True&loc=Local"
maxIdleConns: 10
maxOpenConns: 100
logLevel: "info"
# Redis 配置
redis:
addr: "localhost:6379"
password: ""
db: 0
poolSize: 10
# PostgreSQL 配置 (MCP 数据)
postgresql:
host: "localhost"
port: 5432
user: "postgres"
password: "password"
dbname: "mcp_gateway"
sslmode: "disable"
max_open_conns: 100
max_idle_conns: 20
# SSO 配置
sso:
sso_server_url: "https://passport.goalfy.ai"
client_id: "xv5Xesd4ry1_I3hP3xYXNw"
client_secret: "your-secret"
redirect_uri: "http://localhost:3003"
scope: "openid profile email"
resource_aud: "api://admin"
admin_token: "your-admin-token"
# Gateway 配置
gateway:
base_url: "http://44.247.156.94:8080"
timeout: 30
auth:
login_url: "/api/auth/login"
key: "your-gateway-key"
# OSS (S3) 配置
oss:
endpoint: "https://goalfyagent-data-test.s3.us-west-2.amazonaws.com/"
region: "us-west-2"
access_key_id: "your-access-key"
secret_access_key: "your-secret-key"
bucket: "goalfyagent-data-test"
presign_url_expire: 30m
# 邮件配置
email:
sender: "invite_goalfymax@goalfyai.com"
sender_name: "GoalfyMax"
host: "smtp.mxhichina.com"
port: 465
username: "invite_goalfymax@goalfyai.com"
password: "your-email-password"
invite_url_prefix: "https://passport.goalfy.ai/invite/"
# 告警配置
alert:
dingtalk:
enabled: true
webhook: "https://oapi.dingtalk.com/robot/send?access_token=xxx"
secret: "your-dingtalk-secret"
# 定时任务配置
jobs:
mcp_usage_balance:
enabled: true
run_on_startup: true
delay_minutes: 5
model_token_balance:
enabled: true
run_on_startup: true
delay_minutes: 5
```
---
### 环境变量支持
**使用环境变量覆盖配置**:
```bash
export SERVER_PORT=8088
export DATABASE_DSN="root:newpassword@tcp(localhost:3306)/db"
export REDIS_ADDR="redis.example.com:6379"
```
**在代码中启用**:
```go
viper.AutomaticEnv()
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
```
---
## 部署方案
### Docker 部署
#### Dockerfile
**位置**: `Dockerfile`
**多阶段构建**:
```dockerfile
# Stage 1: 构建
FROM golang:1.25-alpine AS builder
WORKDIR /app
# 安装依赖
RUN apk add --no-cache git
# 复制 go.mod 和 go.sum
COPY go.mod go.sum ./
RUN go mod download
# 复制源代码
COPY . .
# 构建二进制文件
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
-ldflags="-w -s" \
-o goalfymax-admin \
./cmd/server
# Stage 2: 运行
FROM alpine:latest
WORKDIR /app
# 安装 ca-certificates (用于 HTTPS 请求)
RUN apk --no-cache add ca-certificates
# 创建非 root 用户
RUN addgroup -g 1000 appuser && \
adduser -D -u 1000 -G appuser appuser
# 复制二进制文件和配置文件
COPY --from=builder /app/goalfymax-admin .
COPY --from=builder /app/etc ./etc
COPY --from=builder /app/docs ./docs
# 设置权限
RUN chown -R appuser:appuser /app
# 切换到非 root 用户
USER appuser
# 暴露端口
EXPOSE 8087
# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:8087/health || exit 1
# 启动应用
CMD ["./goalfymax-admin", "--env", "prod"]
```
**构建镜像**:
```bash
./build.sh
```
**推送到 ECR**:
```bash
./build-and-push.sh
```
---
### Kubernetes 部署
#### Deployment (k8s/deployment.yaml)
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: goalfymax-admin
namespace: default
spec:
replicas: 2
selector:
matchLabels:
app: goalfymax-admin
template:
metadata:
labels:
app: goalfymax-admin
spec:
containers:
- name: goalfymax-admin
image: 177603749739.dkr.ecr.us-west-2.amazonaws.com/goalfy/goalfymax-admin:latest
imagePullPolicy: Always
ports:
- containerPort: 8087
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 512Mi
livenessProbe:
httpGet:
path: /health
port: 8087
initialDelaySeconds: 30
periodSeconds: 30
timeoutSeconds: 5
failureThreshold: 3
readinessProbe:
httpGet:
path: /health
port: 8087
initialDelaySeconds: 10
periodSeconds: 10
timeoutSeconds: 3
failureThreshold: 3
volumeMounts:
- name: config
mountPath: /app/etc
readOnly: true
env:
- name: ENV
value: "prod"
volumes:
- name: config
configMap:
name: goalfymax-admin-config
```
#### Service (k8s/service.yaml)
```yaml
apiVersion: v1
kind: Service
metadata:
name: goalfymax-admin
namespace: default
spec:
type: ClusterIP
selector:
app: goalfymax-admin
ports:
- protocol: TCP
port: 8087
targetPort: 8087
```
#### ConfigMap (k8s/configmap.yaml)
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: goalfymax-admin-config
namespace: default
data:
config-prod.yaml: |
server:
addr: "0.0.0.0"
port: 8087
database:
dsn: "root:password@tcp(mysql:3306)/goalfymax_admin"
redis:
addr: "redis:6379"
# ... 其他配置
```
---
### 部署流程
#### 1. 本地开发
```bash
# 启动服务
./start.sh
# 启动 SSO 服务
./start_sso.sh
# 启动带 CORS 的服务
./start_with_cors.sh
```
#### 2. 构建 Docker 镜像
```bash
# 本地构建
./build.sh
# 构建并推送到 ECR
./build-and-push.sh
```
#### 3. 部署到 Kubernetes
```bash
# 创建 ConfigMap
kubectl apply -f k8s/configmap.yaml
# 部署应用
kubectl apply -f k8s/deployment.yaml
# 创建 Service
kubectl apply -f k8s/service.yaml
# 查看部署状态
kubectl get pods -l app=goalfymax-admin
kubectl logs -f <pod-name>
```
#### 4. 数据库迁移
```bash
# 执行迁移脚本
./scripts/migrate.sh
```
#### 5. 健康检查
```bash
# 检查服务健康状态
curl http://localhost:8087/health
# 输出: {"status":"ok"}
```
---
### 监控与告警
#### 健康检查端点
```
GET /health
```
**响应**:
```json
{
"status": "ok"
}
```
#### 钉钉告警
**配置**:
```yaml
alert:
dingtalk:
enabled: true
webhook: "https://oapi.dingtalk.com/robot/send?access_token=xxx"
secret: "your-secret"
```
**使用**:
```go
// 发送告警
notifier.SendDingTalk("服务异常", "数据库连接失败")
```
---
## 开发指南
### 本地开发环境搭建
#### 1. 环境要求
- Go 1.25+
- MySQL 8.0+
- Redis 6.0+
- PostgreSQL 13+
#### 2. 安装依赖
```bash
go mod download
```
#### 3. 配置数据库
**创建数据库**:
```sql
CREATE DATABASE goalfymax_admin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
**配置文件** (etc/config.yaml):
```yaml
database:
dsn: "root:password@tcp(localhost:3306)/goalfymax_admin?charset=utf8mb4&parseTime=True&loc=Local"
```
#### 4. 启动服务
```bash
./start.sh
```
或者:
```bash
go run cmd/server/main.go --env dev
```
#### 5. 访问接口
- **健康检查**: http://localhost:8087/health
- **API 文档**: http://localhost:8087/swagger (如果有)
---
### 代码规范
#### 1. 项目结构规范
- **Handler**: 只负责 HTTP 请求处理,不包含业务逻辑
- **Service**: 封装所有业务逻辑,调用 Storage
- **Storage**: 封装所有数据库操作
#### 2. 命名规范
- **文件名**: 小写蛇形命名 (user_service.go)
- **变量名**: 驼峰命名 (userService)
- **常量名**: 大写蛇形命名 (MAX_PAGE_SIZE)
- **接口名**: I 开头 (IUserService)
#### 3. 错误处理
**统一错误响应**:
```go
utils.ErrorResponse(c, http.StatusBadRequest, "参数错误")
```
**统一成功响应**:
```go
utils.SuccessResponse(c, data)
```
#### 4. 日志规范
**使用结构化日志**:
```go
logger.Info("创建用户",
zap.String("username", username),
zap.Uint("user_id", userID),
)
logger.Error("数据库错误",
zap.Error(err),
zap.String("operation", "create user"),
)
```
---
### 添加新功能
#### 1. 添加新的数据模型
**步骤**:
1. 在 `internal/models/` 创建模型文件
2. 定义模型结构
3. 在 `storage/database.go` 的 `autoMigrate()` 中注册
**示例**:
```go
// internal/models/product.go
type Product struct {
BaseModel
Name string `json:"name" gorm:"size:100;not null"`
Price float64 `json:"price" gorm:"type:decimal(10,2)"`
Description string `json:"description" gorm:"type:text"`
}
```
```go
// storage/database.go
func (d *Database) autoMigrate() error {
return d.DB.AutoMigrate(
// ... 其他模型
&models.Product{},
)
}
```
---
#### 2. 添加新的 Storage
**步骤**:
1. 在 `internal/storage/` 创建 storage 文件
2. 实现 CRUD 方法
3. 依赖 Database 对象
**示例**:
```go
// internal/storage/product_storage.go
type ProductStorage struct {
db *Database
}
func NewProductStorage(db *Database) *ProductStorage {
return &ProductStorage{db: db}
}
func (s *ProductStorage) Create(product *models.Product) error {
return s.db.DB.Create(product).Error
}
func (s *ProductStorage) GetByID(id uint) (*models.Product, error) {
var product models.Product
err := s.db.DB.First(&product, id).Error
return &product, err
}
func (s *ProductStorage) List(page, pageSize int) ([]models.Product, int64, error) {
var products []models.Product
var total int64
offset := (page - 1) * pageSize
s.db.DB.Model(&models.Product{}).Count(&total)
err := s.db.DB.Offset(offset).Limit(pageSize).Find(&products).Error
return products, total, err
}
func (s *ProductStorage) Update(id uint, product *models.Product) error {
return s.db.DB.Model(&models.Product{}).Where("id = ?", id).Updates(product).Error
}
func (s *ProductStorage) Delete(id uint) error {
return s.db.DB.Delete(&models.Product{}, id).Error
}
```
---
#### 3. 添加新的 Service
**步骤**:
1. 在 `internal/services/` 创建 service 文件
2. 实现业务逻辑
3. 调用 Storage 方法
**示例**:
```go
// internal/services/product_service.go
type ProductService struct {
storage *storage.ProductStorage
}
func NewProductService(storage *storage.ProductStorage) *ProductService {
return &ProductService{storage: storage}
}
func (s *ProductService) CreateProduct(product *models.Product) error {
// 业务验证
if product.Price < 0 {
return errors.New("价格不能为负数")
}
// 调用 Storage
return s.storage.Create(product)
}
func (s *ProductService) GetProduct(id uint) (*models.Product, error) {
return s.storage.GetByID(id)
}
func (s *ProductService) ListProducts(page, pageSize int) ([]models.Product, int64, error) {
return s.storage.List(page, pageSize)
}
```
---
#### 4. 添加新的 Handler
**步骤**:
1. 在 `internal/api/handlers/` 创建 handler 文件
2. 实现 HTTP 处理方法
3. 在 routes.go 中注册路由
**示例**:
```go
// internal/api/handlers/product_handler.go
type ProductHandler struct {
service *services.ProductService
}
func NewProductHandler(service *services.ProductService) *ProductHandler {
return &ProductHandler{service: service}
}
// Create 创建产品
func (h *ProductHandler) Create(c *gin.Context) {
var req models.Product
if err := c.ShouldBindJSON(&req); err != nil {
utils.ErrorResponse(c, http.StatusBadRequest, "参数错误")
return
}
if err := h.service.CreateProduct(&req); err != nil {
utils.ErrorResponse(c, http.StatusInternalServerError, err.Error())
return
}
utils.SuccessResponse(c, req)
}
// List 产品列表
func (h *ProductHandler) List(c *gin.Context) {
page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
products, total, err := h.service.ListProducts(page, pageSize)
if err != nil {
utils.ErrorResponse(c, http.StatusInternalServerError, err.Error())
return
}
utils.SuccessResponse(c, gin.H{
"list": products,
"total": total,
"page": page,
"page_size": pageSize,
})
}
```
---
#### 5. 注册路由
**在 routes.go 中添加**:
```go
// internal/api/routes/routes.go
func SetupRoutes(r *gin.Engine, deps *Dependencies) {
// ... 初始化 handler
productHandler := handlers.NewProductHandler(deps.ProductService)
// 添加路由
admin := r.Group("/api/admin")
admin.Use(authMiddleware.RequireAuth())
{
products := admin.Group("/products")
products.Use(rbacMiddleware.RequirePagePermission("/products"))
{
products.GET("", productHandler.List)
products.POST("", productHandler.Create)
products.GET("/:id", productHandler.GetByID)
products.PUT("/:id", productHandler.Update)
products.DELETE("/:id", productHandler.Delete)
}
}
}
```
---
### 测试
#### 1. 单元测试
**创建测试文件**:
```go
// internal/services/product_service_test.go
package services
import (
"testing"
"github.com/stretchr/testify/assert"
)
func TestProductService_CreateProduct(t *testing.T) {
// 创建 mock storage
mockStorage := &MockProductStorage{}
service := NewProductService(mockStorage)
// 测试用例
product := &models.Product{
Name: "Test Product",
Price: 99.99,
}
err := service.CreateProduct(product)
assert.NoError(t, err)
assert.NotZero(t, product.ID)
}
func TestProductService_CreateProduct_NegativePrice(t *testing.T) {
mockStorage := &MockProductStorage{}
service := NewProductService(mockStorage)
product := &models.Product{
Name: "Test Product",
Price: -10, // 负数价格
}
err := service.CreateProduct(product)
assert.Error(t, err)
assert.Contains(t, err.Error(), "价格不能为负数")
}
```
**运行测试**:
```bash
go test ./internal/services/...
```
---
#### 2. API 测试
**使用 curl 测试**:
```bash
# 登录
curl -X POST http://localhost:8087/api/sso/login
# 创建用户
curl -X POST http://localhost:8087/api/admin/users \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"username": "testuser",
"email": "test@example.com",
"nickname": "Test User"
}'
# 查询用户列表
curl -X GET "http://localhost:8087/api/admin/users?page=1&page_size=20" \
-H "Authorization: Bearer {token}"
```
**使用测试脚本**:
```bash
./scripts/test_api.sh
./test_sso_api.sh
./test_quota_api.sh
```
---
### 常见问题
#### 1. 数据库连接失败
**问题**:
```
Error 1045: Access denied for user 'root'@'localhost'
```
**解决**:
- 检查 MySQL 用户名和密码
- 检查 MySQL 是否启动
- 检查配置文件中的 DSN
---
#### 2. Redis 连接失败
**问题**:
```
dial tcp 127.0.0.1:6379: connect: connection refused
```
**解决**:
- 检查 Redis 是否启动
- 检查 Redis 端口是否正确
- 检查 Redis 密码配置
---
#### 3. SSO 登录失败
**问题**:
```
invalid_grant: PKCE validation failed
```
**解决**:
- 检查 code_verifier 是否正确存储
- 检查 SSO 服务器配置
- 检查 redirect_uri 是否匹配
---
#### 4. 权限被拒绝
**问题**:
```
403 Forbidden: No permission to access this page
```
**解决**:
- 检查用户是否分配角色
- 检查角色是否有对应页面权限
- 检查页面路径是否匹配
---
## 总结
GoalfyMax Admin 是一个功能完善、架构清晰的企业级后端管理系统:
### 核心优势
1. **架构清晰**: 严格的三层架构,职责分离明确
2. **功能完善**: 用户管理、权限控制、财务管理、邀请码系统等
3. **安全可靠**: SSO 单点登录、RBAC 权限、审计日志、PKCE 安全增强
4. **生产就绪**: Docker + Kubernetes 部署、健康检查、日志监控、钉钉告警
5. **代码规范**: 符合 Go 最佳实践,模块化设计,接口抽象
6. **可扩展性**: 易于添加新功能,支持多数据库
### 技术亮点
- **SSO 单点登录**: 完整的 OAuth2/OIDC 实现,支持 PKCE
- **RBAC 权限**: 灵活的角色-页面权限管理
- **邀请码系统**: 完整的申请-审批-发邮件流程
- **财务管理**: MCP 账户、模型账户、余额管理
- **审计日志**: 记录所有数据变更操作
- **定时任务**: 余额同步、统计任务
- **多数据库**: MySQL + PostgreSQL + Redis
- **容器化部署**: Docker 多阶段构建 + Kubernetes
### 部署环境
- **容器化**: Docker + Kubernetes
- **云平台**: AWS EKS + RDS + S3 + Redis
- **监控告警**: 健康检查 + 钉钉告警
- **高可用**: 多副本部署 + 负载均衡
---
## 附录
### 相关文档
- [快速开始指南](discuss/QUICK_START.md)
- [架构指南](discuss/architecture_guide.md)
- [用户等级配置实现总结](discuss/user-level-config-implementation-summary.md)
- [部署和测试文档](docs/deployment_and_testing.md)
- [邀请码功能文档](docs/invite_code_application_feature.md)
- [邮件模板预览](docs/email_templates_preview.html)
### 脚本工具
- **启动脚本**: `start.sh`, `start_sso.sh`, `start_with_cors.sh`
- **部署脚本**: `build.sh`, `build-and-push.sh`
- **数据库迁移**: `scripts/migrate.sh`
- **测试脚本**: `scripts/test_api.sh`, `test_sso_api.sh`
- **邀请码 API**: `scripts/invite_code_api.py`
### 联系方式
- **项目地址**: /Users/ricardo/Documents/加和科技/goalfylearning-admin
- **Git 仓库**: (待补充)
- **问题反馈**: (待补充)
---
**文档版本**: v1.0
**更新时间**: 2025-12-04
**文档作者**: Claude AI
Reference in New Issue View Git Blame Copy Permalink