first commit

2026-06-03 10:09:03 +08:00
commit 81f5039458
6266 changed files with 188236 additions and 0 deletions
@@ -0,0 +1,253 @@
+# 存储配置功能说明
+
+## 功能概述
+
+系统支持两种文件存储方式：
+1. **本地存储**：文件存储在服务器本地磁盘
+2. **七牛云存储**：文件存储在七牛云对象存储服务
+
+## 数据库变更
+
+### 新增表
+
+**表名**: `yz_system_storage_config`
+
+**字段说明**:
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| id | bigint(20) | 主键ID |
+| storage_type | varchar(20) | 存储类型: local/qiniu |
+| qiniu_access_key | varchar(255) | 七牛云AccessKey |
+| qiniu_secret_key | varchar(255) | 七牛云SecretKey |
+| qiniu_bucket | varchar(128) | 七牛云Bucket名称 |
+| qiniu_domain | varchar(255) | 七牛云CDN域名 |
+| qiniu_region | varchar(50) | 七牛云存储区域 |
+| create_time | datetime | 创建时间 |
+| update_time | datetime | 更新时间 |
+
+### 执行迁移
+
+```bash
+# 在MySQL中执行迁移脚本
+mysql -u your_user -p your_database < go/migrations/add_storage_config_table.sql
+```
+
+## 后端实现
+
+### 新增文件
+
+1. **模型文件**: `go/models/storage_config.go`
+   - 定义 `StorageConfig` 模型
+   - 提供 `GetStorageConfig()` 方法获取配置
+
+2. **控制器文件**: `go/controllers/storage_config.go`
+   - `GetStorageConfig`: 获取存储配置
+   - `SaveStorageConfig`: 保存存储配置
+
+3. **路由注册**: `go/routers/platform/platform.go`
+   ```go
+   beego.Router("/platform/storageConfig", &controllers.StorageConfigController{}, "get:GetStorageConfig")
+   beego.Router("/platform/saveStorageConfig", &controllers.StorageConfigController{}, "post:SaveStorageConfig")
+   ```
+
+### API接口
+
+#### 获取存储配置
+```
+GET /platform/storageConfig
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "storage_type": "qiniu",
+    "qiniu_access_key": "your_access_key",
+    "qiniu_secret_key": "your_secret_key",
+    "qiniu_bucket": "your_bucket",
+    "qiniu_domain": "https://cdn.example.com",
+    "qiniu_region": "z0"
+  }
+}
+```
+
+#### 保存存储配置
+```
+POST /platform/saveStorageConfig
+```
+
+**请求体**:
+```json
+{
+  "storage_type": "qiniu",
+  "qiniu_access_key": "your_access_key",
+  "qiniu_secret_key": "your_secret_key",
+  "qiniu_bucket": "your_bucket",
+  "qiniu_domain": "https://cdn.example.com",
+  "qiniu_region": "z0"
+}
+```
+
+## 前端实现
+
+### 新增文件
+
+1. **API文件**: `platform/src/api/sitesettings.js`
+   - 新增 `getStorageConfig()` 方法
+   - 新增 `saveStorageConfig()` 方法
+
+2. **组件文件**: `platform/src/views/system/platformsettings/components/storageSettings.vue`
+   - 存储配置表单组件
+   - 支持本地存储和七牛云存储切换
+   - 表单验证和数据持久化
+
+3. **页面更新**: `platform/src/views/system/platformsettings/index.vue`
+   - 新增"存储配置"标签页
+
+### 使用说明
+
+1. 登录平台管理后台
+2. 进入"系统设置" -> "平台设置"
+3. 切换到"存储配置"标签页
+4. 选择存储类型：
+   - **本地存储**：无需额外配置
+   - **七牛云存储**：需要填写以下信息
+
+### 七牛云配置步骤
+
+1. **注册七牛云账号**
+   - 访问 https://www.qiniu.com/
+   - 注册并完成实名认证
+
+2. **创建存储空间**
+   - 登录七牛云控制台
+   - 进入"对象存储" -> "空间管理"
+   - 点击"新建空间"
+   - 填写空间名称（Bucket）
+   - 选择存储区域
+   - 设置访问控制（建议选择"公开"）
+
+3. **获取密钥**
+   - 进入"个人中心" -> "密钥管理"
+   - 查看或创建 AccessKey 和 SecretKey
+
+4. **配置CDN域名**
+   - 在存储空间详情页，进入"域名管理"
+   - 添加自定义域名或使用测试域名
+   - 完成域名备案和CNAME解析
+   - 获取CDN加速域名
+
+5. **填写配置信息**
+   - AccessKey: 从密钥管理获取
+   - SecretKey: 从密钥管理获取
+   - Bucket: 存储空间名称
+   - CDN域名: 完整的域名地址（如 https://cdn.example.com）
+   - 存储区域: 选择创建空间时的区域
+
+### 存储区域对照表
+
+| 区域名称 | 区域代码 |
+|---------|---------|
+| 华东-浙江 | z0 |
+| 华北-河北 | z1 |
+| 华南-广东 | z2 |
+| 北美-洛杉矶 | na0 |
+| 亚太-新加坡 | as0 |
+| 华东-浙江2 | cn-east-2 |
+
+## 后续开发建议
+
+### 文件上传服务改造
+
+需要修改文件上传相关的代码，根据 `storage_type` 选择不同的存储方式：
+
+```go
+// 示例代码
+func UploadFile(file *multipart.FileHeader) (string, error) {
+    cfg, _ := models.GetStorageConfig()
+    
+    switch cfg.StorageType {
+    case "qiniu":
+        return uploadToQiniu(file, cfg)
+    case "local":
+        return uploadToLocal(file)
+    default:
+        return uploadToLocal(file)
+    }
+}
+```
+
+### 七牛云SDK集成
+
+需要安装七牛云Go SDK：
+
+```bash
+go get github.com/qiniu/go-sdk/v7
+```
+
+示例上传代码：
+
+```go
+import (
+    "github.com/qiniu/go-sdk/v7/auth/qbox"
+    "github.com/qiniu/go-sdk/v7/storage"
+)
+
+func uploadToQiniu(file *multipart.FileHeader, cfg *models.StorageConfig) (string, error) {
+    mac := qbox.NewMac(cfg.QiniuAccessKey, cfg.QiniuSecretKey)
+    putPolicy := storage.PutPolicy{
+        Scope: cfg.QiniuBucket,
+    }
+    upToken := putPolicy.UploadToken(mac)
+    
+    // 配置上传参数
+    cfg := storage.Config{
+        Zone:          &storage.ZoneHuadong, // 根据 cfg.QiniuRegion 选择
+        UseHTTPS:      true,
+        UseCdnDomains: false,
+    }
+    
+    formUploader := storage.NewFormUploader(&cfg)
+    ret := storage.PutRet{}
+    
+    // 执行上传
+    err := formUploader.PutFile(context.Background(), &ret, upToken, key, localFile, nil)
+    if err != nil {
+        return "", err
+    }
+    
+    // 返回完整URL
+    return cfg.QiniuDomain + "/" + ret.Key, nil
+}
+```
+
+## 注意事项
+
+1. **安全性**
+   - SecretKey 在数据库中明文存储，建议后续加密处理
+   - 生产环境建议使用环境变量或密钥管理服务
+
+2. **成本**
+   - 七牛云存储和流量会产生费用
+   - 建议设置合理的存储策略和CDN缓存规则
+
+3. **迁移**
+   - 切换存储方式时，已有文件不会自动迁移
+   - 需要手动迁移或保持双存储支持
+
+4. **备份**
+   - 重要文件建议定期备份
+   - 七牛云支持跨区域备份功能
+
+## 测试清单
+
+- [ ] 数据库表创建成功
+- [ ] 后端API接口正常
+- [ ] 前端页面显示正常
+- [ ] 本地存储配置保存成功
+- [ ] 七牛云配置保存成功
+- [ ] 表单验证正常工作
+- [ ] 配置切换功能正常
+- [ ] 数据持久化正常