362 lines
10 KiB
Markdown
362 lines
10 KiB
Markdown
# 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. **克隆仓库**
|
||
```bash
|
||
git clone bsm/full/module/base/passport
|
||
cd passport
|
||
```
|
||
|
||
2. **安装依赖**
|
||
```bash
|
||
go mod download
|
||
```
|
||
|
||
3. **安装开发工具**
|
||
```bash
|
||
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 文件**
|
||
```bash
|
||
# Buf 配置已移除；请使用团队约定的 protoc 生成命令
|
||
```
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
服务使用位于 `etc/` 目录下的 YAML 配置文件：
|
||
|
||
- `passport_dev.yaml` - 开发环境
|
||
- `passport_prod.yaml` - 生产环境
|
||
- `passport_test.yaml` - 测试环境
|
||
|
||
### 配置结构
|
||
|
||
```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. **启动主服务**
|
||
```bash
|
||
go run cmd/main/main.go
|
||
```
|
||
|
||
2. **访问服务**
|
||
- gRPC: `localhost:12426`
|
||
- REST API: `localhost:12425`
|
||
- Swagger UI: `http://localhost:12425/passport.swagger.json`
|
||
|
||
### 生产环境部署
|
||
|
||
1. **构建二进制文件**
|
||
```bash
|
||
go build -o passport cmd/main/main.go
|
||
```
|
||
|
||
2. **使用生产配置运行**
|
||
```bash
|
||
./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**
|
||
```bash
|
||
# Edit proto files in proto/
|
||
vim proto/your_service.proto
|
||
```
|
||
|
||
2. **Generate Code**
|
||
```bash
|
||
# Buf 配置已移除；请使用团队约定的 protoc 生成命令
|
||
```
|
||
|
||
3. **Implement Business Logic**
|
||
```bash
|
||
# Add logic in internal/logic/
|
||
vim internal/logic/your_service/your_method.go
|
||
```
|
||
|
||
4. **Register Service**
|
||
```bash
|
||
# Update server registration in internal/server/
|
||
vim internal/server/new.go
|
||
```
|
||
|
||
### Testing
|
||
|
||
```bash
|
||
# Run all tests
|
||
go test ./...
|
||
|
||
# Run tests with coverage
|
||
go test -cover ./...
|
||
|
||
# Test specific package
|
||
go test ./internal/logic/login/
|
||
```
|
||
|
||
### Code Generation
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```dockerfile
|
||
# 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**
|