---
title: 配置管理 API | 全局与租户配置接口 - MengStack官方文档
---

# 配置管理接口

配置分为两级：全局配置（所有租户共享）和租户配置（覆盖全局默认）。

所有接口需要认证，并携带 `X-Tenant-ID` 头。

## 全局配置

### 列出全局配置

**`GET /api/v1/settings`**

#### 响应

```json
{
  "code": 0,
  "data": [
    {
      "id": 1,
      "tenant_id": "",
      "key": "site_name",
      "value": "MengStack",
      "type": "string",
      "scope": "global",
      "updated_by": 1,
      "updated_at": "2026-10-03T10:00:00+08:00"
    }
  ]
}
```

### 获取全局配置

**`GET /api/v1/settings/global/:key`**

#### 路径参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `key` | string | 配置键名 |

#### 响应

返回 `SettingDTO`。

### 更新全局配置

**`PUT /api/v1/settings/global/:key`**

#### 请求体

```json
{
  "value": "新值",
  "type": "string"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `value` | string | 是 | 配置值 |
| `type` | string | 否 | 类型标记（string / number / boolean / json），默认 string |

---

## 租户配置

### 列出租户配置

**`GET /api/v1/settings/tenant`**

返回当前租户的所有配置项。

### 获取租户配置

**`GET /api/v1/settings/tenant/:key`**

#### 路径参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `key` | string | 配置键名 |

### 更新租户配置

**`PUT /api/v1/settings/tenant/:key`**

#### 请求体

```json
{
  "value": "租户级覆盖值",
  "type": "string"
}
```

如果该 key 不存在，自动创建（upsert 语义）。

### 删除租户配置

**`DELETE /api/v1/settings/tenant/:key`**

删除后，该租户将回退到全局默认值。

---

## 配置优先级

```
租户配置 > 全局配置 > 默认值
```

读取配置时，应用层按此优先级合并。