460 lines
10 KiB
Markdown
460 lines
10 KiB
Markdown
# rhttpd - Rust HTTP Server
|
||
|
||
一个高性能、可配置的HTTP服务器，用Rust编写，支持多站点托管、多种代理类型和JavaScript动态配置。
|
||
|
||
## 功能特性
|
||
|
||
### ✅ 已实现 (v0.3.0)
|
||
- **🏗️ 基础架构** - 完整的模块化架构
|
||
- 多站点支持
|
||
- 基于Host头的路由
|
||
- 请求日志记录
|
||
- 错误处理
|
||
|
||
- **🌐 代理功能** - 完整实现
|
||
- **反向代理** - HTTP请求转发，支持负载均衡
|
||
- **TCP代理** - 原始TCP流量转发
|
||
- **WebSocket代理** - WebSocket消息代理框架
|
||
- **连接池管理** - HTTP连接复用
|
||
- **负载均衡** - 5种算法支持
|
||
|
||
- **🔀 路由系统** - 灵活的路由匹配
|
||
- 基于路径模式匹配 (`/api/*`, `/`, `/*`)
|
||
- 支持多路由规则
|
||
- 按优先级匹配
|
||
|
||
- **📁 静态文件服务** - 完整的静态文件支持
|
||
- 自动MIME类型检测 (使用 `mime_guess`)
|
||
- 索引文件支持 (可配置)
|
||
- 目录访问控制
|
||
|
||
- **⚙️ 配置系统** - 多格式配置支持
|
||
- **TOML格式配置** (`config.toml`)
|
||
- **JSON格式配置** - 支持
|
||
- **配置验证机制** - 完整的配置验证
|
||
- **连接池配置** - 可配置连接数和超时
|
||
- **健康检查配置** - 可配置检查间隔和状态
|
||
|
||
- **🧙 JavaScript集成** - 完整实现
|
||
- **真JavaScript执行引擎** - 基于QuickJS (rquickjs)
|
||
- **三级中间件系统** - 全局、站点、路由级别
|
||
- **三种Hook类型** - onRequest、onResponse、onResponseSent
|
||
- **console.log支持** - JavaScript调试输出
|
||
- **Request/Response对象** - 完整的HTTP对象操作
|
||
- **Headers操作** - 请求/响应头修改
|
||
- **配置文件解析** - JavaScript配置文件支持
|
||
|
||
### 🚧 开发工具
|
||
- **完整的开发环境**
|
||
- 单元测试 (7个测试通过)
|
||
- 集成测试 (4个测试通过)
|
||
- 代码格式化 (`cargo fmt`)
|
||
- 静态检查 (`cargo clippy`)
|
||
- 文档生成
|
||
- 项目结构完整
|
||
|
||
### 📚 新增v0.2.0功能
|
||
|
||
#### TCP/WebSocket代理
|
||
```toml
|
||
[[sites."ws.example.com".routes]]
|
||
type = "tcp_proxy"
|
||
path_pattern = "/ws/*"
|
||
target = "ws://websocket-server:8080"
|
||
protocol = "websocket" # tcp, websocket, http
|
||
```
|
||
|
||
#### 连接池配置
|
||
```toml
|
||
[connection_pool]
|
||
max_connections = 100
|
||
idle_timeout = 90 # 秒
|
||
```
|
||
|
||
#### 负载均衡配置
|
||
```toml
|
||
[[sites."api.example.com".routes]]
|
||
type = "reverse_proxy"
|
||
path_pattern = "/api/*"
|
||
target = "http://primary-backend"
|
||
|
||
[sites."api.example.com".routes.load_balancer]
|
||
strategy = "least_connections" # round_robin, least_connections, weighted_round_robin, ip_hash, random
|
||
upstreams = [
|
||
"http://backend1:3000",
|
||
"http://backend2:3000",
|
||
"http://backend3:3000"
|
||
]
|
||
weights = [3, 2, 1] # 可选权重配置
|
||
```
|
||
|
||
#### 健康检查配置
|
||
```toml
|
||
[health_check]
|
||
interval = 30 # 秒
|
||
timeout = 5 # 秒
|
||
path = "/health"
|
||
expected_status = 200
|
||
```
|
||
|
||
### 🔄 升级指南 (v0.1.0 → v0.2.0)
|
||
|
||
#### 配置更新
|
||
v0.2.0新增了`connection_pool`和`health_check`配置字段，如果使用自定义配置，请更新：
|
||
|
||
```toml
|
||
# v0.1.0 配置
|
||
port = 8080
|
||
[sites."example.com"]
|
||
|
||
# v0.2.0 配置 (新增字段)
|
||
port = 8080
|
||
[sites."example.com"]
|
||
|
||
[connection_pool]
|
||
max_connections = 100
|
||
idle_timeout = 90
|
||
|
||
[health_check]
|
||
interval = 30
|
||
timeout = 5
|
||
path = "/health"
|
||
expected_status = 200
|
||
```
|
||
|
||
#### API变更
|
||
- **TCP代理**: 新增`TcpProxyManager`和相关功能
|
||
- **连接池**: 新增`ConnectionPool`用于HTTP连接管理
|
||
- **负载均衡**: 新增`LoadBalancer`支持多种算法
|
||
- **健康检查**: 新增`HealthChecker`用于服务监控
|
||
|
||
#### 行为变更
|
||
- 配置文件新增字段为可选，向后兼容
|
||
- 现有配置继续工作
|
||
- 新功能默认禁用，需显式配置
|
||
|
||
## 快速开始
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
git clone https://github.com/yourusername/rhttpd.git
|
||
cd rhttpd
|
||
cargo build --release
|
||
```
|
||
|
||
### 配置
|
||
|
||
创建配置文件 `config.toml`:
|
||
|
||
```toml
|
||
port = 8080
|
||
sites."example.com".hostname = "example.com"
|
||
|
||
[[sites."example.com".routes]]
|
||
type = "static"
|
||
path_pattern = "/*"
|
||
root = "./public"
|
||
index = ["index.html"]
|
||
|
||
[[sites."example.com".routes]]
|
||
type = "reverse_proxy"
|
||
path_pattern = "/api/*"
|
||
target = "http://localhost:3000"
|
||
|
||
# 新增：连接池配置
|
||
[connection_pool]
|
||
max_connections = 100
|
||
idle_timeout = 90
|
||
|
||
# 新增：健康检查配置
|
||
[health_check]
|
||
interval = 30
|
||
timeout = 5
|
||
path = "/health"
|
||
expected_status = 200
|
||
```
|
||
|
||
### 运行
|
||
|
||
```bash
|
||
# 使用默认配置
|
||
cargo run
|
||
|
||
# 使用指定配置文件
|
||
cargo run -- config.toml
|
||
```
|
||
|
||
## 配置参考
|
||
|
||
### 服务器配置
|
||
|
||
| 字段 | 类型 | 描述 | 默认值 |
|
||
|------|------|------|--------|
|
||
| `port` | `u16` | 监听端口 | 8080 |
|
||
| `sites` | `HashMap<String, SiteConfig>` | 站点配置映射 | `{}` |
|
||
| `js_config` | `Option<String>` | JavaScript配置文件路径 | `None` |
|
||
| `connection_pool` | `Option<ConnectionPoolConfig>` | 连接池配置 | `None` |
|
||
| `health_check` | `Option<HealthCheckConfig>` | 健康检查配置 | `None` |
|
||
|
||
### 站点配置
|
||
|
||
| 字段 | 类型 | 描述 |
|
||
|------|------|------|
|
||
| `hostname` | `String` | 站点主机名 |
|
||
| `routes` | `Vec<RouteRule>` | 路由规则列表 |
|
||
| `tls` | `Option<TlsConfig>` | TLS配置 |
|
||
|
||
### 路由规则
|
||
|
||
#### 静态文件
|
||
```toml
|
||
type = "static"
|
||
path_pattern = "/*" # 路径模式
|
||
root = "./public" # 文件根目录
|
||
index = ["index.html"] # 索引文件列表
|
||
directory_listing = false # 是否允许目录列表
|
||
```
|
||
|
||
#### 反向代理
|
||
```toml
|
||
type = "reverse_proxy"
|
||
path_pattern = "/api/*"
|
||
target = "http://backend:3000"
|
||
```
|
||
|
||
#### 增强的反向代理 (v0.2.0)
|
||
```toml
|
||
[sites."api.example.com".routes]]
|
||
type = "reverse_proxy"
|
||
path_pattern = "/api/*"
|
||
target = "http://primary-backend"
|
||
|
||
[sites."api.example.com".routes.load_balancer]
|
||
strategy = "least_connections"
|
||
upstreams = [
|
||
"http://backend1:3000",
|
||
"http://backend2:3000"
|
||
]
|
||
weights = [3, 2, 1] # 权重：backend1=3, backend2=2, backend3=1
|
||
```
|
||
|
||
#### TCP代理 (v0.2.0)
|
||
```toml
|
||
[[sites."ws.example.com".routes]]
|
||
type = "tcp_proxy"
|
||
path_pattern = "/ws/*"
|
||
target = "ws://websocket-server:8080"
|
||
protocol = "websocket" # tcp, websocket, http
|
||
```
|
||
|
||
### 连接池配置 (v0.2.0)
|
||
|
||
```toml
|
||
[connection_pool]
|
||
max_connections = 100 # 最大连接数
|
||
idle_timeout = 90 # 空闲超时（秒）
|
||
```
|
||
|
||
### 健康检查配置 (v0.2.0)
|
||
|
||
```toml
|
||
[health_check]
|
||
interval = 30 # 检查间隔（秒）
|
||
timeout = 5 # 超时时间（秒）
|
||
path = "/health" # 健康检查路径
|
||
expected_status = 200 # 期望的状态码
|
||
```
|
||
|
||
## 开发
|
||
|
||
### 构建和测试
|
||
|
||
```bash
|
||
# 构建
|
||
cargo build
|
||
|
||
# 构建（优化）
|
||
cargo build --release
|
||
|
||
# 测试
|
||
cargo test
|
||
|
||
# 运行单个测试
|
||
cargo test test_name
|
||
|
||
# 运行测试并输出
|
||
cargo test -- --nocapture
|
||
|
||
# 代码检查
|
||
cargo check
|
||
|
||
# 代码格式化
|
||
cargo fmt
|
||
|
||
# 运行clippy lints
|
||
cargo clippy
|
||
|
||
# 运行clippy（所有目标）
|
||
cargo clippy --all-targets --all-features
|
||
|
||
# 生成文档
|
||
cargo doc --open
|
||
|
||
# 清理构建产物
|
||
cargo clean
|
||
```
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
rhttpd/
|
||
├── src/
|
||
│ ├── main.rs # 应用程序入口
|
||
│ ├── lib.rs # 库根
|
||
│ ├── config/ # 配置管理
|
||
│ │ └── mod.rs
|
||
│ ├── server/ # 服务器实现
|
||
│ │ └── mod.rs
|
||
│ ├── proxy/ # 代理功能
|
||
│ │ ├── mod.rs
|
||
│ │ ├── tcp_proxy.rs # TCP/WebSocket代理
|
||
│ │ ├── connection_pool.rs # 连接池管理
|
||
│ │ ├── load_balancer.rs # 负载均衡
|
||
│ │ └── health_check.rs # 健康检查
|
||
│ └── js_engine/ # JavaScript集成
|
||
│ └── mod.rs
|
||
├── tests/ # 集成测试
|
||
├── doc/ # 文档和需求
|
||
├── public/ # 静态文件示例
|
||
├── static/ # 静态文件示例
|
||
├── config.toml # 配置示例
|
||
├── config.js # JavaScript配置示例
|
||
├── README.md # 项目文档
|
||
├── AGENTS.md # 开发者指南
|
||
├── roadmap.md # 开发路线图
|
||
└── CHANGELOG.md # 变更日志
|
||
```
|
||
|
||
## 示例
|
||
|
||
### 基本静态网站
|
||
```toml
|
||
port = 8080
|
||
|
||
[sites."mysite.com"]
|
||
hostname = "mysite.com"
|
||
|
||
[[sites."mysite.com".routes]]
|
||
type = "static"
|
||
path_pattern = "/*"
|
||
root = "./www"
|
||
index = ["index.html"]
|
||
directory_listing = false
|
||
```
|
||
|
||
### API服务器代理
|
||
```toml
|
||
port = 8080
|
||
|
||
[sites."api.example.com"]
|
||
hostname = "api.example.com"
|
||
|
||
[[sites."api.example.com".routes]]
|
||
type = "reverse_proxy"
|
||
path_pattern = "/v1/*"
|
||
target = "http://backend:3001"
|
||
```
|
||
|
||
### 混合配置 (多后端)
|
||
```toml
|
||
[sites."example.com"]
|
||
|
||
[[sites."example.com".routes]]
|
||
type = "static"
|
||
path_pattern = "/static/*"
|
||
root = "./assets"
|
||
|
||
[[sites."example.com".routes]]
|
||
type = "static"
|
||
path_pattern = "/"
|
||
root = "./public"
|
||
index = ["index.html"]
|
||
|
||
[[sites."example.com".routes]]
|
||
type = "reverse_proxy"
|
||
path_pattern = "/api/*"
|
||
target = "http://backend:3000"
|
||
|
||
[sites."example.com".routes.load_balancer]
|
||
strategy = "least_connections"
|
||
upstreams = ["http://backend1:3000", "http://backend2:3000"]
|
||
```
|
||
|
||
### TCP/WebSocket代理
|
||
```toml
|
||
[sites."ws.example.com"]
|
||
|
||
[[sites."ws.example.com".routes]]
|
||
type = "tcp_proxy"
|
||
path_pattern = "/ws/*"
|
||
target = "ws://chat-server:8080"
|
||
protocol = "websocket"
|
||
```
|
||
|
||
### 带连接池和健康检查的完整配置
|
||
```toml
|
||
port = 8080
|
||
|
||
[connection_pool]
|
||
max_connections = 100
|
||
idle_timeout = 90
|
||
|
||
[health_check]
|
||
interval = 30
|
||
timeout = 5
|
||
path = "/health"
|
||
expected_status = 200
|
||
|
||
[sites."api.example.com"]
|
||
|
||
[[sites."api.example.com".routes]]
|
||
type = "reverse_proxy"
|
||
path_pattern = "/api/*"
|
||
|
||
[sites."api.example.com".routes.load_balancer]
|
||
strategy = "weighted_round_robin"
|
||
upstreams = [
|
||
"http://backend1:3000",
|
||
"http://backend2:3000",
|
||
"http://backend3:3000"
|
||
]
|
||
weights = [5, 3, 2] # backend1权重最高
|
||
```
|
||
|
||
## 性能
|
||
|
||
rhttpd基于以下高性能Rust库构建：
|
||
- `tokio` - 异步运行时
|
||
- `axum` - HTTP框架
|
||
- `hyper` - HTTP实现
|
||
- `reqwest` - HTTP客户端
|
||
- `tower` - 中间件和服务抽象
|
||
|
||
## 贡献
|
||
|
||
欢迎贡献代码！请查看 [AGENTS.md](AGENTS.md) 了解开发指南。
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 支持
|
||
|
||
如有问题或建议，请提交Issue或Pull Request。
|
||
|
||
## 版本
|
||
|
||
**当前版本**: v0.2.0
|
||
|
||
**发布日期**: 2025-01-15 |