012-kaopeilian/docs/规划/后端开发拆分策略/配置一致性检查清单.md

配置一致性检查清单

📋 概述

本文档记录了项目中各个组件之间必须保持一致的配置项，确保系统正常运行。

🔧 数据库配置一致性

MySQL连接配置

组件	配置文件	配置项	当前值
Docker Compose	../../docker-compose.yml	MYSQL_ROOT_PASSWORD	root
后端默认配置	../../kaopeilian-backend/app/config/settings.py	DATABASE_URL	mysql+aiomysql://root:root@localhost:3306/kaopeilian
启动脚本	../../kaopeilian-backend/start_mysql.py	DATABASE_URL 环境变量	mysql+aiomysql://root:root@localhost:3306/kaopeilian

⚠️ 重要：所有数据库连接字符串中的用户名、密码、主机、端口必须完全一致。

Redis连接配置

组件	配置文件	配置项	当前值
Docker Compose	../../docker-compose.yml	Redis端口	6379
后端配置	../../kaopeilian-backend/app/config/settings.py	REDIS_URL	redis://localhost:6379/0

🌐 网络配置一致性

端口配置

服务	组件	配置位置	端口
前端开发服务器	Vue3 + Vite	../../kaopeilian-frontend/vite.config.ts	3001
后端API服务器	FastAPI	../../kaopeilian-backend/start_mysql.py	8000
MySQL数据库	Docker	../../docker-compose.yml	3306
Redis缓存	Docker	../../docker-compose.yml	6379

CORS配置

组件	配置文件	配置项	允许的源
后端	../../kaopeilian-backend/app/config/settings.py	BACKEND_CORS_ORIGINS	["http://localhost:3000", "http://localhost:3001", "http://localhost:5173"]

⚠️ 重要：前端开发服务器的端口必须在后端CORS配置中明确允许。

🔐 认证配置一致性

JWT配置

组件	配置文件	配置项	当前值
后端	../../kaopeilian-backend/app/config/settings.py	SECRET_KEY	环境变量或默认值
后端	../../kaopeilian-backend/app/config/settings.py	ALGORITHM	HS256
后端	../../kaopeilian-backend/app/config/settings.py	ACCESS_TOKEN_EXPIRE_MINUTES	30

认证存储键名

组件	存储位置	键名	用途
前端	localStorage	access_token	访问令牌
前端	localStorage	refresh_token	刷新令牌
前端	localStorage	current_user	当前用户信息

⚠️ 重要：前端的authManager和所有组件必须使用相同的localStorage键名。

📡 API配置一致性

请求格式

API端点	前端发送格式	后端接收格式	Content-Type
/api/v1/auth/login	JSON	Pydantic模型	application/json
/api/v1/auth/register	JSON	Pydantic模型	application/json

API基础路径

组件	配置文件	配置项	当前值
前端	../../kaopeilian-frontend/src/api/config.ts	baseURL	http://localhost:8000
后端	../../kaopeilian-backend/app/config/settings.py	API_V1_STR	/api/v1

🏗️ 环境配置一致性

开发环境

组件	配置文件	环境标识	当前值
前端	../../kaopeilian-frontend/package.json	NODE_ENV	development
后端	../../kaopeilian-backend/app/config/settings.py	ENVIRONMENT	development

✅ 配置检查脚本

自动检查命令

# 在项目根目录执行
cd ../../
./check-config.sh

手动检查清单

• Docker服务正常启动 (docker-compose ps)
• 数据库连接成功 (后端日志无连接错误)
• 前端可以访问后端API (无CORS错误)
• 认证流程完整工作 (登录成功并跳转)
• 权限控制正常 (不同角色访问不同页面)

🚨 常见配置不一致问题

1. 数据库密码不匹配

症状：后端启动时报"Access denied"错误 解决：检查docker-compose.yml的MYSQL_ROOT_PASSWORD与settings.py的DATABASE_URL密码是否一致

2. CORS配置缺失

症状：前端控制台报CORS错误 解决：确保前端运行端口已添加到后端BACKEND_CORS_ORIGINS列表

3. API格式不匹配

症状：前端请求返回400或422错误 解决：检查前端发送的Content-Type和数据格式是否与后端Pydantic模型匹配

4. 认证状态不同步

症状：登录成功但路由守卫仍然拦截 解决：确保前端使用统一的authManager，localStorage键名一致

📝 更新记录

日期	更新内容	更新人
2025-09-20	初始创建配置一致性检查清单	AI Assistant
2025-09-20	添加认证授权模块配置项	AI Assistant

---

注意：每次添加新的配置项或修改现有配置时，都必须更新此文档，确保团队成员了解配置要求。