143 lines
5.7 KiB
Markdown
143 lines
5.7 KiB
Markdown
# 2.5 配置文件说明
|
||
|
||
:::tip 概述
|
||
本项目唯一运行时配置文件为 `manifest/config/config.yaml`，GoFrame gcfg 加载。环境变量覆盖规则：使用 `GF_` 前缀，例如 `GF_DATABASE_DEFAULT_LINK`。本节速览全部配置块，完整键值速查见[附录 C 配置项速查](../appendix/config-reference)。
|
||
:::
|
||
|
||
## 配置文件全景
|
||
|
||
```text
|
||
manifest/config/config.yaml
|
||
├─ server 服务端：监听地址、OpenAPI、优雅重启
|
||
├─ logger 日志：级别、输出、目录
|
||
├─ database 多数据库连接（type/link 切换五方言）
|
||
├─ redis 缓存连接（黑名单/验证码/字典/租户/身份缓存）
|
||
├─ jwt 双令牌：签名密钥、签发者、双有效期
|
||
├─ captcha 图形验证码：字符集、尺寸、干扰参数、万能码
|
||
├─ rateLimit 接口限流：窗口、普通阈值、认证入口阈值
|
||
├─ operationLog 操作日志：总开关、查询类记录开关
|
||
├─ job 定时任务：日志保留天数
|
||
├─ tenant 租户：超管新增的默认归属租户
|
||
├─ app 应用：时区、演示模式、错误信息开关
|
||
├─ api 接口：驼峰转换、受信代理列表
|
||
├─ cors 跨域：允许来源
|
||
├─ file 文件上传：目录、域名、白名单、大小、临时保留天数
|
||
├─ generator 代码生成器：父菜单 ID、覆盖开关
|
||
└─ ip2region 归属地库：xdb 文件路径
|
||
```
|
||
|
||
## 核心配置速览
|
||
|
||
### 服务端
|
||
|
||
```yaml
|
||
server:
|
||
address: ":8000" # 监听地址与端口
|
||
openapiPath: "/api.json" # OpenAPI 文档路径（原生自动生成）
|
||
swaggerPath: "" # Swagger UI（本地托管 resource/swagger/）
|
||
errorStack: true # 响应携带错误堆栈（生产建议 false）
|
||
graceful: true # 优雅重启
|
||
```
|
||
|
||
### 数据库与缓存
|
||
|
||
```yaml
|
||
database:
|
||
default:
|
||
type: "mysql"
|
||
link: "mysql:root:root@tcp(127.0.0.1:3306)/easygoadmin.goframe.elevue?charset=utf8mb4&parseTime=true&loc=Local"
|
||
debug: false # 调试期可开 SQL 日志，生产关闭
|
||
redis:
|
||
default:
|
||
address: "127.0.0.1:6379"
|
||
pass: "123456"
|
||
```
|
||
|
||
### JWT 与验证码
|
||
|
||
```yaml
|
||
jwt:
|
||
secret: "…" # 签名密钥（生产必须改）
|
||
issuer: "easygoadmin"
|
||
accessTokenExpire: 7200 # 访问令牌 2 小时
|
||
refreshTokenExpire: 604800 # 刷新令牌 7 天
|
||
captcha:
|
||
expire: 300
|
||
bypassCode: "618618" # 万能验证码（生产必须留空）
|
||
length: 6
|
||
```
|
||
|
||
### 限流与防护
|
||
|
||
```yaml
|
||
rateLimit:
|
||
enable: true
|
||
limit: 120 # 普通接口每窗口每 IP 每路径上限
|
||
windowSeconds: 60
|
||
authLimit: 10 # 登录/验证码/令牌兑换独立更严阈值
|
||
operationLog:
|
||
enable: true
|
||
logQuery: true
|
||
app:
|
||
demo: false # 演示模式：true 时拦截全部写操作
|
||
errorMsg: true # 详细错误信息（生产建议 false）
|
||
```
|
||
|
||
### 文件与生成器
|
||
|
||
```yaml
|
||
file:
|
||
uploadDir: "…" # 物理根目录（当前配置为开发机绝对路径，建议改相对项目根；
|
||
# 容器部署用 GF_FILE_UPLOADDIR 覆盖并挂持久卷）
|
||
domainUrl: "http://file.goframe.elevue" # 文件访问域名，空则 /upload/ 相对路径
|
||
imageExt: "gif,jpg,jpeg,png,bmp,webp,svg"
|
||
fileExt: "gif,jpg,…,csv,mp3,mp4,sql,js,css"
|
||
maxSize: 10 # 单文件上限 MB
|
||
tempExpireDays: 7 # 临时目录保留天数（0=不清理）
|
||
generator:
|
||
parentMenuId: 189 # 新模块菜单挂载父级 ID
|
||
overwrite: true # 覆盖开关（true 生成即覆盖；false=缺失补生成、存在跳过）
|
||
ip2region:
|
||
path: "manifest/data/ip2region.xdb"
|
||
```
|
||
|
||
## 环境变量覆盖
|
||
|
||
容器化/CI 部署时无需改镜像内配置文件，用环境变量覆盖任意键（12-Factor 标准，**环境变量 > 配置文件**）：
|
||
|
||
```sh
|
||
GF_DATABASE_DEFAULT_LINK="mysql:root:secret@tcp(db:3306)/easygoadmin?charset=utf8mb4&parseTime=true"
|
||
GF_REDIS_DEFAULT_ADDRESS="redis:6379"
|
||
GF_APP_DEMO="false"
|
||
GF_FILE_UPLOADDIR="/data/upload"
|
||
```
|
||
|
||
**键名规则**：配置路径大写、点换下划线并加 `GF_` 前缀。
|
||
|
||
```text
|
||
配置键 database.default.link → 环境变量 GF_DATABASE_DEFAULT_LINK
|
||
配置键 file.uploadDir → 环境变量 GF_FILE_UPLOADDIR
|
||
配置键 jwt.secret → 环境变量 GF_JWT_SECRET
|
||
```
|
||
|
||
**生效语义**（实现见 `utility/config`，启动时经 `RegisterEnvOverride` 接线环境变量优先适配器）：
|
||
|
||
```text
|
||
优先级 环境变量 > 配置文件（未设环境变量时行为与纯文件读取完全一致）
|
||
空值 环境变量为空串视为未设置，不会清空配置文件中的有效值
|
||
范围 仅覆盖配置文件中已存在的键（新增键须先在 config.yaml 声明）
|
||
整节点 读取 database 整节点（如框架初始化连接）时逐叶叠加覆盖，
|
||
连接串同样被环境变量接管
|
||
```
|
||
|
||
**Docker 部署的推荐姿势**：`.env` 用 `MYSQL_HOST` 等运维友好名，由 compose 的 `environment` 块映射为 `GF_` 规范键注入（`docker/docker-compose.yml` 即此模式）；**不要**把友好名原样透传给应用——应用只认 `GF_` 前缀键。`.env` 值中含 `$` 须写成 `$$`（compose 插值会吞掉单 `$`）。
|
||
|
||
::: warning 生产环境必改项
|
||
1. `jwt.secret` 更换为随机长字符串
|
||
2. `captcha.bypassCode` 留空（万能验证码禁止上线）
|
||
3. `app.errorMsg: false`（不暴露错误堆栈）
|
||
4. `server.errorStack: false`
|
||
5. `database.default.debug: false`
|
||
6. `redis.default.pass` 设置强密码
|
||
:::
|