# 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` 设置强密码
:::