refactor: reorganize modules and add Linux build tooling
This commit is contained in:
361
module/base/passport/README.md
Normal file
361
module/base/passport/README.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# 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**
|
||||
Reference in New Issue
Block a user