bsm-infra/full
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
full/module/base/passport
History

README.md

BSM 通行证服务

基于 Go、gRPC 和 Protocol Buffers 构建的综合用户认证和账户管理服务。

🚀 功能特性

  • 用户认证: 支持密码登录和验证码登录
  • 账户管理: 完整的用户资料和数据管理
  • 标签系统: 用户标签和分类管理
  • KYC 集成: 与 Jumio 的身份验证集成
  • 密码找回: 安全的密码重置功能
  • 统计分析: 用户活动和参与度指标
  • gRPC 和 REST API: 通过 gRPC-Gateway 支持双协议
  • 微服务架构: 可扩展和可维护的设计
  • 数据库支持: 兼容 PostgreSQL 和 MySQL
  • 缓存: Redis 集成以优化性能
  • 服务发现: Etcd 集成用于微服务协调

📋 系统要求

  • Go 1.26.5 或更高版本
  • PostgreSQL 或 MySQL 数据库
  • Redis 服务器
  • Etcd（微服务模式需要）
  • Protocol Buffers 编译器 (protoc)
  • Buf CLI（用于 proto 管理）

🛠️ 安装部署

  1. 克隆仓库

    git clone bsm/full/module/base/passport
cd passport

  2. 安装依赖

    go mod download

  3. 安装开发工具

    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest

  4. 生成 Protocol Buffer 文件

    # Buf 配置已移除；请使用团队约定的 protoc 生成命令

⚙️ 配置说明

服务使用位于 etc/ 目录下的 YAML 配置文件：

  • passport_dev.yaml - 开发环境
  • passport_prod.yaml - 生产环境
  • passport_test.yaml - 测试环境

配置结构

Service: passport
Port: 12426

# 数据库配置
Databases:
  Driver: postgres  # 或 mysql
  Source:
    - host=localhost user=postgres password=yourpassword dbname=bsm_dev port=5432 sslmode=disable TimeZone=Asia/Shanghai

# Redis 缓存
Cache: redis://null:yourpassword@localhost:6379/

# 微服务设置
MicroService: 
  Enable: false
  Anonymous:
    - passport.ping.hello

# 微信集成
WeChatConf:
  AppID: your_wechat_app_id
  AppSecret: your_wechat_app_secret

# KYC 配置
Kyc:
  Provider: jumio
  BaseUrl: https://api.jumio.com
  ApiSecret: your_api_secret
  ApiToken: your_api_token
  ApiArgs: additional_args

# 网关设置
Gateway:
  Enable: true
  Port: 12425

# JWT Token 配置
Token:
  Prefix: "/token/"
  Expire: 86400  # 24小时（秒）

# 服务密钥
SecretKey: your_32_character_secret_key_here

🚀 运行服务

开发模式

  1. 启动主服务

    go run cmd/main/main.go

  2. 访问服务

    • gRPC: localhost:12426
    • REST API: localhost:12425
    • Swagger UI: http://localhost:12425/passport.swagger.json

生产环境部署

  1. 构建二进制文件

    go build -o passport cmd/main/main.go

  2. 使用生产配置运行

    ./passport -env=prod

📚 API 文档

gRPC 服务

服务提供以下 gRPC 服务：

账户服务 (Account Service)

  • Get() - 获取完整用户信息
  • SetData() - 更新用户资料数据
  • SetPassword() - 修改用户密码
  • TagCreate() - 创建用户标签
  • TagRemove() - 删除用户标签
  • Statistics() - 获取用户统计信息

登录服务 (Login Service)

  • Pwd() - 密码登录
  • Code() - 验证码登录

注册服务 (Register Service)

  • Code() - 发送注册验证码
  • Pwd() - 密码注册
  • Do() - 完成注册流程

找回密码服务 (Forget Service)

  • Verify() - 验证密码重置请求
  • Reset() - 重置密码

KYC 服务 (KYC Service)

  • Request() - 发起 KYC 验证
  • JumioCallback() - 处理 KYC 提供商回调

REST API

所有 gRPC 服务通过 gRPC-Gateway 自动暴露为 REST 端点：

  • POST /v1/account - 获取用户账户
  • POST /v1/account/data - 更新用户数据
  • POST /v1/account/password - 修改密码
  • POST /v1/login/pwd - 密码登录
  • POST /v1/login/code - 验证码登录
  • POST /v1/register - 用户注册

🏗️ 系统架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   gRPC 客户端   │    │   REST 客户端   │    │   Web 客户端    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  gRPC 网关      │
                    └─────────────────┘
                                 │
                    ┌─────────────────┐
                    │  gRPC 服务器    │
                    └─────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   PostgreSQL    │    │      Redis      │    │      Etcd       │
│     MySQL       │    │      缓存       │    │    服务发现     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🔧 开发指南

项目结构

passport/
├── cmd/                    # Application entry points
│   ├── main/              # Main service
│   └── cli/               # CLI tools
├── internal/              # Private application code
│   ├── config/           # Configuration management
│   ├── impl/             # Service implementations
│   ├── logic/            # Business logic
│   ├── models/           # Database models
│   ├── server/           # gRPC server setup
│   └── vars/             # Constants and variables
├── pb/                   # Generated Protocol Buffer files
├── proto/                # Protocol Buffer definitions
├── etc/                  # Configuration files
├── swagger/              # OpenAPI/Swagger documentation
├── scripts/              # Build and deployment scripts
└── test/                 # Test files and examples

Adding New Features

  1. Define Protocol Buffers

    # Edit proto files in proto/
vim proto/your_service.proto

  2. Generate Code

    # Buf 配置已移除；请使用团队约定的 protoc 生成命令

  3. Implement Business Logic

    # Add logic in internal/logic/
vim internal/logic/your_service/your_method.go

  4. Register Service

    # Update server registration in internal/server/
vim internal/server/new.go

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Test specific package
go test ./internal/logic/login/

Code Generation

# Generate Protocol Buffer files
# Buf 配置已移除；请使用团队约定的 protoc 生成命令

# Lint proto files
# 使用团队约定的 proto lint 工具

# Format proto files
# 使用团队约定的 proto 格式化工具

🔒 Security Features

  • Password Hashing: bcrypt with salt for secure password storage
  • JWT Tokens: Secure token-based authentication
  • Input Validation: Comprehensive request validation
  • SQL Injection Protection: Parameterized queries with GORM
  • Rate Limiting: Built-in request rate limiting
  • CORS Support: Configurable cross-origin resource sharing

📊 Monitoring & Observability

  • Structured Logging: JSON-formatted logs with different levels
  • Metrics: Built-in metrics collection
  • Health Checks: Service health monitoring endpoints
  • Distributed Tracing: APM integration support
  • Performance Monitoring: Request/response time tracking

🐳 Docker Support

# Build stage
FROM golang:1.26.5-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod download
RUN go build -o passport cmd/main/main.go

# Runtime stage
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/passport .
COPY --from=builder /app/etc ./etc
COPY --from=builder /app/swagger ./swagger
CMD ["./passport"]

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Code Style

  • Follow Go conventions and best practices
  • Use gofmt for code formatting
  • Add comments for exported functions
  • Write tests for new features
  • Update documentation as needed

📝 License

This project is proprietary software. All rights reserved.

🆘 Support

For support and questions:

  • Create an issue in the repository
  • Contact the development team
  • Check the documentation in /docs

🔄 Version History

  • v1.0.0 - Initial release with core authentication features
  • v1.1.0 - Added KYC integration and tag system
  • v1.2.0 - Enhanced security and performance optimizations
  • Current - Go 1.26.5 compatibility and bug fixes

🚀 Roadmap

  • OAuth2 integration
  • Multi-factor authentication
  • Advanced user analytics
  • Mobile SDK support
  • GraphQL API support
  • Kubernetes deployment manifests

Built with ❤️ by the BSM Development Team

Reference in New Issue View Git Blame Copy Permalink