签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,142 @@
+# 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` 设置强密码
+:::