# zblog-CommonCloudStorage

**Repository Path**: web/zblog-common-cloud-storage

## Basic Information

- **Project Name**: zblog-CommonCloudStorage
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-15
- **Last Updated**: 2025-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


## 插件简介
=======
# 云存储附件上传插件

> 专为Z-Blog开发的云存储解决方案，支持S3协议和FTP协议的文件存储服务

## 📖 插件简介

========================

## 插件简介

云存储上传插件是一款专为Z-Blog开发的文件存储工具，支持直接将网站上传的图片和附件存储到各大云服务商的对象存储服务中，实现文件的云端存储和CDN加速。插件会将文件直接上传到云存储，而不是本地存储后再同步。

## 🌐 支持的存储服务

### 🔗 AWS S3协议兼容服务
| 服务商 | 服务名称 | 备注 |
|--------|----------|------|
| 腾讯云 | COS（Cloud Object Storage） | 推荐使用 |
| 阿里云 | OSS（Object Storage Service） | 推荐使用 |
| 华为云 | OBS（Object Storage Service） | 推荐使用 |
| 百度云 | BOS（Baidu Object Storage） | 支持 |
| 七牛云 | 对象存储 | 支持 |
| 又拍云 | 对象存储 | 支持 |
| AWS | S3 | 支持 |
| 其他 | 支持S3协议的服务 | 兼容 |

### 📁 FTP服务
- 支持标准FTP协议的文件服务器
- 支持FTPS（FTP over SSL/TLS）安全连接

## 🚀 快速开始

### 安装步骤

1. **下载插件**：获取最新版本的插件文件
2. **上传文件**：将插件文件夹上传到Z-Blog的 `zb_users/plugin/` 目录下
3. **确认名称**：确保文件夹名称为 `CommonCloudStorage`
4. **登录后台**：登录Z-Blog后台管理系统
5. **启用插件**：进入"插件管理"页面，找到"云存储同步插件"并点击"启用"
6. **配置插件**：插件启用后，进入插件管理界面进行详细配置

## 配置说明

### 基本配置项

1. **开启同步**
   - 勾选后启用自动同步功能
   - 未勾选时插件不会执行任何同步操作

2. **签名固定值**
   - AWS S3协议：适用于所有支持S3协议的对象存储服务
   - FTP空间：适用于传统FTP文件服务器

3. **密钥Access Key**
   - S3模式：填写对象存储服务的Access Key ID
   - FTP模式：填写FTP服务器的用户名

4. **密钥Secret Key**
   - S3模式：填写对象存储服务的Secret Access Key
   - FTP模式：填写FTP服务器的密码

5. **存储桶空间名**
   - S3模式：填写存储桶（Bucket）的名称
   - FTP模式：填写FTP服务器的IP地址和端口（如：192.168.1.100:21）

6. **存储桶访问域名**
   - S3模式：填写存储桶的访问域名
   - FTP模式：留空即可

7. **自定义地址**
   - 填写自定义绑定的域名地址
   - 留空则使用当前网站地址
   - 用于CDN加速或自定义域名访问

8. **区域设置**
   - S3模式：**必需填写**，存储区域代码（如：us-east-1、ap-beijing等）
   - FTP模式：留空即可
   - **重要说明**：区域设置在S3协议中用于构建API端点和签名认证，必须与实际存储桶区域一致

9. **自定义端点**
   - 可选配置，用于指定自定义的API端点地址
   - 留空则按以下优先级自动构建：存储桶访问域名 > 默认AWS端点
   - 适用于私有云或特殊配置的对象存储服务
   - 示例：https://s3.amazonaws.com 或 https://cos.ap-beijing.myqcloud.com

### 📋 各云服务商配置示例

#### 腾讯云COS配置
```yaml
签名固定值: AWS S3协议
密钥Access Key: 您的SecretId
密钥Secret Key: 您的SecretKey
存储桶空间名: your-bucket-name
存储桶访问域名: your-bucket-name.cos.ap-beijing.myqcloud.com
自定义地址: https://your-cdn-domain.com  # 可选
区域设置: ap-beijing
自定义端点: 留空  # 或填写: https://cos.ap-beijing.myqcloud.com
```

#### 阿里云OSS配置
```yaml
签名固定值: AWS S3协议
密钥Access Key: 您的AccessKeyId
密钥Secret Key: 您的AccessKeySecret
存储桶空间名: your-bucket-name
存储桶访问域名: your-bucket-name.oss-cn-hangzhou.aliyuncs.com
自定义地址: https://your-cdn-domain.com  # 可选
区域设置: oss-cn-hangzhou
自定义端点: 留空  # 或填写: https://oss-cn-hangzhou.aliyuncs.com
```

#### FTP服务器配置
```yaml
签名固定值: FTP空间
密钥Access Key: ftp用户名
密钥Secret Key: ftp密码
存储桶空间名: 192.168.1.100:21
存储桶访问域名: 留空
自定义地址: https://your-ftp-domain.com  # 可选
区域设置: 留空
```

## ⚙️ 功能使用

### 🔗 连接测试
配置完成后，点击"测试连接"按钮验证配置是否正确。**测试成功后才能正常使用同步功能**。

### 📤 直接上传
启用同步功能后，每当用户上传图片或附件时，插件会直接将文件上传到配置的云存储服务中，文件将直接存储在云端而非本地服务器。

### 🗑️ 同步删除
当在Z-Blog后台删除附件时，插件也会同步删除云端的对应文件，保持数据一致性。

### 🔄 批量替换
插件提供批量替换功能，可以将数据库中文章的附件地址进行批量替换：

| 替换类型 | 功能描述 | 使用场景 |
|----------|----------|----------|
| 替换为自定义地址 | 将本站地址替换为自定义域名地址 | CDN加速、自定义域名 |
| 替换为本站地址 | 将自定义域名地址替换回本站地址 | 恢复原始配置 |

> ⚠️ **重要提醒**：批量替换操作不可逆，请谨慎使用！建议操作前备份数据库。

### 📊 日志查看
插件会记录所有同步操作的日志，可以通过日志页面查看操作历史和错误信息，便于问题排查。

## ❓ 常见问题

### ❌ Q1: 配置正确但连接测试失败？
**A1:** 请按以下步骤排查：
1. **网络连接**：检查服务器网络是否正常
2. **密钥验证**：确认Access Key和Secret Key是否正确
3. **存储桶设置**：验证存储桶名称和区域设置是否匹配
4. **扩展支持**：确保服务器支持curl扩展（S3模式）或ftp扩展（FTP模式）
5. **区域一致性**：**特别注意**：区域设置必须与存储桶实际所在区域完全一致

### 📤 Q2: 文件上传成功但没有同步到云端？
**A2:** 请检查：
- 同步功能是否已开启
- 连接测试是否通过
- 查看日志页面了解具体错误信息

### 🌐 Q3: 如何设置CDN加速？
**A3:** 
1. 在云服务商控制台配置CDN服务
2. 将CDN域名填入"自定义地址"字段
3. 保存配置后测试访问

### 🔄 Q4: 批量替换后图片显示异常？
**A4:** 
- 确认自定义域名可以正常访问
- 检查CDN配置是否正确
- 使用"替换为本站地址"功能恢复原始配置

### 🌍 Q5: 区域设置有什么作用？
**A5:** 区域设置的作用：
- **S3模式**：必需设置，用于构建正确的API端点和AWS签名v4认证
- **FTP模式**：不需要，可以留空
- **错误影响**：错误的区域设置会导致连接失败或签名错误

### 💾 Q6: 文件上传后本地还有备份吗？
**A6:** 
- **成功上传**：文件成功上传到云端后会自动删除本地文件
- **上传失败**：如果云存储上传失败，本地文件会保留作为备份

## 📋 系统要求

### 软件环境
- **Z-Blog版本**：1.4.0 或以上版本
- **PHP版本**：5.6 或以上版本（推荐PHP 7.4+）

### 扩展要求
| 存储类型 | 必需扩展 | 可选扩展 |
|----------|----------|----------|
| S3模式 | curl扩展 | openssl扩展 |
| FTP模式 | ftp扩展 | openssl扩展（FTPS） |

### 资源要求
- 足够的磁盘空间用于临时文件处理
- 稳定的网络连接
- 适当的内存配置（推荐128MB+）

## 🔒 安全建议

### 🔑 密钥管理
- 定期更换Access Key和Secret Key
- 使用最小权限原则配置存储桶权限
- 避免在代码中硬编码密钥信息

### 📊 数据安全
- 合理设置存储桶的访问权限策略
- 定期备份重要数据到多个位置
- 启用版本控制防止误删除

### 👀 监控审计
- 定期监控插件操作日志
- 设置告警机制及时发现异常操作
- 定期审查访问权限和配置

## 💡 技术支持

### 🛠️ 问题排查
如果在使用过程中遇到问题，请按以下步骤排查：

1. **查看插件日志**：了解详细错误信息和操作历史
2. **检查服务器日志**：查看系统级别的错误信息
3. **验证网络连接**：确认服务器到云服务的网络连通性
4. **核对配置信息**：仔细检查各项配置参数是否正确

### 📞 获取帮助
如果以上步骤无法解决问题，请联系技术支持获取帮助：
- 提供详细的错误日志信息
- 描述具体的操作步骤和配置信息
- 说明期望的结果和实际表现

## 🔄 版本更新

请定期关注插件更新，新版本可能包含以下改进：

### 🚀 性能优化
- 上传下载速度提升
- 内存使用优化
- 并发处理能力增强

### 🛡️ 安全增强
- 加密算法升级
- 权限控制细化
- 漏洞修复

### ✨ 新功能
- 支持更多云存储服务
- 新增管理功能
- 用户体验优化

### 🐛 问题修复
- 已知Bug修复
- 兼容性改进
- 稳定性提升

---

## 📄 许可证信息
本插件遵循相关开源协议，具体请查看插件文件中的LICENSE文件。

## 🤝 贡献指南
欢迎提交Issue和Pull Request来帮助改进这个插件。

## 📞 联系方式
- 技术支持：Z-Blog开发团队
- 文档版本：v1.0
- 最后更新：2025/10/15

> 💡 **提示**：本文档会随插件版本更新，请定期查看最新版本。