# Winupdate Neo 部署指南

## 系统架构

本项目使用以下技术栈：

- **前端**: Next.js 15 (TypeScript)
- **数据库**: PostgreSQL + Prisma ORM
- **对象存储**: MinIO (自建 S3 兼容存储)
- **包管理**: Bun
- **运行时**: Node.js

## 部署步骤

### 1. 环境准备

#### 1.1 安装 Bun
```bash
curl -fsSL https://bun.sh/install | bash
# 或在 Windows 上:
powershell -c "irm bun.sh/install.ps1 | iex"
```

#### 1.2 安装 PostgreSQL
确保 PostgreSQL 服务正在运行，并创建数据库。

#### 1.3 部署 MinIO
```bash
# Docker 方式部署 MinIO
docker run -p 9000:9000 -p 9001:9001 \
  -v /data/minio:/data \
  -e "MINIO_ROOT_USER=feie9454" \
  -e "MINIO_ROOT_PASSWORD=zjh94544549ok" \
  minio/minio server /data --console-address ":9001"
```

访问 http://192.168.5.13:9001 进入 MinIO 控制台，创建名为 "winupdate" 的 bucket。

### 2. 项目配置

#### 2.1 克隆项目
```bash
git clone <repository-url>
cd winupdate-neo
```

#### 2.2 安装依赖
```bash
bun install
```

#### 2.3 配置环境变量
复制并编辑 `.env` 文件：

```env
# 数据库配置
DATABASE_URL="postgresql://username:password@localhost:5432/winupdate_neo?schema=public"

# 认证配置
AUTH_USERNAME=admin
AUTH_PASSWORD=password

# 服务端口
PORT=3000

# MinIO 配置（在代码中硬编码，生产环境建议移到环境变量）
```

#### 2.4 初始化数据库
```bash
# 生成 Prisma 客户端
bun run db:generate

# 运行数据库迁移
bun run db:migrate
```

### 3. 测试部署

#### 3.1 测试 MinIO 连接
```bash
bun run test-minio.ts
```

应该看到：
```
🎉 MinIO 测试完全成功！可以开始使用了。
```

#### 3.2 测试文件操作
```bash
bun run test-file-operations.ts
```

应该看到完整的文件上传、下载、删除测试成功。

#### 3.3 启动开发服务器
```bash
bun run dev
```

访问 http://localhost:3000/api-test 查看 API 状态。

### 4. 生产部署

#### 4.1 构建项目
```bash
bun run build
```

#### 4.2 启动生产服务器
```bash
bun run start
```

## 存储架构说明

### MinIO 对象存储结构

```
winupdate bucket/
├── screenshots/          # 截图文件
│   ├── 2025/
│   │   ├── 01/
│   │   │   ├── hostname1/
│   │   │   │   ├── uuid1.webp
│   │   │   │   └── uuid2.webp
│   │   │   └── hostname2/
│   │   └── 02/
│   └── 2024/
├── versions/             # 版本文件
│   ├── 2025/
│   │   ├── 06/
│   │   │   ├── uuid1.exe
│   │   │   └── uuid2.exe
│   │   └── 07/
│   └── 2024/
└── files/               # 其他文件
    └── ...
```

### 性能优化特性

1. **分层目录结构**: 按时间和主机名分层，避免单目录文件过多
2. **数据库索引**: objectName 字段建立索引，快速查找
3. **元数据存储**: 文件元数据存储在 MinIO 中，避免额外数据库查询
4. **缓存友好**: 静态文件设置长期缓存
5. **并发支持**: MinIO 原生支持高并发读写

### 扩展能力

1. **水平扩展**: MinIO 支持分布式部署
2. **存储容量**: 理论上无限制，实际受硬件限制
3. **备份恢复**: 支持 S3 兼容的备份工具
4. **监控告警**: 可集成 Prometheus + Grafana

## API 接口说明

### 文件上传流程

1. 客户端上传文件到 `/api/hosts/{hostname}/screenshots`
2. 服务器将文件存储到 MinIO，生成 objectName
3. 在数据库中保存文件元数据，包含 objectName
4. 返回成功响应

### 文件下载流程

1. 客户端请求 `/api/screenshots/{fileId}`
2. 服务器根据 fileId 从数据库查找 objectName
3. 从 MinIO 下载文件
4. 返回文件数据

## 监控和维护

### 日志监控
- MinIO 操作日志
- 应用程序日志
- 数据库查询日志

### 存储监控
```bash
# 查看存储统计
curl http://localhost:3000/api/storage/stats
```

### 清理策略
- 定期清理过期截图（可配置保留时间）
- 监控存储空间使用情况
- 设置存储告警阈值

## 故障排除

### 常见问题

1. **MinIO 连接失败**
   - 检查 MinIO 服务状态
   - 确认网络连通性
   - 验证认证信息

2. **数据库连接失败**
   - 检查 PostgreSQL 服务状态
   - 确认连接字符串正确
   - 检查用户权限

3. **文件上传失败**
   - 检查磁盘空间
   - 确认 MinIO bucket 存在
   - 查看 MinIO 日志

4. **性能问题**
   - 监控数据库查询性能
   - 检查 MinIO 服务器负载
   - 优化数据库索引

### 性能调优建议

1. **数据库优化**
   - 定期更新统计信息
   - 监控慢查询
   - 适当增加连接池大小

2. **MinIO 优化**
   - 使用 SSD 存储
   - 配置适当的并发数
   - 启用压缩（如果需要）

3. **应用优化**
   - 启用文件缓存
   - 使用 CDN（如果有公网访问需求）
   - 实现文件预签名 URL（减少服务器负载）

## 安全建议

1. **访问控制**
   - 使用强密码
   - 定期轮换认证信息
   - 限制网络访问范围

2. **数据安全**
   - 启用数据加密
   - 定期备份数据
   - 监控异常访问

3. **网络安全**
   - 使用 HTTPS
   - 配置防火墙
   - 启用访问日志