warden

README

Warden

🌐 Language / 语言: English | 中文

一个高性能的允许列表（AllowList）用户数据服务，支持本地和远程配置源的数据同步与合并。

Warden（看守者）—— 守护星门的看守者，决定谁可以通过，谁将被拒绝。正如 Stargate 的看守者守护着星际之门，Warden 守护着你的允许列表，确保只有授权用户能够通过。

📋 项目简介

Warden 是一个基于 Go 语言开发的轻量级 HTTP API 服务，主要用于提供和管理允许列表用户数据（手机号和邮箱）。该服务支持从本地配置文件和远程 API 获取数据，并提供了多种数据合并策略，确保数据的实时性和可靠性。

✨ 核心特性

• 🚀 高性能: 支持每秒 5000+ 请求，平均延迟 21ms
• 🔄 多数据源: 支持本地配置文件和远程 API 两种数据源
• 🎯 灵活策略: 提供 6 种数据合并模式（远程优先、本地优先、仅远程、仅本地等）
• ⏰ 定时更新: 基于 Redis 分布式锁的定时任务，自动同步数据
• 📦 容器化部署: 完整的 Docker 支持，开箱即用
• 📊 结构化日志: 使用 zerolog 提供详细的访问日志和错误日志
• 🔒 分布式锁: 使用 Redis 确保定时任务在分布式环境下不会重复执行

🏗️ 架构设计

Warden 采用分层架构设计，包含 HTTP 层、业务层和基础设施层。系统支持多数据源、多级缓存和分布式锁机制。

详细架构说明请参考：架构设计文档

📦 安装与运行

💡 快速开始: 想要快速体验 Warden？查看我们的 快速开始示例：

• 简单示例 - 基础使用，仅本地数据文件
• 复杂示例 - 完整功能，包含远程 API 和 Mock 服务

前置要求

• Go 1.25+ (参考 go.mod)
• Redis (用于分布式锁和缓存)
• Docker (可选，用于容器化部署)

快速开始

1. 克隆项目

git clone <repository-url>
cd warden

1. 安装依赖

go mod download

1. 配置本地数据文件 创建 data.json 文件（可参考 data.example.json）：

[
    {
        "phone": "13800138000",
        "mail": "admin@example.com"
    }
]

1. 运行服务

go run main.go

详细配置和部署说明请参考：

• 配置文档 - 了解所有配置选项
• 部署文档 - 了解部署方法

⚙️ 配置说明

Warden 支持多种配置方式：命令行参数、环境变量和配置文件。系统提供 6 种数据合并模式，支持灵活的配置策略。

详细配置说明请参考：配置文档

📡 API 文档

Warden 提供了完整的 RESTful API，支持用户列表查询、分页、健康检查等功能。项目还提供了 OpenAPI 3.0 规范文档。

详细 API 文档请参考：API 文档

OpenAPI 规范文件：openapi.yaml

🔌 SDK 使用

Warden 提供了 Go SDK，方便其他项目集成使用。SDK 提供了简洁的 API 接口，支持缓存、认证等功能。

详细 SDK 文档请参考：SDK 文档

🐳 Docker 部署

Warden 支持完整的 Docker 和 Docker Compose 部署，开箱即用。

🚀 快速部署: 查看 示例目录 获取完整的 Docker Compose 配置示例

详细部署文档请参考：部署文档

📊 性能指标

基于 wrk 压力测试结果（30秒测试，16线程，100连接）：

Requests/sec:   5038.81
Transfer/sec:   38.96MB
平均延迟:       21.30ms
最大延迟:       226.09ms

📁 项目结构

warden/
├── main.go                 # 程序入口
├── data.example.json      # 本地数据文件示例
├── go.mod                 # Go 模块定义
├── docker-compose.yml     # Docker Compose 配置
├── docker/
│   └── Dockerfile         # Docker 镜像构建文件
├── example/               # 快速开始示例
│   ├── README.md          # 示例说明文档
│   ├── basic/             # 简单示例（仅本地文件）
│   └── advanced/          # 复杂示例（完整功能）
├── internal/
│   ├── cache/             # Redis 缓存和锁实现
│   ├── cmd/               # 命令行参数解析
│   ├── define/            # 常量定义和数据结构
│   ├── logger/            # 日志初始化
│   ├── parser/            # 数据解析器（本地/远程）
│   ├── router/            # HTTP 路由处理
│   └── version/           # 版本信息
└── pkg/
    └── gocron/            # 定时任务调度器

🔒 安全特性

Warden 实现了多项安全功能，包括 API 认证、SSRF 防护、速率限制、TLS 验证等。

详细安全文档请参考：安全文档

🔧 开发指南

📚 参考示例: 查看 示例目录 了解不同使用场景的完整示例代码和配置。

详细开发文档请参考：开发文档

代码规范

项目遵循 Go 官方代码规范和最佳实践。详细规范请参考：

• CODE_STYLE.md - 代码风格指南
• CONTRIBUTING.md - 贡献指南

📄 许可证

查看 LICENSE 文件了解详情。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 联系方式

如有问题或建议，请通过 Issue 联系。

---

版本: 程序启动时会显示版本、构建时间和代码版本（通过 warden --version 或查看启动日志）

Documentation

Overview

Package main 是应用程序的入口点。 提供 HTTP 服务器、缓存管理、定时任务调度等功能。