998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
176 lines
4.4 KiB
Markdown
176 lines
4.4 KiB
Markdown
# 配置管理使用说明
|
|
|
|
## 📋 概述
|
|
|
|
本文档说明如何使用配置管理工具来确保系统配置一致性，避免常见的配置错误。
|
|
|
|
## 🛠️ 工具列表
|
|
|
|
### 1. 配置一致性检查清单
|
|
**文件**: `配置一致性检查清单.md`
|
|
**用途**: 详细记录所有需要保持一致的配置项
|
|
**使用场景**:
|
|
- 新开发人员入职时的配置参考
|
|
- 系统部署前的配置核对
|
|
- 故障排查时的配置检查
|
|
|
|
### 2. 自动配置检查脚本
|
|
**文件**: `../../../check-config.sh`
|
|
**用途**: 自动检查系统配置状态
|
|
**使用方法**:
|
|
```bash
|
|
# 在项目根目录执行
|
|
./check-config.sh
|
|
```
|
|
|
|
**检查内容**:
|
|
- ✅ Docker服务状态
|
|
- ✅ 端口占用情况
|
|
- ✅ 服务健康状态
|
|
- ✅ 配置文件存在性
|
|
- ✅ 认证功能测试
|
|
- ✅ CORS配置验证
|
|
|
|
### 3. 通用基础提示词
|
|
**文件**: `子agent/00-通用基础/base_prompt.md`
|
|
**用途**: 为所有子agent提供统一的开发规范和调试方法
|
|
**核心内容**:
|
|
- 系统化问题定位策略
|
|
- 配置一致性检查方法
|
|
- 常见错误处理模式
|
|
- 开发最佳实践
|
|
|
|
## 🚀 快速开始
|
|
|
|
### 第一次使用
|
|
1. **阅读配置清单**:
|
|
```bash
|
|
cat "配置一致性检查清单.md"
|
|
```
|
|
|
|
2. **运行配置检查**:
|
|
```bash
|
|
cd ../../../
|
|
./check-config.sh
|
|
```
|
|
|
|
3. **根据结果修复问题**:
|
|
- 如果有失败项，按照建议进行修复
|
|
- 重新运行检查直到所有项都通过
|
|
|
|
### 日常开发使用
|
|
|
|
#### 开发前检查
|
|
```bash
|
|
# 快速检查系统状态
|
|
cd ../../../
|
|
./check-config.sh
|
|
|
|
# 如果有问题，启动必要服务
|
|
docker-compose up -d
|
|
```
|
|
|
|
#### 遇到问题时
|
|
1. **先运行配置检查**:
|
|
```bash
|
|
cd ../../../
|
|
./check-config.sh
|
|
```
|
|
|
|
2. **对照配置清单**:
|
|
- 检查数据库连接配置
|
|
- 验证CORS域名设置
|
|
- 确认API格式匹配
|
|
|
|
3. **查看通用提示词**:
|
|
- 按照分层验证法定位问题
|
|
- 使用错误分类处理方法
|
|
|
|
## 📊 配置检查结果解读
|
|
|
|
### 正常输出示例
|
|
```
|
|
🎉 所有检查都通过了！系统配置正常。
|
|
通过: 15
|
|
失败: 0
|
|
```
|
|
|
|
### 异常输出示例
|
|
```
|
|
⚠️ 发现 3 个问题，请检查配置。
|
|
通过: 12
|
|
失败: 3
|
|
|
|
💡 解决建议:
|
|
1. 确保Docker服务已启动: docker-compose up -d
|
|
2. 检查端口是否被占用或服务未启动
|
|
3. 参考 '配置一致性检查清单.md' 核对配置
|
|
```
|
|
|
|
## 🔧 常见问题解决
|
|
|
|
### 1. Docker服务未运行
|
|
**症状**: `❌ Docker 服务 mysql 未运行`
|
|
**解决**:
|
|
```bash
|
|
cd ../../../
|
|
docker-compose up -d
|
|
```
|
|
|
|
### 2. 端口被占用
|
|
**症状**: `❌ 端口 8000 未占用`
|
|
**解决**: 检查对应服务是否启动，或端口是否被其他程序占用
|
|
|
|
### 3. 认证功能失败
|
|
**症状**: `❌ 检查登录API 失败`
|
|
**解决**:
|
|
1. 检查后端服务是否正常运行
|
|
2. 验证数据库连接配置
|
|
3. 确认测试用户是否存在
|
|
|
|
### 4. CORS配置问题
|
|
**症状**: `❌ 检查CORS预检请求 失败`
|
|
**解决**:
|
|
1. 检查后端CORS配置中是否包含前端端口
|
|
2. 确认前端运行在正确的端口上
|
|
|
|
## 📝 配置维护流程
|
|
|
|
### 添加新配置项
|
|
1. 在`配置一致性检查清单.md`中记录新配置
|
|
2. 如需要，在`../../../check-config.sh`中添加检查逻辑
|
|
3. 更新`子agent/00-通用基础/base_prompt.md`中的相关说明
|
|
|
|
### 修改现有配置
|
|
1. 同时更新所有相关组件的配置
|
|
2. 运行配置检查脚本验证
|
|
3. 更新配置清单文档
|
|
|
|
### 部署新环境
|
|
1. 复制配置文件模板
|
|
2. 根据环境修改配置值
|
|
3. 运行配置检查确保一致性
|
|
4. 测试核心功能正常工作
|
|
|
|
## 🎯 最佳实践
|
|
|
|
### 开发团队协作
|
|
1. **统一工具**: 所有团队成员都使用相同的配置检查工具
|
|
2. **定期检查**: 每天开始工作前运行一次配置检查
|
|
3. **问题共享**: 遇到新的配置问题时，及时更新文档和工具
|
|
|
|
### 配置管理原则
|
|
1. **版本控制**: 所有配置文件都纳入版本控制
|
|
2. **环境隔离**: 不同环境使用不同的配置文件
|
|
3. **敏感信息**: 密码等敏感信息使用环境变量管理
|
|
4. **文档同步**: 配置变更时同步更新文档
|
|
|
|
### 故障处理流程
|
|
1. **快速定位**: 使用配置检查脚本快速发现问题
|
|
2. **系统排查**: 按照分层验证法逐层检查
|
|
3. **根本解决**: 不仅修复症状，还要解决根本原因
|
|
4. **经验沉淀**: 将解决方案更新到文档和工具中
|
|
|
|
---
|
|
|
|
**记住**: 配置一致性是分布式系统稳定运行的基础，投入时间维护配置管理工具能够大大提高开发效率和系统可靠性！ |