# xiaoniu-registry

**Repository Path**: mrbread/xiaoniu-registry

## Basic Information

- **Project Name**: xiaoniu-registry
- **Description**: 使用golang语言实现一个简单的注册中心
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2022-05-16
- **Last Updated**: 2025-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xiaoniu-registry 菜牛注册中心

一个轻量级、高性能的微服务注册中心，使用 Go 语言开发。

## 功能特性

### 核心功能
- 🚀 **服务注册与发现**: 支持微服务实例的注册、注销和查询
- 💓 **健康检查**: 自动检测服务实例健康状态，支持心跳机制
- 🔄 **实例管理**: 支持手动上线/下线实例
- 📊 **监控面板**: 提供 Web 控制台和 REST API
- 📈 **系统监控**: 实时监控系统指标和性能数据

### 技术特性
- ⚡ **高性能**: 基于内存存储，响应速度快
- 🔒 **并发安全**: 使用读写锁保证数据一致性
- 💾 **数据持久化**: 支持数据备份和恢复
- 🛡️ **中间件支持**: 内置 CORS、日志、限流、恢复等中间件
- ⚙️ **配置管理**: 支持环境变量配置
- 🔧 **优雅关闭**: 支持优雅停机

## 快速开始

### 环境要求
- Go 1.16+
- 无其他外部依赖

### 安装运行

1. **克隆项目**
```bash
git clone <repository-url>
cd xiaoniu-registry
```

2. **编译运行**
```bash
go mod tidy
go run cmd/server.go
```

3. **访问控制台**
打开浏览器访问: http://localhost:8080

### 配置选项

通过环境变量配置服务:

```bash
# 服务器配置
export SERVER_HOST=0.0.0.0
export SERVER_PORT=8080
export SERVER_READ_TIMEOUT=30
export SERVER_WRITE_TIMEOUT=30

# 健康检查配置
export HEALTH_CHECK_INTERVAL=15
export HEALTH_CHECK_TIMEOUT=30

# 持久化配置
export PERSISTENCE_ENABLED=true
export PERSISTENCE_DATA_DIR=./data
export PERSISTENCE_BACKUP_DIR=./data/backup
export PERSISTENCE_INTERVAL=30

# 日志配置
export LOG_LEVEL=INFO
export LOG_FORMAT=text
```

## API 文档

### 服务管理

#### 获取服务列表
```http
GET /api/service/list
```

### 实例管理

#### 注册实例
```http
GET /api/instance/add?serviceName=user-service&ip=192.168.1.100&port=8080&weight=1
```

#### 删除实例
```http
GET /api/instance/delete?serviceName=user-service&ip=192.168.1.100&port=8080
```

#### 查询实例列表
```http
GET /api/instance/list?serviceName=user-service
```

#### 手动下线实例
```http
GET /api/instance/offline?serviceName=user-service&ip=192.168.1.100&port=8080
```

#### 手动上线实例
```http
GET /api/instance/online?serviceName=user-service&ip=192.168.1.100&port=8080
```

### 心跳管理

#### 发送心跳
```http
GET /api/beat?serviceName=user-service&ip=192.168.1.100&port=8080
```

### 监控端点

#### 健康检查
```http
GET /health
```

#### 详细状态
```http
GET /status
```

#### 系统指标
```http
GET /metrics
```

## 响应格式

所有 API 返回统一的 JSON 格式:

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

状态码说明:
- `200`: 成功
- `400`: 请求参数错误
- `404`: 资源不存在
- `500`: 服务器内部错误

## 架构设计

### 目录结构
```
xiaoniu-registry/
├── cmd/                    # 应用入口
│   └── server.go
├── internal/               # 内部包
│   ├── cache/             # 缓存层
│   ├── config/            # 配置管理
│   ├── heartbeat/         # 心跳处理
│   ├── html/              # Web 页面
│   ├── instance/          # 实例管理
│   ├── metrics/           # 监控指标
│   ├── middleware/        # 中间件
│   ├── persistence/       # 数据持久化
│   ├── response/          # 响应处理
│   ├── router/            # 路由管理
│   └── service/           # 服务管理
├── frontend/              # 前端资源
│   └── template/
└── data/                  # 数据目录
    └── backup/
```

### 核心组件

1. **缓存层 (cache)**: 基于内存的数据存储，使用读写锁保证并发安全
2. **健康检查**: 定时检查实例健康状态，自动清理不健康实例
3. **持久化**: 定期将数据保存到文件，支持服务重启后数据恢复
4. **监控**: 收集系统运行指标，提供监控面板
5. **中间件**: 提供 CORS、日志、限流、恢复等功能

## 使用场景

### 微服务架构
- 作为微服务注册中心，管理服务实例
- 支持服务发现和负载均衡
- 提供健康检查和故障转移

### 开发测试
- 本地开发环境的服务注册
- 测试环境的服务管理
- 服务依赖关系梳理

## 性能特点

- **内存存储**: 所有数据存储在内存中，读写性能极高
- **并发安全**: 使用读写锁，支持高并发访问
- **轻量级**: 无外部依赖，部署简单
- **低延迟**: 毫秒级响应时间

## 监控指标

系统提供丰富的监控指标:

- **请求统计**: 总请求数、心跳请求数、API 请求数
- **服务统计**: 服务总数、实例总数、健康实例数
- **系统信息**: 运行时间、内存使用、协程数量、GC 次数
- **组件状态**: 各组件健康状态

## 注意事项

1. **数据持久化**: 默认启用数据持久化，数据保存在 `./data` 目录
2. **健康检查**: 实例需要定期发送心跳，否则会被标记为不健康
3. **并发限制**: 内置简单的速率限制，防止恶意请求
4. **内存使用**: 所有数据存储在内存中，注意内存使用情况

## 贡献指南

欢迎提交 Issue 和 Pull Request 来改进项目。

## 许可证

本项目采用 MIT 许可证。