2.5 配置文件说明

概述

本项目唯一运行时配置文件为 manifest/config/config.yaml，GoFrame gcfg 加载。环境变量覆盖规则：使用 GF_ 前缀，例如 GF_DATABASE_DEFAULT_LINK。本节速览全部配置块，完整键值速查见附录 C 配置项速查。

配置文件全景

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 文件路径

核心配置速览

服务端

server:
  address:     ":8000"          # 监听地址与端口
  openapiPath: "/api.json"      # OpenAPI 文档路径（原生自动生成）
  swaggerPath: ""               # Swagger UI（本地托管 resource/swagger/）
  errorStack:  true             # 响应携带错误堆栈（生产建议 false）
  graceful:     true             # 优雅重启

数据库与缓存

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 与验证码

jwt:
  secret:            "…"         # 签名密钥（生产必须改）
  issuer:            "easygoadmin"
  accessTokenExpire: 7200        # 访问令牌 2 小时
  refreshTokenExpire: 604800     # 刷新令牌 7 天
captcha:
  expire:     300
  bypassCode: "618618"          # 万能验证码（生产必须留空）
  length:     6

限流与防护

rateLimit:
  enable:        true
  limit:         120            # 普通接口每窗口每 IP 每路径上限
  windowSeconds: 60
  authLimit:     10             # 登录/验证码/令牌兑换独立更严阈值
operationLog:
  enable:   true
  logQuery: true
app:
  demo:     false              # 演示模式：true 时拦截全部写操作
  errorMsg: true               # 详细错误信息（生产建议 false）

文件与生成器

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 标准，环境变量 > 配置文件）：

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_ 前缀。

配置键 database.default.link  →  环境变量 GF_DATABASE_DEFAULT_LINK
配置键 file.uploadDir         →  环境变量 GF_FILE_UPLOADDIR
配置键 jwt.secret             →  环境变量 GF_JWT_SECRET

生效语义（实现见 utility/config，启动时经 RegisterEnvOverride 接线环境变量优先适配器）：

优先级   环境变量 > 配置文件（未设环境变量时行为与纯文件读取完全一致）
空值     环境变量为空串视为未设置，不会清空配置文件中的有效值
范围     仅覆盖配置文件中已存在的键（新增键须先在 config.yaml 声明）
整节点   读取 database 整节点（如框架初始化连接）时逐叶叠加覆盖，
         连接串同样被环境变量接管

Docker 部署的推荐姿势：.env 用 MYSQL_HOST 等运维友好名，由 compose 的 environment 块映射为 GF_ 规范键注入（docker/docker-compose.yml 即此模式）；不要把友好名原样透传给应用——应用只认 GF_ 前缀键。.env 值中含 $ 须写成 $$（compose 插值会吞掉单 $）。

生产环境必改项

1. jwt.secret 更换为随机长字符串
2. captcha.bypassCode 留空（万能验证码禁止上线）
3. app.errorMsg: false（不暴露错误堆栈）
4. server.errorStack: false
5. database.default.debug: false
6. redis.default.pass 设置强密码