# kinder-guardian

**Repository Path**: yahveyeye_admin/kinder-guardian

## Basic Information

- **Project Name**: kinder-guardian
- **Description**: 幼儿园空地一体智能守护系统是一个深度融合人工智能、物联网与Web技术的综合性安全管理平台
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-25
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🌟 Smart Kindergarten: 智慧幼儿园全场景 AI 监控与管理系统

> **引领幼教行业的数字化与智能化变革** —— 本系统是一个集成尖端人工智能算法与现代化 Web 管理架构的综合性解决方案，专为幼儿园安全监控、考勤管理及情感关怀设计。

---

## 💎 项目核心价值

在幼儿教育环境中，安全与关怀是永恒的核心。**Smart Kindergarten** 通过 AI 技术补齐人工监控的盲区，打造“全天候、防疏忽、秒响应”的安全闭环。

- **安全无死角**: 实时捕捉摔倒、越界、陌生人闯入等高危行为。
- **管理数字化**: 建立完整的幼儿、教职工档案，实现考勤与事件的闭环管理。
- **情感数字化**: 通过面部分析捕捉孩子的微笑，记录成长中的美好时刻。

---

## ✨ 核心功能矩阵

### 1. 🤖 AI 智能感知引擎
- **危险预警 (Safety First)**: 毫秒级识别跌倒动作及非法区域闯入。
- **入侵检测 (Security)**: 智能筛选陌生人，防止非法人员进入园所。
- **关怀分析 (Emotion)**: 自动统计微笑频次，量化孩子的快乐指数。
- **智能采集 (Data)**: 无需人工干预，通过摄像头自动完成人脸信息建模。

### 2. 📊 Web 后台管理中心
- **实时看板**: 基于 **WebSocket** 的实时告警弹窗，确保危险瞬间即达。
- **数据魔方**: 多维度图表展示，汇总分析园所安全指数与互动评分。
- **异步处理**: 引入 **Redis** 队列，确保海量监控数据上报时的系统稳定性。
- **安全加固**: 全链路 **API Key** 保护，确保存储与通信的绝对私密。

---

## 🛠️ 技术底座

本系统采用现代化的技术协议栈，确保高性能与易维护性：

- **深度学习**: 基于 `OpenCV` + `Dlib` + `TensorFlow/Keras` 的高精度识别框架。
- **后端服务**: `Python 3.11` + `Flask` + `Socket.IO` 打造的高并发通信网关。
- **中间件**: `Redis` 任务队列 + `MySQL 8.0` 事件库。
- **自动化运维**: 容器化部署支持 (`Podman/Docker`)，内置自愈机制。

---

## 🚀 快速启动指南

### 前提条件
- **Python 3.11+** 和 **uv** 包管理器
- **Podman** 或 **Docker** 容器运行时
- **Windows/Linux/macOS** 操作系统

### 1. 启动容器服务
项目依赖的所有数据库服务都通过容器提供：

```bash
# 切换到项目根目录
cd e:\repo\smartkindergarten

# 启动所有容器服务 (MySQL + Redis)
docker-compose up -d
# 或使用 Podman
podman-compose up -d

# 检查容器状态
docker ps  # 或 podman ps
```

### 2. 启动Web管理后台
```bash
cd kindergartenweb
uv run runit.py
```
访问: http://localhost:5001

### 3. 启动AI监控系统
```bash
cd kindergartensystem
uv run manage_services.py
```
**注意**: 系统默认配置为不播放测试视频，只启动摄像头流服务。

### 4. 访问系统
- **Web管理后台**: http://localhost:5001
- **摄像头实时流**: http://localhost:5002

---

## 🔧 容器服务配置

### 容器服务地址
- **Windows**: `host.docker.internal` (容器内部访问主机的特殊DNS)
- **Linux/macOS**: 使用容器名称或 `docker.for.mac.localhost`

### 端口分配
| 服务 | 端口 | 说明 |
|------|------|------|
| Web管理后台 | 5001 | Flask应用端口 |
| 摄像头流服务 | 5002 | OpenCV视频流端口 |
| MySQL容器 | 3306 | 数据库服务端口 |
| Redis容器 | 6379 | 缓存和队列服务端口 |

### 验证容器连接
```bash
# 检查端口配置
python check_ports.py

# 测试服务连接
python -c "
import socket
for host, port, service in [('host.docker.internal', 3306, 'MySQL'), ('host.docker.internal', 6379, 'Redis'), ('127.0.0.1', 5001, 'Web后台'), ('127.0.0.1', 5002, '摄像头流')]:
    sock = socket.socket()
    sock.settimeout(2)
    result = sock.connect_ex((host, port))
    sock.close()
    status = '✅' if result == 0 else '❌'
    print(f'{status} {service}: {host}:{port}')
"
```

---

## 📋 常见问题解决

### 1. 端口冲突 (OSError [WinError 10048])
**问题**: 端口5001或5002已被占用
**解决**: 
- 确保没有其他程序占用这些端口
- 使用 `netstat -ano | findstr :5001` 检查
- 修改 `config.py` 中的端口配置

### 2. 容器连接失败
**问题**: 无法连接到 `host.docker.internal`
**解决**:
- 确保容器服务已启动: `docker-compose up -d`
- Windows: 检查Docker Desktop网络设置
- Linux/macOS: 使用容器名称替代 `host.docker.internal`

### 3. 视频播放问题
**问题**: 系统启动时播放测试视频
**解决**: 已修复，`manage_services.py` 默认不播放测试视频

---

## 📁 项目结构

```
smartkindergarten/
├── kindergartenweb/         # Web管理后台 (Flask + SocketIO)
│   ├── app/                # 应用代码
│   ├── config.py           # Web配置 (已配置为容器服务)
│   └── runit.py            # Web启动脚本
├── kindergartensystem/     # AI监控系统
│   ├── code/              # AI算法代码
│   │   ├── config.py      # AI系统配置 (已配置为容器服务)
│   │   └── *.py           # 各种AI监控服务
│   └── manage_services.py  # 服务管理器
├── docker-compose.yml      # 容器服务定义 (MySQL + Redis)
├── start_container_services.bat  # 容器服务启动指南
├── stop_all_services.bat   # 停止所有服务脚本
├── check_ports.py         # 端口检查工具
├── README.md              # 本文件
├── ARCHITECTURE.md        # 架构设计文档
├── DEPLOYMENT.md          # 部署指南
└── REQUIREMENTS.md        # 需求分析文档
```

---

## 🛠️ 实用工具脚本

项目提供了精简而实用的工具脚本帮助您管理和维护系统：

### 核心启动脚本
- `start_container_services.bat` - **容器服务专用启动指南** (主启动脚本)
  - 指导如何启动容器服务
  - 提供详细的操作步骤
  - 包含故障排除建议

### 系统管理脚本
- `stop_all_services.bat` - **停止所有服务脚本**
  - 一键停止所有应用服务
  - 清理系统进程

### 诊断检查工具
- `check_ports.py` - **端口检查工具**
  - 检查项目端口配置
  - 检测端口冲突
  - 验证服务连接状态

### 容器管理命令
- `docker-compose.yml` - **容器服务定义文件**
  - 定义MySQL和Redis容器服务
  - 配置容器网络和数据卷
  - 支持Podman和Docker

---

## 🔄 系统维护

### 日常启动流程
```bash
# 1. 启动容器服务
docker-compose up -d

# 2. 启动Web管理后台 (终端1)
cd kindergartenweb && uv run runit.py

# 3. 启动AI监控系统 (终端2)
cd kindergartensystem && uv run manage_services.py
```

### 停止系统
```bash
# 停止应用服务
stop_all_services.bat

# 停止容器服务
docker-compose down
```

### 数据备份
```bash
# 备份MySQL数据
docker exec mysql-kindergarten mysqldump -uroot -pK1nderg@rtenDB! kindergarten > backup_$(date +%Y%m%d).sql

# 备份Redis数据
docker exec redis-kindergarten redis-cli SAVE
```

---

## 📚 详细文档

| 文档名称 | 内容概览 |
| :-- | :-- |
| 🚀 [部署指南](DEPLOYMENT.md) | 从零开始的环境搭建、依赖配置与一键启动手册。 |
| 🏗️ [架构设计](ARCHITECTURE.md) | 深度剖析系统设计理念、数据流转图及核心组件逻辑。 |
| 📋 [需求分析](REQUIREMENTS.md) | 详尽的功能矩阵、非功能性需求及用户场景建模。 |
| 📖 **本README文档** | **完整的使用说明、快速启动指南、故障排除和修复总结** |

---

## 📞 技术支持

### 遇到问题？
1. **检查容器状态**: `docker ps` 确保所有容器正常运行
2. **查看日志**: `docker logs mysql-kindergarten` 或 `docker logs redis-kindergarten`
3. **检查端口**: 运行 `python check_ports.py` 检查端口配置
4. **验证配置**: 检查 `config.py` 和 `.env` 文件中的服务地址配置

### 关键配置文件
- `kindergartenweb/config.py` - Web应用配置
- `kindergartensystem/code/config.py` - AI系统配置
- `kindergartensystem/.env` - AI系统环境变量
- `kindergartenweb/.env` - Web应用环境变量
- `docker-compose.yml` - 容器服务定义

---

## 🌈 未来展望

我们计划在后续迭代中引入：
- 📲 **移动端 APP**: 实时推送告警推送至家长与老师手机。
- 📊 **多园所云管理**: 支持分布式部署，统一管理连锁幼儿园。
- 🔍 **异常情绪预警**: 识别哭闹、打闹等更精细的情绪和行为。

---

## 🎯 修复总结

本项目已完成重要修复，确保：

### ✅ 容器服务支持
- MySQL和Redis服务完全通过容器提供
- 配置文件已更新为使用 `host.docker.internal`
- 支持 Podman 和 Docker 容器运行时

### ✅ 端口冲突解决
- Web管理后台: 端口 5001
- 摄像头流服务: 端口 5002  
- 无端口冲突问题

### ✅ 视频播放控制
- 系统启动时不播放测试视频
- 只启动必要的摄像头流服务

### ✅ 完整文档支持
- 详细的启动和使用说明
- 故障排除指南
- 实用工具脚本

---

*Powered by Advanced AI & Antigravity Engineers*