# PiMapper 

**Repository Path**: fu-ce-wei/pi-mapper

## Basic Information

- **Project Name**: PiMapper 
- **Description**: PiMapper：一个专注于树莓派等移动设备，外接usb挂载mount文件夹数据源，提供文件映射播放路由
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-28
- **Last Updated**: 2025-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PiMapper - 树莓派视频文件映射服务

## 📋 项目介绍

PiMapper 是一个专为树莓派等移动设备设计的视频文件管理服务。它能够自动检测USB挂载的视频文件夹，提供高效的文件扫描、索引和流媒体服务，支持通过HTTP API获取视频列表和直接播放。

## 🎯 核心功能

- **🎬 视频文件管理**：自动扫描 `/mnt/sda` 目录下的视频文件
- **🔄 智能索引**：使用Redis SET结构存储文件名，确保唯一性和高效查询
- **⚡ 并发处理**：支持3个goroutine并发处理文件，提升扫描效率
- **📊 定时任务**：每6小时自动执行文件扫描，程序启动时立即执行一次
- **🔗 HTTP API**：提供RESTful接口获取视频列表和文件信息
- **📁 静态文件服务**：直接通过HTTP提供视频文件访问
- **🔍 健康检查**：提供系统状态监控接口

## 🚀 快速开始

### 环境要求

- **Go 1.20+**
- **Redis 6.0+**
- **Linux/macOS/Windows**
- **USB存储设备**（用于视频存储）

### 安装依赖

```bash
# 安装Go依赖
make deps

# 安装系统依赖（Ubuntu/Debian）
make install-deps

# 启动Redis
make setup-redis
```

### 配置项目

1. **创建配置文件**（可选，已提供默认配置）
```bash
cp configs/config.yml configs/config.local.yml
# 编辑 config.local.yml 根据实际需求修改
```

2. **设置目录权限**
```bash
make setup-directories
```

### 构建和运行

```bash
# 构建应用
make build

# 开发模式运行
make run-dev

# 生产模式运行
./bin/pi-mapper -config configs/config.yml
```

## 📡 API 接口

### 获取视频列表

```http
GET /api/v1/videos/list?count=5
```

**参数：**
- `count` (可选): 返回视频数量，默认5个，最大20个

**响应示例：**
```json
{
  "videos": [
    {
      "name": "movie1.mp4",
      "url": "http://localhost:8080/videos/movie1.mp4",
      "size": 104857600,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 100,
  "count": 5
}
```

### 获取视频详情

```http
GET /api/v1/videos/{filename}
```

### 健康检查

```http
GET /health
```

### 访问视频文件

```http
GET /videos/{filename}
```

## 🏗️ 项目架构

```
pi-mapper/
├── cmd/server/          # 主程序入口
├── internal/
│   ├── config/         # 配置管理
│   ├── handler/        # HTTP处理器
│   ├── service/        # 业务逻辑层
│   └── task/           # 定时任务调度器
├── dto/                # 数据传输对象
├── pkg/
│   ├── logger/         # 日志封装
│   └── redis/          # Redis客户端封装
├── configs/            # 配置文件
├── bin/                # 构建产物
└── logs/               # 日志文件
```

## ⚙️ 配置说明

### 主要配置项

```yaml
# 服务器配置
server:
  port: 8080
  mode: "debug"  # debug, release, test

# Redis配置
redis:
  host: "localhost"
  port: 6379
  password: ""
  db: 0

# 文件扫描配置
scanner:
  root_path: "/mnt/sda"
  max_files: 500
  file_extensions: [".mp4", ".avi", ".mkv", ".mov"]
  workers: 3
  select_count: 10

# 定时任务配置
scheduler:
  interval: "6h"
  timeout: "30m"
  immediate_run: true
```

## 🐳 Docker 部署

### 构建镜像

```bash
make docker-build
```

### 运行容器

```bash
# 使用Makefile
make docker-run

# 手动运行
docker run -d \
  --name pi-mapper \
  -p 8080:8080 \
  -v $(pwd)/configs:/app/configs \
  -v /mnt/sda:/mnt/sda \
  pi-mapper:latest
```

### Docker Compose

```yaml
version: '3.8'
services:
  pi-mapper:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./configs:/app/configs
      - /mnt/sda:/mnt/sda
    depends_on:
      - redis
    restart: unless-stopped
  
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    restart: unless-stopped
```

## 🔧 开发指南

### 常用命令

```bash
# 安装依赖
make deps

# 格式化代码
make fmt

# 运行测试
make test

# 构建所有平台版本
make build-all

# 开发模式运行
make run-dev

# 文件变更自动重启
make watch
```

### 调试技巧

1. **查看日志**
```bash
tail -f logs/pi-mapper.log
```

2. **Redis监控**
```bash
redis-cli monitor
```

3. **API测试**
```bash
curl http://localhost:8080/api/v1/videos/list
curl http://localhost:8080/health
```

## 📊 性能优化

### 树莓派优化建议

1. **内存限制**：使用较小的Redis数据集
2. **磁盘IO**：使用SSD或高速SD卡
3. **网络**：使用有线连接代替WiFi
4. **监控**：定期清理旧日志文件

### 配置文件优化

```yaml
# 树莓派专用配置
scanner:
  max_files: 100  # 减少扫描文件数
  workers: 2      # 减少并发数
  
redis:
  pool_size: 5    # 减少连接池大小
```

## 🛠️ 故障排除

### 常见问题

1. **Redis连接失败**
   - 检查Redis服务是否运行
   - 确认端口和主机配置

2. **文件扫描失败**
   - 检查目录权限
   - 确认路径存在且可读

3. **构建失败**
   - 确保Go版本 >= 1.20
   - 运行 `make deps` 安装依赖

### 调试模式

```bash
# 开启调试日志
export LOG_LEVEL=debug
./bin/pi-mapper
```

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [Gin Web Framework](https://github.com/gin-gonic/gin)
- [Redis](https://redis.io/)
- [Zap Logger](https://github.com/uber-go/zap)
- [Lumberjack](https://github.com/natefinch/lumberjack)