# simple-ota-server

**Repository Path**: xjshiMax/simple-ota-server

## Basic Information

- **Project Name**: simple-ota-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-11-30
- **Last Updated**: 2025-12-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Simple OTA Server

一个简单的OTA（Over-The-Air）固件更新服务器，提供固件管理界面和API接口。

## 项目说明

本项目是一个用于设备固件OTA更新的Web服务，支持固件上传、版本管理、查询和下载功能。

## 功能特性

- ✅ 固件管理页面（列表查看、删除、版本设置、上传）
- ✅ 版本查询接口（HTTP API）
- ✅ 固件下载接口（支持断点续传）
- ✅ 响应式Web界面

## 界面展示

### 固件管理界面

![固件管理界面](./doc/gujianguanli.png)

固件管理界面支持：
- 查看所有固件文件列表
- 显示文件大小、上传时间、版本号
- 上传新固件（支持拖拽）
- 删除固件文件
- 设置版本信息

### 版本设置界面

![版本设置界面](./doc/shezhibanben.png)

版本设置界面支持：
- 设置固件版本号（x.y.z格式）
- 标记为最新版本
- 添加版本更新说明
- 显示下载URL，方便测试

## 技术栈

- **前端**: HTML + JavaScript (ES6+)
- **后端**: Python (Flask/FastAPI)
- **存储**: 文件系统 + JSON配置文件

## 环境要求

- Python 3.8+
- 现代浏览器（Chrome, Firefox, Safari, Edge）

## 快速开始

### 方式1：使用安装脚本（推荐）

```bash
# 一键安装（自动创建虚拟环境、安装依赖、初始化配置）
chmod +x scripts/setup.sh
./scripts/setup.sh

# 运行服务
./scripts/run.sh
```

`setup.sh` 会自动完成：
- ✅ 检查Python版本
- ✅ 创建虚拟环境
- ✅ 安装所有依赖
- ✅ 创建必要目录
- ✅ 初始化配置文件

### 方式2：手动安装

如果不想使用安装脚本，可以手动执行：

```bash
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或 venv\Scripts\activate  # Windows

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

# 创建必要目录
mkdir -p firmware config logs
```

### 运行服务

```bash
# 方式1: 使用启动脚本（推荐）
# 如果使用setup.sh安装，脚本已自动设置权限
./scripts/run.sh

# 方式2: 直接运行（需要先激活虚拟环境）
source venv/bin/activate  # Linux/macOS
python src/backend/app.py

# 方式3: 使用Flask命令（需要先激活虚拟环境）
source venv/bin/activate  # Linux/macOS
export FLASK_APP=src/backend/app.py
flask run --host=0.0.0.0 --port=9080
```

**注意**: 
- 如果使用 `setup.sh` 安装，直接运行 `./scripts/run.sh` 即可，脚本会自动激活虚拟环境
- 如果手动安装，需要先激活虚拟环境再运行

### 访问服务

打开浏览器访问: `http://localhost:9080`

### 使用API

```bash
# 查询最新版本
curl http://localhost:9080/api/version/latest

# 获取固件列表
curl http://localhost:9080/api/firmware/list
```

更多详细信息请参考 [部署文档](./DEPLOY.md)

## 配置说明

### 修改端口

默认端口为 `9080`。如果需要修改端口，有以下几种方式：

#### 方式1：使用环境变量文件（推荐）

创建或编辑 `.env` 文件：

```bash
# 复制示例文件
cp env.example .env

# 编辑 .env 文件，修改端口
PORT=8080  # 改为你想要的端口
```

重启服务后，新端口生效。

#### 方式2：直接设置环境变量

```bash
# 临时设置（当前终端有效）
export PORT=8080
./scripts/run.sh

# 或在启动时设置
PORT=8080 ./scripts/run.sh
```

#### 方式3：修改脚本默认值

如果不想使用环境变量，可以直接修改脚本文件：

- **开发环境**: 修改 `scripts/run.sh` 第38行
  ```bash
  export PORT=${PORT:-8080}  # 将9080改为你想要的端口
  ```

- **生产环境**: 修改 `scripts/run_prod.sh` 第38行
  ```bash
  export PORT=${PORT:-8080}  # 将9080改为你想要的端口
  ```

- **代码默认值**: 修改 `src/backend/app.py` 第80行
  ```python
  port = int(os.getenv('PORT', 8080))  # 将9080改为你想要的端口
  ```

**注意**: 修改端口后，访问地址也会相应改变，例如：
- 原地址: `http://localhost:9080`
- 新地址: `http://localhost:8080`

### 其他配置

更多配置选项请参考 `env.example` 文件，包括：
- `HOST`: 服务器地址（默认: 0.0.0.0）
- `FIRMWARE_DIR`: 固件存储目录（默认: firmware）
- `CONFIG_DIR`: 配置目录（默认: config）
- `MAX_UPLOAD_SIZE`: 最大上传大小（默认: 100MB）

### 自定义固件类型

后端与前端的固件类型下拉选项、校验和接口返回都来自可配置的固件类型映射：

1) 编辑配置文件：`config/firmware_types.json`（`setup.sh` 会自动生成示例）  
```json
{
  "types": [
    { "code": 1, "name": "网关固件" },
    { "code": 2, "name": "传感器固件" },
    { "code": 10, "name": "自定义板卡" }
  ]
}
```
2) 可通过环境变量 `FIRMWARE_TYPES_FILE` 指向自定义路径（例如挂载到容器外部）。  
3) 修改后重启服务以使缓存刷新生效。  
4) 通过 `GET /api/firmware/types` 验证当前生效的映射；版本设置与最新版本查询接口需要使用这些编码。  

## 项目结构

```
simple-ota-server/
├── README.md              # 项目说明
├── REQUIREMENTS.md        # 需求文档
├── DESIGN.md              # 设计方案
├── DEPLOY.md              # 部署文档
├── API.md                 # API接口文档
├── .cursorrules           # 开发规则（AI助手使用）
├── requirements.txt       # Python依赖
├── env.example            # 环境变量示例
├── .gitignore             # Git忽略文件
├── doc/                   # 文档和截图
│   ├── gujianguanli.png   # 固件管理界面截图
│   └── shezhibanben.png   # 版本设置界面截图
├── firmware/              # 固件存储目录
├── config/                # 配置文件目录
│   └── version_info.json  # 版本信息
├── scripts/               # 部署脚本
│   ├── setup.sh           # 安装脚本
│   ├── run.sh             # 开发环境启动
│   └── run_prod.sh        # 生产环境启动
└── src/                   # 源代码
    ├── backend/           # Python后端
    │   ├── app.py         # Flask应用主文件
    │   ├── routes/        # 路由模块
    │   │   ├── firmware.py
    │   │   ├── version.py
    │   │   └── download.py
    │   ├── services/      # 业务逻辑
    │   │   ├── file_service.py
    │   │   └── version_service.py
    │   └── utils/         # 工具函数
    │       ├── file_utils.py
    │       └── validators.py
    └── frontend/          # HTML/JS前端
        ├── index.html     # 主页面
        ├── css/
        │   └── style.css
        └── js/
            └── app.js
```

## 相关文档

- [需求文档](./REQUIREMENTS.md) - 详细功能需求说明
- [设计方案](./DESIGN.md) - 系统架构和技术选型
- [API文档](./API.md) - 接口使用说明
- [部署指南](./DEPLOY.md) - 部署和配置说明
- [开发规则](./.cursorrules) - 开发规范和最佳实践

## 许可证

待定