auth

package
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 19, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package auth 提供用户认证相关的 HTTP 处理器

Package auth 提供用户认证相关的中间件

Package auth 提供用户认证相关功能

Index

Constants

View Source 
const (
	// DefaultCLITokenTTL 是未指定有效期时使用的期限。
	// DefaultCLITokenTTL is used when the caller does not specify an expiry.
	DefaultCLITokenTTL = 7 * 24 * time.Hour

	// MaxCLITokenTTL 是 CLI 令牌允许的最长有效期。
	// MaxCLITokenTTL is the maximum lifetime accepted for a CLI token.
	MaxCLITokenTTL = 30 * 24 * time.Hour
)
View Source 
const (
	SessionKeyUserID   = "user_id"
	SessionKeyUsername = "username"
)

会话键常量

View Source 
const (
	ErrMsgInvalidCredentials = "用户名或密码错误"
	ErrMsgEmptyCredentials   = "用户名和密码不能为空"
	ErrMsgUserInactive       = "用户账户已禁用"
	ErrMsgSessionError       = "会话错误"
	ErrMsgInternalError      = "内部服务器错误"
	ErrMsgCLIHeaderRequired  = "缺少 CLI 请求标识"
	ErrMsgCLITokenInvalid    = "CLI 令牌无效或已过期"
)

错误消息常量（不暴露具体是用户名还是密码错误）

View Source 
const (
	ContextKeyUser = "auth_user"
)

上下文键常量

View Source 
const DefaultBcryptCost = 10

DefaultBcryptCost 默认 bcrypt 加密成本

View Source 
const DefaultLanguage = "zh"

DefaultLanguage 默认用户语言偏好

Variables

View Source 
var (
	// ErrInvalidCLITokenTTL 表示令牌有效期不是 7 到 30 天内的整数天数。
	// ErrInvalidCLITokenTTL means the lifetime is not an integer number of days from 7 to 30.
	ErrInvalidCLITokenTTL = errors.New("auth: CLI 令牌有效期必须是 7d 到 30d")
	// ErrInvalidCLIToken 表示令牌不存在、已撤销或已过期。
	// ErrInvalidCLIToken means the token is unknown, revoked, or expired.
	ErrInvalidCLIToken = errors.New("auth: CLI 令牌无效")
	// ErrCLITokenRevoked 表示令牌已经撤销。
	// ErrCLITokenRevoked means the token has been revoked.
	ErrCLITokenRevoked = errors.New("auth: CLI 令牌已撤销")
	// ErrCLITokenExpired 表示令牌已经过期。
	// ErrCLITokenExpired means the token has expired.
	ErrCLITokenExpired = errors.New("auth: CLI 令牌已过期")
)
View Source 
var (
	ErrUserNotFound      = errors.New("auth: 用户不存在")
	ErrInvalidPassword   = errors.New("auth: 密码错误")
	ErrUserInactive      = errors.New("auth: 用户已禁用")
	ErrEmptyCredentials  = errors.New("auth: 用户名或密码不能为空")
	ErrPasswordTooShort  = errors.New("auth: 密码长度不能少于6位")
	ErrUserAlreadyExists = errors.New("auth: 用户名已存在")
)

错误定义

Functions

func AdminRequired 

func AdminRequired() gin.HandlerFunc

AdminRequired 管理员权限验证中间件 验证用户是否为管理员，如果不是则返回 403 错误 注意：此中间件应在 LoginRequired 之后使用

func AuthenticateCLIToken 

func AuthenticateCLIToken(database *gorm.DB, plaintext string, now time.Time) (*CLIToken, *User, error)

AuthenticateCLIToken 校验令牌、用户状态，并更新最近使用时间。 AuthenticateCLIToken validates the token and user, then updates last-used time.

func CLIAuthRequired 

func CLIAuthRequired() gin.HandlerFunc

CLIAuthRequired 验证 CLI Bearer 令牌并按当前数据库状态加载用户。 CLIAuthRequired validates a CLI Bearer token and loads the current user state.

func CLIClientRequired 

func CLIClientRequired() gin.HandlerFunc

CLIClientRequired 只允许带有 CLI 请求标识的调用进入 CLI 接口。 CLIClientRequired allows requests with the CLI marker to enter CLI endpoints.

func CLILogin 

func CLILogin(c *gin.Context)

CLILogin 通过用户名密码签发 CLI Bearer 令牌。 CLILogin issues a CLI Bearer token after username/password verification. @Tags auth @Accept json @Produce json @Param request body CLILoginRequest true "CLI 登录请求" @Success 200 {object} CLILoginResponse @Router /api/v1/auth/cli/login [post]

func CLILogout 

func CLILogout(c *gin.Context)

CLILogout 撤销当前 CLI Bearer 令牌。 CLILogout revokes the current CLI Bearer token. @Tags auth @Produce json @Success 200 {object} LogoutResponse @Router /api/v1/auth/cli/logout [post]

func CLIWhoAmI 

func CLIWhoAmI(c *gin.Context)

CLIWhoAmI 返回当前 CLI 令牌对应的用户。 CLIWhoAmI returns the user associated with the current CLI token. @Tags auth @Produce json @Success 200 {object} UserInfoResponse @Router /api/v1/auth/cli/whoami [get]

func GetUserIDFromContext 

func GetUserIDFromContext(c *gin.Context) uint64

GetUserIDFromContext 从 Gin 上下文获取用户 ID

func GetUserInfo 

func GetUserInfo(c *gin.Context)

GetUserInfo 获取当前登录用户信息 @Tags auth @Produce json @Success 200 {object} UserInfoResponse @Router /api/v1/auth/user-info [get]

func GetUsernameFromContext 

func GetUsernameFromContext(c *gin.Context) string

GetUsernameFromContext 从 Gin 上下文获取用户名

func Login 

func Login(c *gin.Context)

Login 处理用户登录 @Tags auth @Accept json @Produce json @Param request body LoginRequest true "登录请求" @Success 200 {object} LoginResponse @Router /api/v1/auth/login [post]

func LoginRequired 

func LoginRequired() gin.HandlerFunc

LoginRequired 登录验证中间件 验证用户是否已登录，如果未登录则返回 401 错误

func LoginRequiredSessionOnly 

func LoginRequiredSessionOnly() gin.HandlerFunc

LoginRequiredSessionOnly 轻量会话登录验证中间件（不查数据库） 适用于高频静态资源代理场景，避免每个请求触发数据库读取。

func Logout 

func Logout(c *gin.Context)

Logout 处理用户登出 @Tags auth @Produce json @Success 200 {object} LogoutResponse @Router /api/v1/auth/logout [post]

func NormalizeLanguage 

func NormalizeLanguage(value string) string

NormalizeLanguage 归一化用户语言偏好

func ParseCLITokenTTL 

func ParseCLITokenTTL(value string) (time.Duration, error)

ParseCLITokenTTL 校验并解析形如 7d、14d、30d 的有效期。 ParseCLITokenTTL validates and parses lifetimes such as 7d, 14d, or 30d.

func RevokeCLIToken 

func RevokeCLIToken(database *gorm.DB, plaintext string, now time.Time) error

RevokeCLIToken 撤销令牌；重复撤销保持成功，便于登出请求幂等。 RevokeCLIToken revokes a token; repeated revocation remains successful.

func SetUserToContext 

func SetUserToContext(c *gin.Context, user *User)

SetUserToContext 将用户信息存入 Gin 上下文

func UpdateProfile 

func UpdateProfile(c *gin.Context)

UpdateProfile 更新当前登录用户的个人信息（支持邮箱和语言偏好）。 @Tags auth @Accept json @Produce json @Param request body UpdateProfileRequest true "更新个人信息请求" @Success 200 {object} UpdateProfileResponse @Router /api/v1/auth/profile [put]

Types

type CLILoginData 

type CLILoginData struct {
	Token     string    `json:"token"`
	TokenType string    `json:"token_type"`
	ExpiresAt time.Time `json:"expires_at"`
	User      *UserInfo `json:"user"`
}

CLILoginData 是 CLI 登录响应中的令牌信息。 CLILoginData contains the token information in a CLI login response.

type CLILoginRequest 

type CLILoginRequest struct {
	Username  string `json:"username" binding:"required"`
	Password  string `json:"password" binding:"required"`
	ExpiresIn string `json:"expires_in"`
}

CLILoginRequest 是 CLI 登录请求。 CLILoginRequest is the CLI login request.

type CLILoginResponse 

type CLILoginResponse struct {
	ErrorMsg string        `json:"error_msg"`
	Data     *CLILoginData `json:"data"`
}

CLILoginResponse 是 CLI 登录响应。 CLILoginResponse is the CLI login response.

type CLIToken 

type CLIToken struct {
	ID          uint64     `json:"id" gorm:"primaryKey;autoIncrement"`
	UserID      uint64     `json:"user_id" gorm:"index;not null"`
	TokenPrefix string     `json:"token_prefix" gorm:"size:16;index;not null"`
	TokenHash   string     `json:"-" gorm:"column:token_hash;size:64;unique;not null"`
	ExpiresAt   time.Time  `json:"expires_at" gorm:"index;not null"`
	RevokedAt   *time.Time `json:"revoked_at,omitempty" gorm:"index"`
	LastUsedAt  *time.Time `json:"last_used_at,omitempty"`
	CreatedAt   time.Time  `json:"created_at" gorm:"autoCreateTime"`
	UpdatedAt   time.Time  `json:"updated_at" gorm:"autoUpdateTime"`
}

CLIToken 保存 CLI 令牌的不可逆信息，不保存令牌原文。 CLIToken stores irreversible token data and never stores the plaintext token.

func (CLIToken) TableName 

func (CLIToken) TableName() string

TableName 指定 CLI 令牌表名。 TableName specifies the CLI token table name.

type CLITokenIssue 

type CLITokenIssue struct {
	Token     string    `json:"token"`
	ExpiresAt time.Time `json:"expires_at"`
}

CLITokenIssue 是创建令牌后仅返回一次的结果。 CLITokenIssue is returned once when a token is created.

func IssueCLIToken 

func IssueCLIToken(database *gorm.DB, user *User, expiresIn string, now time.Time) (*CLITokenIssue, error)

IssueCLIToken 校验用户并生成随机令牌，只把哈希和元数据写入数据库。 IssueCLIToken validates the user and stores only a hash and metadata.

type ErrorResponse 

type ErrorResponse struct {
	ErrorMsg string      `json:"error_msg"`
	Data     interface{} `json:"data"`
}

错误响应

type LoginRequest 

type LoginRequest struct {
	Username string `json:"username" binding:"required"`
	Password string `json:"password" binding:"required"`
}

LoginRequest 登录请求

type LoginResponse 

type LoginResponse struct {
	ErrorMsg string      `json:"error_msg"`
	Data     interface{} `json:"data"`
}

LoginResponse 登录响应

type LogoutResponse 

type LogoutResponse struct {
	ErrorMsg string      `json:"error_msg"`
	Data     interface{} `json:"data"`
}

LogoutResponse 登出响应

type UpdateProfileRequest 

type UpdateProfileRequest struct {
	Email    string `json:"email" binding:"omitempty,max=255"`
	Language string `json:"language" binding:"omitempty,oneof=zh en"`
}

UpdateProfileRequest 更新当前登录用户的个人信息请求。

type UpdateProfileResponse 

type UpdateProfileResponse struct {
	ErrorMsg string    `json:"error_msg"`
	Data     *UserInfo `json:"data"`
}

UpdateProfileResponse 更新当前登录用户的个人信息响应。

type User 

type User struct {
	ID           uint64    `json:"id" gorm:"primaryKey;autoIncrement"`
	Username     string    `json:"username" gorm:"size:255;unique;not null"`
	PasswordHash string    `json:"-" gorm:"column:password_hash;size:255"` // 密码哈希，OAuth 用户可为空
	Nickname     string    `json:"nickname" gorm:"size:255"`
	Email        string    `json:"email" gorm:"size:255;index"`
	Language     string    `json:"language" gorm:"size:8;default:zh"`
	AvatarURL    string    `json:"avatar_url" gorm:"column:avatar_url;size:255"` // 头像 URL
	OAuthID      string    `json:"oauth_id" gorm:"size:255;index"`               // OAuth 提供商 ID，格式: provider:id
	IsActive     bool      `json:"is_active" gorm:"default:true"`
	IsAdmin      bool      `json:"is_admin" gorm:"default:false"`
	LastLoginAt  time.Time `json:"last_login_at"`
	CreatedAt    time.Time `json:"created_at" gorm:"autoCreateTime"`
	UpdatedAt    time.Time `json:"updated_at" gorm:"autoUpdateTime"`
}

User 用户模型 用于存储系统用户信息，支持用户名密码认证和 OAuth 认证

func FindByID 

func FindByID(db *gorm.DB, id uint64) (*User, error)

FindByID 根据 ID 查找用户

func FindByOAuthID 

func FindByOAuthID(db *gorm.DB, oauthID string) (*User, error)

FindByOAuthID 根据 OAuth ID 查找用户

func FindByUsername 

func FindByUsername(db *gorm.DB, username string) (*User, error)

FindByUsername 根据用户名查找用户

func GetUserFromContext 

func GetUserFromContext(c *gin.Context) *User

GetUserFromContext 从 Gin 上下文获取用户信息

func (*User) CheckPassword 

func (u *User) CheckPassword(password string) bool

CheckPassword 验证密码是否正确 使用 bcrypt 算法比较密码哈希

func (*User) Create 

func (u *User) Create(db *gorm.DB) error

Create 创建新用户

func (*User) IsValidBcryptHash 

func (u *User) IsValidBcryptHash() bool

IsValidBcryptHash 检查密码哈希是否为有效的 bcrypt 哈希

func (*User) SetPassword 

func (u *User) SetPassword(password string, cost int) error

SetPassword 设置用户密码 使用 bcrypt 算法对密码进行哈希处理 cost 参数指定 bcrypt 的计算成本，如果为 0 则使用默认值

func (User) TableName 

func (User) TableName() string

TableName 指定表名 使用 auth_users 避免与 oauth.User 的 users 表冲突

func (*User) ToUserInfo 

func (u *User) ToUserInfo() *UserInfo

ToUserInfo 将 User 转换为 UserInfo

func (*User) UpdateLastLogin 

func (u *User) UpdateLastLogin(db *gorm.DB) error

UpdateLastLogin 更新最后登录时间

type UserInfo 

type UserInfo struct {
	ID          uint64    `json:"id"`
	Username    string    `json:"username"`
	Nickname    string    `json:"nickname"`
	Email       string    `json:"email"`
	Language    string    `json:"language"`
	AvatarURL   string    `json:"avatar_url"`
	IsActive    bool      `json:"is_active"`
	IsAdmin     bool      `json:"is_admin"`
	LastLoginAt time.Time `json:"last_login_at"`
	CreatedAt   time.Time `json:"created_at"`
}

UserInfo 用户信息（用于 API 响应，不包含敏感信息）

type UserInfoResponse 

type UserInfoResponse struct {
	ErrorMsg string    `json:"error_msg"`
	Data     *UserInfo `json:"data"`
}

UserInfoResponse 用户信息响应

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.