"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服务解决方案，适用于中小型应用或特定场景下的负载均衡和反向代理需求。
|
- SSL/TLS 支持
|
||||||
|
- 静态文件服务
|
||||||
## 目标
|
|
||||||
|
|
||||||
实现一个类似nginx功能的http服务器
|
|
||||||
## 核心功能
|
|
||||||
|
|
||||||
- 支持静态文件服务
|
|
||||||
- 反向代理（Proxy）
|
- 反向代理（Proxy）
|
||||||
- 路径重写（Rewrite）
|
- 路径重写（Rewrite）
|
||||||
- TLS加密支持
|
|
||||||
- 端口复用
|
|
||||||
- 健康检查
|
- 健康检查
|
||||||
|
- 访问控制（IP白名单/黑名单）
|
||||||
|
- JWT认证
|
||||||
|
- 访问统计
|
||||||
|
- 管理接口
|
||||||
|
- 配置热重载
|
||||||
|
- 端口复用
|
||||||
- 日志管理（支持Console和File两种Appender）
|
- 日志管理（支持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
|
```json
|
||||||
{
|
{
|
||||||
"logging" :{
|
"logging": {
|
||||||
"appenders": {
|
"appenders": {
|
||||||
"out" :{
|
"out": {
|
||||||
"type": "file",
|
"type": "file",
|
||||||
"options":{
|
"options": {
|
||||||
"file": "gohttpd.log"
|
"file": "gohttpd.log"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"categories": {
|
"categories": {
|
||||||
"default": {
|
"default": {
|
||||||
"appenders": [ "out" ],
|
"appenders": ["out"],
|
||||||
"level": "debug"
|
"level": "debug"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"admin" : {
|
"admin": {
|
||||||
"name": "admin",
|
"name": "admin",
|
||||||
"port" : 8088,
|
"port": 8088,
|
||||||
"username": "admin",
|
"username": "admin",
|
||||||
"password": "admin",
|
"password": "admin",
|
||||||
"directives":[
|
"directives": [
|
||||||
"Set-Header Access-Control-Allow-Origin *"
|
"Set-Header Access-Control-Allow-Origin *"
|
||||||
],
|
],
|
||||||
"paths": [
|
"paths": [
|
||||||
|
|
@ -54,125 +70,136 @@
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"servers":[{
|
"servers": [{
|
||||||
"port" : 8080,
|
"port": 8080,
|
||||||
"name":"test",
|
"name": "test",
|
||||||
"paths":[
|
"paths": [
|
||||||
{
|
{
|
||||||
"path": "/",
|
"path": "/",
|
||||||
"root": "/home/kingecg/code/gohttp/public/",
|
"root": "/path/to/public/",
|
||||||
"default": "index.html"
|
"default": "index.html"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"path": "/ws",
|
"path": "/ws",
|
||||||
"upstreams":["http://localhost:3000"],
|
"upstreams": ["http://localhost:3000"],
|
||||||
"directives":[
|
"directives": [
|
||||||
"HostSchemas $target",
|
"HostSchemas $target",
|
||||||
"HeaderOrigin",
|
"HeaderOrigin",
|
||||||
"Path /ws /",
|
"Path /ws /",
|
||||||
"RemoveCookie token"
|
"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
|
指令名 参数1 参数2 ... 参数n
|
||||||
```
|
```
|
||||||
指令系统用来对特定的request/response进行处理。目前只支持：
|
|
||||||
|
|
||||||
- 返回的response中设置header
|
### 支持的指令
|
||||||
- 反向代理时，修改发送到上游服务器的请求
|
- `Set-Header`: 设置响应头
|
||||||
|
- `HostSchemas`: 设置代理目标地址
|
||||||
|
- `HeaderOrigin`: 添加Origin头
|
||||||
|
- `Path`: 重写URL路径
|
||||||
|
- `RemoveCookie`: 删除指定Cookie
|
||||||
|
|
||||||
命名规则：
|
## 管理接口
|
||||||
模块支持的指令，以模块名作为前缀，如：Proxy_Path 是反向代理模块的Path指令。
|
- `/admin/reload`: 重新加载配置
|
||||||
没有前缀的，是全局指令，如：Set-Header 是设置header的指令。
|
- `/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注册、路由解析、中间件管理
|
- Server: Restful API注册、路由解析、中间件管理
|
||||||
|
|
@ -180,50 +207,39 @@ paths 配置
|
||||||
- HealthCheck: 上游服务器健康检测
|
- HealthCheck: 上游服务器健康检测
|
||||||
- Admin: 管理后台API
|
- Admin: 管理后台API
|
||||||
|
|
||||||
### 技术选型
|
### 依赖库
|
||||||
- **编程语言**: Go (v1.23.0+)
|
- `git.pyer.club/kingecg/cmux`: 多路复用支持
|
||||||
- **依赖库**:
|
- `git.pyer.club/kingecg/godaemon`: 守护进程支持
|
||||||
- `git.pyer.club/kingecg/cmux`: 多路复用支持
|
- `git.pyer.club/kingecg/gologger`: 自定义日志库
|
||||||
- `git.pyer.club/kingecg/godaemon`: 守护进程支持
|
- `github.com/golang-jwt/jwt/v5`: JWT支持
|
||||||
- `git.pyer.club/kingecg/gologger`: 自定义日志库
|
- `github.com/nanmu42/gzip`: Gzip压缩支持
|
||||||
- `github.com/golang-jwt/jwt/v5`: JWT支持
|
- `github.com/samber/lo`: 工具库
|
||||||
- `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
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
./gohttpd
|
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