# ai-box

**Repository Path**: roggie/ai-box

## Basic Information

- **Project Name**: ai-box
- **Description**: 通用AI盒子管理功能
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI-Box NVR System

AI-Box NVR System 是一个基于 FastAPI 的网络设备管理系统，给盒子提供一个基础的认证管理、网络配置、安全防护、系统监控等功能。

## 目录

- [功能特性](#功能特性)
- [运行环境](#运行环境)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [安装部署](#安装部署)
- [启动停止](#启动停止)
- [API 接口](#api-接口)
- [配置说明](#配置说明)
- [开发指南](#开发指南)
- [常见问题](#常见问题)

## 功能特性

### 核心功能

```
AI-Box NVR System
├── 认证管理
│   ├── 系统初始化（首次设置密码和密保问题）
│   ├── 密码登录
│   ├── Token 验证
│   ├── 修改密码
│   ├── 密保问题设置
│   └── 忘记密码（通过密保问题重置）
├── 网络管理
│   ├── 以太网配置（DHCP/静态IP）
│   ├── WiFi 管理（扫描/连接/删除）
│   ├── 热点管理（启动/停止/密码设置）
│   └── 移动网络配置（4G/5G）
├── 安全防护
│   ├── 密码管理
│   └── 密保问题管理
├── 系统状态
│   ├── CPU 状态监控
│   ├── 内存状态监控
│   ├── 存储状态监控
│   ├── NPU 状态监控
│   └── 网络带宽监控
├── 系统信息
│   ├── 版本信息
│   ├── 系统唯一编号
│   └── 网卡信息
└── 系统设置
    ├── 网络连通性测试（Ping）
    ├── 时间设置（手动/NTP同步）
    ├── 系统升级（在线/USB）
    └── 系统重启
```

### 技术特性

- **异步架构**: 基于 FastAPI + aiosqlite 的全异步设计
- **JWT 认证**: 基于 Bearer Token 的无状态认证
- **安全加密**: 使用 bcrypt 进行密码哈希
- **SQLite 数据库**: 轻量级嵌入式数据库
- **RESTful API**: 标准的 REST API 设计
- **自动文档**: Swagger UI 和 ReDoc 自动生成

## 运行环境

### 系统要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Linux (推荐 Ubuntu 20.04+) |
| Python | 3.8+ |
| 内存 | 最低 512MB |
| 存储 | 最低 100MB |

### 依赖列表

| 包名 | 版本 | 说明 |
|------|------|------|
| fastapi | >=0.104.0 | Web 框架 |
| uvicorn | >=0.24.0 | ASGI 服务器 |
| pydantic | >=2.5.0 | 数据验证 |
| pydantic-settings | >=2.1.0 | 配置管理 |
| python-jose | >=3.3.0 | JWT 处理 |
| bcrypt | >=4.0.0 | 密码加密 |
| aiosqlite | >=0.19.0 | 异步 SQLite |
| psutil | >=5.9.0 | 系统监控 |
| httpx | >=0.25.0 | HTTP 客户端 |
| aiofiles | >=23.2.1 | 异步文件操作 |
| python-multipart | >=0.0.6 | 表单解析 |

## 项目结构

```
ai-box/
├── app/                      # 应用主目录
│   ├── main.py              # 应用入口
│   ├── config.py            # 配置管理
│   ├── database.py          # 数据库连接
│   ├── dependencies.py      # 依赖注入
│   ├── exceptions.py        # 异常处理
│   ├── middleware/          # 中间件
│   │   └── logging_middleware.py
│   ├── models/              # 数据模型
│   ├── routers/             # 路由模块
│   │   ├── auth.py          # 认证路由
│   │   ├── network.py       # 网络路由
│   │   ├── security.py      # 安全路由
│   │   ├── status.py        # 状态路由
│   │   ├── system_info.py   # 系统信息路由
│   │   └── system_settings.py # 系统设置路由
│   ├── schemas/             # 请求/响应模型
│   ├── services/            # 业务逻辑
│   │   ├── auth_service.py  # 认证服务
│   │   ├── wifi_service.py  # WiFi 服务
│   │   ├── ethernet_service.py # 以太网服务
│   │   ├── hotspot_service.py # 热点服务
│   │   ├── mobile_service.py # 移动网络服务
│   │   ├── system_service.py # 系统服务
│   │   ├── status_service.py # 状态服务
│   │   └── upgrade_service.py # 升级服务
│   └── utils/               # 工具函数
│       ├── hardware.py      # 硬件相关
│       ├── logger.py        # 日志工具
│       ├── network_utils.py # 网络工具
│       └── system_utils.py  # 系统工具
├── config/                   # 配置文件
│   └── version.json         # 版本信息
├── data/                     # 数据目录
│   └── ai_box.db            # SQLite 数据库
├── docs/                     # 文档
│   └── api.md               # API 文档
├── logs/                     # 日志目录
│   ├── app.log              # 应用日志
│   └── server.log           # 服务器日志
├── scripts/                  # 脚本目录
│   ├── install.sh           # 安装脚本
│   ├── start.sh             # 启动脚本
│   ├── stop.sh              # 停止脚本
│   └── restart.sh           # 重启脚本
├── requirements.txt          # Python 依赖
└── README.md                 # 项目说明
```

## 快速开始

### 方式一：使用脚本（推荐）

```bash
# 1. 克隆项目
cd /opt
git clone <repository-url> ai-box
cd ai-box

# 2. 安装并启动
./scripts/install.sh
./scripts/start.sh

# 3. 访问服务
# API 文档: http://<device-ip>:1234/docs
```

### 方式二：手动安装

```bash
# 1. 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动服务
python -m uvicorn app.main:app --host 0.0.0.0 --port 1234
```

## 安装部署

### 安装脚本

项目提供自动化安装脚本，支持 systemd 服务注册：

```bash
# 执行安装
./scripts/install.sh
```

安装脚本会自动完成：
1. 检查系统环境
2. 创建 Python 虚拟环境
3. 安装所有依赖
4. 配置 systemd 服务（可选）
5. 设置开机自启（可选）

### Systemd 服务

安装后可使用 systemd 管理：

```bash
# 启动服务
sudo systemctl start ai-box

# 停止服务
sudo systemctl stop ai-box

# 重启服务
sudo systemctl restart ai-box

# 查看状态
sudo systemctl status ai-box

# 查看日志
journalctl -u ai-box -f
```

### 卸载

```bash
# 停止并禁用服务
sudo systemctl stop ai-box
sudo systemctl disable ai-box

# 删除服务文件
sudo rm /etc/systemd/system/ai-box.service
sudo systemctl daemon-reload

# 删除项目目录
rm -rf /opt/ai-box
```

## 启动停止

### 使用脚本管理

```bash
# 启动服务（后台运行）
./scripts/start.sh

# 停止服务
./scripts/stop.sh

# 重启服务
./scripts/restart.sh
```

### 启动脚本说明

`start.sh` 会执行以下操作：
1. 检查 Python 版本
2. 检查/创建虚拟环境
3. 安装/更新依赖
4. 后台启动服务
5. 保存进程 PID 到 `.server.pid`
6. 日志输出到 `logs/server.log`

### 停止脚本说明

`stop.sh` 支持多种方式停止服务：
1. 通过 PID 文件停止（优先）
2. 通过 TCP 端口查找进程停止
3. 通过进程名查找停止


### 手动管理

```bash
# 前台启动（调试用）
source venv/bin/activate
python -m uvicorn app.main:app --host 0.0.0.0 --port 1234

# 后台启动
nohup python -m uvicorn app.main:app --host 0.0.0.0 --port 1234 > logs/server.log 2>&1 &

# 停止
pkill -f "uvicorn app.main:app"
```

## API 接口

### 内网服务地址

| 项目 | 地址 |
|------|------|
| API 地址 | `http://<device-ip>:1234` |
| Swagger UI | `http://<device-ip>:1234/docs` |
| ReDoc | `http://<device-ip>:1234/redoc` |


### 外网接口文档

https://s.apifox.cn/be7936cb-4f38-4704-8252-c6a670e65a7d

### 首次使用流程

```bash
# 1. 检查初始化状态
curl http://localhost:1234/api/auth/initialize/status

# 2. 初始化系统（设置密码和密保问题）
curl -X POST http://localhost:1234/api/auth/initialize \
  -H "Content-Type: application/json" \
  -d '{"password": "yourpassword", "security_question": "您的生日?", "security_answer": "1990-01-01"}'

# 3. 登录获取 Token
curl -X POST http://localhost:1234/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password": "yourpassword"}'
```

### API 模块概览

| 模块 | 前缀 | 说明 |
|------|------|------|
| 认证管理 | `/api/auth` | 登录、初始化、密码找回 |
| 网络管理 | `/api/network` | WiFi、以太网、热点、移动网络 |
| 安全设置 | `/api/security` | 密码管理、密保问题 |
| 系统状态 | `/api/status` | CPU、内存、存储、NPU、带宽 |
| 系统信息 | `/api/system-info` | 版本、序列号、网卡信息 |
| 系统设置 | `/api/system-settings` | Ping、时间、升级、重启 |

### 认证方式

除了初始化相关接口外，其他接口需要在请求头携带 JWT Token：

```bash
curl -H "Authorization: Bearer <token>" http://localhost:1234/api/status/all
```

详细 API 文档请参考 [docs/api.md](docs/api.md)。

## 配置说明

### 环境变量

可以通过 `.env` 文件或环境变量配置：

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| APP_NAME | AI-Box NVR System | 应用名称 |
| APP_VERSION | 1.0.0 | 应用版本 |
| DEBUG | false | 调试模式 |
| JWT_SECRET_KEY | (内置值) | JWT 密钥（生产环境需修改） |
| JWT_EXPIRE_MINUTES | 1440 | Token 有效期（分钟） |
| NTP_SERVER | ntp.aliyun.com | NTP 服务器地址 |
| UPGRADE_SERVER_URL | - | 升级服务器地址 |

### 配置示例

创建 `.env` 文件：

```env
# 应用配置
APP_NAME=AI-Box NVR System
DEBUG=false

# JWT 配置（生产环境必须修改）
JWT_SECRET_KEY=your-secure-secret-key-here
JWT_EXPIRE_MINUTES=1440

# NTP 服务器
NTP_SERVER=ntp.aliyun.com

# 升级服务器
UPGRADE_SERVER_URL=http://upgrade.example.com
```

## 开发指南

### 本地开发

```bash
# 克隆项目
git clone <repository-url> ai-box
cd ai-box

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 开发模式启动（支持热重载）
python -m uvicorn app.main:app --host 0.0.0.0 --port 1234 --reload
```

### 添加新的 API 接口

1. 在 `app/schemas/` 创建请求/响应模型
2. 在 `app/services/` 创建业务逻辑
3. 在 `app/routers/` 创建路由
4. 在 `app/main.py` 注册路由

### 代码规范

- 使用 Python 类型注解
- 遵循 PEP 8 编码规范
- 使用 async/await 异步编程
- 日志使用 `app.utils.logger.Loggers`

## 常见问题

### Q: 服务启动后无法访问？

1. 检查端口是否被占用：`lsof -i:1234`
2. 检查防火墙设置：`sudo ufw status`
3. 查看服务日志：`tail -f logs/server.log`

### Q: 忘记密码怎么办？

系统提供密保问题找回功能：
```bash
# 获取密保问题
curl http://localhost:1234/api/auth/security-question

# 通过答案重置密码
curl -X POST http://localhost:1234/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"answer": "your-answer", "new_password": "newpassword"}'
```

### Q: 如何重置系统？

```bash
# 停止服务
./scripts/stop.sh

# 删除数据库（会清除所有配置）
rm -f data/ai_box.db

# 重新启动，系统将回到未初始化状态
./scripts/start.sh
```

### Q: 如何修改端口？

修改以下文件中的端口配置：
1. `app/main.py` - 默认端口
2. `scripts/start.sh` - 启动脚本
3. `scripts/stop.sh` - 停止脚本
4. `scripts/install.sh` - 安装脚本

### Q: 如何查看日志？

```bash
# 查看服务器日志
tail -f logs/server.log

# 查看应用日志
tail -f logs/app.log

# 查看 systemd 日志（如使用 systemd）
journalctl -u ai-box -f
```