# 5.12 系统配置管理

:::tip 概述
系统配置采用两级结构：config（配置分组）+ config_item（配置项）。面向"网站名称、Logo、开关类参数"等运行时可改的业务配置，与 manifest/config.yaml（工程配置）职责分离。
:::

## 两级结构

```text
goframe_config       配置分组：name / code（uk_code 全局唯一）/ sort
goframe_config_item  配置项：config_id（所属分组）/ value / options / type / status / sort

示例：
  config:      { name: "网站配置", code: "web" }
  config_item: { key: "siteName", value: "EasyGoAdmin", type: "input" }
               { key: "siteLogo", value: "/upload/...", type: "image" }
```

## 职责边界（与 config.yaml 的区分）

| | config 模块（数据库） | config.yaml（文件） |
|--|---------------------|-------------------|
| 面向 | 业务运营（站名/Logo/开关） | 工程运行（数据库/Redis/JWT/限流） |
| 修改方式 | 管理页面在线改 | 改文件/环境变量 + 重启 |
| 消费方 | 前端站点、业务接口 | 后端启动与中间件 |
| 例 | 网站名称、备案号 | database.default.link、jwt.secret |

**判据**：改了要不要重启？要重启的是 yaml；不重启即时生效的是 config 模块。

## 接口清单

```text
config（/api/config）       七件套 sys:config:*
  GET  /api/config/web/index   sys:configWeb:data   获取网站配置
  POST /api/config/web/save    sys:configWeb:save   保存网站配置
config_item（/api/config/item） 七件套 sys:configitem:*
```

注意权限码特例：网站配置是 `sys:configWeb:data|save`（非 `sys:config:web*`）。

## 网站配置流（前端 setting 页面）

```text
前端加载：GET /api/config/web/index
  → 后端按分组 code="web" 聚合 config_item
  → 返回 {siteName, siteLogo, ...}（type 决定前端渲染控件）

保存：POST /api/config/web/save
  → 批量更新 config_item.value
  → 其他实例下次读取即生效（在线配置，无缓存层）
```

## 配置项类型（type）

| type | 前端控件 | 示例 |
|------|---------|------|
| input | 文本框 | 站点名称 |
| image | 图片选择 | 站点 Logo |
| select | 下拉（options 提供选项） | 开关类配置 |
| textarea | 多行文本 | 备案信息/统计代码 |

options 列存 JSON 选项数组，配合 select 类型使用。

## 开发新配置项

```text
1. 字典/配置管理页面：确认 config 分组存在（如 web），不存在先建分组
2. config_item 新增行：key / value / type / options / sort
3. 前端读取处消费（GET /api/config/web/index 的返回字段）
4. 后端需要消费时（少用）：查询 config_item 按 key 取值
```

## 运维注意

+ config 模块是**平台级**（无租户隔离）——租户差异化配置不在设计内
+ code 全局唯一（uk_code），分组语义清晰避免冲突
+ 在线保存即时生效，无需重启；无缓存层（读频率低，直接查库）
+ 与 `app.demo` 等工程开关分离——工程开关不放 config 模块（重启才能改语义的不适宜在线化）