RhenCloud/Cloud-Index
1
0
Fork 0
mirror of https://github.com/RhenCloud/Cloud-Index.git synced 2025-12-06 15:26:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

初始化文档

Browse Source
This commit is contained in:
RhenCloud
2025-11-09 14:21:55 +08:00
commit e97717dfe7
26 changed files with 8747 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

334
docs/guide/configuration.md Normal file
View File

@@ -0,0 +1,334 @@
---
title: 配置指南
createTime: 2025/11/09 00:26:55
permalink: /guide/configuration
---
# 配置说明
本文档详细说明了 Cloud Index 的各种配置选项。
## 配置方式
Cloud Index 通过环境变量进行配置，有两种主要方式：
### 1. 环境变量文件 (.env)
在项目根目录创建 `.env` 文件：
```bash
cp .env.example .env
```
编辑 `.env` 文件，添加需要的配置。
### 2. 系统环境变量
直接在系统中设置环境变量（适用于 Docker、Serverless 等环境）。
## 存储后端配置
### STORAGE_TYPE（必需）
选择要使用的存储后端：
```env
# Cloudflare R2
STORAGE_TYPE=r2
# Amazon S3
STORAGE_TYPE=s3
# GitHub 仓库
STORAGE_TYPE=github
# GitHub Release
STORAGE_TYPE=github-release
```
## Cloudflare R2 配置
当 `STORAGE_TYPE=r2` 时，需要配置以下环境变量：
```env
# ===== R2 基础配置 =====
STORAGE_TYPE=r2
# R2 API 访问凭证
ACCESS_KEY_ID=your_access_key_id
SECRET_ACCESS_KEY=your_secret_access_key
# R2 存储桶信息
R2_ENDPOINT_URL=https://your-account-id.r2.cloudflarestorage.com
R2_BUCKET_NAME=your-bucket-name
R2_REGION=auto
# ===== 可选配置 =====
# 公开访问 URL（用于生成可分享的文件链接）
R2_PUBLIC_URL=https://pub-your-bucket.r2.dev
# 预签名 URL 过期时间（秒），默认 3600
R2_PRESIGN_EXPIRES=3600
```
**配置说明：**
| 配置项 | 说明 | 获取方式 |
|-------|------|---------|
| `ACCESS_KEY_ID` | R2 API Token ID | Cloudflare 控制面板 |
| `SECRET_ACCESS_KEY` | R2 API Token Secret | Cloudflare 控制面板 |
| `R2_ENDPOINT_URL` | R2 端点 URL | Cloudflare 控制面板（Account ID） |
| `R2_BUCKET_NAME` | 存储桶名称 | Cloudflare 控制面板 |
| `R2_PUBLIC_URL` | 公开 URL（可选） | Cloudflare 控制面板 → Custom Domain |
**获取凭证步骤：**
1. 登录 [Cloudflare 控制面板](https://dash.cloudflare.com)
2. 进入 R2 → API Tokens
3. 创建新 Token，复制 ID 和 Secret
4. 记录你的 Account ID（在 R2 仓库页面显示）
## Amazon S3 配置
当 `STORAGE_TYPE=s3` 时，需要配置以下环境变量：
```env
# ===== S3 基础配置 =====
STORAGE_TYPE=s3
# AWS 访问凭证
ACCESS_KEY_ID=your_aws_access_key
SECRET_ACCESS_KEY=your_aws_secret_key
# S3 存储桶信息
S3_BUCKET_NAME=your-bucket-name
S3_REGION=us-east-1
# ===== 可选配置 =====
# 自定义 S3 端点（用于兼容的 S3 服务）
S3_ENDPOINT_URL=https://s3.amazonaws.com
# 公开访问 URL
S3_PUBLIC_URL=https://your-bucket-name.s3.amazonaws.com
# 预签名 URL 过期时间（秒）
S3_PRESIGN_EXPIRES=3600
```
**配置说明：**
| 配置项 | 说明 | 获取方式 |
|-------|------|---------|
| `ACCESS_KEY_ID` | AWS Access Key ID | AWS IAM 控制台 |
| `SECRET_ACCESS_KEY` | AWS Secret Access Key | AWS IAM 控制台 |
| `S3_BUCKET_NAME` | 存储桶名称 | AWS S3 控制台 |
| `S3_REGION` | 存储桶区域 | AWS S3 控制台 |
**常用区域代码：**
```
us-east-1 - 美国东部（N. Virginia）
us-west-2 - 美国西部（Oregon）
eu-west-1 - 欧洲（Ireland）
ap-northeast-1 - 亚太（Tokyo）
cn-north-1 - 中国（北京）
```
## GitHub 存储配置
当 `STORAGE_TYPE=github` 时，需要配置以下环境变量：
```env
# ===== GitHub 基础配置 =====
STORAGE_TYPE=github
# GitHub 账户信息
GITHUB_REPO_OWNER=your-username
GITHUB_REPO_NAME=your-repo-name
GITHUB_ACCESS_TOKEN=your_github_personal_token
# ===== 可选配置 =====
# 使用的分支，默认 main
GITHUB_BRANCH=main
# GitHub Raw 内容代理 URL（用于加速访问）
GITHUB_RAW_PROXY_URL=https://raw.ghproxy.com
# 预签名 URL 过期时间（秒）
GITHUB_PRESIGN_EXPIRES=3600
```
**配置说明：**
| 配置项 | 说明 | 获取方式 |
|-------|------|---------|
| `GITHUB_REPO_OWNER` | GitHub 用户名或组织名 | GitHub Profile |
| `GITHUB_REPO_NAME` | 仓库名称 | GitHub 仓库页面 |
| `GITHUB_ACCESS_TOKEN` | Personal Access Token | GitHub Settings → Developer settings |
| `GITHUB_RAW_PROXY_URL` | Raw 内容代理（可选） | 第三方代理服务 |
**获取 Token 步骤：**
1. 登录 GitHub
2. 进入 Settings → Developer settings → Personal access tokens
3. 创建新 Token（New fine-grained personal access token）
4. 勾选 `contents` 权限（读写仓库内容）
5. 复制 Token，保存到 `.env` 文件
**推荐代理服务：**
```
https://raw.ghproxy.com - 国内加速
https://ghproxy.com - 国内加速
https://raw.githubusercontent.com - 官方（无加速）
```
## 应用配置
### 缓存配置
```env
# 缩略图缓存过期时间（秒），默认 3600（1小时）
THUMB_TTL_SECONDS=3600
```
### 应用服务器配置
```env
# Flask 调试模式（开发环境推荐启用）
FLASK_ENV=development
FLASK_DEBUG=1
# 应用监听地址
FLASK_RUN_HOST=0.0.0.0
# 应用监听端口
FLASK_RUN_PORT=5000
```
### 日志配置
```env
# 日志级别
LOG_LEVEL=INFO
# 日志文件路径
LOG_FILE=/var/log/Cloud Index/app.log
```
## 完整配置示例
### R2 + 国内代理
```env
# 存储配置
STORAGE_TYPE=r2
ACCESS_KEY_ID=abc123xyz
SECRET_ACCESS_KEY=def456uvw
R2_ENDPOINT_URL=https://account123.r2.cloudflarestorage.com
R2_BUCKET_NAME=my-bucket
R2_REGION=auto
R2_PUBLIC_URL=https://pub-my-bucket.r2.dev
R2_PRESIGN_EXPIRES=7200
# 应用配置
FLASK_ENV=production
FLASK_RUN_HOST=0.0.0.0
FLASK_RUN_PORT=8080
THUMB_TTL_SECONDS=7200
```
### GitHub + 加速代理
```env
# 存储配置
STORAGE_TYPE=github
GITHUB_REPO_OWNER=myusername
GITHUB_REPO_NAME=my-storage
GITHUB_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxx
GITHUB_BRANCH=main
GITHUB_RAW_PROXY_URL=https://raw.ghproxy.com
# 应用配置
FLASK_ENV=production
THUMB_TTL_SECONDS=3600
```
### Amazon S3 + CDN
```env
# 存储配置
STORAGE_TYPE=s3
ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
S3_BUCKET_NAME=my-bucket
S3_REGION=us-west-2
S3_PUBLIC_URL=https://d123.cloudfront.net
# 应用配置
FLASK_ENV=production
FLASK_RUN_PORT=5000
```
## 环境变量优先级
1. 系统环境变量（最高）
2. `.env` 文件变量
3. 代码中的默认值（最低）
## 配置验证
启动应用后，检查日志输出确保配置正确：
```bash
python app.py
```
如果看到以下输出，说明配置成功：
```
* Serving Flask app 'app'
* Running on http://127.0.0.1:5000
[INFO] Storage backend initialized: R2
```
如果看到错误信息，检查：
1. 必需的环境变量是否都已设置
2. 凭证是否正确
3. 网络连接是否正常
## 故障排除
### 环境变量未被读取
确保：
1. `.env` 文件在项目根目录
2. 变量名称正确（区分大小写）
3. 没有多余的空格或引号
### 连接存储后端失败
检查：
1. 网络连接是否正常
2. 凭证是否有效
3. 防火墙是否阻止出站连接
4. 存储桶是否存在
### 公开 URL 不可用
确保：
1. 已配置公开 URL（可选）
2. 存储桶允许公开访问
3. CDN（如有）已配置
## 下一步
- [环境变量详解](./environment.md) - 每个环境变量的详细说明
- [部署指南](./deployment.md) - 生产环境部署
- [存储后端指南](../storage/) - 详细的后端配置指南

545
docs/guide/docker.md Normal file
View File

@@ -0,0 +1,545 @@
---
title: Docker 部署
createTime: 2025/11/09 00:26:55
permalink: /guide/docker
---
# Docker 部署
详细的 Docker 部署指南。
## 前置要求
- Docker 已安装（[获取 Docker](https://docs.docker.com/get-docker/)）
- Docker Compose 已安装（通常随 Docker Desktop 一同安装）
- 基本的 Docker 命令行知识
## 快速开始
### 1. 构建镜像
```bash
git clone https://github.com/RhenCloud/Cloud-Index.git
cd Cloud Index
# 构建镜像
docker build -t Cloud Index:latest .
```
### 2. 运行容器
```bash
docker run -d \
--name Cloud Index \
-p 5000:5000 \
-e STORAGE_TYPE=r2 \
-e R2_ENDPOINT_URL=https://account.r2.cloudflarestorage.com \
-e ACCESS_KEY_ID=your_key \
-e SECRET_ACCESS_KEY=your_secret \
-e R2_BUCKET_NAME=your_bucket \
Cloud Index:latest
```
### 3. 访问应用
打开浏览器访问 `http://localhost:5000`
## Docker Compose 部署
### 基础配置
创建 `docker-compose.yml`：
```yaml
version: '3.8'
services:
Cloud Index:
build: .
container_name: Cloud Index
ports:
- "5000:5000"
environment:
STORAGE_TYPE: r2
R2_ENDPOINT_URL: https://account.r2.cloudflarestorage.com
R2_BUCKET_NAME: your-bucket
ACCESS_KEY_ID: your_key
SECRET_ACCESS_KEY: your_secret
FLASK_ENV: production
volumes:
- ./cache:/app/static/thumbs
restart: always
```
启动服务：
```bash
docker-compose up -d
docker-compose logs -f
```
### 完整配置（含 Nginx）
```yaml
version: '3.8'
services:
app:
build:
context: .
dockerfile: Dockerfile
container_name: Cloud Index-app
environment:
STORAGE_TYPE: r2
R2_ENDPOINT_URL: ${R2_ENDPOINT_URL}
R2_BUCKET_NAME: ${R2_BUCKET_NAME}
ACCESS_KEY_ID: ${ACCESS_KEY_ID}
SECRET_ACCESS_KEY: ${SECRET_ACCESS_KEY}
FLASK_ENV: production
THUMB_TTL_SECONDS: 86400
volumes:
- app-cache:/app/static/thumbs
- app-logs:/app/logs
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:5000/"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
networks:
- r2-network
nginx:
image: nginx:alpine
container_name: Cloud Index-nginx
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./ssl:/etc/nginx/ssl:ro
- ./cache:/app/static/thumbs:ro
depends_on:
- app
restart: unless-stopped
networks:
- r2-network
volumes:
app-cache:
app-logs:
networks:
r2-network:
driver: bridge
```
## Dockerfile 详解
标准的 Dockerfile 配置：
```dockerfile
# 使用官方 Python 运行时作为基础镜像
FROM python:3.11-slim
# 设置工作目录
WORKDIR /app
# 安装系统依赖
RUN apt-get update && apt-get install -y \
gcc \
libjpeg-dev \
zlib1g-dev \
&& rm -rf /var/lib/apt/lists/*
# 复制依赖文件
COPY requirements.txt .
# 安装 Python 依赖
RUN pip install --no-cache-dir -r requirements.txt
# 复制应用代码
COPY . .
# 设置环境变量
ENV FLASK_APP=app.py
ENV FLASK_ENV=production
ENV FLASK_RUN_HOST=0.0.0.0
# 暴露端口
EXPOSE 5000
# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
CMD curl -f http://localhost:5000/ || exit 1
# 启动应用
CMD ["python", "app.py"]
```
## 环境变量配置
### 方式一：直接在命令行指定
```bash
docker run -d \
--name Cloud Index \
-p 5000:5000 \
-e STORAGE_TYPE=r2 \
-e R2_ENDPOINT_URL=https://account.r2.cloudflarestorage.com \
-e R2_BUCKET_NAME=my-bucket \
-e ACCESS_KEY_ID=key123 \
-e SECRET_ACCESS_KEY=secret456 \
Cloud Index:latest
```
### 方式二：使用环境文件
创建 `.env.docker`：
```env
STORAGE_TYPE=r2
R2_ENDPOINT_URL=https://account.r2.cloudflarestorage.com
R2_BUCKET_NAME=my-bucket
ACCESS_KEY_ID=key123
SECRET_ACCESS_KEY=secret456
FLASK_ENV=production
THUMB_TTL_SECONDS=86400
```
运行时指定：
```bash
docker run -d \
--name Cloud Index \
-p 5000:5000 \
--env-file .env.docker \
Cloud Index:latest
```
### 方式三：Docker Compose 环境文件
创建 `.env`，`docker-compose.yml` 自动读取：
```bash
cp .env.example .env
# 编辑 .env 文件
docker-compose up -d
```
## 数据卷管理
### 挂载缓存目录
```bash
# 本地缓存
docker run -d \
--name Cloud Index \
-p 5000:5000 \
-v $(pwd)/cache:/app/static/thumbs \
--env-file .env.docker \
Cloud Index:latest
# 命名卷
docker volume create r2-cache
docker run -d \
--name Cloud Index \
-p 5000:5000 \
-v r2-cache:/app/static/thumbs \
--env-file .env.docker \
Cloud Index:latest
```
### 挂载日志目录
```bash
docker run -d \
--name Cloud Index \
-p 5000:5000 \
-v $(pwd)/logs:/app/logs \
-v $(pwd)/cache:/app/static/thumbs \
--env-file .env.docker \
Cloud Index:latest
```
## 网络配置
### 单容器模式
```bash
docker run -d \
--name Cloud Index \
-p 5000:5000 \
--env-file .env.docker \
Cloud Index:latest
```
### Docker Compose 网络
```yaml
networks:
r2-network:
driver: bridge
```
容器内相互通信：
```yaml
services:
app:
networks:
- r2-network
nginx:
depends_on:
- app
networks:
- r2-network
```
访问 `http://app:5000` 时，Nginx 容器可以连接到应用容器。
## 常用命令
### 镜像操作
```bash
# 列出镜像
docker images
# 删除镜像
docker rmi Cloud Index:latest
# 标记镜像
docker tag Cloud Index:v1.0
# 推送到仓库
docker push myrepo/Cloud Index:v1.0
# 构建带标签的镜像
docker build -t Cloud Index:v1.0 .
```
### 容器操作
```bash
# 列出运行中的容器
docker ps
# 列出所有容器
docker ps -a
# 查看容器日志
docker logs Cloud Index
docker logs -f Cloud Index # 实时日志
docker logs --tail 100 Cloud Index # 最后 100 行
# 进入容器
docker exec -it Cloud Index bash
# 停止容器
docker stop Cloud Index
# 启动容器
docker start Cloud Index
# 重启容器
docker restart Cloud Index
# 删除容器
docker rm Cloud Index # 容器必须已停止
# 查看容器统计信息
docker stats Cloud Index
```
### Docker Compose 操作
```bash
# 启动所有服务
docker-compose up -d
# 停止所有服务
docker-compose down
# 查看日志
docker-compose logs -f
# 查看特定服务日志
docker-compose logs -f app
# 重启服务
docker-compose restart
# 构建镜像
docker-compose build
# 删除卷
docker-compose down -v
```
## 生产部署最佳实践
### 1. 使用数据卷持久化存储
```yaml
volumes:
app-cache:
driver: local
app-logs:
driver: local
services:
app:
volumes:
- app-cache:/app/static/thumbs
- app-logs:/app/logs
```
### 2. 设置资源限制
```yaml
services:
app:
resources:
limits:
cpus: '1'
memory: 512M
reservations:
cpus: '0.5'
memory: 256M
```
### 3. 配置健康检查
```yaml
services:
app:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:5000/"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
```
### 4. 日志驱动配置
```yaml
services:
app:
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
```
### 5. 重启策略
```yaml
services:
app:
restart: unless-stopped # 推荐值
# unless-stopped: 容器异常退出时重启，停止后不重启
# always: 总是重启
# on-failure: 仅在非 0 退出码时重启
# no: 不自动重启
```
## 监控和维护
### 查看容器资源使用
```bash
# 实时监控
docker stats Cloud Index
# 查看完整统计信息
docker stats --no-stream Cloud Index
```
### 清理无用资源
```bash
# 清理停止的容器
docker container prune
# 清理无用的镜像
docker image prune
# 清理无用的数据卷
docker volume prune
# 一次性清理所有无用资源
docker system prune -a
```
### 备份数据卷
```bash
# 备份名称为 r2-cache 的卷
docker run --rm \
-v r2-cache:/data \
-v $(pwd):/backup \
ubuntu \
tar czf /backup/r2-cache.tar.gz -C /data .
# 恢复
docker run --rm \
-v r2-cache:/data \
-v $(pwd):/backup \
ubuntu \
tar xzf /backup/r2-cache.tar.gz -C /data
```
## 故障排除
### 容器无法启动
```bash
# 查看详细错误日志
docker logs Cloud Index
# 进入容器调试
docker run -it --rm Cloud Index:latest bash
```
### 端口已被占用
```bash
# 查看占用端口的进程
lsof -i :5000
# 使用其他端口
docker run -d -p 8080:5000 Cloud Index:latest
```
### 卷权限问题
```bash
# 检查卷权限
docker inspect r2-cache
# 修复权限（进入容器操作）
docker exec Cloud Index chmod -R 755 /app/static/thumbs
```
### 内存溢出
```bash
# 设置内存限制
docker run -d \
--memory=512m \
--memory-swap=1g \
Cloud Index:latest
# 清理缓存
docker exec Cloud Index rm -rf /app/static/thumbs/*
```
## 参考资源
- [Docker 官方文档](https://docs.docker.com/)
- [Docker Compose 文件参考](https://docs.docker.com/compose/compose-file/)
- [Best practices for writing Dockerfiles](https://docs.docker.com/develop/dev-best-practices/dockerfile_best-practices/)

358
docs/guide/environment.md Normal file
View File

@@ -0,0 +1,358 @@
---
title: 环境配置
createTime: 2025/11/09 00:26:55
permalink: /guide/environment
---
# 环境变量完整参考
本文档列出了 Cloud Index 支持的所有环境变量及其详细说明。
## 环境变量表
### 核心配置
| 变量名 | 类型 | 必需 | 默认值 | 说明 |
|-------|------|------|-------|------|
| `STORAGE_TYPE` | string | ✅ | - | 存储后端类型：`r2`、`s3`、`github` |
| `FLASK_ENV` | string | ❌ | development | Flask 环境：`development` 或 `production` |
| `FLASK_DEBUG` | bool | ❌ | 0 | 调试模式（0 或 1） |
| `FLASK_RUN_HOST` | string | ❌ | 127.0.0.1 | 应用监听地址 |
| `FLASK_RUN_PORT` | int | ❌ | 5000 | 应用监听端口 |
### R2 配置
| 变量名 | 类型 | 必需 | 说明 |
|-------|------|------|------|
| `R2_ENDPOINT_URL` | string | ✅ | R2 端点 URL（包含 Account ID） |
| `R2_BUCKET_NAME` | string | ✅ | R2 存储桶名称 |
| `R2_REGION` | string | ❌ | 区域代码，R2 通常使用 `auto` |
| `R2_PUBLIC_URL` | string | ❌ | 公开访问 URL（用于生成分享链接） |
| `R2_PRESIGN_EXPIRES` | int | ❌ | 3600 | 预签名 URL 有效期（秒） |
| `ACCESS_KEY_ID` | string | ✅ | R2 API Token ID |
| `SECRET_ACCESS_KEY` | string | ✅ | R2 API Token Secret |
### S3 配置
| 变量名 | 类型 | 必需 | 说明 |
|-------|------|------|------|
| `S3_BUCKET_NAME` | string | ✅ | S3 存储桶名称 |
| `S3_REGION` | string | ✅ | AWS 区域代码（如 `us-east-1`） |
| `S3_ENDPOINT_URL` | string | ❌ | 自定义 S3 端点（默认 AWS 官方） |
| `S3_PUBLIC_URL` | string | ❌ | 公开访问 URL |
| `S3_PRESIGN_EXPIRES` | int | ❌ | 3600 | 预签名 URL 有效期（秒） |
| `ACCESS_KEY_ID` | string | ✅ | AWS Access Key ID |
| `SECRET_ACCESS_KEY` | string | ✅ | AWS Secret Access Key |
### GitHub 配置
| 变量名 | 类型 | 必需 | 说明 |
|-------|------|------|------|
| `GITHUB_REPO_OWNER` | string | ✅ | GitHub 用户名或组织名 |
| `GITHUB_REPO_NAME` | string | ✅ | GitHub 仓库名称 |
| `GITHUB_ACCESS_TOKEN` | string | ✅ | GitHub Personal Access Token |
| `GITHUB_BRANCH` | string | ❌ | 使用的分支，默认 `main` |
| `GITHUB_RAW_PROXY_URL` | string | ❌ | Raw 内容代理 URL（国内加速） |
| `GITHUB_PRESIGN_EXPIRES` | int | ❌ | 3600 | 预签名 URL 有效期（秒） |
### 缓存配置
| 变量名 | 类型 | 必需 | 默认值 | 说明 |
|-------|------|------|-------|------|
| `THUMB_TTL_SECONDS` | int | ❌ | 3600 | 缩略图缓存过期时间（秒） |
| `CACHE_DIR` | string | ❌ | static/thumbs | 缓存目录路径 |
### 日志配置
| 变量名 | 类型 | 必需 | 默认值 | 说明 |
|-------|------|------|-------|------|
| `LOG_LEVEL` | string | ❌ | INFO | 日志级别（DEBUG/INFO/WARNING/ERROR） |
| `LOG_FILE` | string | ❌ | - | 日志文件路径 |
## 详细说明
### STORAGE_TYPE
**类型**: String
**必需**: Yes
**可选值**:
- `r2` - Cloudflare R2
- `s3` - Amazon S3
- `github` - GitHub 仓库
- `github-release` - GitHub Release（开发中）
**示例**:
```env
STORAGE_TYPE=r2
```
### FLASK_ENV
**类型**: String
**必需**: No
**默认**: development
**可选值**:
- `development` - 开发模式（启用自动重载、详细错误日志）
- `production` - 生产模式（性能优化、最小化日志）
**示例**:
```env
FLASK_ENV=production
```
### FLASK_DEBUG
**类型**: Integer (0 or 1)
**必需**: No
**默认**: 0
**说明**: 启用 Flask 调试器和代码热加载（仅用于开发）
**示例**:
```env
FLASK_DEBUG=1
```
⚠️ **警告**: 不要在生产环境启用调试模式！
### FLASK_RUN_HOST
**类型**: String
**必需**: No
**默认**: 127.0.0.1
**说明**: 应用监听的 IP 地址
**常用值**:
```env
FLASK_RUN_HOST=0.0.0.0 # 监听所有网络接口（推荐用于部署）
FLASK_RUN_HOST=127.0.0.1 # 仅本地访问（开发用）
FLASK_RUN_HOST=192.168.1.10 # 监听特定 IP
```
### FLASK_RUN_PORT
**类型**: Integer
**必需**: No
**默认**: 5000
**说明**: 应用监听的端口号
**示例**:
```env
FLASK_RUN_PORT=8080 # 使用 8080 端口
FLASK_RUN_PORT=80 # 使用 HTTP 默认端口
```
### ACCESS_KEY_ID 和 SECRET_ACCESS_KEY
**类型**: String
**必需**: Yes（对于 R2 和 S3）
**说明**: 云存储服务的 API 凭证
⚠️ **安全提示**:
- ✅ 在 `.env` 文件中存储凭证
- ✅ 将 `.env` 加入 `.gitignore`
- ❌ 不要在代码中硬编码凭证
- ❌ 不要上传 `.env` 到 Git
- ❌ 不要在日志中打印凭证
**示例**:
```env
ACCESS_KEY_ID=abc123xyz789
SECRET_ACCESS_KEY=def456uvw789ghi
```
### R2_ENDPOINT_URL
**类型**: String
**必需**: Yes（对于 R2）
**格式**: `https://<account-id>.r2.cloudflarestorage.com`
**说明**: Cloudflare R2 API 端点
**获取方式**: 在 Cloudflare 控制面板 R2 部分查看
**示例**:
```env
R2_ENDPOINT_URL=https://a1b2c3d4e5f6g7h8i.r2.cloudflarestorage.com
```
### R2_BUCKET_NAME
**类型**: String
**必需**: Yes（对于 R2）
**说明**: R2 存储桶名称
**示例**:
```env
R2_BUCKET_NAME=my-storage
```
### R2_PUBLIC_URL
**类型**: String
**必需**: No
**说明**: R2 公开访问 URL，用于生成可分享的文件链接
**格式**: `https://pub-<bucket-name>.r2.dev`
**获取方式**: 在 Cloudflare 控制面板 R2 存储桶设置中配置自定义域
**示例**:
```env
R2_PUBLIC_URL=https://pub-my-storage.r2.dev
```
### S3_REGION
**类型**: String
**必需**: Yes（对于 S3）
**说明**: AWS 区域代码
**常用值**:
```
us-east-1 美国东部（N. Virginia）
us-west-2 美国西部（Oregon）
eu-west-1 欧洲（Ireland）
ap-northeast-1 亚太（Tokyo）
ap-southeast-1 亚太（Singapore）
cn-north-1 中国（北京）
```
**示例**:
```env
S3_REGION=ap-northeast-1
```
### GITHUB_REPO_OWNER
**类型**: String
**必需**: Yes（对于 GitHub）
**说明**: GitHub 用户名或组织名
**示例**:
```env
GITHUB_REPO_OWNER=myusername
GITHUB_REPO_OWNER=my-organization # 组织名
```
### GITHUB_ACCESS_TOKEN
**类型**: String
**必需**: Yes（对于 GitHub）
**格式**: `ghp_xxxxxxxxxxxxxxxxxxxxx`
**说明**: GitHub Personal Access Token
⚠️ **安全提示**: Token 具有访问仓库的权限，保护好它！
### GITHUB_RAW_PROXY_URL
**类型**: String
**必需**: No
**说明**: GitHub Raw 文件内容的代理 URL（用于加速国内访问）
**推荐代理服务**:
```
https://raw.ghproxy.com/ 国内加速（推荐）
https://ghproxy.com/ 国内加速
https://raw.githubusercontent.com/ 官方（无代理）
```
**示例**:
```env
GITHUB_RAW_PROXY_URL=https://raw.ghproxy.com
```
### THUMB_TTL_SECONDS
**类型**: Integer
**必需**: No
**默认**: 3600
**说明**: 生成的缩略图缓存过期时间（秒）
**常用值**:
```
3600 1 小时
86400 1 天
604800 1 周
2592000 30 天
```
**示例**:
```env
THUMB_TTL_SECONDS=86400 # 缩略图缓存 1 天
```
### LOG_LEVEL
**类型**: String
**必需**: No
**默认**: INFO
**可选值**: DEBUG, INFO, WARNING, ERROR, CRITICAL
**示例**:
```env
LOG_LEVEL=DEBUG # 开发环境
LOG_LEVEL=WARNING # 生产环境
```
## 快速参考
### 最小配置（R2）
```env
STORAGE_TYPE=r2
ACCESS_KEY_ID=your_key
SECRET_ACCESS_KEY=your_secret
R2_ENDPOINT_URL=https://account.r2.cloudflarestorage.com
R2_BUCKET_NAME=mybucket
```
### 最小配置（S3）
```env
STORAGE_TYPE=s3
ACCESS_KEY_ID=your_key
SECRET_ACCESS_KEY=your_secret
S3_BUCKET_NAME=mybucket
S3_REGION=us-east-1
```
### 最小配置（GitHub）
```env
STORAGE_TYPE=github
GITHUB_REPO_OWNER=myusername
GITHUB_REPO_NAME=my-storage
GITHUB_ACCESS_TOKEN=ghp_xxx
```
## 验证配置
运行以下命令验证环境变量是否正确加载：
```bash
python -c "import os; from dotenv import load_dotenv; load_dotenv(); print('STORAGE_TYPE:', os.getenv('STORAGE_TYPE'))"
```
## 相关文档
- [配置说明](./configuration.md) - 配置指南
- [部署指南](./deployment.md) - 生产部署
- [存储后端指南](../storage/) - 各后端详细配置

228
docs/guide/introduction.md Normal file
View File

@@ -0,0 +1,228 @@
---
title: 项目介绍
createTime: 2025/11/09 00:26:55
permalink: /guide/introduction
---
# 项目介绍
## 项目概述
**Cloud Index** 是一个现代化的、功能完整的云存储文件管理系统。它提供了一个统一的文件浏览、管理和共享界面，支持多种云存储后端，使用户能够轻松地在不同的云存储服务之间切换。
## 在线演示
你可以在在线演示中体验 Cloud Index 的主要功能（浏览、预览、上传、下载等）。
- Demo 地址：[https://r2.demo.cloud-index.rhen.cloud](https://r2.demo.cloud-index.rhen.cloud)（使用Cloudflare R2作为存储后端）
- Demo 地址：[https://github.demo.cloud-index.rhen.cloud](https://github.demo.cloud-index.rhen.cloud)（使用Github Repository作为存储后端）
### 项目特点
#### 1. 多后端支持
通过灵活的架构设计，支持多种云存储服务：
- **Cloudflare R2** - 低成本的S3兼容对象存储
- **Amazon S3** - 业界标准的对象存储服务
- **GitHub Repository** - 将GitHub仓库作为存储后端
- **GitHub Release** - 利用Release API存储文件（开发中）
后端可以通过简单的配置进行切换，无需修改代码。
#### 2. 完整的文件操作功能
提供常见的文件管理功能：
- 📁 目录浏览与导航
- 📝 文件详情查看（名称、大小、修改时间等）
- ⬆️ 文件上传
- 🗑️ 文件删除
- ✏️ 文件/文件夹重命名
- 📂 创建新文件夹
- 📋 复制文件/文件夹
- 🔄 移动文件/文件夹
#### 3. 智能媒体处理
- 🖼️ 自动生成缩略图，支持缓存
- 👁️ 图片预览
- 📊 文件类型识别和对应图标
- 🎨 美观的预览界面
#### 4. 分享与访问
- 🌐 生成公共访问URL（如果存储支持）
- 🔗 预签名URL支持，具有过期时间控制
- 📱 移动设备友好的响应式设计
- 🌙 深色模式支持
#### 5. 企业级特性
- 🔐 环境变量配置管理
- 📊 文件大小格式化显示
- 🌍 国际化支持（中文/英文）
- ⚡ 高性能缓存机制
## 项目架构
### 核心组件
```
Cloud-Index/
├── app.py # Flask 应用主入口
├── handlers/
│ └── routes.py # 路由处理
├── storages/
│ ├── base.py # 存储基类
│ ├── factory.py # 存储工厂（策略模式）
│ ├── r2.py # Cloudflare R2 实现
│ ├── s3.py # Amazon S3 实现
│ └── github.py # GitHub 存储实现
├── templates/ # HTML 模板
│ ├── base.html # 基础模板
│ ├── index.html # 主页面
│ └── footer.html # 页脚
└── static/ # 静态资源
├── css/ # 样式表
├── js/ # JavaScript 文件
└── thumbs/ # 缩略图缓存
```
### 架构模式
1. **工厂模式** - `StorageFactory` 负责根据配置创建相应的存储实现
2. **策略模式** - 不同的存储后端实现相同的 `BaseStorage` 接口
3. **MVC模式** - 使用 Flask 框架实现标准的 MVC 架构
## 技术栈
| 组件 | 技术 | 说明 |
|-----|------|------|
| **后端框架** | Flask | 轻量级 Python Web 框架 |
| **前端** | HTML5/CSS3/JS | 原生 Web 技术 |
| **对象存储** | AWS S3 SDK | boto3 库 |
| **文件处理** | Pillow | 图片处理库 |
| **API调用** | requests | HTTP 库 |
| **部署** | Docker/Vercel | 容器化和Serverless部署 |
## 工作流程
### 文件浏览流程
```
用户请求
↓
Flask 路由处理
↓
存储工厂获取对应后端
↓
执行存储操作（list/get/delete等）
↓
模板渲染
↓
返回给用户
```
### 文件上传流程
```
用户上传文件
↓
Flask 接收请求
↓
验证文件
↓
调用存储后端上传
↓
返回结果
```
### 缩略图生成流程
```
请求图片缩略图
↓
检查缓存
↓
缓存命中？ → 返回缓存
↓ 否
获取原始文件
↓
使用 Pillow 生成缩略图
↓
保存到本地缓存
↓
返回缩略图
```
## 存储后端选择指南
### Cloudflare R2
**最佳用途**: 低成本、小企业、边缘计算优先
- 💰 价格最低（存储费用免费，仅收取请求费）
- 🚀 全球 CDN 加速
- 🔄 S3 API 兼容
- 适合: 静态资源、备份、媒体库
### Amazon S3
**最佳用途**: 大企业、高可用性、完整生态
- 📊 功能最完整
- 🔒 安全性最高
- 🌍 全球可用
- 💼 企业级支持
- 适合: 生产环境、大规模应用、合规要求高
### GitHub Repository
**最佳用途**: 轻量级、免费、版本控制
- 🆓 完全免费（利用GitHub存储）
- 📝 自动版本控制
- 🔐 访问权限管理
- 易于备份和迁移
- 适合: 文档、配置文件、小文件、开源项目
## 性能指标
- **文件列表响应** < 100ms（本地缓存）
- **缩略图生成** 平均 50-200ms（取决于图片大小）
- **文件上传** 无限制（取决于网络）
- **并发连接** 支持数百并发请求
- **缓存有效期** 可配置（默认1小时）
## 与其他解决方案对比
| 特性 | Cloud Index | Nextcloud | MinIO | S3 Web UI |
|-----|---------|----------|-------|-----------|
| 多后端支持 | ✅ | ❌ | ❌ | ❌ |
| 易部署 | ✅ | ❌ | ⚠️ | ❌ |
| 低成本 | ✅ | ❌ | ⚠️ | ❌ |
| 功能完整度 | ✅ | ✅✅ | ✅ | ⚠️ |
| 学习曲线 | 低 | 高 | 中 | 低 |
## 未来规划
- [ ] GitHub Release 存储支持
- [ ] 基于数据库的用户权限管理
- [ ] 操作日志记录与审计
- [ ] Office 文档预览支持
- [ ] 视频预览支持
- [ ] 文件夹打包下载
- [ ] API 文档完善
- [ ] WebDAV 支持
- [ ] 搜索功能增强
- [ ] 分享链接和权限管理
## 许可证
GPLv3 License - 详见项目根目录的 LICENSE 文件
## 相关链接
- 📖 [GitHub 仓库](https://github.com/RhenCloud/Cloud-Index>)
- 🐛 [问题报告](https://github.com/RhenCloud/Cloud-Index/issues>)
- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions>)

259
docs/guide/quickstart.md Normal file
View File

@@ -0,0 +1,259 @@
---
title: 快速开始
createTime: 2025/11/09 00:26:55
permalink: /guide/quickstart
---
# 快速开始
本指南将帮助你快速上手 Cloud Index。
## 5 分钟快速开始
### 第 1 步：启动应用
安装完成后，启动应用：
```bash
python app.py
```
你会看到类似的输出：
```
* Serving Flask app 'app'
* Debug mode: off
* Running on http://127.0.0.1:5000
```
### 第 2 步：打开浏览器
访问 `http://localhost:5000`，你会看到文件管理界面。
### 第 3 步：浏览文件
主界面显示存储桶/仓库中的文件和文件夹：
- 📁 **文件夹** - 点击打开，浏览子文件夹
- 📄 **文件** - 点击查看详情或下载
- 🖼️ **图片** - 点击查看预览和缩略图
## 基本操作
### 文件浏览
| 操作 | 说明 |
|-----|------|
| **点击文件夹** | 打开文件夹，查看内容 |
| **点击文件名** | 查看文件详情 |
| **右键菜单** | 显示更多操作选项 |
### 文件信息
每个文件显示以下信息：
- 📝 **文件名** - 文件的完整名称
- 📏 **大小** - 文件大小（自动格式化为 B/KB/MB/GB）
- 📅 **修改时间** - 最后修改时间
- 🏷️ **文件类型** - 文件对应的图标
### 操作菜单
点击文件右侧的菜单按钮（⋮）或右键点击文件，获得以下选项：
**如果是文件：**
- 📥 **下载** - 下载文件到本地
- 🔗 **复制链接** - 复制文件的公开访问链接
- 🗑️ **删除** - 删除文件
- ✏️ **重命名** - 重命名文件
**如果是文件夹：**
- 📂 **新建文件夹** - 在当前文件夹创建子文件夹
- ⬆️ **上传文件** - 上传文件到当前文件夹
- ✏️ **重命名** - 重命名文件夹
- 🗑️ **删除** - 删除整个文件夹（包含子文件）
## 常见任务
### 上传文件
#### 使用 UI 上传
1. 点击"上传文件"按钮
2. 选择要上传的文件
3. 点击"确认"
4. 等待上传完成
#### 通过拖拽上传
1. 将文件拖到浏览器窗口
2. 选择目标文件夹
3. 放下鼠标，上传开始
### 下载文件
#### 单个文件下载
1. 点击文件
2. 点击菜单中的"下载"
3. 文件保存到下载文件夹
#### 复制公开链接
1. 点击文件菜单
2. 选择"复制链接"
3. 粘贴链接分享给他人
### 创建文件夹
1. 在目标位置点击"新建文件夹"
2. 输入文件夹名称
3. 确认创建
### 移动/复制文件
1. 右键点击文件/文件夹
2. 选择"剪切"或"复制"
3. 导航到目标文件夹
4. 右键选择"粘贴"
### 删除文件/文件夹
1. 右键点击文件/文件夹
2. 选择"删除"
3. 确认删除
**⚠️ 注意**: 删除操作不可撤销，请谨慎操作。
## 图片预览
Cloud Index 对图片文件提供了特殊支持：
- 🖼️ **缩略图显示** - 列表中显示图片缩略图
- 👁️ **图片预览** - 点击图片查看全尺寸预览
- ⚡ **缓存加速** - 缩略图被缓存以加快加载速度
- 📐 **自适应大小** - 根据屏幕尺寸自动调整
## 深色模式
Cloud Index 支持深色模式，点击右上角的主题按钮 🌙/☀️ 切换：
- 🌙 **深色模式** - 适合低光环境，保护眼睛
- ☀️ **浅色模式** - 经典亮色主题
## 响应式设计
应用在所有设备上都能正常使用：
| 设备 | 特性 |
|-----|------|
| **桌面** | 完整的侧边栏和功能菜单 |
| **平板** | 自适应布局，触屏友好 |
| **手机** | 简化菜单，优化触屏交互 |
## 键盘快捷键
| 快捷键 | 功能 |
|-------|------|
| `Ctrl/Cmd + U` | 上传文件 |
| `Ctrl/Cmd + N` | 新建文件夹 |
| `Delete` | 删除选中项 |
| `Escape` | 关闭弹窗 |
## 性能提示
### 加快加载速度
1. **使用缓存** - 缩略图被自动缓存
2. **减少文件数** - 大文件夹可能加载较慢
3. **选择快速网络** - 使用稳定的网络连接
4. **启用 CDN** - 为存储配置 CDN 加速（如 Cloudflare）
### 上传大文件
对于超过 100MB 的文件：
1. 使用有线网络而不是 WiFi
2. 避免在高峰期上传
3. 确保足够的磁盘空间
4. 完成后验证文件完整性
## 设置和配置
### 环境变量设置
编辑 `.env` 文件配置：
```env
# 选择存储后端
STORAGE_TYPE=r2 # 或 s3, github
# 存储凭证
ACCESS_KEY_ID=your_key
SECRET_ACCESS_KEY=your_secret
# 缩略图缓存时间
THUMB_TTL_SECONDS=3600
```
详见 [环境变量配置](./environment.md)
### 存储后端切换
修改 `STORAGE_TYPE` 环境变量即可切换存储后端，无需修改代码：
```bash
# 使用 Cloudflare R2
STORAGE_TYPE=r2
# 或使用 Amazon S3
STORAGE_TYPE=s3
# 或使用 GitHub 仓库
STORAGE_TYPE=github
```
重启应用生效：
```bash
# 关闭当前应用 (Ctrl+C)
# 重新启动
python app.py
```
## 故障排除
### 文件显示不完整
- 检查存储配置是否正确
- 验证访问凭证是否有效
- 查看浏览器控制台是否有错误信息
### 上传失败
- 检查文件大小是否超过限制
- 确保网络连接稳定
- 验证存储空间是否充足
### 缩略图不显示
- 刷新页面重试
- 检查 `static/thumbs/` 文件夹权限
- 确保图片格式受支持（JPG, PNG, GIF, WebP）
## 下一步
- 📖 [配置说明](./configuration.md) - 了解高级配置
- 🚀 [部署指南](./deployment.md) - 在生产环境部署
- 💾 [存储后端配置](../storage/) - 配置不同的存储后端
## 获取帮助
遇到问题？
- 📖 查看 [完整文档](./introduction.md)
- 🐛 提交 [Issue](https://github.com/RhenCloud/Cloud-Index/issues>)
- 💬 在 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions>) 提问
祝你使用愉快！🎉

382
docs/guide/vercel.md Normal file
View File

@@ -0,0 +1,382 @@
---
title: Vercel 部署
createTime: 2025/11/09 00:26:55
permalink: /guide/vercel
---
# Vercel 部署
在 Vercel 上快速部署 Cloud Index 的完整指南。
## 优势
- ✅ 零配置部署
- ✅ 自动 HTTPS
- ✅ 全球 CDN 加速
- ✅ 自动扩展
- ✅ 免费额度充足
- ✅ 与 GitHub 无缝集成
## 前置要求
- GitHub 账户
- Vercel 账户（[注册免费账户](https://vercel.com/signup)）
- 存储后端配置（R2、S3 或 GitHub）
## 部署步骤
### 第 1 步：Fork 项目
访问 [Cloud Index GitHub 仓库](https://github.com/RhenCloud/Cloud-Index)，点击 "Fork" 按钮。
### 第 2 步：连接到 Vercel
1. 登录 [Vercel 控制台](https://vercel.com/dashboard)
2. 点击 "Add New..." → "Project"
3. 点击 "Import Git Repository"
4. 连接 GitHub 账户
5. 选择你 Fork 的仓库
### 第 3 步：配置项目
在 Import 页面：
1. **Project Name** - 输入项目名称（如 `cloud-index`）
2. **Framework** - 选择 "Python" 或保持默认
3. **Root Directory** - 保持默认（根目录）
### 第 4 步：配置环境变量
点击 "Environment Variables"，添加以下变量：
**基础配置：**
```
STORAGE_TYPE = r2
```
**R2 存储配置：**
```
R2_ENDPOINT_URL = https://your-account-id.r2.cloudflarestorage.com
R2_BUCKET_NAME = your-bucket-name
ACCESS_KEY_ID = your_access_key
SECRET_ACCESS_KEY = your_secret_key
R2_PUBLIC_URL = https://pub-your-bucket.r2.dev
```
或 **S3 存储配置：**
```
STORAGE_TYPE = s3
S3_BUCKET_NAME = your-bucket-name
S3_REGION = us-east-1
ACCESS_KEY_ID = your_access_key
SECRET_ACCESS_KEY = your_secret_key
```
或 **GitHub 存储配置：**
```
STORAGE_TYPE = github
GITHUB_REPO_OWNER = your-username
GITHUB_REPO_NAME = your-repo-name
GITHUB_ACCESS_TOKEN = your_github_token
GITHUB_RAW_PROXY_URL = https://raw.ghproxy.com
```
**应用配置：**
```
FLASK_ENV = production
THUMB_TTL_SECONDS = 604800
```
### 第 5 步：部署
1. 检查配置无误
2. 点击 "Deploy" 按钮
3. 等待部署完成
部署完成后，Vercel 会提供一个 URL（如 `https://cloud-index.vercel.app`）
## 配置自定义域名
### 1. 添加域名
1. 进入项目设置 → "Domains"
2. 输入你的域名（如 `cloud.example.com`）
3. 点击 "Add"
### 2. 配置 DNS
Vercel 会提供 DNS 记录，按照说明在你的域名提供商处配置：
- **CNAME** 记录指向 Vercel
- 或使用 **A** 记录指向 Vercel IP
### 3. 验证和启用
DNS 生效后（通常需要几分钟到几小时），Vercel 会自动验证并启用 HTTPS。
## 自动部署
当你推送代码到 GitHub 时，Vercel 会自动部署新版本。
### 触发部署
提交代码到 main 分支：
```bash
git add .
git commit -m "Update configuration"
git push origin main
```
Vercel 会自动开始部署。你可以在 Vercel Dashboard 中查看部署进度。
## 更新配置
### 方式一：通过 Vercel Dashboard
1. 进入项目设置
2. 选择 "Environment Variables"
3. 编辑相应变量
4. 需要重新部署时，点击 Redeploy
### 方式二：通过代码
在项目根目录创建 `vercel.json` 文件（已包含）：
```json
{
"version": 2,
"builds": [
{
"src": "app.py",
"use": "@vercel/python"
},
{
"src": "/static/**",
"use": "@vercel/static"
}
],
"routes": [
{
"src": "/(.*)",
"dest": "app.py"
}
]
}
```
编辑后推送到 GitHub，Vercel 会自动重新部署。
## 日志查看
### 查看部署日志
1. 进入项目
2. 点击 "Deployments" 选项卡
3. 选择相应的部署
4. 查看 "Logs" 中的详细信息
### 查看实时日志
1. 进入项目
2. 点击 "Functions" 选项卡
3. 选择 `app.py`
4. 查看实时日志
### 使用 Vercel CLI
```bash
# 安装 CLI
npm i -g vercel
# 登录
vercel login
# 查看日志
vercel logs <project-url>
# 实时日志
vercel logs <project-url> --follow
```
## 性能优化
### 1. 启用 Edge Caching
在 `vercel.json` 中配置缓存头：
```json
"routes": [
{
"src": "/static/(.*)",
"headers": {
"cache-control": "public, max-age=86400, immutable"
},
"dest": "app.py"
},
{
"src": "/(.*)",
"dest": "app.py"
}
]
```
### 2. 优化缓存设置
增大缩略图缓存时间（在 Environment Variables）：
```
THUMB_TTL_SECONDS = 2592000 # 30 天
```
### 3. 使用 Vercel Analytics
1. 进入项目设置
2. 选择 "Analytics"
3. 启用 Vercel Analytics
可以实时监控应用性能和用户行为。
## 监控和告警
### Vercel Monitoring
在项目设置中配置告警：
1. 进入项目 → "Settings" → "Notifications"
2. 设置部署失败时的通知
3. 选择通知方式（Email、Slack 等）
### 错误追踪
Vercel 自动集成错误追踪。通过以下方式查看：
1. 进入 "Functions" 选项卡
2. 查看错误率和详细错误信息
## 限制和配额
### 计算
- **免费版**: 100GB-Hours/月
- 每次冷启动 < 10 秒
- 单个函数最大执行时间 900 秒
### 存储
- **缓存**: 512MB（临时）
- **函数空间**: 50MB 代码
### 带宽
- **免费版**: 100GB/月
### 费用估算
假设月均 1 万次请求，每次执行 500ms：
- 计算: 5,000 秒 / 1,000 = 5GB-Hours（远低于 100GB 免费额度）
- **预计费用**: 免费 ✅
## 故障排除
### 部署失败
检查：
1. `vercel.json` 配置是否正确
2. `requirements.txt` 是否包含所有依赖
3. Python 版本是否兼容（推荐 3.9+）
### 环境变量未生效
1. 确保在 Environment Variables 中正确配置
2. 重新部署应用（Redeploy）
3. 清理浏览器缓存
### 冷启动慢
- Vercel 自动缓存函数以加速启动
- 增加使用频率会自动改善冷启动时间
- 无需手动优化
### 存储无法连接
检查：
1. 环境变量是否正确
2. 凭证是否有效
3. 防火墙/安全组是否允许访问
### 缓存空间不足
清理或减少缓存：
1. 减小缩略图生成质量
2. 减少缓存过期时间
3. 定期手动清理
## 成本优化建议
1. **使用 Cloudflare R2** 而不是 S3（成本更低）
2. **启用缓存** 减少存储访问次数
3. **监控使用量** 避免超限
4. **使用付费计划** 如果超过免费额度（$20/月 Pro 计划）
## 与本地开发保持同步
### 拉取最新变化
```bash
git pull origin main
```
### 测试本地更改
```bash
python app.py
# 访问 http://localhost:5000
```
### 推送到 Vercel
```bash
git add .
git commit -m "Bug fix or feature"
git push origin main
```
Vercel 会自动检测并部署。
## 回滚部署
如果新部署出现问题：
1. 进入项目 → "Deployments"
2. 选择之前的稳定版本
3. 点击 "Redeploy to Production"
应用会立即回滚到之前的版本。
## 获取帮助
- 📖 [Vercel 文档](https://vercel.com/docs)
- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues>)
- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions>)
- 📧 Email: <i@rhen.cloud>
## 总结
| 功能 | 本地 | Docker | Vercel |
|-----|------|--------|--------|
| 部署难度 | 简单 | 中等 | 简单 |
| 成本 | 自有服务器 | 中等 | 小 |
| 性能 | 取决于服务器 | 好 | 优秀 |
| 扩展性 | 有限 | 中等 | 自动 |
| 推荐用途 | 开发测试 | 生产环境 | 中小型应用 |
Vercel 最适合需要快速部署、无需运维的应用！🚀