248 lines
5.2 KiB
Markdown
248 lines
5.2 KiB
Markdown
# 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
|
||
- 配置防火墙
|
||
- 启用访问日志
|