# HomeAssistant-server **Repository Path**: tomorrowgit/home-assistant-server ## Basic Information - **Project Name**: HomeAssistant-server - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-06-19 - **Last Updated**: 2025-06-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # HomeAssistant Server 基于FastAPI构建的智能家居控制系统后端服务，采用阿里开源Python项目架构设计，为Flutter前端应用提供RESTful API接口。 ## 🏗️ 项目架构 ``` HomeAssistant-server/ ├── app/ # 核心业务应用目录 │ ├── api/ # 接口层（FastAPI） │ │ ├── endpoints/ # API端点 │ │ └── router.py # 路由汇总 │ ├── services/ # 服务层（业务逻辑） │ ├── models/ # 数据模型（SQLAlchemy ORM） │ ├── repositories/ # 数据访问层（Repository模式） │ ├── schemas/ # 请求/响应 DTO（Pydantic） │ ├── rules/ # 自动化规则引擎 │ ├── devices/ # 设备管理（驱动/协议适配） │ ├── scenes/ # 场景编排模块 │ └── core/ # 核心模块（配置、数据库、异常等） ├── jobs/ # 定时任务（APScheduler） ├── eventbus/ # 事件总线（异步解耦） ├── common/ # 通用工具（配置、日志、常量等） ├── tests/ # 单元测试和集成测试 ├── scripts/ # 部署、运维、初始化脚本 ├── migrations/ # 数据库迁移脚本 ├── docker/ # Docker配置文件 ├── main.py # 应用入口 ├── config.py # 配置中心 ├── requirements.txt # Python依赖 ├── .env # 环境变量配置 └── README.md # 项目说明 ``` ## ✨ 主要功能 ### 🔌 设备管理 - 智能设备自动发现和连接 - 支持多种设备类型（灯泡、开关、传感器、门锁、摄像头、温控器、音箱） - 设备状态实时监控和控制 - 设备分组和位置管理 - 设备使用统计和日志 ### 🎬 场景管理 - 自定义场景创建和编辑 - 场景动作编排（设备控制、延时、通知） - 场景执行状态跟踪 - 场景分类和收藏 - 场景执行统计 ### 🤖 自动化规则 - 基于时间、设备状态、传感器数值的触发器 - 灵活的条件组合（AND/OR逻辑） - 多样化的执行动作 - 自动化规则优先级管理 - 执行历史和统计 ### 👥 用户管理 - 用户注册、登录、权限管理 - 基于JWT的身份认证 - 角色权限控制（管理员、用户、访客） - 用户偏好设置 - 操作日志记录 ### 📊 系统监控 - 系统运行状态监控 - 设备在线状态统计 - 操作日志记录和查询 - 系统配置管理 - 性能指标收集 ## 🛠️ 技术栈 ### 后端框架 - **FastAPI 0.104.1**: 现代异步Web框架 - **Uvicorn**: ASGI服务器 - **Pydantic**: 数据验证和序列化 - **SQLAlchemy 2.0**: 异步ORM框架 ### 数据存储 - **MySQL 5.6.16**: 主数据库 - **Redis**: 缓存和会话存储 - **连接池**: 数据库连接池管理 ### 任务和事件 - **APScheduler**: 定时任务调度 - **自定义事件总线**: 异步事件处理 - **asyncio**: 异步编程支持 ### 监控和日志 - **Loguru**: 结构化日志 - **Prometheus**: 指标收集 - **Grafana**: 监控仪表板 ### 部署和运维 - **Docker**: 容器化部署 - **Nginx**: 反向代理和负载均衡 - **Docker Compose**: 多服务编排 ## 🚀 快速开始 ### 环境要求 - Python 3.8+ (推荐 3.9+) - MySQL 8.0+ (可选) - Redis 6.0+ (可选) ### 🚀 一键启动 (推荐) ```bash # 快速启动 - 自动检查依赖和配置 python quick_start.py ``` ### 📋 诊断启动问题 ```bash # 如果启动遇到问题，运行诊断脚本 python diagnose.py ``` ### 🔧 手动安装 #### 1. 创建虚拟环境 ```bash python3 -m venv .venv source .venv/bin/activate # macOS/Linux # 或 .venv\Scripts\activate # Windows ``` #### 2. 安装依赖 ```bash # 方式1：安装核心依赖（推荐） pip install -r requirements-core.txt # 方式2：使用自动安装脚本 python install_deps.py # 方式3：最小依赖安装 pip install fastapi uvicorn python-dotenv pydantic ``` #### 3. 配置环境 ```bash # 配置文件已存在，可直接使用 # 或使用配置管理工具 python manage_config.py ``` #### 4. 初始化数据库（可选） ```bash # 如果使用MySQL，执行数据库初始化 mysql -u root -p < migrations/create_tables.sql ``` #### 5. 启动服务 ```bash # 测试应用（无需数据库） python test_app.py # 完整应用（需要数据库） python main.py ``` #### 6. 访问服务 - 主页: http://localhost:8000/ - API文档: http://localhost:8000/docs - 健康检查: http://localhost:8000/health - 设备列表: http://localhost:8000/api/v1/devices ## 📖 安装问题解决 ### 常见问题 #### 1. pip命令不存在 ```bash # 使用python3 -m pip替代pip python3 -m pip install package_name ``` #### 2. 依赖安装失败 ```bash # 分步安装 pip install fastapi uvicorn python-dotenv pip install sqlalchemy pymysql aiomysql pip install pydantic python-jose[cryptography] passlib[bcrypt] ``` #### 3. 权限问题 ```bash # 使用--user参数 pip install --user package_name ``` #### 4. 网络问题 ```bash # 使用国内镜像源 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple package_name ``` ### 验证安装 ```bash # 测试基本导入 python3 -c "import fastapi; print('FastAPI OK')" python3 -c "import sqlalchemy; print('SQLAlchemy OK')" python3 -c "import uvicorn; print('Uvicorn OK')" ``` ## 🔧 配置管理 ### 配置文件结构 - **`.env`** - 实际使用的环境配置文件 [//]: # (- **`.env.example`** - 配置模板文件) ### 配置管理工具 ```bash # 运行配置管理脚本 python manage_config.py ``` 功能包括： 1. 查看当前配置 2. 重置为示例配置 3. 备份当前配置 4. 验证配置格式 ### 主要配置项 #### 基础配置 ```bash DEBUG=true # 调试模式 HOST=0.0.0.0 # 服务器地址 PORT=8000 # 服务器端口 APP_NAME=HomeAssistant Server # 应用名称 ``` #### 数据库配置 ```bash # 阿里云MySQL数据库 DATABASE_URL=mysql+aiomysql://user:password@host:port/database DATABASE_POOL_SIZE=10 # 连接池大小 DATABASE_MAX_OVERFLOW=20 # 最大溢出连接数 ``` #### 安全配置 ```bash SECRET_KEY=your-secret-key # 应用密钥 JWT_SECRET_KEY=your-jwt-secret-key # JWT密钥 JWT_EXPIRE_MINUTES=10080 # JWT过期时间（7天） ``` ## 🐳 Docker部署 ### 使用Docker Compose ```bash # 构建和启动服务 cd docker docker-compose up -d # 查看服务状态 docker-compose ps # 查看日志 docker-compose logs -f homeassistant-server ``` ### 服务访问 - API服务: http://localhost:8000 - MySQL: localhost:3306 - Redis: localhost:6379 - Nginx: http://localhost:80 - Prometheus: http://localhost:9090 - Grafana: http://localhost:3000 ## 📖 API文档 ### 设备管理 API #### 获取设备列表 ```http GET /api/v1/devices ``` #### 创建设备 ```http POST /api/v1/devices Content-Type: application/json { "name": "智能灯泡", "type": "light", "location": "客厅", "properties": { "brightness": 100, "color": "#FFFFFF" } } ``` #### 控制设备 ```http POST /api/v1/devices/{device_id}/control Content-Type: application/json { "action": "turn_on", "parameters": { "brightness": 80 } } ``` ### 场景管理 API #### 获取场景列表 ```http GET /api/v1/scenes ``` #### 执行场景 ```http POST /api/v1/scenes/{scene_id}/execute ``` ### 自动化管理 API #### 获取自动化规则 ```http GET /api/v1/automations ``` #### 创建自动化规则 ```http POST /api/v1/automations Content-Type: application/json { "name": "晚上自动关灯", "description": "每天晚上11点自动关闭所有灯光", "triggers": [...], "conditions": [...], "actions": [...] } ``` ## 🧪 测试 ### 运行测试 ```bash # 单元测试 pytest tests/ # 集成测试 pytest tests/integration/ # 测试覆盖率 pytest --cov=app tests/ ``` ### 测试应用 ```bash # 启动测试应用（无需数据库） python test_app.py # 访问测试端点 curl http://localhost:8000/ curl http://localhost:8000/health curl http://localhost:8000/api/v1/devices ``` ## 📊 监控和日志 ### 日志配置 - 日志文件: `logs/homeassistant.log` - 日志级别: DEBUG, INFO, WARNING, ERROR, CRITICAL - 日志轮转: 10MB/文件，保留5个备份 ### 监控指标 - 系统运行状态 - API请求统计 - 设备在线状态 - 场景执行统计 - 自动化规则执行统计 ### Prometheus指标 访问 http://localhost:9090 查看Prometheus监控面板 ### Grafana仪表板 访问 http://localhost:3000 查看Grafana仪表板 - 默认用户名: admin - 默认密码: admin123 ## 🔒 安全考虑 ### 身份认证 - JWT Token认证 - Token过期时间: 7天 - 支持Token刷新 ### 权限控制 - 基于角色的访问控制（RBAC） - 三种角色: admin, user, guest - API级别的权限检查 ### 数据安全 - 密码使用bcrypt加密 - 敏感配置加密存储 - SQL注入防护 - XSS攻击防护 ## 🔍 故障排除 ### 配置问题 ```bash # 检查配置文件 python manage_config.py # 验证配置格式 python -c "from dotenv import load_dotenv; load_dotenv(); print('配置加载成功')" ``` ### 数据库连接问题 1. 检查数据库URL格式 2. 验证数据库服务器状态 3. 确认网络连接和防火墙设置 ### 依赖问题 ```bash # 重新安装依赖 pip install --force-reinstall -r requirements-core.txt # 检查Python版本 python3 --version # 需要3.8+ ``` ### 端口占用 ```bash # 检查端口占用 lsof -i :8000 # 修改端口 export PORT=8001 python test_app.py ``` ## 🤝 贡献指南 1. Fork项目 2. 创建功能分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 创建Pull Request ## 📝 开发规范 ### 代码风格 - 使用Black进行代码格式化 - 使用isort进行导入排序 - 使用flake8进行代码检查 ### 提交规范 - feat: 新功能 - fix: 修复bug - docs: 文档更新 - style: 代码格式调整 - refactor: 代码重构 - test: 测试相关 - chore: 构建过程或辅助工具的变动 ## 🗺️ 路线图 ### v1.1.0 (计划中) - [ ] WebSocket实时通信 - [ ] 语音控制集成 - [ ] 第三方设备协议支持 - [ ] 移动端推送通知 ### v1.2.0 (计划中) - [ ] 机器学习智能推荐 - [ ] 地理位置自动化 - [ ] 天气数据集成 - [ ] 能耗监控和分析 ### v2.0.0 (长期计划) - [ ] 微服务架构重构 - [ ] 多租户支持 - [ ] 插件系统 - [ ] 云端同步 ## 📞 联系方式 - 项目维护者: [Your Name] - 邮箱: your.email@example.com - 项目主页: https://github.com/your-username/HomeAssistant-server ## 📄 许可证 本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 ## 🆘 支持 如果您遇到问题或有建议，请： 1. 查看本文档的故障排除部分 2. 运行 `python manage_config.py` 进行配置诊断 3. 搜索[已有Issues](../../issues) 4. 创建新的[Issue](../../issues/new) ## 🎉 项目特色 ### 架构设计 - **分层架构**: 清晰的分层设计，职责分离 - **依赖注入**: 统一的依赖管理 - **异步优先**: 全异步架构，高并发支持 - **事件驱动**: 基于事件的松耦合设计 ### 扩展性 - **插件化设备驱动**: 支持多种设备协议 - **灵活的自动化规则**: 可视化规则配置 - **模块化设计**: 易于扩展新功能 - **配置化管理**: 运行时配置修改 ### 可靠性 - **异常处理**: 完善的异常处理机制 - **事务管理**: 数据一致性保证 - **健康检查**: 系统状态监控 - **日志记录**: 完整的操作日志 ### 性能优化 - **异步处理**: 高并发请求处理 - **连接池**: 数据库连接复用 - **缓存机制**: Redis缓存加速 - **索引优化**: 数据库查询优化 --- ⭐ 如果这个项目对您有帮助，请给我们一个星标！ 🚀 **快速开始**: 运行 `./quick_start.sh` 一键启动项目！