# switch-admin

**Repository Path**: fatzeng/switch-admin

## Basic Information

- **Project Name**: switch-admin
- **Description**: switch-admin是Switch项目的中央后端服务。它提供了一个强大的控制平面，用于管理特性开关、复杂的发布工作流程，并确保系统稳定性和可追溯性。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 26
- **Forks**: 0
- **Created**: 2025-07-17
- **Last Updated**: 2026-02-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Go语言, Gin, gorm

## README

# Switch: 动态特性开关与远程配置系统

<div align="center">

<img src="switch.svg" alt="Switch Logo" width="300">

**为现代应用开发打造的强大实时特性开关系统**

[![Go Version](https://img.shields.io/badge/Go-1.18+-blue.svg)](https://golang.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen.svg)](https://gitee.com/fatzeng/collections/413616)

[English](README.md) | [中文](README_zh.md)

</div>

---

## 🎯 什么是Switch？

**Switch是一个分布式实时特性管控平台**
，为企业级应用提供安全、高效的动态配置能力。它通过先进的WebSocket长连接架构和多驱动通信机制，实现了配置变更的毫秒级下发，让开发团队能够在不重启应用的情况下，精确控制功能发布、用户体验和系统行为。

### 🏗️ 核心架构优势

**1. 企业级通信架构**

- **WebSocket长连接框架** - 基于`switch-components/pc`的持久连接管理
- **多驱动支持** - Webhook、Kafka、长轮询三种通信模式
- **智能网络发现** - 自动适配NAT环境，解决复杂网络场景
- **分层确认机制** - 确保配置下发的可靠性和一致性

**2. 灵活的因子系统**

```go
// 不只是简单的true/false，而是基于复杂规则的智能决策
if _switch.IsOpen(ctx, "feature_enabled") {
    // 系统会根据配置的多维度因子（例如：用户属性、地理位置、时间窗口等）
    // 实时计算是否启用该功能
}
```

**3. 多租户管理体系**

- **租户隔离** - 完整的数据和权限隔离
- **环境管理** - 开发、测试、生产环境的独立配置搭配严格的配置推送制度
- **审批工作流** - 敏感变更的多级审批机制

## 系统架构

Switch生态系统由以下核心组件组成：

- **switch-admin**: 后端服务，负责管理配置和客户端通信
- **switch-frontend**: Web界面，用于配置管理
- **switch-sdk-go**: Go SDK，用于将开关集成到业务应用中形成客户端
- **switch-sdk-core**: 核心定义和接口
- **switch-components**: 通信和核心逻辑的实现
- **switch-client-demo**: 演示应用示例

---

# Switch-Admin: 后端管理服务

`switch-admin`是Switch项目的中央后端服务。它提供了一个强大的控制平面，用于管理特性开关、复杂的发布工作流程，并确保系统稳定性和可追溯性。

---

## ✨ 功能特性

- **多租户架构**: 支持多租户，具有完整的权限管理
- **实时通信**: 基于WebSocket与所有连接的客户端通信
- **多种通信模式**:
    - 拉取模式：客户端主动获取配置
    - 推送模式：服务器推送配置给客户端
    - Kafka模式：基于消息队列的分发
- **审批工作流**: 内置审批系统，用于敏感环境变更
- **环境管理**: 管理不同环境下的开关（开发、测试、生产），支持环境自定义
- **驱动配置**: 灵活的驱动系统，支持不同的通信模式
- **审计与追溯**: 完整的变更和操作审计追踪
- **客户端注册与信任**: 安全的客户端注册和信任管理系统

---

## 🏛️ 通信流程

![Switch Architecture](switch_architecture.svg)

### 通信过程详解：

Switch采用基于WebSocket的长连接架构，实现毫秒级的配置下发和实时通信。整个通信过程包含以下关键步骤：

#### 1. 连接建立阶段

```
客户端                    服务端
   |                        |
   |--- TCP连接建立 -------->|
   |                        |
   |<--- WebSocket升级响应 --|
   |                        |
```

- **客户端**: 发起TCP连接，通过HTTP协议进行WebSocket握手升级
- **服务端**: 处理WebSocket连接升级，建立持久化连接通道

#### 2. 连接初始化阶段

```
客户端                    服务端
   |                        |
   |--- 启动读写循环 -------->|
   |<--- 启动读写循环 --------|
   |                        |
   |<--- Say Hello ---------|
   |                        |
```

- **客户端**: 开启异步的读写循环，等待服务端的问候消息
- **服务端**: 开启异步的读写循环，主动发送"Say Hello"建立连接确认

#### 3. 身份认证阶段

```
客户端                    服务端
   |                        |
   |--- 处理Say Hello ------>|
   |                        |
   |--- 发送注册消息 -------->|
   |                        |
   |<--- 处理注册(受信) ------|
   |<--- 发送注册成功响应 -----|
   |                        |
```

- **客户端**: 解析服务端的问候消息，发送包含服务标识、版本、环境等信息的注册请求
- **服务端**: 验证客户端身份，建立信任关系，返回注册成功响应

#### 4. 配置同步阶段

```
客户端                    服务端
   |                        |
   |--- 处理注册响应 -------->|
   |                        |
   |--- 拉取驱动配置 -------->|
   |--- 拉取开关配置 -------->|
   |--- 拉取增量配置 -------->|
   |                        |
   |<--- 响应驱动配置 --------|
   |<--- 响应开关配置 --------|
   |<--- 响应增量配置 --------|
   |                        |
   |<--- 服务端等待后续请求----|
   |                        |
```

- **客户端**: 处理注册响应，获取驱动配置（Webhook/Kafka/长轮询），开启增量配置的监听，获取完整的开关配置
- **服务端**: 完成客户端注册，等待后续的业务请求

#### 5. 业务通信阶段

```
客户端                    服务端
   |                        |
   |                        |
   |<--- 推送增量配置 --------|
   |----- 返回响应 ---------->|
   |                        |
```

- **客户端**: 等待服务端发送的增量配置，并更新自己的驱动逻辑
- **服务端**: 获取到变更的驱动配置并推送给已连接的客户端

### 通信特点：

- **双向通信**: 支持客户端主动请求和服务端主动推送
- **多连接架构**: 三个独立的WebSocket连接，互不干扰：
    - **全量开关连接**: 承载完整的开关配置数据同步
    - **全量配置连接**: 承载完整的配置项数据同步
    - **增量开关连接**: 承载实时的开关变更推送
- **智能重连**: 自动处理网络异常和连接断开
- **消息确认**: 关键操作支持ACK确认机制
- **负载均衡**: 支持多实例部署和客户端负载分发
- **安全传输**: 支持TLS加密和身份认证

---

## 🚀 快速开始

### 前置条件

- **Go 1.18+** - 现代Go语言支持
- **数据库**: MySQL 8.0+ - 数据持久化
- **Kafka** (可选) - 消息队列支持

### 安装和运行

#### 1. 克隆仓库

```bash
git clone https://gitee.com/fatzeng/switch-admin.git ./switch-admin
cd switch-admin
```

#### 2. 配置服务

编辑 `configs/config.yaml` 设置数据库连接、通知驱动（Kafka/Webhook）和其他服务设置。

详细的配置说明请参见：`configs/switch-config.yaml`

```bash
vim configs/config.yaml
```

#### 3. 安装依赖

```bash
go mod tidy
```

#### 4. 运行应用

```bash
go run cmd/server/main.go
```

服务将启动，自动运行数据库迁移，并初始化数据（包括默认的 `admin`/`admin` 用户、权限、默认因子、配置等）。

---

## 🔧 核心概念：发布工作流

为了确保稳定性和可追溯性，`switch-admin` 采用结构化的发布工作流，而非简单的增删改查操作。该工作流基于四个关键模型：

1. **`PublishRequest`**: 表示变更开关的*意图*。它将完整的期望配置捕获为JSON对象。
2. **`SwitchSnapshot`**: 开关在特定时间点配置的不可变记录。它作为实时状态的基准。
3. **`ApprovalForm`**: 当变更针对受保护环境时生成的请求。只有在获得批准后，变更才能继续。
4. **`递进式的发布流程`**: 开关的推送必须遵循配置的环境发布顺序递进式推送，保证开关在各环境下的一致性。

这个工作流保证每个变更都是有意的、可审计的和安全的。

---

## 📁 项目结构

```
switch-admin/
├── cmd/
│   └── server/                     # 应用入口点
├── configs/                        # 服务配置文件
├── info/                           # 用户信息相关
├── internal/
│   ├── admin_driver/               # 数据库和外部服务驱动
│   ├── admin_model/                # 数据库实体模型 (GORM)
│   ├── api/                        # HTTP处理器、路由和中间件 (Gin)
│   │   ├── controller/             # 控制器层
│   │   └── middleware/             # 中间件
│   ├── config/                     # 配置管理
│   ├── dto/                        # 数据传输对象
│   ├── notifier/                   # 客户端更新通知系统
│   ├── repository/                 # 数据访问对象 (DAO) 层
│   ├── service/                    # 业务逻辑层
│   ├── types/                      # 类型定义和错误处理
│   ├── utils/                      # 工具函数
│   └── ws/                         # WebSocket通信处理器
├── LICENSE                         # 许可证文件
├── README.md                       # 英文说明文档
├── README_zh.md                    # 中文说明文档
├── go.mod                          # Go模块定义
├── go.sum                          # Go模块依赖校验
└── switch.svg                      # 项目Logo
```

### 关键组件：

- **`api/`**: 前端交互的RESTful API端点
- **`service/`**: 开关管理、审批工作流的核心业务逻辑
- **`admin_model/`**: 租户、开关、环境等数据库模型
- **`repository/`**: 与GORM集成的数据访问层
- **`ws/`**: 实时客户端通信的WebSocket服务器
- **`notifier/`**: 配置更新的推送通知系统
- **`admin_driver/`**: 数据库驱动和外部服务集成

---

## 🤝 贡献指南

我们欢迎并感谢所有形式的贡献！无论是报告问题、提出功能建议、改进文档，还是提交代码，您的参与都将帮助 Switch 变得更好。

### 如何贡献

1. **Fork 本仓库**并创建您的特性分支
2. **编写代码**并确保遵循项目的代码规范
3. **添加测试**以覆盖您的更改
4. **提交 Pull Request**，并详细描述您的更改内容和动机

### 贡献类型

- 🐛 **Bug 修复**: 发现并修复问题
- ✨ **新功能**: 提出并实现新特性
- 📝 **文档改进**: 完善文档和示例
- 🎨 **代码优化**: 提升代码质量和性能
- 🧪 **测试增强**: 增加测试覆盖率

更多详细信息，请参阅我们的贡献指南文档。

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE)。