205 lines
6.6 KiB
Markdown
205 lines
6.6 KiB
Markdown
# 服务器配置
|
||
|
||
<cite>
|
||
**本文档引用文件**
|
||
- [config.go](file://pkg/config/config.go)
|
||
- [manager.go](file://pkg/config/manager.go)
|
||
- [main.go](file://cmd/server/main.go)
|
||
- [start.sh](file://start.sh)
|
||
- [dev.sh](file://scripts/dev.sh)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [服务器配置项详解](#服务器配置项详解)
|
||
3. [环境变量覆盖机制](#环境变量覆盖机制)
|
||
4. [配置示例](#配置示例)
|
||
5. [性能调优建议](#性能调优建议)
|
||
6. [配置结构体说明](#配置结构体说明)
|
||
|
||
## 简介
|
||
CarrotSkin项目采用基于环境变量的配置管理机制，通过Viper库实现灵活的配置加载与覆盖。服务器模块的配置主要集中在`ServerConfig`结构体中，定义了端口、运行模式、读写超时等关键参数。本文档详细说明这些配置项的作用、默认值以及如何通过环境变量进行覆盖，为开发者提供清晰的配置指导。
|
||
|
||
**Section sources**
|
||
- [config.go](file://pkg/config/config.go#L26-L32)
|
||
- [main.go](file://cmd/server/main.go#L27-L124)
|
||
|
||
## 服务器配置项详解
|
||
|
||
### server.port
|
||
- **作用**：指定服务器监听的端口号
|
||
- **数据类型**：string
|
||
- **默认值**：":8080"
|
||
- **说明**：该配置值应包含冒号前缀，表示监听所有网络接口上的指定端口。例如":8080"表示监听8080端口。
|
||
|
||
### server.mode
|
||
- **作用**：设置服务器运行模式
|
||
- **数据类型**：string
|
||
- **默认值**："debug"
|
||
- **说明**：支持"debug"和"production"两种模式。在生产模式下，Gin框架会自动切换到发布模式，关闭调试信息输出，提高性能和安全性。
|
||
|
||
### server.read_timeout
|
||
- **作用**：设置HTTP服务器读取请求的超时时间
|
||
- **数据类型**：time.Duration
|
||
- **默认值**："30s"
|
||
- **说明**：防止客户端长时间不发送数据导致服务器资源被占用。超时后连接将被关闭。
|
||
|
||
### server.write_timeout
|
||
- **作用**：设置HTTP服务器写入响应的超时时间
|
||
- **数据类型**：time.Duration
|
||
- **默认值**："30s"
|
||
- **说明**：防止响应过程过长占用服务器资源。对于大文件下载等长时间操作，可能需要适当增加此值。
|
||
|
||
**Section sources**
|
||
- [config.go](file://pkg/config/config.go#L137-L141)
|
||
- [config.go](file://pkg/config/config.go#L26-L32)
|
||
|
||
## 环境变量覆盖机制
|
||
|
||
CarrotSkin项目支持通过环境变量覆盖默认配置，实现不同环境下的灵活配置管理。环境变量前缀为`CARROTSKIN`，具体映射关系如下：
|
||
|
||
| 配置项 | 环境变量 | 优先级 |
|
||
|--------|----------|--------|
|
||
| server.port | CARROTSKIN_SERVER_PORT | 高 |
|
||
| server.mode | CARROTSKIN_SERVER_MODE | 高 |
|
||
| server.read_timeout | CARROTSKIN_SERVER_READ_TIMEOUT | 高 |
|
||
| server.write_timeout | CARROTSKIN_SERVER_WRITE_TIMEOUT | 高 |
|
||
|
||
配置加载流程：
|
||
1. 加载`.env`文件中的环境变量
|
||
2. 设置各项配置的默认值
|
||
3. 绑定环境变量映射关系
|
||
4. 从环境变量中读取并覆盖配置
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[开始] --> B[加载.env文件]
|
||
B --> C[设置默认配置值]
|
||
C --> D[绑定环境变量映射]
|
||
D --> E[从环境变量覆盖配置]
|
||
E --> F[返回配置实例]
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [config.go](file://pkg/config/config.go#L108-L134)
|
||
|
||
**Section sources**
|
||
- [config.go](file://pkg/config/config.go#L192-L196)
|
||
- [config.go](file://pkg/config/config.go#L108-L134)
|
||
|
||
## 配置示例
|
||
|
||
### 开发环境配置
|
||
在开发环境中，通常使用默认配置或通过`dev.sh`脚本启动：
|
||
|
||
```bash
|
||
# 启动开发服务器
|
||
./scripts/dev.sh
|
||
```
|
||
|
||
或者手动设置环境变量：
|
||
```bash
|
||
export CARROTSKIN_SERVER_PORT=":8080"
|
||
export CARROTSKIN_SERVER_MODE="debug"
|
||
export CARROTSKIN_SERVER_READ_TIMEOUT="30s"
|
||
export CARROTSKIN_SERVER_WRITE_TIMEOUT="30s"
|
||
go run ./cmd/server
|
||
```
|
||
|
||
### 生产环境配置
|
||
生产环境建议使用`start.sh`脚本，并设置更严格的配置：
|
||
|
||
```bash
|
||
# 生产环境启动脚本示例
|
||
export CARROTSKIN_SERVER_PORT=":80"
|
||
export CARROTSKIN_SERVER_MODE="production"
|
||
export CARROTSKIN_SERVER_READ_TIMEOUT="15s"
|
||
export CARROTSKIN_SERVER_WRITE_TIMEOUT="15s"
|
||
./start.sh
|
||
```
|
||
|
||
### Docker环境配置
|
||
在Docker环境中，可以通过环境变量进行配置：
|
||
|
||
```dockerfile
|
||
environment:
|
||
- CARROTSKIN_SERVER_PORT=:80
|
||
- CARROTSKIN_SERVER_MODE=production
|
||
- CARROTSKIN_SERVER_READ_TIMEOUT=20s
|
||
- CARROTSKIN_SERVER_WRITE_TIMEOUT=20s
|
||
```
|
||
|
||
**Section sources**
|
||
- [start.sh](file://start.sh#L1-L37)
|
||
- [dev.sh](file://scripts/dev.sh#L1-L29)
|
||
|
||
## 性能调优建议
|
||
|
||
### 高并发场景下的超时设置
|
||
在高并发场景下，合理的超时设置对系统稳定性至关重要：
|
||
|
||
- **低延迟场景**：对于API服务等需要快速响应的场景，建议将读写超时设置为10-15秒
|
||
- **大文件传输场景**：对于包含文件上传下载的功能，建议适当增加write_timeout至60秒以上
|
||
- **内网服务**：如果是内网服务且网络环境稳定，可以将超时时间设置得更短，如5-10秒
|
||
|
||
### 连接池与超时的协同优化
|
||
```mermaid
|
||
flowchart LR
|
||
A[客户端请求] --> B{连接建立}
|
||
B --> |成功| C[读取请求]
|
||
C --> D{读取超时}
|
||
D --> |超时| E[关闭连接]
|
||
D --> |成功| F[处理请求]
|
||
F --> G[写入响应]
|
||
G --> H{写入超时}
|
||
H --> |超时| I[关闭连接]
|
||
H --> |成功| J[完成响应]
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [main.go](file://cmd/server/main.go#L93-L98)
|
||
|
||
**Section sources**
|
||
- [main.go](file://cmd/server/main.go#L93-L98)
|
||
- [config.go](file://pkg/config/config.go#L139-L140)
|
||
|
||
## 配置结构体说明
|
||
|
||
### ServerConfig 结构体
|
||
```go
|
||
type ServerConfig struct {
|
||
Port string `mapstructure:"port"`
|
||
Mode string `mapstructure:"mode"`
|
||
ReadTimeout time.Duration `mapstructure:"read_timeout"`
|
||
WriteTimeout time.Duration `mapstructure:"write_timeout"`
|
||
}
|
||
```
|
||
|
||
- **Port**：端口号，字符串类型，需包含冒号前缀
|
||
- **Mode**：运行模式，可选值为"debug"或"production"
|
||
- **ReadTimeout**：读取超时，time.Duration类型，支持"30s"、"1m"等格式
|
||
- **WriteTimeout**：写入超时，time.Duration类型，支持"30s"、"1m"等格式
|
||
|
||
### 配置初始化流程
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Main as main.go
|
||
participant Config as config.go
|
||
participant Viper as Viper库
|
||
Main->>Config : config.Init()
|
||
Config->>Viper : 加载.env文件
|
||
Viper-->>Config : 返回环境变量
|
||
Config->>Config : setDefaults()
|
||
Config->>Config : setupEnvMappings()
|
||
Config->>Config : overrideFromEnv()
|
||
Config-->>Main : 返回配置实例
|
||
Main->>Main : 启动HTTP服务器
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [config.go](file://pkg/config/config.go#L108-L134)
|
||
- [main.go](file://cmd/server/main.go#L27-L32)
|
||
|
||
**Section sources**
|
||
- [config.go](file://pkg/config/config.go#L26-L32)
|
||
- [manager.go](file://pkg/config/manager.go#L19-L28) |