# admuxplus

**Repository Path**: ad-united/admuxplus

## Basic Information

- **Project Name**: admuxplus
- **Description**: No description available
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-08
- **Last Updated**: 2025-12-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ADMUX - ADX广告交易系统

[![Go Version](https://img.shields.io/badge/Go-1.25-blue.svg)](https://golang.org/dl/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![OpenRTB](https://img.shields.io/badge/Protocol-OpenRTB%202.5-orange.svg)](https://iabtechlab.com/openrtb/)

## 📖 项目简介

ADMUX 是一个基于 Go 语言开发的高性能 ADX (Ad Exchange) 广告交易系统，支持实时竞价 (RTB)，采用微服务架构设计。系统实现了完整的广告投放流程，包括竞价请求处理、DSP 竞价广播、响应排序与选择、事件追踪等核心功能。

### 核心特性

- 🚀 **高性能**：毫秒级响应，支持高并发竞价
- 🔄 **实时竞价**：完整的 OpenRTB 2.5 协议支持
- 📡 **并发广播**：智能 DSP 竞价广播与结果聚合
- 🎯 **精准定向**：多维度定向引擎（用户画像、设备、上下文）
- 📊 **实时监控**：集成 Prometheus 监控与告警
- 🛡️ **高可用**：熔断、降级、重试机制
- 🔍 **事件追踪**：完整的曝光、点击、转化事件追踪

## 🏗️ 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                      接入层                                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  SSP Adapter │  │  SSP Adapter │  │  SSP Adapter │      │
│  │   (快手)     │  │   (小米)     │  │   (巨量)     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────────┐
│                   ADX Server (竞价引擎核心)                   │
│  1. 请求验证与特征补全    2. DSP定向(Targeting)             │
│  3. 并发竞价广播         4. 候选过滤(Filtering)             │
│  5. 排序与选择(Ranking)  6. 响应打包(Packing)              │
└─────────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────────┐
│                     竞价执行层                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ DSP bidder  │  │ DSP bidder  │  │ DSP bidder  │      │
│  │     A       │  │     B       │  │     C       │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
```

## 📁 项目结构

```
admux/
├── golang/                   # Go 后端服务统一目录
│   ├── cmd/                  # 各服务入口文件
│   │   ├── adx_engine/       # ADX 引擎服务 ⭐
│   │   ├── dsp_engine/       # DSP 引擎服务
│   │   └── media_mgr/        # 媒体管理服务
│   ├── internal/             # 内部包，不对外暴露
│   │   ├── adx_engine/       # ADX 引擎实现
│   │   │   ├── adxserver/    # HTTP 服务层
│   │   │   ├── adxcore/      # 竞价核心逻辑
│   │   │   ├── sspadapter/   # SSP 适配器
│   │   │   ├── dspbidder/    # DSP 竞价器
│   │   │   └── config/       # 配置管理
│   │   ├── dsp_engine/       # DSP 引擎实现
│   │   └── event_tracking/   # 事件追踪服务
│   └── pkg/                  # 项目内可复用包
│       ├── protogen/         # Protobuf 生成的代码
│       ├── utils/            # 工具函数
│       ├── logger/           # 日志组件
│       └── config/           # 配置组件
├── web/                      # 前端应用
│   ├── admin/                # React 管理端
│   ├── customer/             # React 用户端
│   └── shared/               # 前端共享代码
├── shared/                   # 跨栈共享代码
│   ├── proto/                # gRPC 协议定义
│   └── types/                # TypeScript 类型定义
├── infrastructure/           # 基础设施代码
│   ├── docker/               # Docker 配置
│   ├── k8s/                  # Kubernetes 配置
│   └── terraform/            # Terraform 基础设施代码
├── docs/                     # 项目文档
│   ├── ADX_SYSTEM_TECHNICAL_DESIGN.md  # 系统设计文档
│   └── project_layout.md     # 项目布局指南
├── scripts/                  # 脚本文件
└── tools/                    # 开发和运维工具
```

## 🚀 快速开始

### 环境要求

- **Go**: 1.24+ (推荐 1.25)
- **Docker**: 20.10+
- **Make**: 3.8+

### 安装与运行

#### 1. 克隆项目

```bash
git clone https://github.com/echoface/admux.git
cd admux
```

#### 2. 安装依赖

```bash
go mod download
```

#### 3. 配置环境

创建配置文件：

```bash
cp config/dev.yaml.example config/dev.yaml
# 编辑配置文件
vim config/dev.yaml
```

#### 4. 构建服务

```bash
# 构建所有服务
make build

# 或仅构建 ADX 引擎
make build-adx
```

#### 5. 运行服务

```bash
# 启动 ADX 引擎服务
make run-adx

# 或直接运行
cd golang/cmd/adx_engine
go run main.go
```

#### 6. 验证服务

```bash
# 健康检查
curl http://localhost:8080/health

# 查看指标
curl http://localhost:8080/metrics

# 测试竞价接口
curl -X POST http://localhost:8080/bid/rtb/v1 \
  -H "Content-Type: application/json" \
  -d @testdata/bid_request.json
```

## 📡 API 接口

### 核心端点

| 方法 | 路径 | 描述 |
|------|------|------|
| `GET` | `/` | 服务状态检查 |
| `GET` | `/health` | 健康检查 |
| `GET` | `/health/live` | 存活探针 |
| `GET` | `/health/ready` | 就绪探针 |
| `GET` | `/metrics` | Prometheus 指标 |
| `POST` | `/bid/rtb/v1` | OpenRTB 竞价接口 |
| `POST` | `/bid/kuaishou` | 快手 SSP 竞价接口 |

### 请求示例

**OpenRTB 竞价请求:**

```bash
curl -X POST http://localhost:8080/bid/rtb/v1 \
  -H "Content-Type: application/json" \
  -d '{
    "id": "test-request-123",
    "imp": [{
      "id": "imp-1",
      "banner": {
        "w": 300,
        "h": 250
      }
    }],
    "device": {
      "ua": "Mozilla/5.0",
      "ip": "192.168.1.1"
    },
    "user": {
      "id": "user-123"
    }
  }'
```

## 🛠️ 开发指南

### 项目布局

项目采用标准的 Go 项目布局：
- `cmd/`: 应用入口
- `internal/`: 私有业务逻辑
- `pkg/`: 可复用的公共包

详细说明请参考 [docs/project_layout.md](docs/project_layout.md)

### 常用命令

```bash
# 生成 protobuf 代码
make proto

# 运行测试
make test

# 运行集成测试
make test-integration

# 代码格式化
make fmt

# 代码静态检查
make lint

# 清理生成文件
make clean
```

### 添加新功能

1. **定义协议** (如需 API 变更)
   ```bash
   # 在 shared/proto/ 中定义 .proto 文件
   # 然后运行
   make proto
   ```

2. **实现业务逻辑**
   ```bash
   # 在 golang/internal/ 中实现
   ```

3. **创建服务入口** (如需新服务)
   ```bash
   # 在 golang/cmd/ 中创建 main.go
   ```

4. **编写测试**
   ```bash
   # 确保新功能包含单元测试
   ```

详细开发流程请参考 [docs/project_layout.md](docs/project_layout.md)

## 📚 技术文档

- [ADX 系统技术设计](docs/ADX_SYSTEM_TECHNICAL_DESIGN.md) - 完整的技术方案与架构设计
- [项目布局指南](docs/project_layout.md) - 项目结构与开发规范
- [BIDDER TARGETING 设计](golang/docs/BIDDER_TARGETING_DESIGN.md) - DSP 定向引擎设计
- [广播逻辑设计](golang/docs/ADX_ENGINE_BROADCAST_LOGIC_DESIGN.md) - 并发竞价广播机制

## 🔧 技术栈

| 组件 | 技术选型 | 说明 |
|------|---------|------|
| **开发语言** | Go 1.24+ | 高性能、并发友好 |
| **Web 框架** | Gin | 高性能 HTTP 框架 |
| **协议标准** | OpenRTB 2.5 | 广告行业标准 |
| **监控** | Prometheus | 指标收集与告警 |
| **日志** | Zerolog/Zap | 结构化日志 |
| **配置** | Viper | 配置管理，支持热更新 |
| **测试** | Testify | Go 测试框架 |
| **序列化** | Protobuf | 高效的序列化协议 |
| **对象存储** | MinIO/S3 | 素材存储 |
| **缓存** | Redis | 分布式缓存 |
| **数据库** | MongoDB/PostgreSQL | 文档/关系型数据库 |

## 🎯 核心模块

### 1. ADX 引擎 (`golang/internal/adx_engine/`)

**核心组件:**
- **adxserver**: HTTP 服务层，处理竞价请求
- **adxcore**: 竞价核心逻辑，包括管道处理、DSP 广播、排序选择
- **sspadapter**: SSP 适配器，支持多平台（快手、小米、巨量等）
- **dspbidder**: DSP 竞价器，并发请求与结果聚合

**关键特性:**
- 异步并发竞价 (Goroutine Pool)
- 超时控制 (100-300ms per DSP)
- 熔断机制 (Circuit Breaker)
- 重试策略 (指数退避)

### 2. 配置管理

支持多环境配置:
- `dev.yaml` - 开发环境
- `test.yaml` - 测试环境
- `staging.yaml` - 预发布环境
- `prod.yaml` - 生产环境

### 3. 监控体系

集成 Prometheus 指标:
- 请求量 (QPS)
- 响应时间 (Latency)
- 错误率 (Error Rate)
- 竞价成功率 (Bid Win Rate)

## 📊 性能指标

| 指标 | 目标值 | 监控路径 |
|------|--------|----------|
| **ADX 响应时间** | < 200ms (P99) | `/metrics` |
| **并发 QPS** | > 50,000 | Prometheus |
| **系统可用性** | > 99.99% | 健康检查 |
| **事件延迟** | < 5s | 实时计算 |

## 🐳 Docker 部署

```bash
# 构建镜像
docker build -t admux/adx-engine:latest .

# 运行容器
docker run -d \
  -p 8080:8080 \
  -v $(PWD)/config:/app/config \
  --name admux-adx \
  admux/adx-engine:latest
```

使用 Docker Compose:

```bash
cd infrastructure/docker
docker-compose up -d
```

## 🧪 测试

### 运行单元测试

```bash
# 运行所有测试
make test

# 运行特定包测试
go test ./internal/adx_engine/...

# 生成测试覆盖率报告
make test-coverage
```

### 性能测试

```bash
# 运行基准测试
go test -bench=. ./internal/adx_engine/...

# 使用工具进行压测
cd tools/benchmark
go run . --qps=1000 --duration=60s
```

## 🤝 贡献指南

我们欢迎所有形式的贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 代码规范

- 遵循 [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
- 所有新代码必须包含单元测试
- 使用 `make fmt` 格式化代码
- 保持测试覆盖率 > 80%

## 📝 更新日志

### v1.0.0 (2025-12-08)
- ✨ 初始版本发布
- 🚀 ADX 引擎核心功能
- 📡 OpenRTB 2.5 协议支持
- 🔄 并发竞价广播机制
- 📊 Prometheus 监控集成
- 🛡️ 熔断与重试机制

## 📄 许可证

本项目基于 MIT 许可证开源 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 👥 团队

- **架构师**: [@echoface](https://github.com/echoface)
- **开发团队**: ADMUX Core Team

## 📧 联系我们

- 项目 Issues: [GitHub Issues](https://github.com/echoface/admux/issues)
- 讨论交流: [GitHub Discussions](https://github.com/echoface/admux/discussions)
- 商务合作: contact@admux.com

## 🙏 致谢

感谢以下开源项目:

- [Gin](https://github.com/gin-gonic/gin) - HTTP Web 框架
- [Prometheus](https://github.com/prometheus/prometheus) - 监控系统
- [OpenRTB](https://iabtechlab.com/openrtb/) - 广告行业协议标准

---

<div align="center">

**[⬆ 回到顶部](#admux---adx广告交易系统)**

Made with ❤️ by ADMUX Team

</div>