"docs(readme): 全面更新README文档，完善项目描述和配置说明"
This commit is contained in:
程广
parent
dc5528c558
commit
b58e51e4f5
326
README.md
326
README.md
|
|
@ -1,49 +1,65 @@
|
|||
# gohttp
|
||||
# GoHTTP Server
|
||||
|
||||
## 项目概述
|
||||
一个基于Go语言开发的高性能HTTP服务器，支持多域名、SSL/TLS、静态文件服务等特性。类似Nginx功能的轻量级HTTP服务器实现，提供静态文件服务、反向代理、路径重写、TLS支持等功能。
|
||||
|
||||
### 项目背景和价值
|
||||
- **背景**: 实现一个类似Nginx功能的HTTP服务器，提供静态文件服务、反向代理、路径重写、TLS支持等功能。
|
||||
- **价值**: 提供轻量级、高性能的HTTP服务解决方案，适用于中小型应用或特定场景下的负载均衡和反向代理需求。
|
||||
|
||||
## 目标
|
||||
|
||||
实现一个类似nginx功能的http服务器
|
||||
## 核心功能
|
||||
|
||||
- 支持静态文件服务
|
||||
## 主要特性
|
||||
- 多服务器配置支持
|
||||
- SSL/TLS 支持
|
||||
- 静态文件服务
|
||||
- 反向代理（Proxy）
|
||||
- 路径重写（Rewrite）
|
||||
- TLS加密支持
|
||||
- 端口复用
|
||||
- 健康检查
|
||||
- 访问控制（IP白名单/黑名单）
|
||||
- JWT认证
|
||||
- 访问统计
|
||||
- 管理接口
|
||||
- 配置热重载
|
||||
- 端口复用
|
||||
- 日志管理（支持Console和File两种Appender）
|
||||
- Gzip压缩支持
|
||||
|
||||
## 配置
|
||||
## 快速开始
|
||||
|
||||
### 系统要求
|
||||
- Go 1.23.0+
|
||||
|
||||
### 安装
|
||||
```bash
|
||||
git clone [repository-url]
|
||||
cd gohttp
|
||||
go mod tidy
|
||||
make build
|
||||
```
|
||||
|
||||
### 配置
|
||||
1. 主配置文件 (config.json)
|
||||
2. 域名配置文件 (include/*.json)
|
||||
|
||||
### 配置示例
|
||||
```json
|
||||
{
|
||||
"logging" :{
|
||||
"logging": {
|
||||
"appenders": {
|
||||
"out" :{
|
||||
"out": {
|
||||
"type": "file",
|
||||
"options":{
|
||||
"options": {
|
||||
"file": "gohttpd.log"
|
||||
}
|
||||
}
|
||||
},
|
||||
"categories": {
|
||||
"default": {
|
||||
"appenders": [ "out" ],
|
||||
"appenders": ["out"],
|
||||
"level": "debug"
|
||||
}
|
||||
}
|
||||
},
|
||||
"admin" : {
|
||||
"admin": {
|
||||
"name": "admin",
|
||||
"port" : 8088,
|
||||
"port": 8088,
|
||||
"username": "admin",
|
||||
"password": "admin",
|
||||
"directives":[
|
||||
"directives": [
|
||||
"Set-Header Access-Control-Allow-Origin *"
|
||||
],
|
||||
"paths": [
|
||||
|
|
@ -54,125 +70,136 @@
|
|||
}
|
||||
]
|
||||
},
|
||||
"servers":[{
|
||||
"port" : 8080,
|
||||
"name":"test",
|
||||
"paths":[
|
||||
"servers": [{
|
||||
"port": 8080,
|
||||
"name": "test",
|
||||
"paths": [
|
||||
{
|
||||
"path": "/",
|
||||
"root": "/home/kingecg/code/gohttp/public/",
|
||||
"root": "/path/to/public/",
|
||||
"default": "index.html"
|
||||
},
|
||||
{
|
||||
"path": "/ws",
|
||||
"upstreams":["http://localhost:3000"],
|
||||
"directives":[
|
||||
"upstreams": ["http://localhost:3000"],
|
||||
"directives": [
|
||||
"HostSchemas $target",
|
||||
"HeaderOrigin",
|
||||
"Path /ws /",
|
||||
"RemoveCookie token"
|
||||
]
|
||||
],
|
||||
"health_check": {
|
||||
"interval": "10s",
|
||||
"timeout": "5s",
|
||||
"retries": 3
|
||||
}
|
||||
}
|
||||
]
|
||||
}]
|
||||
}
|
||||
```
|
||||
- logging 日志配置
|
||||
- admin 管理后台配置
|
||||
- servers 服务器配置
|
||||
|
||||
日志采用自己实现的类log4j库，目前只支持console 和file两种appeder
|
||||
|
||||
servers 配置
|
||||
|
||||
- port 端口
|
||||
- name 服务器名称
|
||||
- paths 路径配置
|
||||
- certfile 证书文件
|
||||
- keyfile 证书密钥文件
|
||||
- directives 指令 针对response的指令，目前只实现了set-header
|
||||
|
||||
|
||||
paths 配置
|
||||
|
||||
- path 路径
|
||||
- root 根目录
|
||||
- default 默认文件
|
||||
- upstreams 代理地址
|
||||
- directives 这里指令针对的是代理请求，有以下几种：
|
||||
- HostSchemas [$target] 代理地址
|
||||
- HeaderOrigin 代理请求时，添加Origin头
|
||||
- Path [/ws] [/] 代理请求时，重写URL路径，用第二个参数替换url中的第一个部分
|
||||
- RemoveCookie [token] 代理请求时，删除cookie中的某些字段
|
||||
|
||||
### 健康检查配置（新）
|
||||
|
||||
健康检查功能允许系统定期检查上游服务器的健康状态，并在请求时自动跳过不健康的服务器。
|
||||
|
||||
#### 配置选项
|
||||
|
||||
- `health_check` - 在server配置中的健康检查参数
|
||||
- `interval` - 检查间隔时间（如"10s"）
|
||||
- `timeout` - 单次检查超时时间（如"5s"）
|
||||
- `retries` - 健康检查失败重试次数
|
||||
|
||||
#### 示例配置
|
||||
|
||||
```json
|
||||
{
|
||||
"servers":[{
|
||||
"port" : 8080,
|
||||
"name":"test",
|
||||
|
||||
"paths":[{
|
||||
"path": "/",
|
||||
"root": "/home/kingecg/code/gohttp/public/",
|
||||
"default": "index.html"
|
||||
},{
|
||||
"path": "/ws",
|
||||
"upstreams":["http://localhost:3000"],
|
||||
"directives":[
|
||||
"HostSchemas $target",
|
||||
"HeaderOrigin",
|
||||
"Path /ws /",
|
||||
"RemoveCookie token"
|
||||
],
|
||||
"health_check": {
|
||||
"interval": "10s", // 每10秒检查一次
|
||||
"timeout": "5s", // 每次检查5秒超时
|
||||
"retries": 3 // 失败3次才认为是不健康
|
||||
},
|
||||
}]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
#### 特性
|
||||
## 配置说明
|
||||
|
||||
- 自动检测上游服务器的健康状态
|
||||
- 请求失败时自动重试其他可用服务器
|
||||
- 定期后台检查服务器状态
|
||||
- 详细的日志记录便于监控和调试
|
||||
### 主配置文件
|
||||
- `logging`: 日志配置
|
||||
- `appenders`: 日志输出配置（支持console和file）
|
||||
- `categories`: 日志类别配置
|
||||
- `admin`: 管理后台配置
|
||||
- `port`: 管理接口端口
|
||||
- `username`: 管理员用户名
|
||||
- `password`: 管理员密码
|
||||
- `directives`: 管理接口指令
|
||||
- `servers`: 服务器配置列表
|
||||
|
||||
### 指令系统
|
||||
### 服务器配置
|
||||
- `name`: 服务名称
|
||||
- `port`: 监听端口
|
||||
- `certfile`: SSL证书文件路径
|
||||
- `keyfile`: SSL密钥文件路径
|
||||
- `paths`: 路径配置列表
|
||||
- `directives`: 全局指令
|
||||
|
||||
指令系统采用了nginx的指令系统，指令的格式为：
|
||||
### 路径配置
|
||||
- `path`: URL路径
|
||||
- `root`: 本地文件系统路径
|
||||
- `default`: 默认文件
|
||||
- `upstreams`: 代理服务器地址列表
|
||||
- `directives`: 路径特定指令
|
||||
- `health_check`: 健康检查配置
|
||||
- `interval`: 检查间隔时间
|
||||
- `timeout`: 检查超时时间
|
||||
- `retries`: 失败重试次数
|
||||
|
||||
## 指令系统
|
||||
|
||||
指令系统采用类似Nginx的指令系统，格式为：
|
||||
```
|
||||
指令名 参数1 参数2 ... 参数n
|
||||
```
|
||||
指令系统用来对特定的request/response进行处理。目前只支持：
|
||||
|
||||
- 返回的response中设置header
|
||||
- 反向代理时，修改发送到上游服务器的请求
|
||||
### 支持的指令
|
||||
- `Set-Header`: 设置响应头
|
||||
- `HostSchemas`: 设置代理目标地址
|
||||
- `HeaderOrigin`: 添加Origin头
|
||||
- `Path`: 重写URL路径
|
||||
- `RemoveCookie`: 删除指定Cookie
|
||||
|
||||
命名规则：
|
||||
模块支持的指令，以模块名作为前缀，如：Proxy_Path 是反向代理模块的Path指令。
|
||||
没有前缀的，是全局指令，如：Set-Header 是设置header的指令。
|
||||
## 管理接口
|
||||
- `/admin/reload`: 重新加载配置
|
||||
- `/admin/stats`: 查看统计信息
|
||||
- `/admin/health`: 健康检查
|
||||
|
||||
## 系统架构
|
||||
## 构建和部署
|
||||
|
||||
### 整体架构
|
||||
### 构建
|
||||
```bash
|
||||
make clean && make build
|
||||
```
|
||||
构建后的可执行文件位于target目录。
|
||||
|
||||
### 运行
|
||||
```bash
|
||||
./target/<platform>/gohttpd
|
||||
```
|
||||
|
||||
### 系统服务安装
|
||||
安装脚本会执行以下操作：
|
||||
1. 检查是否已安装gohttpd
|
||||
2. 创建目录 `/usr/local/gohttpd`
|
||||
3. 复制所有必要文件到安装目录
|
||||
4. 创建软链接到 `/usr/local/bin/gohttpd`
|
||||
5. 安装并启用系统服务
|
||||
|
||||
安装命令：
|
||||
```bash
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
安装完成后，可以通过以下命令管理服务：
|
||||
```bash
|
||||
# 启动服务
|
||||
sudo systemctl start gohttpd.service
|
||||
|
||||
# 停止服务
|
||||
sudo systemctl stop gohttpd.service
|
||||
|
||||
# 重启服务
|
||||
sudo systemctl restart gohttpd.service
|
||||
|
||||
# 查看服务状态
|
||||
sudo systemctl status gohttpd.service
|
||||
|
||||
# 查看服务日志
|
||||
sudo journalctl -u gohttpd.service
|
||||
```
|
||||
|
||||
默认安装路径：
|
||||
- 程序安装目录：`/usr/local/gohttpd/`
|
||||
- 可执行文件链接：`/usr/local/bin/gohttpd`
|
||||
- 服务配置文件：`/etc/systemd/system/gohttpd.service`
|
||||
|
||||
## 技术架构
|
||||
- **架构模式**: 单体架构，模块化设计
|
||||
- **关键组件**:
|
||||
- Server: Restful API注册、路由解析、中间件管理
|
||||
|
|
@ -180,50 +207,39 @@ paths 配置
|
|||
- HealthCheck: 上游服务器健康检测
|
||||
- Admin: 管理后台API
|
||||
|
||||
### 技术选型
|
||||
- **编程语言**: Go (v1.23.0+)
|
||||
- **依赖库**:
|
||||
- `git.pyer.club/kingecg/cmux`: 多路复用支持
|
||||
- `git.pyer.club/kingecg/godaemon`: 守护进程支持
|
||||
- `git.pyer.club/kingecg/gologger`: 自定义日志库
|
||||
- `github.com/golang-jwt/jwt/v5`: JWT支持
|
||||
- `github.com/nanmu42/gzip`: Gzip压缩支持
|
||||
- `github.com/samber/lo`: 工具库
|
||||
### 依赖库
|
||||
- `git.pyer.club/kingecg/cmux`: 多路复用支持
|
||||
- `git.pyer.club/kingecg/godaemon`: 守护进程支持
|
||||
- `git.pyer.club/kingecg/gologger`: 自定义日志库
|
||||
- `github.com/golang-jwt/jwt/v5`: JWT支持
|
||||
- `github.com/nanmu42/gzip`: Gzip压缩支持
|
||||
- `github.com/samber/lo`: 工具库
|
||||
|
||||
## 安装指南
|
||||
## 许可证
|
||||
本项目采用 MIT 许可证。查看 [LICENSE](LICENSE) 文件了解更多详细信息。
|
||||
|
||||
### 开发环境搭建
|
||||
1. 安装Go语言环境（版本>=1.23.0）
|
||||
2. 克隆项目代码到本地：
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd /persistent/home/kingecg/work/code/gohttp
|
||||
```
|
||||
3. 安装依赖：
|
||||
```bash
|
||||
go mod tidy
|
||||
```
|
||||
|
||||
### 构建与运行
|
||||
- **构建命令**:
|
||||
```bash
|
||||
make clean && make build
|
||||
```
|
||||
- **运行命令**:
|
||||
```bash
|
||||
./target/<platform>/gohttpd
|
||||
```
|
||||
- **部署**: 使用`install.sh`脚本完成安装
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
make clean && make build
|
||||
```
|
||||
在target目录下生成可执行文件
|
||||
MIT License
|
||||
|
||||
## 运行
|
||||
Copyright (c) [year] [copyright holders]
|
||||
|
||||
```bash
|
||||
./gohttpd
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
```
|
||||
|
||||
注意：请确保更新 LICENSE 文件中的 [year] 和 [copyright holders] 信息。
|
||||
Loading…
Reference in New Issue