# 轻量级spring boot3.0 可视化管理properties和yaml配置

**Repository Path**: io123/spring-boot-propeties-web-starter

## Basic Information

- **Project Name**: 轻量级spring boot3.0 可视化管理properties和yaml配置
- **Description**: 全新自动化配置管理
全面支持spring boot 3.0，一套配置省去复杂配置参数管理，结构化配置页面，可视化配置，方便管理。
支持版本管理
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-04-26
- **Last Updated**: 2025-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Props Management Spring Boot Starter

一个功能强大的Spring Boot配置文件管理界面的Starter，支持可视化管理properties和YAML配置文件，提供在线编辑、版本管理、变更追踪和文件过滤等高级功能。

## 项目结构

本项目采用**多模块Maven架构**，便于开发和使用：

```
props-management-parent/
├── props-starter/          # 核心Starter模块
│   ├── src/main/java/      # Starter核心代码
│   ├── src/main/resources/ # Web界面和配置
│   └── pom.xml            # Starter依赖配置
├── props-demo/            # 演示和测试模块
│   ├── src/main/java/     # 演示应用代码
│   ├── src/main/resources/ # 演示配置文件
│   └── pom.xml           # 演示应用配置
├── pom.xml               # 父项目配置
├── build-starter.sh      # Starter构建脚本
└── run-demo.sh          # 演示应用启动脚本
```

**模块说明**:
- **props-starter**: 可独立打包的Spring Boot Starter库
- **props-demo**: 演示应用，展示Starter的所有功能

## 功能特性

### 🏗️ 核心功能
- 📁 **配置文件管理**: 自动扫描并显示项目中的properties和YAML配置文件
- ✏️ **智能在线编辑**: 可视化编辑配置项，支持启动时/运行时配置区分
- 📝 **版本管理**: 每次修改可创建版本，支持版本备注和历史查看
- 🎨 **现代化界面**: 基于Vue3构建的美观响应式管理界面
- 🔧 **零配置启动**: 开箱即用，支持自定义配置

### 🚀 高级功能
- 🔒 **配置可编辑性控制**: 自动识别启动时配置（如server.port、数据源配置）并标记为只读
- 📊 **变更比较**: 实时显示当前配置值与最新保存版本的差异
- 💾 **前端缓存**: 自动缓存未保存的配置修改，防止意外丢失
- 🎯 **文件排除系统**: 支持多种文件排除模式，灵活控制扫描范围
- 🌐 **UTF-8编码支持**: 完整支持中文等多语言配置内容
- 📱 **响应式界面**: 支持列宽调整、悬浮提示等用户体验优化
- 🖼️ **iframe嵌入支持**: 提供API接口支持在任意外部网站中嵌入Props Management界面

## 系统要求

- Spring Boot 3.0+
- Java 17+
- Maven 3.6+

## 🚀 快速演示

### 运行内置演示

项目内置了一个完整的演示应用，包含多种类型的配置文件，可以立即体验所有功能：

**方式一：使用启动脚本（推荐）**

Linux/macOS:
```bash
./run-demo.sh
```

Windows:
```cmd
run-demo.bat
```

**方式二：手动启动**

```bash
# 1. 构建并安装Starter模块
./build-starter.sh

# 2. 启动演示应用
cd props-demo
mvn spring-boot:run -Dspring-boot.run.profiles=demo
```

演示应用启动后，访问以下地址：

- 🎯 **配置管理界面**: http://localhost:8080/props-management
- 🔧 **演示API**: 
  - 当前配置: http://localhost:8080/demo/config
  - 健康检查: http://localhost:8080/demo/health  
  - 系统信息: http://localhost:8080/demo/info

### 演示功能

演示应用包含以下配置文件：

1. **application-demo.properties** - 基础配置文件，包含数据库、缓存、安全等配置
2. **config/demo-services.yml** - 复杂YAML配置，包含微服务、监控、集成等配置
3. **demo/feature-flags.properties** - 功能开关配置文件

你可以：
- ✏️ 在管理界面中修改配置值（支持中文等多语言）
- 🔒 查看启动时配置的只读保护（如server.port等）
- ⚠️ 实时查看哪些配置已被修改（黄色高亮显示）
- 💾 体验前端缓存功能（刷新页面后修改仍保留）
- 📊 查看修改后的效果（通过访问 `/demo/config` 接口）
- 💾 保存配置版本并添加备注
- 📜 查看版本历史和内容
- 🗑️ 删除不需要的版本

## 开发指南

### 构建Starter

```bash
# 构建和安装Starter到本地Maven仓库
./build-starter.sh
```

此脚本会：
1. 编译父项目和所有模块
2. 打包Starter模块
3. 安装到本地Maven仓库
4. 显示如何在其他项目中使用

### 在你的项目中使用

#### 1. 添加依赖

在你的Spring Boot项目中添加以下依赖：

```xml
<dependency>
    <groupId>com.props</groupId>
    <artifactId>props-management-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

#### 2. 启动应用

无需额外配置，启动你的Spring Boot应用后访问：

```
http://localhost:8080/props-management
```

#### 3. 配置版本管理（可选）

如果需要版本管理功能，在`application.properties`中添加：

```properties
# 启用版本管理，配置版本保存目录
props.management.version-dir=/path/to/version/storage
```

## 配置说明

所有配置项都以`props.management`为前缀：

### 基础配置

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `enabled` | Boolean | `true` | 是否启用配置管理功能 |
| `version-dir` | String | 无 | 版本管理目录，不配置则不启用版本管理 |
| `scan-paths` | String[] | `["", "config/"]` | 配置文件扫描路径 |
| `management-path` | String | `/props-management` | 管理界面访问路径 |
| `allow-online-edit` | Boolean | `true` | 是否允许在线编辑 |
| `max-versions` | Integer | `10` | 最大保留版本数量 |

### 文件排除配置

支持三种文件排除方式，可灵活组合使用：

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `exclude-files` | String[] | `[]` | 排除的文件模式，支持通配符（*, ?） |
| `exclude-prefixes` | String[] | `[]` | 排除文件名前缀 |
| `exclude-suffixes` | String[] | `[]` | 排除文件名后缀 |

### 配置示例

```properties
# 基础配置
props.management.enabled=true
props.management.management-path=/admin/config

# 版本管理配置
props.management.version-dir=/data/config-versions
props.management.max-versions=20

# 扫描配置
props.management.scan-paths=,config/,custom/
props.management.allow-online-edit=true

# 文件排除配置 - 支持通配符匹配
props.management.exclude-files=test-*.properties,temp.yml,*-local.*,bootstrap.properties

# 文件排除配置 - 按前缀排除
props.management.exclude-prefixes=test-,temp-,local-,dev-

# 文件排除配置 - 按后缀排除  
props.management.exclude-suffixes=-test.properties,-dev.yml,-local.yaml,-temp.properties
```

### 通配符支持

文件排除的通配符模式支持：
- `*`: 匹配任意数量的字符
- `?`: 匹配单个字符
- 精确匹配：无通配符时进行完全匹配

示例：
- `test-*.properties` - 匹配所有以`test-`开头的properties文件
- `config-?.yml` - 匹配`config-a.yml`、`config-1.yml`等
- `application-local.properties` - 精确匹配特定文件

## 使用说明

### 配置文件管理

1. **查看配置文件**: 左侧列表显示所有扫描到的配置文件
2. **选择文件**: 点击文件名查看其配置内容
3. **智能编辑**: 点击配置项的"编辑"按钮修改值
   - 🔒 启动时配置（如server.port、数据源配置）显示锁定图标，无法编辑
   - ✏️ 运行时配置可以正常编辑
4. **变更追踪**: 修改后的配置项会高亮显示，便于识别变更
5. **保存生效**: 修改后的配置立即生效到Spring Environment中

### 高级功能

#### 配置可编辑性控制

系统自动识别以下类型的启动时配置并设为只读：

**服务器配置**:
- `server.port`, `server.address`, `server.servlet.context-path`

**数据源配置**:
- `spring.datasource.*` (URL、用户名、密码等)

**应用配置**:
- `spring.application.name`, `spring.profiles.active`

**安全配置**:
- `management.endpoints.*`, `management.security.*`

#### 变更比较功能

- ⚠️ **修改标识**: 已修改的配置项会显示黄色警告图标
- 🔍 **悬浮提示**: 鼠标悬浮在修改的配置项上可查看原值 vs 当前值
- 📊 **统计显示**: 标题栏显示修改的配置项数量

#### 前端缓存系统

- 💾 **自动缓存**: 修改配置后自动保存到浏览器本地存储
- 🔄 **断点续传**: 页面刷新后自动恢复未保存的修改
- 📊 **缓存状态**: 实时显示当前文件和全局的缓存数量
- 🗑️ **缓存管理**: 支持清空单个文件或全部缓存
- ⚠️ **缓存提醒**: 有缓存时显示醒目的提醒条

### 版本管理

1. **保存版本**: 点击"保存版本"按钮，输入备注信息保存当前配置快照
2. **查看历史**: 点击"查看版本"查看所有历史版本
3. **版本对比**: 可查看各版本的详细内容（支持UTF-8编码）
4. **版本清理**: 超过最大版本数时自动清理旧版本
5. **缓存清理**: 保存版本后自动清空相关的前端缓存

## 界面功能

### 主界面
![img.png](docs/img.png)
- **配置文件列表**: 显示文件名、类型和大小
- **配置项表格**: 展示key-value配置项，支持列宽调整
- **实时编辑**: 支持键盘快捷键（Enter保存，Esc取消）
- **可视化标识**: 
  - 🔒 只读配置显示锁定图标
  - ⚠️ 已修改配置显示警告图标
  - 💾 缓存配置显示特殊标识

### 版本管理

- **版本列表**: 显示版本号、备注和创建时间
- **版本查看**: 在新窗口查看版本内容（支持UTF-8）
- **版本删除**: 支持删除不需要的版本

### 用户体验优化

- **响应式设计**: 适配不同屏幕尺寸
- **列宽调整**: 可拖拽调整表格列宽，双击恢复默认
- **悬浮提示**: 丰富的悬浮提示信息
- **Toast通知**: 操作结果的即时反馈
- **加载状态**: 清晰的加载和错误状态提示

## 🖼️ iframe嵌入功能

Props Management提供了强大的iframe嵌入支持，允许在任意外部网站中集成配置管理界面。

### 功能特性

- ✅ **跨域支持**: 完整的CORS配置，支持从任意域名调用
- ✅ **动态路径**: 自动适配自定义管理路径配置
- ✅ **参数自定义**: 支持自定义iframe尺寸、边框、标题等
- ✅ **多种接口**: 提供HTML和JSON两种格式的API接口
- ✅ **安全沙箱**: iframe包含适当的安全属性设置

### API接口

#### 1. HTML接口（直接返回iframe代码）

```http
GET /api{管理路径}/embed?width=100%&height=600px&border=1&title=Props+Management
```

**返回**: 直接可用的iframe HTML代码

**示例**:
```bash
curl "http://localhost:8080/api/demo/props-management/embed?width=800px&height=500px"
```

#### 2. JSON接口（返回结构化数据，推荐）

```http
GET /api{管理路径}/embed-json?width=100%&height=600px&border=1&title=Props+Management
```

**返回**: JSON格式的响应，包含iframe代码和相关信息

**示例**:
```bash
curl "http://localhost:8080/api/demo/props-management/embed-json?width=800px&height=500px"
```

**响应格式**:
```json
{
  "success": true,
  "iframeHtml": "<iframe src=\"...\">...</iframe>",
  "iframeUrl": "http://localhost:8080/demo/props-management/index.html",
  "managementPath": "/demo/props-management",
  "baseUrl": "http://localhost:8080"
}
```

### 支持的参数

| 参数名 | 默认值 | 说明 | 示例 |
|--------|--------|------|------|
| `width` | `100%` | iframe宽度 | `800px`, `100%`, `50vw` |
| `height` | `600px` | iframe高度 | `500px`, `80vh` |
| `border` | `1` | 边框宽度（0为无边框） | `0`, `1`, `2` |
| `title` | `Props Management` | iframe标题 | `配置管理`, `My Props` |

### 使用示例

#### 方法一：直接嵌入HTML（推荐）

```html
<!DOCTYPE html>
<html>
<head>
    <title>我的网站</title>
</head>
<body>
    <h1>系统配置管理</h1>
    <div id="props-container">加载中...</div>

    <script>
    // 直接获取iframe HTML代码
    fetch('/api/demo/props-management/embed?width=100%&height=600px&title=配置管理')
        .then(response => response.text())
        .then(html => {
            document.getElementById('props-container').innerHTML = html;
        })
        .catch(error => {
            console.error('加载失败:', error);
            document.getElementById('props-container').innerHTML = 
                '<div style="color: red;">配置管理界面加载失败</div>';
        });
    </script>
</body>
</html>
```

#### 方法二：使用JSON接口

```javascript
fetch('/api/demo/props-management/embed-json?width=800px&height=500px')
    .then(response => response.json())
    .then(data => {
        if (data.success) {
            // 插入iframe
            document.getElementById('props-container').innerHTML = data.iframeHtml;
            
            // 获取更多信息
            console.log('Props Management URL:', data.iframeUrl);
            console.log('管理路径:', data.managementPath);
            console.log('基础URL:', data.baseUrl);
        } else {
            throw new Error(data.message || '加载失败');
        }
    })
    .catch(error => {
        console.error('Error:', error);
        document.getElementById('props-container').innerHTML = 
            '<div style="color: red;">加载失败: ' + error.message + '</div>';
    });
```

#### 方法三：跨域调用

```javascript
// 从外部网站调用其他服务器的Props Management
fetch('http://your-props-server.com:8080/api/demo/props-management/embed-json', {
    mode: 'cors',  // 明确指定跨域模式
    headers: {
        'Accept': 'application/json'
    }
})
.then(response => {
    if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    return response.json();
})
.then(data => {
    if (data.success) {
        document.getElementById('external-props').innerHTML = data.iframeHtml;
    } else {
        throw new Error(data.message);
    }
})
.catch(error => {
    console.error('跨域调用失败:', error);
});
```

### URL模式说明

根据`props.management.management-path`配置，API的URL模式为：

- **HTML接口**: `http://your-server:port/api{管理路径}/embed`
- **JSON接口**: `http://your-server:port/api{管理路径}/embed-json`

**示例**:
- 默认配置：`http://localhost:8080/api/props-management/embed`
- 自定义路径：`http://localhost:8080/api/demo/props-management/embed`
- 其他路径：`http://localhost:8080/api/admin/config/embed`

### 示例页面

项目提供了完整的嵌入示例页面：

- **嵌入演示**: `http://localhost:8080/demo/props-management/embed-demo.html`
- **外部集成示例**: `http://localhost:8080/demo/props-management/external-embed-example.html`

这些页面包含：
- 💡 详细的使用说明和代码示例
- 🔧 可调整参数的实时预览
- 📋 复制粘贴的代码模板
- 🌐 跨域调用的完整示例

### 安全考虑

1. **CORS配置**: 接口支持`Access-Control-Allow-Origin: *`，生产环境建议限制允许的域名
2. **iframe沙箱**: 生成的iframe包含适当的`sandbox`属性
3. **内容安全**: 嵌入的iframe遵循同源策略和安全限制
4. **访问控制**: 建议结合Spring Security等进行访问权限控制

### 常见用例

1. **管理后台集成**: 在企业管理后台中嵌入配置管理功能
2. **监控面板**: 在运维监控大屏中嵌入配置状态
3. **开发工具**: 在开发者控制台中提供配置管理入口
4. **多系统集成**: 在微服务管理平台中统一配置管理界面
5. **客户端应用**: 在桌面应用或移动应用的WebView中嵌入配置功能

## 技术架构

### 后端

- **Spring Boot Auto Configuration**: 自动配置机制
- **REST API**: 提供配置管理接口，支持UTF-8编码
- **PropertySource动态更新**: 运行时更新配置
- **文件版本管理**: 本地文件存储版本历史
- **智能配置识别**: 自动区分启动时和运行时配置
- **文件过滤引擎**: 支持多种排除模式的文件扫描

### 前端

- **Vue 3**: 现代化JavaScript框架
- **原生HTML/CSS**: 无构建依赖，直接引入CDN
- **响应式设计**: 适配不同屏幕尺寸
- **异步交互**: 基于Axios的API调用，配置UTF-8编码
- **本地存储**: LocalStorage实现前端缓存
- **交互优化**: 丰富的用户界面交互功能

## 安全考虑

1. **生产环境**: 建议通过Spring Security等限制访问权限
2. **敏感配置**: 谨慎编辑包含密码等敏感信息的配置
3. **版本管理**: 版本文件可能包含敏感信息，注意存储目录权限
4. **启动时配置保护**: 自动保护关键的启动时配置，避免误操作
5. **文件排除**: 可排除测试、临时等敏感配置文件


### 扩展开发

可以通过以下方式扩展功能：

1. **自定义配置解析器**: 实现特定格式的配置文件解析
2. **权限控制**: 集成Spring Security实现访问控制
3. **审计日志**: 记录配置修改的详细日志
4. **集群同步**: 实现多实例间的配置同步
5. **自定义排除规则**: 扩展文件排除逻辑
6. **国际化支持**: 扩展多语言界面支持

## 常见问题

### Q: 修改配置后没有生效？

A: 确保`allow-online-edit`配置为`true`