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

README.md

Initial Service

Go Version License Build Status

一个高性能、可扩展的微服务，基于 gRPC 和 HTTP Gateway 架构，提供应用配置管理、版本更新检查、国家地区数据等基础服务功能。

🚀 特性

  • 🔧 配置管理: 多应用、多平台配置参数管理
  • 📱 版本控制: 智能应用版本更新检查
  • 🌍 地理数据: 完整的全球国家和地区层级数据
  • 🏷️ 系统数据: 灵活的系统标签和分类管理
  • ⚡ 高性能: Redis缓存 + 数据库优化
  • 🐳 容器化: 完整的Docker支持
  • 📊 监控: 健康检查和APM集成
  • 🔒 安全: 完善的错误处理和输入验证

📋 目录

🚀 快速开始

环境要求

  • Go: 1.25.1+
  • PostgreSQL: 12+
  • Redis: 6+
  • Docker: 20.10+ (可选)
  • Protocol Buffers: 3.15+ (开发需要)

快速安装

# 克隆项目
git clone bsm/full/module/base/initial.git
cd initial

# 安装依赖
make deps

# 生成代码
make proto

# 构建应用
make build

# 运行服务
make run

Docker 快速启动

# 启动完整服务栈
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f initial-service

📁 项目结构

initial/
├── 📁 cmd/                     # 应用程序入口
│   ├── 📁 main/               # 主服务入口
│   └── 📁 cli/                # 命令行工具
├── 📁 internal/               # 内部包
│   ├── 📁 cache/              # 缓存服务
│   ├── 📁 config/             # 配置管理
│   ├── 📁 excode/             # 错误码定义
│   ├── 📁 impl/               # 实现层
│   ├── 📁 logic/              # 业务逻辑
│   │   ├── 📁 check/          # 检查相关逻辑
│   │   └── 📁 data/           # 数据相关逻辑
│   ├── 📁 models/             # 数据模型
│   └── 📁 server/             # 服务器实现
├── 📁 pb/                     # Protocol Buffers 生成代码
├── 📁 proto/                  # Protocol Buffers 定义文件
├── 📁 swagger/                # API 文档
├── 📁 scripts/                # 脚本和SQL文件
├── 📁 test/                   # 测试文件
├── 📁 etc/                    # 配置文件
├── 🐳 Dockerfile              # Docker 镜像构建
├── 🐳 docker-compose.yml      # Docker 编排
├── 🔧 Makefile               # 构建脚本
└── 📖 README.md              # 项目文档

🔧 核心功能

1. 检查服务 (Check Service)

🏥 健康检查 (Hello)

rpc Hello(Crc) returns (StatusReply)
  • 功能: 服务健康状态检查
  • 特性: 输入验证、状态监控
  • 用途: 负载均衡器健康检查、服务发现

⚙️ 配置管理 (Config)

rpc Config(ConfigRequest) returns (ConfigReply)
  • 功能: 多应用配置参数管理
  • 特性:
    • 支持多操作系统配置
    • 配置优先级处理
    • 自动去重机制
    • Redis缓存加速

🔄 版本更新 (Updates)

rpc Updates(CheckForUpdatesRequest) returns (CheckForUpdatesReply)
  • 功能: 智能版本更新检查
  • 特性:
    • 多平台支持 (Windows/Linux/macOS)
    • 架构区分 (amd64/arm64)
    • 版本比较算法
    • 更新文件管理

2. 数据服务 (Data Service)

🌍 国家数据 (Country)

rpc Country(Empty) returns (CountryReply)
  • 数据: ISO代码、货币、时区、电话区号
  • 特性: 启用状态过滤、排序优化
  • 缓存: 24小时长期缓存

🗺️ 地区数据 (Areas)

rpc Areas(AreasRequest) returns (AreasReply)
  • 功能: 层级地区数据查询
  • 层级: 国家 → 省/州 → 市 → 区/县 → 乡镇
  • 特性:
    • 按国家筛选
    • 层级深度控制
    • 拼音支持

🏷️ 系统数据 (Datas)

rpc Datas(Empty) returns (DatasReply)
  • 功能: 系统标签和分类管理
  • 用途: 下拉选项、分类标签、系统配置

📚 API文档

gRPC 服务

服务 方法 描述 端口
Check Hello 健康检查 12101
Check Config 配置获取 12101
Check Updates 更新检查 12101
Data Country 国家数据 12101
Data Areas 地区数据 12101
Data Datas 系统数据 12101

HTTP Gateway

端点 方法 描述
/initial.Check/Hello POST 健康检查
/initial.Check/Config POST 获取配置
/initial.Check/Updates POST 检查更新
/initial.Data/Country POST 国家列表
/initial.Data/Areas POST 地区数据
/initial.Data/Datas POST 系统数据

Swagger 文档

🛠️ 开发指南

开发环境设置

# 安装开发工具
make install-tools

# 设置Git钩子
git config core.hooksPath .githooks

# 启动开发模式
make dev

代码生成

# 生成 protobuf 代码
make proto

# 生成 Swagger 文档
make swagger

测试

# 运行所有测试
make test

# 测试覆盖率
make test-coverage

# gRPC 功能测试
make test-grpc

# 代码检查
make lint

# 安全扫描
make security

数据库管理

# 初始化数据库
make init-db

# 备份数据库
make backup-db

🚀 部署说明

Docker 部署

# 构建镜像
make docker-build

# 启动服务栈
make docker-compose-up

# 查看日志
make docker-compose-logs

# 停止服务
make docker-compose-down

生产环境部署

  1. 环境准备

    # 创建生产配置
cp etc/initial_dev.yaml etc/initial_prod.yaml
# 编辑生产配置...

  2. 数据库初始化

    # 执行SQL脚本
psql -h your-db-host -U postgres -d initial_db -f scripts/initial_country_202509081640.sql
psql -h your-db-host -U postgres -d initial_db -f scripts/initial_areas_202509081640.sql

  3. 服务启动

    # 构建生产版本
make build-linux

# 启动服务
./build/initial-linux-amd64

Kubernetes 部署

# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: initial-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: initial-service
  template:
    metadata:
      labels:
        app: initial-service
    spec:
      containers:
      - name: initial-service
        image: initial:latest
        ports:
        - containerPort: 12101
        - containerPort: 12102
        env:
        - name: SERVICE_ENV
          value: "production"

⚡ 性能优化

缓存策略

数据类型 缓存时间 策略
配置数据 10分钟 按应用+OS缓存
国家数据 24小时 全量缓存
地区数据 12小时 按国家缓存
系统数据 6小时 全量缓存

数据库优化

  • 索引优化: 关键字段建立复合索引
  • 查询优化: 使用 CASE WHEN 进行优先级排序
  • 连接池: 配置合适的连接池大小
  • 读写分离: 支持主从数据库配置

监控指标

# 服务健康检查
curl http://localhost:12102/health

# 性能指标
curl http://localhost:12102/metrics

🔧 配置说明

环境配置文件

# etc/initial_prod.yaml
Service: initial
Port: 12101

# 数据库配置
Databases:
  Driver: postgres
  Source:
    - host=db-host user=postgres password=*** dbname=initial_db port=5432 sslmode=require

# 缓存配置
Cache: redis://username:password@redis-host:6379/0

# 网关配置
Gateway:
  Enable: true
  Port: 12102

# 微服务配置
MicroService:
  Enable: true
  Registry: etcd://etcd-cluster:2379

# APM监控
APM:
  Platform: elasticAPM
  Endpoint: http://apm-server:8200

环境变量

变量名 描述 默认值
SERVICE_ENV 运行环境 development
CONFIG_FILE 配置文件路径 etc/initial_dev.yaml
LOG_LEVEL 日志级别 info
TZ 时区设置 Asia/Shanghai

🐛 故障排除

常见问题

  1. 服务启动失败

    # 检查端口占用
netstat -tlnp | grep :12101

# 检查配置文件
make lint

  2. 数据库连接失败

    # 测试数据库连接
psql -h your-db-host -U postgres -d initial_db -c "SELECT 1;"

  3. Redis连接失败

    # 测试Redis连接
redis-cli -h your-redis-host ping

日志分析

# 查看服务日志
tail -f logs/initial.log

# 查看错误日志
grep ERROR logs/initial.log

# 查看性能日志
grep "slow query" logs/initial.log

性能调优

  1. 内存优化

    # 监控内存使用
go tool pprof http://localhost:6060/debug/pprof/heap

  2. CPU优化

    # CPU性能分析
go tool pprof http://localhost:6060/debug/pprof/profile

📊 数据模型

核心表结构

initial_config - 配置表

CREATE TABLE initial_config (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(255) NOT NULL,
    app VARCHAR(255) NOT NULL,
    os VARCHAR(255) DEFAULT '',
    key TEXT DEFAULT '',
    value TEXT DEFAULT '',
    version BIGINT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

initial_apps - 应用版本表

CREATE TABLE initial_apps (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(255) NOT NULL,
    version VARCHAR(255) DEFAULT '',
    app VARCHAR(255) DEFAULT '',
    os VARCHAR(255) DEFAULT '',
    arch VARCHAR(255) DEFAULT '',
    summary TEXT DEFAULT '',
    files TEXT DEFAULT '',
    pubdate TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

initial_country - 国家表

CREATE TABLE initial_country (
    id SERIAL PRIMARY KEY,
    iso2 VARCHAR(2) UNIQUE NOT NULL,
    iso3 VARCHAR(3) UNIQUE NOT NULL,
    num_code VARCHAR(3),
    phone_code VARCHAR(10),
    currency VARCHAR(24) NOT NULL,
    currency_symbol VARCHAR(24) NOT NULL,
    region VARCHAR(24) NOT NULL,
    name VARCHAR(255) NOT NULL,
    local_name VARCHAR(255) NOT NULL,
    timezones TEXT,
    translations TEXT,
    enabled BOOLEAN DEFAULT true,
    sort_order INTEGER DEFAULT 0
);

🤝 贡献指南

开发流程

  1. Fork 项目
  2. 创建特性分支: git checkout -b feature/amazing-feature
  3. 提交更改: git commit -m 'Add amazing feature'
  4. 推送分支: git push origin feature/amazing-feature
  5. 创建 Pull Request

代码规范

  • 遵循 Go 官方代码规范
  • 使用 gofmt 格式化代码
  • 添加必要的注释和文档
  • 编写单元测试

提交规范

type(scope): description

[optional body]

[optional footer]

类型:

  • feat: 新功能
  • fix: 修复bug
  • docs: 文档更新
  • style: 代码格式
  • refactor: 重构
  • test: 测试
  • chore: 构建过程或辅助工具的变动

📄 许可证

本项目采用内部许可证，仅供 BSM 内部使用。

👥 团队

🔗 相关链接

⭐ 如果这个项目对你有帮助，请给它一个星标！

Made with ❤️ by BSM Team

Reference in New Issue View Git Blame Copy Permalink