rxthinkcmf/rxthinkcmf-wiki

Fork 0

Files

T

gitadmin e213a9b31d 签入版本

2026-10-08 17:50:29 +08:00

12 KiB

Raw Blame History

5.12 系统配置管理

:::tip 概述系统配置管理用于动态配置参数，支持分组管理。与参数管理的区别：配置管理支持键值对的分组管理（如网站配置、邮件配置），参数管理是独立的参数实体（如单个开关、阈值）。 :::

模块特点

特性	说明
Service 基类	`BaseService`（系统共享，不隔离）；读取封装 `ConfigService`
关联	与 ConfigItem 一对多（通过 config_id）
用途	网站名称、Logo、版权信息等动态配置
控制器	`ConfigController`（配置组）+ `ConfigItemController`（配置项）
值处理	`HasConfigValueProcessing` Trait：按 type 做文件迁移与 `valueList` 生成

数据库表结构

主表 `laravel_config`（配置组）

字段	类型	说明
id	int	主键，自增
name	varchar(150)	配置组名称（如「网站配置」）
code	varchar(150)	配置组编码（如 `website_config`）
sort	int	排序（升序）
note	varchar(255)	备注说明
create_user / create_time / update_user / update_time		审计字段（模型 Trait 自动写入）
is_delete	int	软删除标记（0=正常，1=已删除）

子表 `laravel_config_item`（配置项）

字段	类型	说明
id	int	主键，自增
config_id	int	所属配置组 ID（关联 laravel_config.id）
name	varchar(150)	配置项名称（如「网站名称」）
code	varchar(150)	配置项编码（如 `site_name`）
value	text	配置值，按 type 存相对路径、`文件名\|路径`、逗号串或富文本 HTML
options	text	选项串 `k=v,k=v`（逗号分隔），用于 radio / checkbox / select 等类型
type	varchar(150)	表单类型：hidden / readonly / number / text / textarea / password / radio / checkbox / select / selects / icon / date / datetime / image / images / file / files / ueditor
status	int	状态（1=正常，2=停用）
sort	int	排序（升序）
note	varchar(255)	配置项备注
create_user / create_time / update_user / update_time		审计字段
is_delete	int	软删除标记

API 接口

配置组

方法	路径	权限码	说明
GET	`/api/config/page`	sys:config:page	分页列表
GET	`/api/config/list`	sys:config:list	全量列表
GET	`/api/config/detail/{id}`	sys:config:detail	详情
POST	`/api/config/add`	sys:config:add	新增
PUT	`/api/config/update`	sys:config:update	修改
DELETE	`/api/config/delete/{id}`	sys:config:delete	删除
DELETE	`/api/config/batchDelete`	sys:config:batchDelete	批量删除

网站配置（快捷接口）

方法	路径	权限码	说明
GET	`/api/config/web/index`	sys:config:webIndex	获取网站配置（按组返回所有配置项）
POST	`/api/config/web/save`	sys:config:update	保存网站配置（批量更新配置项值）

配置项

方法	路径	权限码	说明
GET	`/api/config/item/page`	sys:config:page	分页列表
GET	`/api/config/item/list`	sys:config:list	全量列表
GET	`/api/config/item/detail/{id}`	sys:config:detail	详情
POST	`/api/config/item/add`	sys:config:add	新增
PUT	`/api/config/item/update`	sys:config:update	修改
DELETE	`/api/config/item/delete/{id}`	sys:config:delete	删除
DELETE	`/api/config/item/batchDelete`	sys:config:batchDelete	批量删除

配置项详情响应

GET /api/config/item/detail/{id}：

value — 数据库存储的原始值；
valueList — 按类型加工后的可展示值，供前端直接使用（不涉及的类型为 null）；
configCode — 所属配置组编码。

{
    "code": 0,
    "ok": true,
    "msg": "操作成功",
    "data": {
        "id": 7,
        "name": "网站图集",
        "code": "website_album",
        "value": "config/20260923/110133_AtVRHXAW.png,config/20260923/110133_8ERxsPCx.png,config/20260923/110133_lYnVEf9f.png",
        "options": "",
        "configId": 1,
        "type": "images",
        "status": 1,
        "sort": 30,
        "note": "网站图集",
        "createUser": "admin",
        "createTime": "2026-09-01 10:37:35",
        "updateUser": "admin",
        "updateTime": "2026-09-01 10:37:35",
        "isDelete": 0,
        "configCode": "website_config",
        "valueList": [
            "http://cdn.example.com/config/20260923/110133_AtVRHXAW.png",
            "http://cdn.example.com/config/20260923/110133_8ERxsPCx.png",
            "http://cdn.example.com/config/20260923/110133_lYnVEf9f.png"
        ]
    }
}

value 的类型化处理

配置项的 value 随 type 变化，保存与读取由 HasConfigValueProcessing Trait 统一处理， ConfigItemService（配置项 CRUD）与 ConfigService（网站配置）共用。文件一律落在 config/file.php 的 upload_dir 下的 config/ 子目录。

type	入库 value	详情 value	详情 valueList
`image`	`config/Ymd/xxx.png`（去域名 + 临时文件迁移）	完整 URL	`null`
`images`	逗号分隔的相对路径	原值	逐个完整 URL
`file` / `files`	`文件名\|相对路径`（逗号分隔）	原值	`文件名\|完整URL`
`checkbox`	逗号分隔原值	原值	拆分后的数组
`ueditor`	富文本 HTML，内嵌图片迁移为 `[IMG_URL]/config/...` 占位	占位还原为当前 `FILE_DOMAIN_URL`	`null`
其余类型	原值	原值	`null`

处理规则：

保存（beforeAdd / beforeUpdate）：走 save_file() —— 去掉域名前缀、把 temp/ 临时文件迁移到正式目录；富文本走 save_content() —— 迁移内容中的图片并写入 [IMG_URL] 占位；
读取：走 get_file_url() 补全域名；富文本把 [IMG_URL] 还原为 FILE_DOMAIN_URL；
迁移失败时保留原值，不清空字段；
image 与 ueditor 的 value 直接返回可渲染值（前端回显直连 value），其余类型 value 保持原值。

使用场景

场景	配置组	配置项示例
网站基本信息	网站配置	网站名称、Logo、版权信息、ICP备案号
邮件配置	邮件配置	SMTP服务器、端口、用户名、密码、发件人
短信配置	短信配置	API Key、模板ID、签名
存储配置	存储配置	存储类型（本地/OSS）、AccessKey、Bucket
支付配置	支付配置	商户号、密钥、回调地址
其他	自定义分组	任何需要后台动态配置的参数

代码示例

后端获取配置值

配置值可通过 ConfigService（网站配置快捷接口的封装）或 ConfigItem 模型直接查询：

<?php
use App\Models\ConfigItem;
use App\Models\Config;

// 获取单个配置项的值（按配置组 code + 配置项 code 查询）
$config = Config::where('code', 'website_config')->where('is_delete', 0)->first();
$value = $config
    ? ConfigItem::where('config_id', $config->id)
        ->where('code', 'site_name')
        ->where('status', 1)
        ->where('is_delete', 0)
        ->value('value')
    : null;
// 返回：'My CMS'

// 获取整个配置组的所有配置项（关联数组）
$config = Config::where('code', 'website_config')->where('is_delete', 0)->first();
if ($config) {
    $items = ConfigItem::where('config_id', $config->id)
        ->where('status', 1)
        ->where('is_delete', 0)
        ->pluck('value', 'code');
    // 返回：['site_name' => 'My CMS', 'site_logo' => '...', 'copyright' => '...']
}

网站配置快捷服务

// app/Services/ConfigService.php
public function getWebConfig(): array    // GET /api/config/web/index：按组返回 configId/configName/dataList（含 param、valueList）
public function saveWebConfig(array $data): void   // POST /api/config/web/save：按编码批量回写，经 save_file / save_content 归一化

前端获取配置值

GET /api/config/web/index 返回按配置组分组的配置项数组：

[
  {
    "configId": 1,
    "configName": "网站配置",
    "dataList": [
      {
        "id": 3, "configId": 1, "name": "网站Logo", "code": "website_logo",
        "value": "http://cdn.example.com/config/20260923/110055_w3KY8kS7.png",
        "valueList": null, "options": "", "type": "image",
        "status": 1, "sort": 10, "note": "网站Logo", "param": null
      },
      {
        "id": 7, "code": "website_album", "type": "images",
        "value": "config/20260923/110133_AtVRHXAW.png,config/20260923/110133_8ERxsPCx.png",
        "valueList": [
          "http://cdn.example.com/config/20260923/110133_AtVRHXAW.png",
          "http://cdn.example.com/config/20260923/110133_8ERxsPCx.png"
        ],
        "param": null
      },
      {
        "id": 11, "code": "website_keywords", "type": "checkbox",
        "value": "1,2,5,3",
        "valueList": ["1", "2", "5", "3"],
        "options": "1=软件架构,2=官方网站",
        "param": { "1": "软件架构", "2": "官方网站" }
      }
    ]
  }
]

取值约定：

image 与 ueditor 读 value（返回可直接渲染的完整 URL / 富文本 HTML）；
images / files 读 valueList（完整 URL 串、文件名|完整URL 串）；
radio / checkbox / select 的候选项读 param（由 options 解析成键值对象）；
其余类型的 value 为数据库原值，拼接 FILE_DOMAIN_URL 即可访问。

// 获取网站配置（按配置组分组）
const { data } = await http.get('/api/config/web/index')

data.forEach((group) => {
  group.dataList.forEach((item) => {
    // image / ueditor 取 value，images / files 取 valueList，选项类取 param
  })
})

网站配置保存接口

POST /api/config/web/save 的请求体为「配置项编码 => 配置值」的扁平结构，只更新已存在的生效配置项，编码不存在时忽略；数组值（多图 / 多文件 / 复选）按逗号拼接后入库，文件与图片同样迁移到 config/ 子目录。

# -----------------------------------------------------------------------------
# 批量保存网站配置（key 为配置项编码）
# -----------------------------------------------------------------------------
curl -X POST http://localhost:8000/api/config/web/save \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "website_name": "My CMS",
    "website_logo": "http://cdn.example.com/temp/20261007/123456_a1b2c3d4.png",
    "website_album": [
      "http://cdn.example.com/temp/20261007/123456_a1b2c3d4.png",
      "http://cdn.example.com/temp/20261007/123456_e5f6a7b8.png"
    ],
    "website_keywords": ["1", "2"]
  }'

与参数管理的区别

维度	配置管理（Config）	参数管理（Param）
数据结构	分组 + 配置项（一对多）	独立参数实体
适用场景	关联性强的配置（如网站配置包含多个字段）	独立的开关、阈值
管理界面	按组展示，表单式编辑	列表式管理
获取方式	`ConfigItem` 模型查询或 `/api/config/web/index` 接口	`ParamService::get(code)`
服务封装	`ConfigService`（webIndex/webSave）	`ParamService`（带缓存）

数据库操作示例

-- 查询所有未删除的配置组
SELECT * FROM laravel_config WHERE is_delete = 0 ORDER BY sort;

-- 查询某个配置组下的所有启用配置项
SELECT ci.* FROM laravel_config_item ci
INNER JOIN laravel_config c ON ci.config_id = c.id
WHERE c.code = 'website_config' AND ci.status = 1 AND ci.is_delete = 0
ORDER BY ci.sort;

-- 直接更新配置项值
UPDATE laravel_config_item SET value = '新网站名称'
WHERE code = 'site_name' AND config_id = (
  SELECT id FROM laravel_config WHERE code = 'website_config' AND is_delete = 0
);

12 KiB Raw Blame History Unescape Escape