# ota-server

**Repository Path**: shmilyhe/ota-server

## Basic Information

- **Project Name**: ota-server
- **Description**: 一个完整的固件在线升级(OTA)解决方案，包含后端服务、前端管理界面和设备客户端。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2025-06-19
- **Last Updated**: 2026-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OTA 项目

一个完整的固件在线升级(OTA)解决方案，包含后端服务、前端管理界面和设备客户端。

## 项目结构

```
ota-project/
├── ota-backend/          # 后端服务 (Go + Gin + GORM)
├── ota-frontend/         # 前端管理界面 (Vue 3 + TypeScript + Element Plus)
├── ota-client/           # 设备客户端 (Go)
├── test/                 # 测试脚本
├── Makefile             # 项目构建脚本
└── README.md
```

## 功能特性

### 后端服务 (ota-backend)
- 🎯 产品管理
- 📦 固件版本管理  
- 📋 升级任务管理
- 🔌 设备管理
- 🔒 文件签名验证
- 📊 升级记录追踪
- 🌐 RESTful API

### 前端管理界面 (ota-frontend)
- 🎨 现代化界面设计
- 📱 响应式布局
- 📊 数据可视化
- 🔄 实时数据更新
- 📋 完整的CRUD操作

### 设备客户端 (ota-client)
- 🔄 定期检查固件更新
- 📦 自动下载固件文件
- 🔒 签名验证确保安全性
- 📊 升级状态实时报告
- ⚙️ 灵活的配置管理
- 📝 详细的日志记录

## 快速开始

### 环境要求

- Go 1.21+
- Node.js 18+
- MySQL 8.0+ 或 SQLite 3

### 1. 启动后端服务

```bash
cd ota-backend
make deps
make run
```

后端服务将在 `http://localhost:8081` 启动

### 2. 启动前端界面

```bash
cd ota-frontend
npm install
npm run dev
```

前端界面将在 `http://localhost:5173` 启动

### 3. 构建和运行客户端

```bash
cd ota-client
make build

# 使用默认配置运行
make run

# 或使用自定义配置
./bin/ota-client -f your-config.yaml
```

## 项目配置

### 后端配置 (ota-backend/config.yaml)

```yaml
server:
  port: 8081
  
database:
  type: "sqlite"
  sqlite:
    path: "ota.db"

storage:
  path: "./storage"
  max_size: 104857600  # 100MB
  allowed_types: [".bin", ".hex", ".img"]
```

### 客户端配置 (ota-client/config.yaml)

```yaml
server:
  url: "http://localhost:8081"

device:
  product_id: "1234"
  sn: "DEV001"
  version: "1.0.0"
  key: "_sF~#_Nx3'6Mrp)"

client:
  check_interval: 10
  download_timeout: 300
  temp_dir: "./temp"
  log_level: "info"
```

## API 文档

### OTA 设备接口

#### 检查更新
```http
POST /ota/check
Content-Type: application/json

{
    "product_id": "1234",
    "current_version": "1.0.0",
    "sn": "DEV001"
}
```

#### 下载固件
```http
GET /ota/download/{product_id}/{filename}
```

#### 报告升级状态
```http
POST /ota/report
Content-Type: application/json

{
    "sn": "DEV001",
    "product_id": "1234",
    "version": "1.1.0",
    "status": "success",
    "message": "升级成功"
}
```

### Web 管理接口

详细的 API 文档请参考各子项目的 README 文件。

## 工作流程

1. **产品管理**: 在前端界面创建产品，设置签名密钥
2. **固件上传**: 上传固件文件，系统自动生成签名
3. **任务创建**: 创建升级任务，指定目标设备和固件版本
4. **设备检查**: 客户端定期检查是否有待执行的升级任务
5. **固件下载**: 发现更新时自动下载固件和签名文件
6. **签名验证**: 验证下载文件的完整性和来源
7. **执行升级**: 执行固件升级并报告状态
8. **状态跟踪**: 在管理界面查看升级进度和结果

## 安全特性

- 🔒 **文件签名**: 支持多种签名算法(HMAC-SHA256/SHA512)
- 🛡️ **访问控制**: API 接口访问控制
- 🔐 **传输安全**: 支持 HTTPS
- 📋 **审计日志**: 完整的操作日志记录
- 🚫 **文件验证**: 严格的文件类型和大小限制

## 部署指南

### Docker 部署

```bash
# 构建所有服务
make docker-build

# 启动服务
make docker-up
```

### 生产部署

1. **后端部署**:
   ```bash
   cd ota-backend
   make build-linux
   # 部署到服务器
   ```

2. **前端部署**:
   ```bash
   cd ota-frontend
   npm run build
   # 部署 dist/ 目录到 Web 服务器
   ```

3. **客户端部署**:
   ```bash
   cd ota-client
   make build-all
   # 选择对应平台的可执行文件部署到设备
   ```

## 监控和日志

- **后端日志**: 支持多级别日志，可配置输出格式
- **前端日志**: 浏览器控制台和网络请求日志
- **客户端日志**: 可配置的日志级别和输出格式
- **数据库日志**: GORM 查询日志
- **文件操作日志**: 完整的文件上传下载记录

## 故障排除

### 常见问题

1. **连接问题**: 检查服务端口和网络配置
2. **签名验证失败**: 确认密钥配置正确
3. **文件上传失败**: 检查文件大小和类型限制
4. **数据库连接失败**: 验证数据库配置和权限

### 调试模式

各组件都支持调试模式，设置相应的日志级别为 `debug` 即可获得详细信息。

## 开发指南

### 添加新功能

1. **后端**: 在 `ota-backend/handlers/` 添加处理器
2. **前端**: 在 `ota-frontend/src/` 添加页面和服务
3. **客户端**: 在 `ota-client/internal/` 添加功能模块

### 测试

```bash
# 后端测试
cd ota-backend && make test

# 前端测试
cd ota-frontend && npm run test

# 客户端测试
cd ota-client && make test
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

---

## 各子项目详细说明

- [ota-backend/README.md](ota-backend/README.md) - 后端服务详细文档
- [ota-frontend/README.md](ota-frontend/README.md) - 前端界面详细文档  
- [ota-client/README.md](ota-client/README.md) - 设备客户端详细文档