快速开始

本指南聚焦“怎么用”:

如何导入 SDK
如何注册 SDK 路由
如何给业务接口加鉴权

1. 安装依赖

go get github.com/phalanx-labs/beacon-sso-sdk

2. 配置环境变量

必填: OAuth2 + 基础能力

SSO_CLIENT_ID=your-client-id
SSO_CLIENT_SECRET=your-client-secret
SSO_REDIRECT_URI=http://localhost:8080/api/oauth/callback
SSO_ENDPOINT_AUTH_URI=https://sso.example.com/oauth/authorize
SSO_ENDPOINT_TOKEN_URI=https://sso.example.com/oauth/token
SSO_ENDPOINT_USERINFO_URI=https://sso.example.com/oauth/userinfo
SSO_ENDPOINT_INTROSPECTION_URI=https://sso.example.com/oauth/introspect
SSO_ENDPOINT_REVOCATION_URI=https://sso.example.com/oauth/revoke

必填: gRPC 能力（账户/用户/商户接口）

SSO_GRPC_HOST=sso.example.com
SSO_GRPC_PORT=5566

可选: 使用 Well-Known 自动发现端点

SSO_WELL_KNOWN_URI=https://sso.example.com/.well-known/openid-configuration

配置了 SSO_WELL_KNOWN_URI 后，可由元数据自动发现 OAuth 端点。

3. 启动并挂载路由（完整示例）

package main

import (
	"context"

	xConsts "github.com/bamboo-services/bamboo-base-go/defined/context"
	xReg "github.com/bamboo-services/bamboo-base-go/major/register"
	xRegNode "github.com/bamboo-services/bamboo-base-go/major/register/node"
	xResult "github.com/bamboo-services/bamboo-base-go/major/result"
	"github.com/gin-gonic/gin"
	"github.com/redis/go-redis/v9"
	bSdkMiddleware "github.com/phalanx-labs/beacon-sso-sdk/middleware"
	bSdkRoute "github.com/phalanx-labs/beacon-sso-sdk/route"
	bSdkStartup "github.com/phalanx-labs/beacon-sso-sdk/startup"
	"gorm.io/gorm"
)

func main() {
	// 1) 初始化注册节点（数据库、Redis + SDK 配置）
	nodes := []xRegNode.RegNodeList{
		{Key: xConsts.DatabaseKey, Node: initDatabase},
		{Key: xConsts.RedisClientKey, Node: initRedis},
	}
	nodes = append(nodes, bSdkStartup.NewStartupConfig()...)

	reg := xReg.Register(context.Background(), nodes)

	// 2) 注册业务路由
	reg.Serve.GET("/api/status", func(c *gin.Context) {
		xResult.SuccessHasData(c, "服务正常", gin.H{
			"status": "running",
		})
	})

	// 3) 挂载 SDK 路由（登录、账户、用户）
	sdkRoute := bSdkRoute.NewRoute(reg.Init.Ctx)
	sdkRoute.OAuthRouter(reg.Serve.Group("/api"))
	sdkRoute.AccountRouter(reg.Serve.Group("/api"))
	sdkRoute.UserRouter(reg.Serve.Group("/api"))

	// 4) 给你的业务路由加鉴权中间件
	protected := reg.Serve.Group("/api/private")
	protected.Use(bSdkMiddleware.CheckAuth(reg.Init.Ctx))
	protected.GET("/profile", func(c *gin.Context) {
		token, _ := c.Get("authorization")
		xResult.SuccessHasData(c, "访问成功", gin.H{"token": token})
	})

	// 5) 启动服务
	_ = reg.Serve.Run(":8080")
}

// 数据库初始化节点
func initDatabase(ctx context.Context) (any, error) {
	// TODO: 替换为你的数据库初始化逻辑
	var db *gorm.DB
	return db, nil
}

// Redis 初始化节点
func initRedis(ctx context.Context) (any, error) {
	// TODO: 替换为你的 Redis 初始化逻辑
	var rdb *redis.Client
	return rdb, nil
}

4. SDK 默认路由（按上面示例前缀 `/api`）

路由组	方法	路径	用途
OAuth2	GET	`/api/oauth/login`	跳转到 SSO 登录
OAuth2	GET	`/api/oauth/callback`	处理回调，交换令牌
OAuth2	POST	`/api/oauth/logout`	注销
Account	POST	`/api/account/register/email`	邮箱注册
Account	POST	`/api/account/login/password`	密码登录
Account	POST	`/api/account/token/refresh`	刷新令牌
Account	POST	`/api/account/password/change`	修改密码（需登录）
Account	POST	`/api/account/token/revoke`	注销令牌（需登录）
User	GET	`/api/user/userinfo`	获取当前用户（需登录）
User	GET	`/api/user/by-id`	按用户 ID 查询（需登录，query: `user_id`）

5. 验证接入

启动服务后，访问以下地址测试：

GET http://localhost:8080/api/status（服务存活）
GET http://localhost:8080/api/oauth/login（跳转 SSO）
带 Authorization: Bearer <token> 请求 GET /api/private/profile（验证鉴权中间件）

下一步

环境变量配置 - 完整配置项说明
认证检查中间件 - 保护你的业务接口
OAuth2 子系统 - 登录流程和 Token 相关接口
gRPC 服务 - 账户、用户、商户能力

快速开始

On this page