新增说明文件
This commit is contained in:
zyj
207
STORAGE_QUICK_START.md
Normal file
207
STORAGE_QUICK_START.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# BBolt 存储快速开始
|
||||
|
||||
## 🚀 已完成的工作
|
||||
|
||||
✅ 安装 BBolt 依赖 (`go.etcd.io/bbolt@latest`)
|
||||
✅ 创建存储服务基础架构 (`storage/store.go`)
|
||||
✅ 实现站点数据 CRUD (`storage/site_store.go`)
|
||||
✅ 实现下载记录管理 (`storage/download_store.go`)
|
||||
✅ 集成到应用主服务 (`app.go`)
|
||||
✅ 更新类型定义 (`types/site_config.go`)
|
||||
✅ 修复前端类型绑定 (`webpage.vue`)
|
||||
|
||||
## 📁 新增文件
|
||||
|
||||
```
|
||||
go-site-clone/
|
||||
├── storage/ # 存储层（新增）
|
||||
│ ├── store.go # BBolt 核心封装
|
||||
│ ├── site_store.go # 站点配置存储
|
||||
│ └── download_store.go # 下载记录存储
|
||||
├── types/
|
||||
│ └── site_config.go # 站点配置类型定义（新增）
|
||||
├── data/ # 数据目录（运行时自动创建）
|
||||
│ └── site-clone.db # BBolt 数据库文件
|
||||
└── STORAGE.md # 存储方案文档（新增）
|
||||
```
|
||||
|
||||
## 🎯 核心功能
|
||||
|
||||
### 1. 自动初始化
|
||||
应用启动时自动创建数据库和必要的 buckets：
|
||||
- `sites` - 站点配置
|
||||
- `download_records` - 下载记录
|
||||
- `access_logs` - 访问日志（预留）
|
||||
- `settings` - 系统设置（预留）
|
||||
|
||||
### 2. 双重存储
|
||||
- **数据库**: BBolt 存储（快速查询）
|
||||
- **配置文件**: Nginx conf 文件（运行时使用）
|
||||
- 自动同步两者状态
|
||||
|
||||
### 3. 数据持久化
|
||||
- 站点配置自动保存
|
||||
- 下载记录自动记录
|
||||
- 支持数据查询和统计
|
||||
|
||||
## 🔧 使用方法
|
||||
|
||||
### 前端调用示例
|
||||
|
||||
```typescript
|
||||
import { App } from "../../../bindings/go-site-clone";
|
||||
|
||||
// 1. 添加站点
|
||||
await App.AddNginxSite({
|
||||
ID: "",
|
||||
Name: "example.com",
|
||||
Domains: ["example.com", "127.0.0.1"],
|
||||
Port: 8080,
|
||||
Path: "www/example.com",
|
||||
Index: "index.html",
|
||||
Enabled: true
|
||||
});
|
||||
|
||||
// 2. 获取所有站点
|
||||
const sites = await App.GetAllNginxSites();
|
||||
|
||||
// 3. 删除站点
|
||||
await App.DeleteNginxSite("example.com");
|
||||
|
||||
// 4. 添加下载记录
|
||||
await App.AddDownloadRecord({
|
||||
id: "",
|
||||
url: "https://example.com",
|
||||
site_name: "example.com",
|
||||
status: "processing",
|
||||
total_files: 100,
|
||||
downloaded: 0
|
||||
});
|
||||
|
||||
// 5. 获取下载统计
|
||||
const stats = await App.GetDownloadStats();
|
||||
```
|
||||
|
||||
## 📊 可用 API
|
||||
|
||||
### 站点管理
|
||||
- `AddNginxSite(site)` - 添加站点
|
||||
- `GetAllNginxSites()` - 获取所有站点
|
||||
- `UpdateNginxSite(site)` - 更新站点
|
||||
- `DeleteNginxSite(name)` - 删除站点
|
||||
- `EnableNginxSite(name)` - 启用站点
|
||||
- `DisableNginxSite(name)` - 禁用站点
|
||||
|
||||
### 下载记录
|
||||
- `AddDownloadRecord(record)` - 添加记录
|
||||
- `GetAllDownloadRecords()` - 获取所有记录
|
||||
- `GetRecentDownloadRecords(limit)` - 获取最近记录
|
||||
- `GetDownloadStats()` - 获取统计信息
|
||||
- `DeleteDownloadRecord(id)` - 删除记录
|
||||
- `ClearOldDownloadRecords(days)` - 清理旧记录
|
||||
|
||||
### 数据备份
|
||||
- `BackupDatabase(path)` - 备份数据库
|
||||
|
||||
## 🎨 数据结构
|
||||
|
||||
### 站点配置
|
||||
```go
|
||||
type NginxSiteConfig struct {
|
||||
ID string // 唯一标识
|
||||
Name string // 站点名称
|
||||
Domains []string // 域名列表
|
||||
Port int // 端口号
|
||||
Path string // 文件路径
|
||||
Index string // 默认首页
|
||||
Enabled bool // 是否启用
|
||||
}
|
||||
```
|
||||
|
||||
### 下载记录
|
||||
```go
|
||||
type DownloadRecord struct {
|
||||
ID string // 记录ID
|
||||
URL string // 下载URL
|
||||
SiteName string // 站点名称
|
||||
Status string // 状态: success/failed/processing
|
||||
TotalFiles int // 总文件数
|
||||
Downloaded int // 已下载数
|
||||
CSSCount int // CSS 数量
|
||||
ScriptCount int // JS 数量
|
||||
ImageCount int // 图片数量
|
||||
VideoCount int // 视频数量
|
||||
ErrorMsg string // 错误信息
|
||||
StartTime time.Time // 开始时间
|
||||
EndTime time.Time // 结束时间
|
||||
Duration int64 // 耗时（秒）
|
||||
}
|
||||
```
|
||||
|
||||
## 💡 最佳实践
|
||||
|
||||
### 1. 错误处理
|
||||
```typescript
|
||||
try {
|
||||
await App.AddNginxSite(siteConfig);
|
||||
message.success('添加成功');
|
||||
} catch (error) {
|
||||
message.error('添加失败: ' + error.message);
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 数据同步
|
||||
添加、更新、删除站点时，系统会自动：
|
||||
- 更新数据库
|
||||
- 生成/更新/删除 nginx 配置文件
|
||||
- 如果 nginx 运行中，自动重载配置
|
||||
|
||||
### 3. 定期备份
|
||||
```typescript
|
||||
// 建议定期备份数据库
|
||||
const backupPath = `backups/backup-${Date.now()}.db`;
|
||||
await App.BackupDatabase(backupPath);
|
||||
```
|
||||
|
||||
### 4. 清理旧数据
|
||||
```typescript
|
||||
// 清理 30 天前的下载记录
|
||||
const deleted = await App.ClearOldDownloadRecords(30);
|
||||
console.log(`清理了 ${deleted} 条记录`);
|
||||
```
|
||||
|
||||
## 📝 注意事项
|
||||
|
||||
1. **数据库位置**: `data/site-clone.db`（自动创建）
|
||||
2. **备份方式**: 直接复制 db 文件或使用 API
|
||||
3. **并发安全**: BBolt 内部处理，无需担心
|
||||
4. **性能**: 适合 < 10,000 站点，< 100,000 记录
|
||||
5. **迁移**: 首次运行自动从 nginx 配置迁移
|
||||
|
||||
## 🔍 调试
|
||||
|
||||
### 查看数据库内容
|
||||
可以使用 bbolt 命令行工具：
|
||||
```bash
|
||||
go install go.etcd.io/bbolt/cmd/bbolt@latest
|
||||
bbolt dump data/site-clone.db
|
||||
```
|
||||
|
||||
### 数据库统计
|
||||
```bash
|
||||
bbolt stats data/site-clone.db
|
||||
```
|
||||
|
||||
## 📚 更多信息
|
||||
|
||||
详细文档请查看 [STORAGE.md](./STORAGE.md)
|
||||
|
||||
## ✅ 验证安装
|
||||
|
||||
运行应用后检查：
|
||||
1. `data/` 目录是否创建
|
||||
2. `data/site-clone.db` 文件是否存在
|
||||
3. 添加站点后，数据库中是否有记录
|
||||
4. 控制台是否显示 "数据库初始化成功"
|
||||
|
||||
完成！🎉
|
||||
Reference in New Issue
Block a user