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

22
docs/.vuepress/client.ts Normal file
View File

@@ -0,0 +1,22 @@
import { defineClientConfig } from 'vuepress/client'
// import RepoCard from 'vuepress-theme-plume/features/RepoCard.vue'
// import NpmBadge from 'vuepress-theme-plume/features/NpmBadge.vue'
// import NpmBadgeGroup from 'vuepress-theme-plume/features/NpmBadgeGroup.vue'
// import Swiper from 'vuepress-theme-plume/features/Swiper.vue'
// import CustomComponent from './theme/components/Custom.vue'
// import './theme/styles/custom.css'
export default defineClientConfig({
enhance({ app }) {
// built-in components
// app.component('RepoCard', RepoCard)
// app.component('NpmBadge', NpmBadge)
// app.component('NpmBadgeGroup', NpmBadgeGroup)
// app.component('Swiper', Swiper) // you should install `swiper`
// your custom components
// app.component('CustomComponent', CustomComponent)
},
})

16
docs/.vuepress/collections.ts Normal file
View File

@@ -0,0 +1,16 @@
import { defineUserConfig } from "vuepress";
import { plumeTheme } from "vuepress-theme-plume";
export default defineUserConfig({
theme: plumeTheme({
collections: [
{
type: "doc",
dir: "guide",
linkPrefix: "/guide/",
title: "TypeScript 笔记",
sidebar: ["basic", "types"],
},
],
}),
});

168
docs/.vuepress/config.ts Normal file
View File

@@ -0,0 +1,168 @@
/**
* 查看以下文档了解主题配置
* - @see https://theme-plume.vuejs.press/config/intro/ 配置说明
* - @see https://theme-plume.vuejs.press/config/theme/ 主题配置项
*
* 请注意，对此文件的修改都会重启 vuepress 服务。
* 部分配置项的更新没有必要重启 vuepress 服务，建议请在 `.vuepress/config.ts` 文件中配置
*
* 特别的，请不要在两个配置文件中重复配置相同的项，当前文件的配置项会被覆盖
*/
import { viteBundler } from "@vuepress/bundler-vite";
import { defineUserConfig } from "vuepress";
import { plumeTheme } from "vuepress-theme-plume";
export default defineUserConfig({
base: "/",
lang: "zh-CN",
title: "Cloud Index Docs",
description: "一个支持多种云存储后端的文件管理、索引和浏览服务",
head: [
// 配置站点图标
["link", { rel: "icon", type: "image/png", href: "https://theme-plume.vuejs.press/favicon-32x32.png" }],
],
bundler: viteBundler(),
shouldPrefetch: false, // 站点较大，页面数量较多时，不建议启用
theme: plumeTheme({
/* 添加您的部署域名, 有助于 SEO, 生成 sitemap */
hostname: "https://docs.cloud-index.rhen.cloud",
/* 文档仓库配置，用于 editLink */
docsRepo: "RhenCloud/Cloud Index", // TODO: 替换为你的仓库，例如 'RhenCloud/cloud-index-docs'
docsDir: "docs",
docsBranch: "docs",
/* 页内信息 */
editLink: true,
lastUpdated: {},
contributors: true,
// changelog: false,
/**
* 编译缓存，加快编译速度
* @see https://theme-plume.vuejs.press/config/basic/#cache
*/
cache: "filesystem",
/**
* 为 markdown 文件自动添加 frontmatter 配置
* @see https://theme-plume.vuejs.press/config/basic/#autofrontmatter
*/
autoFrontmatter: {
permalink: false, // 禁用自动生成随机 permalink，改为手动配置
createTime: true, // 是否生成创建时间
title: true, // 是否生成标题
},
/* 本地搜索, 默认启用 */
search: { provider: "local" },
/**
* Algolia DocSearch
* 启用此搜索需要将 本地搜索 search 设置为 false
* @see https://theme-plume.vuejs.press/config/plugins/search/#algolia-docsearch
*/
// search: {
// provider: 'algolia',
// appId: '',
// apiKey: '',
// indices: [''],
// },
/**
* Shiki 代码高亮
* @see https://theme-plume.vuejs.press/config/plugins/code-highlight/
*/
// codeHighlighter: {
// twoslash: true, // 启用 twoslash
// whitespace: true, // 启用 空格/Tab 高亮
// lineNumbers: true, // 启用行号
// },
/* 文章字数统计、阅读时间，设置为 false 则禁用 */
// readingTime: true,
/**
* markdown
* @see https://theme-plume.vuejs.press/config/markdown/
*/
// markdown: {
// abbr: true, // 启用 abbr 语法 *[label]: content
// annotation: true, // 启用 annotation 语法 [+label]: content
// pdf: true, // 启用 PDF 嵌入 @[pdf](/xxx.pdf)
// caniuse: true, // 启用 caniuse 语法 @[caniuse](feature_name)
// plot: true, // 启用隐秘文本语法 !!xxxx!!
// bilibili: true, // 启用嵌入 bilibili视频 语法 @[bilibili](bid)
// youtube: true, // 启用嵌入 youtube视频 语法 @[youtube](video_id)
// artPlayer: true, // 启用嵌入 artPlayer 本地视频 语法 @[artPlayer](url)
// audioReader: true, // 启用嵌入音频朗读功能 语法 @[audioReader](url)
// icon: { provider: 'iconify' }, // 启用内置图标语法 ::icon-name::
// table: true, // 启用表格增强容器语法 ::: table
// codepen: true, // 启用嵌入 codepen 语法 @[codepen](user/slash)
// replit: true, // 启用嵌入 replit 语法 @[replit](user/repl-name)
// codeSandbox: true, // 启用嵌入 codeSandbox 语法 @[codeSandbox](id)
// jsfiddle: true, // 启用嵌入 jsfiddle 语法 @[jsfiddle](user/id)
// npmTo: true, // 启用 npm-to 容器 ::: npm-to
// demo: true, // 启用 demo 容器 ::: demo
// repl: { // 启用 代码演示容器
// go: true, // ::: go-repl
// rust: true, // ::: rust-repl
// kotlin: true, // ::: kotlin-repl
// python: true, // ::: python-repl
// },
// math: { // 启用数学公式
// type: 'katex',
// },
// chartjs: true, // 启用 chart.js
// echarts: true, // 启用 ECharts
// mermaid: true, // 启用 mermaid
// flowchart: true, // 启用 flowchart
// image: {
// figure: true, // 启用 figure
// lazyload: true, // 启用图片懒加载
// mark: true, // 启用图片标记
// size: true, // 启用图片大小
// },
// include: true, // 在 Markdown 文件中导入其他 markdown 文件内容
// imageSize: 'local', // 启用 自动填充 图片宽高属性，避免页面抖动
// },
/**
* 水印
* @see https://theme-plume.vuejs.press/guide/features/watermark/
*/
// watermark: true,
/**
* 评论 comments
* @see https://theme-plume.vuejs.press/guide/features/comments/
*/
// comment: {
// provider: '', // "Artalk" | "Giscus" | "Twikoo" | "Waline"
// comment: true,
// repo: '',
// repoId: '',
// category: '',
// categoryId: '',
// mapping: 'pathname',
// reactionsEnabled: true,
// inputPosition: 'top',
// },
/**
* 资源链接替换
* @see https://theme-plume.vuejs.press/guide/features/replace-assets/
*/
// replaceAssets: 'https://cdn.example.com',
/**
* 加密功能
* @see https://theme-plume.vuejs.press/guide/features/encryption/
*/
// encrypt: {},
}),
});

30
docs/.vuepress/navbar.ts Normal file
View File

@@ -0,0 +1,30 @@
/**
* @see https://theme-plume.vuejs.press/config/navigation/ 查看文档了解配置详情
*
* Navbar 配置文件，它在 `.vuepress/plume.config.ts` 中被导入。
*/
import { defineNavbarConfig } from "vuepress-theme-plume";
export default defineNavbarConfig([
{ text: "首页", link: "/" },
{
text: "📖 文档",
items: [
{ text: "项目介绍", link: "/guide/introduction" },
{ text: "快速开始", link: "/guide/quickstart" },
{ text: "安装指南", link: "/guide/installation" },
{ text: "配置指南", link: "/guide/configuration" },
{ text: "部署指南", link: "/guide/deployment" },
],
},
{
text: "☁️ 存储后端",
items: [
{ text: "后端概览", link: "/storage/overview" },
{ text: "Cloudflare R2", link: "/storage/r2" },
{ text: "Amazon S3", link: "/storage/s3" },
{ text: "GitHub", link: "/storage/github" },
],
},
]);

125
docs/.vuepress/plume.config.ts Normal file
View File

@@ -0,0 +1,125 @@
/**
* 查看以下文档了解主题配置
* - @see https://theme-plume.vuejs.press/config/intro/ 配置说明
* - @see https://theme-plume.vuejs.press/config/theme/ 主题配置项
*
* 请注意，对此文件的修改不会重启 vuepress 服务，而是通过热更新的方式生效
* 但同时部分配置项不支持热更新，请查看文档说明
* 对于不支持热更新的配置项，请在 `.vuepress/config.ts` 文件中配置
*
* 特别的，请不要在两个配置文件中重复配置相同的项，当前文件的配置项会覆盖 `.vuepress/config.ts` 文件中的配置
*/
import { defineThemeConfig } from "vuepress-theme-plume";
import navbar from "./navbar";
import collections from "./collections";
/**
* @see https://theme-plume.vuejs.press/config/basic/
*/
export default defineThemeConfig({
logo: "https://theme-plume.vuejs.press/plume.png",
appearance: true, // 配置 深色模式
social: [
{ icon: "github", link: "https://github.com/RhenCloud/Cloud-Index" }, // TODO: 替换为实际仓库 URL
],
// navbarSocialInclude: ['github'], // 允许显示在导航栏的 social 社交链接
aside: true, // 页内侧边栏， 默认显示在右侧
outline: [2, 3], // 页内大纲， 默认显示 h2, h3
/**
* 文章版权信息
* @see https://theme-plume.vuejs.press/guide/features/copyright/
*/
// copyright: true,
// prevPage: true, // 是否启用上一页链接
// nextPage: true, // 是否启用下一页链接
// createTime: true, // 是否显示文章创建时间
/* 站点页脚 */
// footer: {
// message: 'Power by <a target="_blank" href="https://v2.vuepress.vuejs.org/">VuePress</a> & <a target="_blank" href="https://theme-plume.vuejs.press">vuepress-theme-plume</a>',
// copyright: '',
// },
/**
* @see https://theme-plume.vuejs.press/config/basic/#profile
*/
profile: {
avatar: "https://theme-plume.vuejs.press/plume.png",
name: "Cloud Index Docs",
description: "一个支持多种云存储后端的文件管理、索引和浏览服务",
// circle: true,
// location: '',
// organization: '',
},
navbar,
// collections,
/**
* 侧边栏配置
* @see https://theme-plume.vuejs.press/config/navigation/#sidebar
*/
sidebar: {
"/guide/": [
{
text: "📖 使用指南",
collapsed: false,
items: [
{ text: "项目介绍", link: "/guide/introduction" },
{ text: "快速开始", link: "/guide/quickstart" },
{
text: "配置",
collapsed: false,
items: [
{ text: "配置指南", link: "/guide/configuration" },
{ text: "环境配置", link: "/guide/environment" },
],
},
{
text: "部署",
collapsed: false,
items: [
// { text: "Docker 部署", link: "/guide/docker" },
{ text: "Vercel 部署", link: "/guide/vercel" },
],
},
],
},
],
"/storage/": [
{
text: "☁️ 存储后端",
collapsed: false,
items: [
{ text: "后端概览", link: "/storage/overview" },
{ text: "Cloudflare R2", link: "/storage/r2" },
{ text: "Amazon S3", link: "/storage/s3" },
{ text: "GitHub", link: "/storage/github" },
],
},
],
},
/**
* 公告板
* @see https://theme-plume.vuejs.press/guide/features/bulletin/
*/
// bulletin: {
// layout: 'top-right',
// contentType: 'markdown',
// title: '公告板标题',
// content: '公告板内容',
// },
/* 过渡动画 @see https://theme-plume.vuejs.press/config/basic/#transition */
// transition: {
// page: true, // 启用 页面间跳转过渡动画
// postList: true, // 启用 博客文章列表过渡动画
// appearance: 'fade', // 启用 深色模式切换过渡动画, 或配置过渡动画类型
// },
});

8
docs/.vuepress/public/plume.svg Normal file
View File

@@ -0,0 +1,8 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 72 72">
<path fill="#5086a1" d="M42.334 49.147a29.945 29.945 0 0 1-19.338-8.151c-8.014-7.365-8.378-18.076-8.533-22.649l-.022-.627a2.904 2.904 0 0 1 3.457-2.951c17.005 3.355 21.695 16.324 22.056 17.4a49.543 49.543 0 0 1 3.574 15.922a1 1 0 0 1-.967 1.052c-.029.001-.106.004-.227.004" />
<path fill="#8cccd5" d="M44.436 55.316c-11.646 0-17.376-6.974-17.653-7.354a1 1 0 0 1 .262-1.424a11.103 11.103 0 0 1 12.774-1.574c-1.465-9.078 1.877-13.568 2.031-13.77a.998.998 0 0 1 .75-.39a.97.97 0 0 1 .78.325c8.944 9.771 8.793 16.532 7.908 19.691c-.034.14-1.062 4.092-4.772 4.406c-.711.062-1.405.09-2.08.09" />
<g fill="none" stroke="#333" stroke-linecap="round" stroke-linejoin="round" stroke-width="1">
<path d="M55.184 57.69S34.96 45.877 23.097 24.206m22.131 30.096c-11.93.46-17.628-6.88-17.628-6.88" />
<path d="M40.528 42.483c-.56-7.195 2.116-10.679 2.116-10.679c8.834 9.654 8.406 16.162 7.681 18.747m-13.311-3.129a30.15 30.15 0 0 1-13.341-7.162c-8.072-7.419-8.067-18.241-8.232-22.577a1.903 1.903 0 0 1 2.264-1.932C34.694 19.103 39.02 32.528 39.02 32.528" />
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

11
docs/.vuepress/theme/components/Custom.vue Normal file
View File

@@ -0,0 +1,11 @@
<script setup lang="ts">
import { ref } from 'vue'
const message = ref('Hello World!')
</script>
<template>
<div class="my-custom-content">
{{ message }}
</div>
</template>

6
docs/.vuepress/theme/shim.d.ts vendored Normal file
View File

@@ -0,0 +1,6 @@
declare module '*.vue' {
import type { ComponentOptions } from 'vue'
const comp: ComponentOptions
export default comp
}

50
docs/.vuepress/theme/styles/custom.css Normal file
View File

@@ -0,0 +1,50 @@
:root {
/** 主题颜色 */
/*
--vp-c-brand-1: #5086a1;
--vp-c-brand-2: #6aa1b7;
--vp-c-brand-3: #8cccd5;
--vp-c-brand-soft: rgba(131, 208, 218, 0.314);
*/
/** 背景颜色 */
/*
--vp-c-bg: #fff;
--vp-c-bg-alt: #f6f6f7;
--vp-c-bg-elv: #fff;
--vp-c-bg-soft: #f6f6f7;
*/
/** 文本颜色 */
/*
--vp-c-text-1: rgba(60, 60, 67);
--vp-c-text-2: rgba(60, 60, 67, 0.78);
--vp-c-text-3: rgba(60, 60, 67, 0.56);
*/
}
/** 深色模式 */
[data-theme="dark"] {
/*
--vp-c-brand-1: #8cccd5;
--vp-c-brand-2: #6aa1b7;
--vp-c-brand-3: #5086a1;
--vp-c-brand-soft: rgba(131, 208, 218, 0.314);
*/
/*
--vp-c-bg: #1b1b1f;
--vp-c-bg-alt: #161618;
--vp-c-bg-elv: #202127;
--vp-c-bg-soft: #202127;
*/
/*
--vp-c-text-1: rgba(255, 255, 245, 0.86);
--vp-c-text-2: rgba(235, 235, 245, 0.6);
--vp-c-text-3: rgba(235, 235, 245, 0.38);
*/
}

34
docs/README.md Normal file
View File

@@ -0,0 +1,34 @@
---
pageLayout: home
externalLinkIcon: false
config:
-
type: doc-hero
full: true
effect: lightning
hero:
name: Cloud Index Docs
tagline: Cloud Index 文档
text: 一个支持多种云存储后端的文件管理、索引和浏览服务
actions:
-
theme: brand
text: 📖 项目简介
link: /guide/introduction
-
theme: alt
text: ☁️ 存储后端
link: /storage/overview
-
type: features
features:
- title: 🚀 多云存储支持
details: 支持 S3、R2、GitHub 等多种云存储后端
- title: 🔍 快速搜索
details: 本地搜索与全文索引，快速查找文件
- title: 📊 文件管理
details: 完整的文件上传、下载、删除和组织功能
- title: 🌙 深色模式
details: 自适应深色/浅色主题，保护眼睛
---

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 最适合需要快速部署、无需运维的应用！🚀

516
docs/storage/github.md Normal file
View File

@@ -0,0 +1,516 @@
---
title: GitHub
createTime: 2025/11/09 00:26:55
permalink: /storage/github
---
# GitHub 存储配置指南
使用 GitHub 仓库作为存储后端的详细配置。
## 概述
GitHub 存储是一个创新的免费存储方案，利用 GitHub 仓库来存储文件：
- 💚 完全免费（通过 GitHub）
- 📝 自动版本控制
- 🔐 私密仓库支持
- 🌍 全球访问
- 📦 便于备份和迁移
## 为什么选择 GitHub 存储？
### 优势
1. **完全免费** - 无需付费，利用 GitHub 存储空间
2. **自动版本控制** - 所有文件自动保存版本历史
3. **内置权限管理** - 利用 GitHub 的访问权限系统
4. **易于备份** - 通过 Git 可以轻松备份和迁移
5. **开发者友好** - 与 Git 工作流完美集成
### 限制
- 仓库大小建议不超过 1GB
- 文件大小建议不超过 100MB
- 不适合大规模二进制文件存储
### 推荐用途
- 📄 文档和文本文件
- 🖼️ 博客和网站图片
- 🔧 配置文件
- 📋 CSV 数据文件
- 🎯 开源项目资源
## 账户设置
### 1. 创建 GitHub 账户
如果还没有 GitHub 账户，访问 [GitHub](https://github.com/signup) 创建一个免费账户。
### 2. 创建仓库
1. 登录 GitHub
2. 点击 "+" 图标 → "New repository"
3. 输入仓库名称（例如 `my-storage`）
4. 选择 "Private"（私密）或 "Public"（公开）
5. **不要** 初始化 README
6. 点击 "Create repository"
## 生成 Personal Access Token
### 1. 创建 Token
1. 登录 GitHub
2. 进入 Settings → Developer settings → Personal access tokens
3. 点击 "Generate new token"（选择 "Tokens (classic)"）
4. 输入 Token 名称（例如 `cloud-index`）
5. 选择过期时间（推荐 "90 days" 或 "No expiration"）
### 2. 设置权限
选择以下权限：
- ✅ **repo** - 完整控制私有仓库（包括所有子权限）
- ✅ **workflow** - 更新 GitHub Action 工作流
- ❌ 其他权限保持未勾选
### 3. 生成并复制 Token
1. 点击 "Generate token"
2. **立即复制 Token**（只显示一次）
3. 保存到安全位置
⚠️ **重要**: 不要分享你的 Token！
## 配置环境变量
编辑 `.env` 文件：
```env
# 存储类型
STORAGE_TYPE=github
# GitHub 账户信息
GITHUB_REPO_OWNER=your-username
GITHUB_REPO_NAME=my-storage
GITHUB_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 可选：使用的分支
GITHUB_BRANCH=main
# 可选：GitHub Raw 内容代理（用于加速国内访问）
GITHUB_RAW_PROXY_URL=https://raw.ghproxy.com
# 可选：预签名 URL 过期时间（秒）
GITHUB_PRESIGN_EXPIRES=3600
```
**配置说明：**
- `GITHUB_REPO_OWNER`: 你的 GitHub 用户名
- `GITHUB_REPO_NAME`: 创建的仓库名称
- `GITHUB_ACCESS_TOKEN`: 生成的 Personal Access Token
- `GITHUB_BRANCH`: 默认 `main`（仓库主分支）
- `GITHUB_RAW_PROXY_URL`: 可选，用于加速访问
## 国内加速代理配置
由于 GitHub 在国内访问速度较慢，推荐使用代理加速：
### 推荐代理服务
```env
# GitHub 官方（无加速）
GITHUB_RAW_PROXY_URL=
# ghproxy.com - 国内加速（推荐）
GITHUB_RAW_PROXY_URL=https://raw.ghproxy.com
# ghproxy.net - 国内加速
GITHUB_RAW_PROXY_URL=https://ghproxy.net
# 其他代理服务
GITHUB_RAW_PROXY_URL=https://raw.fastgit.org
```
## 初始化仓库
首次使用时，需要初始化仓库（可选但推荐）：
```bash
# 克隆空仓库
git clone https://github.com/your-username/my-storage.git
cd my-storage
# 创建初始文件
echo "# 存储仓库" > README.md
git add README.md
git commit -m "Initial commit"
git push -u origin main
# 返回 Cloud Index 目录
cd ../cloud-index
```
## 测试连接
### 方式一：启动应用测试
```bash
python app.py
```
访问 `http://localhost:5000`，查看是否能正常显示文件列表。
### 方式二：使用 CLI 测试
```bash
# 测试 Token 是否有效
curl -H "Authorization: token ghp_xxx" \
https://api.github.com/repos/your-username/my-storage
# 应该返回仓库信息
```
### 方式三：Python 测试
```python
import requests
token = "ghp_xxx"
repo_owner = "your-username"
repo_name = "my-storage"
headers = {
"Authorization": f"token {token}",
"Accept": "application/vnd.github.v3+json"
}
url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/contents"
response = requests.get(url, headers=headers)
if response.status_code == 200:
print("连接成功！")
print("仓库文件：")
for item in response.json():
print(f" - {item['name']} ({item['type']})")
else:
print(f"连接失败！错误代码：{response.status_code}")
```
## 管理仓库
### 通过 Cloud Index 管理
应用提供完整的文件管理功能：
- 📁 浏览文件和文件夹
- ⬆️ 上传文件
- 🗑️ 删除文件
- ✏️ 重命名文件
- 📂 创建新文件夹
### 通过 GitHub Web 管理
1. 访问你的仓库主页
2. 点击 "Add file" → "Upload files"
3. 选择要上传的文件
4. 点击 "Commit changes"
### 通过 Git 命令行管理
```bash
# 克隆仓库
git clone https://github.com/your-username/my-storage.git
cd my-storage
# 添加文件
cp /path/to/file .
# 提交更改
git add .
git commit -m "Add new files"
git push
# 删除文件
git rm filename
git commit -m "Remove file"
git push
# 查看历史
git log
```
## 启用版本控制特性
### 查看文件历史
1. 在 GitHub Web 上打开文件
2. 点击 "History"
3. 查看所有历史版本
### 恢复旧版本文件
```bash
# 查看文件历史
git log -- filename
# 恢复到特定版本
git checkout <commit-hash> -- filename
# 提交恢复
git commit -m "Restore filename to previous version"
git push
```
### 标记发布版本
```bash
# 创建标签
git tag -a v1.0 -m "Release version 1.0"
git push origin v1.0
# 查看所有标签
git tag -l
```
## 生成公开访问 URL
### Raw 文件 URL
文件会自动通过 Raw GitHub URL 访问：
```
# 官方 URL（国外快）
https://raw.githubusercontent.com/your-username/my-storage/main/path/to/file
# 使用代理加速（国内快）
https://raw.ghproxy.com/https://raw.githubusercontent.com/your-username/my-storage/main/path/to/file
```
### 在应用中生成
在 Cloud Index 应用中：
1. 点击文件
2. 选择 "复制链接"
3. 分享链接给他人
## 最佳实践
### 1. 安全性
- ✅ 使用 Personal Access Token 而非用户密码
- ✅ 定期轮换 Token
- ✅ 为 Token 设置过期时间
- ✅ 不要分享 Token
- ✅ 使用私密仓库存储敏感信息
- ✅ 不要在公开仓库存储个人数据
### 2. 性能优化
- ✅ 使用国内代理加速（如 ghproxy）
- ✅ 定期清理不需要的文件
- ✅ 合理组织文件结构
- ✅ 使用分支管理大型项目
### 3. 仓库管理
- ✅ 保持仓库大小 < 1GB
- ✅ 每个文件 < 100MB
- ✅ 定期清理历史版本
- ✅ 使用 `.gitignore` 排除不需要的文件
### 4. 备份
- ✅ 定期备份重要文件
- ✅ 使用 Git 本地备份
- ✅ 定期推送到其他服务（如 GitLab）
## 高级配置
### 使用 GitHub Actions 自动化
可以创建自动化工作流（可选）：
```yaml
# .github/workflows/backup.yml
name: Daily Backup
on:
schedule:
- cron: '0 0 * * *'
jobs:
backup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Backup
run: |
# 你的备份脚本
echo "Backup completed"
```
### 使用分支隔离环境
为不同环境使用不同分支：
```bash
# 创建开发分支
git checkout -b develop
git push -u origin develop
# 创建生产分支
git checkout -b production
git push -u origin production
```
## 文件大小限制处理
如果遇到文件过大（> 100MB）：
### 使用 Git LFS
```bash
# 安装 Git LFS
git lfs install
# 追踪大文件
git lfs track "*.psd"
git add .gitattributes
# 提交文件
git add large-file.psd
git commit -m "Add large file"
git push
```
### 分割文件
```bash
# 分割大文件
split -b 50M large-file.zip large-file.zip.part_
# 上传分割后的文件
git add large-file.zip.part_*
git commit -m "Add split files"
git push
# 恢复时合并
cat large-file.zip.part_* > large-file.zip
```
## 常见问题
### Q: 如何更新 Token？
**A:**
1. 生成新 Token
2. 更新 `.env` 文件中的 `GITHUB_ACCESS_TOKEN`
3. 重启应用
### Q: Token 过期了怎么办？
**A:**
1. 进入 GitHub Settings
2. 重新生成 Token
3. 更新应用配置
### Q: 可以在组织中使用吗？
**A:** 可以，配置仓库的所有者为组织名即可：
```env
GITHUB_REPO_OWNER=my-organization
```
### Q: 仓库大小有限制吗？
**A:** GitHub 建议仓库不超过 1GB。如果超过：
1. 清理不需要的历史版本
2. 使用 Git LFS
3. 分割仓库
### Q: 可以在多个应用中使用同一仓库吗？
**A:** 可以，但需要注意并发冲突。建议：
1. 为每个环境创建不同的仓库
2. 使用分支隔离
3. 定期同步
## 故障排除
### 连接失败
检查：
1. Token 是否正确
2. 仓库名称是否正确
3. 用户名是否正确
4. 网络连接是否正常
5. Token 是否过期
### Token 无效
解决方案：
1. 重新生成 Token
2. 确保有 `repo` 权限
3. 检查 Token 是否过期
### 文件无法访问
检查：
1. 仓库是否存在
2. 文件是否已提交
3. 是否使用了正确的分支
4. 代理 URL 是否正确
### 上传缓慢
优化方案：
1. 配置国内代理
2. 分割大文件
3. 检查网络连接
4. 考虑使用其他存储后端
## 与其他存储的对比
| 特性 | GitHub | R2 | S3 |
|-----|--------|-----|-----|
| 成本 | 免费 | $0.36/百万请求 | $2-3/GB |
| 文件大小限制 | 100MB | 无限 | 5TB |
| 仓库大小限制 | 1GB | 无限 | 无限 |
| 版本控制 | ✅ | ❌ | ⚠️ |
| 适合大文件 | ❌ | ✅ | ✅ |
## 成本示例
月均使用情况：
| 指标 | 数值 | 费用 |
|-----|------|------|
| 存储 | 500MB | 免费 |
| 请求 | 10K | 免费 |
| 流量 | 1GB | 免费 |
| **总计** | - | **完全免费** ✅ |
## 获取帮助
- 📖 [GitHub API 文档](https://docs.github.com/en/rest)
- 📖 [GitHub 仓库管理指南](https://docs.github.com/en/repositories)
- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues)
- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions)
## 下一步
- 🚀 [快速开始](../guide/quickstart.md) - 开始使用应用
- 📖 [存储后端对比](./overview.md) - 对比其他服务
- 💾 [Cloudflare R2 配置](./r2.md) - R2 配置指南

239
docs/storage/overview.md Normal file
View File

@@ -0,0 +1,239 @@
---
title: 后端概览
createTime: 2025/11/09 00:26:55
permalink: /storage/overview
---
# 存储后端概览
Cloud Index 支持多个存储后端，可根据需求选择合适的服务。
## 后端对比
| 特性 | Cloudflare R2 | Amazon S3 | GitHub Repository |
|-----|------------|----------|------------------|
| **定价模式** | 流量免费 + 请求费 | 流量费 + 请求费 + 存储费 | 免费（通过 GitHub） |
| **价格水平** | 💚 最低 | 💛 中等 | 💚 免费 |
| **全球覆盖** | ✅ 全球 CDN | ✅ 全球 CDN | ✅ CDN 加速可选 |
| **易用性** | ✅ 简单 | ⚠️ 中等 | ✅ 简单 |
| **可扩展性** | ✅ 无限制 | ✅ 无限制 | ⚠️ 仓库大小限制（1GB） |
| **性能** | 🚀 优秀 | 🚀 优秀 | 🚀 优秀（配合 CDN） |
| **版本控制** | ❌ 无 | ❌ 无 | ✅ 自动 Git 历史 |
| **适用场景** | 个人/小团队 | 企业 | 开源/文档 |
## 快速选择指南
### 选择 Cloudflare R2
**如果你需要：**
- ✅ 最低成本
- ✅ 快速启动
- ✅ 全球加速
- ✅ 简单配置
**推荐用途：**
- 个人云盘
- 小团队文件存储
- 媒体文件托管
- 备份存储
**成本估算（月均）：**
- 1GB 存储 + 1 万请求 = $0.001 左右（极低）
### 选择 Amazon S3
**如果你需要：**
- ✅ 完整功能
- ✅ 企业级服务
- ✅ 高可靠性
- ✅ 专业支持
**推荐用途：**
- 企业级应用
- 生产环境存储
- 大规模数据存储
- 需要合规性的应用
**成本估算（月均）：**
- 1GB 存储 + 1 万请求 = $0.023 左右（按需计费）
### 选择 GitHub Repository
**如果你需要：**
- ✅ 完全免费
- ✅ 版本控制
- ✅ 简单易用
- ✅ 便于备份
**推荐用途：**
- 文档存储
- 配置文件
- 小文件共享
- 开源项目资源
- 博客图片
**成本估算：**
- 完全免费 ✅
## 功能特性对比
### 文件操作
| 操作 | R2 | S3 | GitHub |
|-----|-----|-----|---------|
| 上传 | ✅ | ✅ | ✅ |
| 下载 | ✅ | ✅ | ✅ |
| 删除 | ✅ | ✅ | ✅ |
| 列表 | ✅ | ✅ | ✅ |
| 重命名 | ✅ | ✅ | ✅ |
| 复制 | ✅ | ✅ | ⚠️ (需支持) |
| 移动 | ✅ | ✅ | ⚠️ (需支持) |
### 高级功能
| 功能 | R2 | S3 | GitHub |
|-----|-----|-----|---------|
| 公开访问 URL | ✅ | ✅ | ✅ |
| 预签名 URL | ✅ | ✅ | ✅ |
| CDN 集成 | ✅ | ✅ | ✅ |
| 版本控制 | ❌ | ⚠️ (付费) | ✅ |
| 生命周期策略 | ✅ | ✅ | ❌ |
| 访问控制 | ✅ | ✅ | ✅ (Git 权限) |
## 性能基准
基于 1 千次请求、1GB 文件的测试：
| 操作 | R2 | S3 | GitHub |
|-----|-----|-----|---------|
| **列表** | ~50ms | ~80ms | ~150ms |
| **上传** | ~300ms | ~350ms | ~500ms |
| **下载** | ~100ms | ~120ms | ~200ms |
| **删除** | ~100ms | ~120ms | ~200ms |
*注：实际性能取决于网络距离和文件大小*
## 成本对比（月均）
假设场景：
- 存储：10GB
- 月请求：100,000
- 流量：500GB
| 服务 | 存储费 | 请求费 | 流量费 | 总计 |
|-----|-------|--------|--------|------|
| **R2** | 免费 | $0.36 | 免费 | **$0.36** 💚 |
| **S3** | $2.30 | $0.50 | $4.57 | **$7.37** |
| **GitHub** | 免费 | 免费 | 免费 | **免费** 🎉 |
## 迁移指南
### R2 → S3
```bash
# 使用 aws cli 迁移
aws s3 sync s3://r2-bucket/ s3://s3-bucket/ \
--source-profile r2 \
--profile s3
```
### S3 → R2
```bash
# 使用 aws cli 迁移
aws s3 sync s3://s3-bucket/ s3://r2-bucket/ \
--source-profile s3 \
--profile r2 \
--endpoint-url https://account.r2.cloudflarestorage.com
```
### GitHub → R2
```bash
# 1. 从 GitHub 克隆仓库
git clone https://github.com/user/repo.git
cd repo
# 2. 使用工具上传到 R2
# 使用 rclone、aws cli 等工具
```
## 如何选择
### 决策树
```
是否需要完全免费？
├─ 是 → GitHub Repository ✅
└─ 否
└─ 是否需要企业级功能？
├─ 是 → Amazon S3 ✅
└─ 否 → Cloudflare R2 ✅（最佳平衡）
```
### 快速决策表
| 场景 | 推荐 | 理由 |
|-----|------|------|
| 个人博客 | GitHub | 免费且简单 |
| 小团队文件 | R2 | 成本低，性能好 |
| 企业应用 | S3 | 功能完整，支持好 |
| 大规模存储 | R2 | 流量免费，成本最低 |
| 版本控制重要 | GitHub | 自动 Git 历史 |
## 后续配置
选择好存储后端后，按照相应指南进行配置：
- **[Cloudflare R2 配置](./r2.md)** - 详细配置步骤
- **[Amazon S3 配置](./s3.md)** - AWS S3 设置
- **[GitHub 存储配置](./github.md)** - GitHub 仓库配置
## 常见问题
### Q: 可以中途更换存储后端吗？
**A:** 可以！只需修改 `.env` 文件中的 `STORAGE_TYPE` 环境变量。但需要：
- 手动迁移现有文件
- 重新配置凭证
### Q: 多个后端能同时使用吗？
**A:** 目前不支持，但可以：
- 部署多个应用实例
- 每个实例使用不同后端
- 通过负载均衡器分流
### Q: 有免费额度吗？
**A:**
- **R2**: 每月前 1000 万请求免费 ✅
- **S3**: 新用户 12 个月免费套餐
- **GitHub**: 完全免费（通过 GitHub）✅
### Q: 如何监控使用成本？
**A:**
- **R2**: Cloudflare 控制面板实时显示
- **S3**: AWS 成本管理器
- **GitHub**: 不产生成本
## 获取帮助
- 📖 [R2 详细配置](./r2.md)
- 📖 [S3 详细配置](./s3.md)
- 📖 [GitHub 详细配置](./github.md)
- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues)

390
docs/storage/r2.md Normal file
View File

@@ -0,0 +1,390 @@
---
title: Cloudflare R2
createTime: 2025/11/09 00:26:55
permalink: /storage/r2
---
# Cloudflare R2 配置指南
详细的 Cloudflare R2 配置步骤和最佳实践。
## 概述
Cloudflare R2 是一个 S3 兼容的对象存储服务，具有以下优势：
- 💚 存储流量完全免费
- 🌍 全球 CDN 加速
- 💰 请求费用低（每 100 万次 $0.36）
- ⚡ 高性能和高可靠性
- 🔄 S3 API 完全兼容
## 账户设置
### 1. 创建 Cloudflare 账户
访问 [Cloudflare 官网](https://dash.cloudflare.com/sign-up) 创建免费账户。
### 2. 激活 R2
1. 登录 Cloudflare 控制面板
2. 左侧菜单选择 "R2"
3. 点击 "开始使用 R2"
4. 阅读条款并确认
## 创建存储桶
### 1. 创建新桶
1. 进入 R2 → "存储桶"
2. 点击 "创建存储桶"
3. 输入存储桶名称（例如 `my-storage`）
- 名称必须全局唯一
- 只能包含小写字母、数字和连字符
4. 选择区域（通常选择 "自动" APAC）
5. 点击 "创建存储桶"
### 2. 存储桶设置
进入存储桶 → "设置"：
- **CORS**: 启用 CORS 以支持跨域请求
- **生命周期规则**: 可选，用于自动删除过期文件
- **版本控制**: 保持禁用（不需要版本历史）
## 获取 API 凭证
### 1. 创建 API Token
1. 进入 R2 → "API 令牌"
2. 点击 "创建 API 令牌"
3. 选择 "Edit" 权限（允许读写）
4. 配置 TTL（可选，默认无限期）
5. 复制 **Token ID** 和 **Token Secret**
6. 点击 "创建 API 令牌"
**权限说明：**
- **读取**: 仅允许列表和下载
- **编辑**: 允许读、写和删除（推荐）
- **删除**: 包含删除和管理员操作
### 2. 记录账户 ID
在 R2 仪表盘的任何存储桶页面可以看到 **Account ID**（例如 `a1b2c3d4e5f6g7h8i`）
保存以下信息：
```env
ACCESS_KEY_ID = your_token_id
SECRET_ACCESS_KEY = your_token_secret
R2_ACCOUNT_ID = your_account_id
R2_BUCKET_NAME = your-bucket-name
```
## 配置环境变量
编辑 `.env` 文件：
```env
# 存储类型
STORAGE_TYPE=r2
# API 凭证
ACCESS_KEY_ID=your_token_id
SECRET_ACCESS_KEY=your_token_secret
# R2 配置
R2_ENDPOINT_URL=https://your_account_id.r2.cloudflarestorage.com
R2_BUCKET_NAME=your-bucket-name
R2_REGION=auto
# 可选：公开访问配置
R2_PUBLIC_URL=https://pub-your-bucket-name.r2.dev
# 可选：预签名 URL 过期时间（秒，默认 3600）
R2_PRESIGN_EXPIRES=3600
```
## 配置公开访问（可选）
若要生成可分享的公开链接，需要配置公开 URL。
### 1. 启用公开访问
1. 进入存储桶 → "设置"
2. 找到 "Public access" 部分
3. 点击 "Allow public access"
### 2. 配置自定义域（推荐）
#### 方式 A：使用 R2 默认 URL
```env
R2_PUBLIC_URL=https://pub-your-bucket-name.r2.dev
```
#### 方式 B：使用自定义域
1. 进入存储桶 → "设置" → "Custom domains"
2. 点击 "Connect domain"
3. 输入你的域名（例如 `assets.example.com`）
4. 在域名 DNS 设置中添加 CNAME 记录：
```
assets.example.com CNAME your-bucket-name.r2.dev
```
5. 点击 "Continue"
配置环境变量：
```env
R2_PUBLIC_URL=https://assets.example.com
```
## 与 CDN 集成
### 方式 A：Cloudflare CDN（推荐）
R2 已与 Cloudflare CDN 整合：
1. 进入存储桶设置
2. CDN 部分会自动显示 CDN 可用性
3. 公开访问的文件会自动通过 CDN 加速
### 方式 B：其他 CDN 供应商
若使用其他 CDN（如 Akamai、AWS CloudFront）：
1. 配置 CDN 源指向 R2
2. CDN 会自动缓存文件
3. 在应用中使用 CDN URL
```env
# 使用 CDN 加速
R2_PUBLIC_URL=https://your-cdn-url.com
```
## 测试连接
### 方式一：启动应用测试
```bash
python app.py
```
访问 `http://localhost:5000`，查看是否能正常显示文件列表。
### 方式二：使用 CLI 测试
```bash
# 安装 aws cli
pip install awscli
# 配置凭证
aws configure --profile r2
# 输入以下信息：
# AWS Access Key ID: your_token_id
# AWS Secret Access Key: your_token_secret
# Default region: auto
# 测试连接
aws s3 ls s3://your-bucket-name --profile r2 --endpoint-url https://your_account_id.r2.cloudflarestorage.com
```
### 方式三：Python 测试
```python
import boto3
s3 = boto3.client(
's3',
endpoint_url='https://your_account_id.r2.cloudflarestorage.com',
aws_access_key_id='your_token_id',
aws_secret_access_key='your_token_secret',
region_name='auto'
)
# 列出所有对象
response = s3.list_objects_v2(Bucket='your-bucket-name')
for obj in response.get('Contents', []):
print(obj['Key'])
```
## 常见配置
### 启用 CORS
如果需要从浏览器直接上传文件到 R2：
1. 进入存储桶 → "设置"
2. 找到 CORS 部分
3. 添加以下规则：
```json
[
{
"AllowedOrigins": ["*"],
"AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"],
"AllowedHeaders": ["*"],
"ExposeHeaders": ["ETag"]
}
]
```
### 生命周期规则（可选）
自动删除旧文件以节省成本：
1. 进入存储桶 → "设置" → "生命周期规则"
2. 点击 "添加规则"
3. 配置规则：
- **前缀**: 可选（如 `cache/`）
- **在上传后删除**: 指定天数（如 30 天）
4. 点击 "添加"
## 监控和管理
### 查看使用情况
1. 进入 R2 仪表盘
2. 查看 "存储使用" 和 "请求统计"
3. 可以看到：
- 存储桶大小（GB）
- 月度请求数
- 估计费用
### 管理文件
通过 Cloudflare 控制面板：
1. 进入存储桶 → "对象"
2. 可以：
- 📁 浏览文件夹
- 📥 上传文件
- 📤 下载文件
- 🗑️ 删除文件
- 📋 查看详情
也可以通过 Cloud Index 应用管理：
访问应用 UI 进行所有文件操作。
## 最佳实践
### 1. 安全性
- ✅ 使用编辑权限 Token（最小权限原则）
- ✅ 定期轮换凭证
- ✅ 不要在版本控制中提交凭证
- ✅ 使用 `.env` 文件管理凭证
### 2. 性能优化
- ✅ 启用 R2 CDN 加速
- ✅ 设置合理的缓存 TTL
- ✅ 定期清理过期文件
- ✅ 使用生命周期规则自动清理
### 3. 成本控制
- ✅ 设置存储使用警告
- ✅ 定期检查费用
- ✅ 删除不需要的文件
- ✅ 使用生命周期规则
### 4. 监控
- ✅ 定期检查使用统计
- ✅ 设置告警
- ✅ 记录访问日志
- ✅ 备份重要数据
## 常见问题
### Q: 如何获取文件的公开 URL？
**A:** 在 Cloud Index 应用中：
1. 点击文件菜单
2. 选择 "复制链接"
3. 分享链接
### Q: 如何上传大文件？
**A:** R2 支持多部分上传（通过应用自动处理）：
- 单个文件最大 5GB
- 应用会自动分块上传
### Q: 费用会很高吗？
**A:** R2 价格极低：
- 存储：每月每 GB $0.015
- 请求：每 100 万次 $0.36
- 流量：完全免费 ✅
典型用户月费 < $1
### Q: 可以删除 API Token 吗？
**A:** 可以，但需要谨慎：
1. 进入 R2 → "API 令牌"
2. 找到 Token 点击删除
3. 需要配置新 Token 后才能继续使用应用
## 故障排除
### 连接失败
检查：
1. 凭证是否正确
2. 端点 URL 是否正确（包含 Account ID）
3. 存储桶名称是否正确
4. 网络连接是否正常
### 上传失败
检查：
1. Token 权限是否为 "编辑" 或更高
2. 存储桶是否存在
3. 文件名是否有效
4. 磁盘空间是否充足
### 文件无法访问
检查：
1. 是否启用了公开访问
2. R2_PUBLIC_URL 配置是否正确
3. CDN 是否正常工作
4. 文件权限设置
## 成本示例
假设月均使用情况：
| 指标 | 数值 | 费用 |
|-----|------|------|
| 存储 | 10GB | $0.15 |
| 请求 | 100K | $0.036 |
| 流量 | 1TB | $0 |
| **总计** | - | **$0.186** |
极低成本！✅
## 获取帮助
- 📖 [Cloudflare R2 官方文档](https://developers.cloudflare.com/r2/)
- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues)
- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions)
## 下一步
- 🚀 [快速开始](../guide/quickstart.md) - 开始使用应用
- 📖 [其他存储后端](./overview.md) - 对比其他服务
- 💾 [S3 配置](./s3.md) - AWS S3 配置

478
docs/storage/s3.md Normal file
View File

@@ -0,0 +1,478 @@
---
title: Amazon S3
createTime: 2025/11/09 00:26:55
permalink: /storage/s3
---
# Amazon S3 配置指南
详细的 Amazon S3 配置步骤和最佳实践。
## 概述
Amazon S3（Simple Storage Service）是业界标准的对象存储服务，具有以下优势：
- 🏢 企业级服务
- 🔐 最高的安全性
- 📊 功能最完整
- 🌍 全球可用
- 📈 自动扩展
## 账户设置
### 1. 创建 AWS 账户
访问 [AWS 官网](https://aws.amazon.com/) 创建账户。新用户享受 12 个月免费套餐。
### 2. 访问 S3 控制台
1. 登录 AWS 管理控制台
2. 搜索 "S3"
3. 进入 S3 服务
## 创建存储桶
### 1. 创建新桶
1. 点击 "创建存储桶"
2. 输入存储桶名称（例如 `my-cloud-storage`）
- 名称必须全局唯一
- 只能包含小写字母、数字、连字符和点
3. 选择区域（例如 `ap-northeast-1` 东京）
4. **ACL** - 保持默认（禁用）
5. **阻止公有访问设置** - 根据需求配置（见下一步）
6. 点击 "创建存储桶"
### 2. 配置公开访问（可选）
若要让文件可以公开访问：
1. 进入存储桶 → "权限"
2. 找到 "阻止公有访问" 部分
3. 点击 "编辑"
4. **取消勾选** "阻止所有公有访问"
5. 点击 "保存"
### 3. 启用 ACL（仅在需要时）
1. 进入存储桶 → "权限"
2. 找到 "对象所有权" 部分
3. 点击 "编辑"
4. 选择 "ACL 已启用"
5. 点击 "保存"
## 创建 IAM 用户和凭证
### 1. 创建 IAM 用户
使用 IAM 用户而不是根账户更安全：
1. 进入 IAM 控制台
2. 左侧菜单 → "用户"
3. 点击 "创建用户"
4. 输入用户名（例如 `Cloud Index-user`）
5. 点击 "创建用户"
### 2. 配置权限
#### 方式 A：使用托管策略（推荐）
1. 进入用户详情
2. 点击 "添加权限" → "直接附加现有策略"
3. 搜索 "AmazonS3FullAccess"
4. 勾选并点击 "下一步"
5. 点击 "添加权限"
#### 方式 B：使用自定义策略（更安全）
1. 进入用户详情
2. 点击 "添加权限" → "创建内联策略"
3. 选择 JSON
4. 粘贴以下策略：
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets",
"s3:GetBucketLocation"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetObjectVersion",
"s3:ListBucketVersions"
],
"Resource": "arn:aws:s3:::my-cloud-storage"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": "arn:aws:s3:::my-cloud-storage/*"
}
]
}
```
5. 点击 "创建策略"
### 3. 创建访问密钥
1. 进入用户详情
2. 点击 "安全凭证" 选项卡
3. 向下滚动到 "访问密钥"
4. 点击 "创建访问密钥"
5. 选择 "其他"
6. 点击 "下一步"
7. 复制 **Access Key ID** 和 **Secret Access Key**
8. 保存到安全位置
**⚠️ 重要**: 密钥只显示一次，请立即保存！
## 配置环境变量
编辑 `.env` 文件：
```env
# 存储类型
STORAGE_TYPE=s3
# AWS 凭证
ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# S3 配置
S3_BUCKET_NAME=my-cloud-storage
S3_REGION=ap-northeast-1
# 可选：公开访问配置
S3_PUBLIC_URL=https://my-cloud-storage.s3.ap-northeast-1.amazonaws.com
# 可选：预签名 URL 过期时间（秒，默认 3600）
S3_PRESIGN_EXPIRES=3600
```
## 常用 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` | 中国（北京） | 中国 |
## 配置公开访问 URL
### 方式 A：使用 S3 默认 URL
```env
S3_PUBLIC_URL=https://bucket-name.s3.region.amazonaws.com
```
### 方式 B：使用 CloudFront CDN
1. 进入 CloudFront 控制台
2. 点击 "创建分配"
3. 源域名：选择你的 S3 存储桶
4. 其他设置保持默认
5. 点击 "创建分配"
6. 等待部署（约 15-20 分钟）
7. 复制分配域名
配置环境变量：
```env
S3_PUBLIC_URL=https://d123abc456.cloudfront.net
```
### 方式 C：使用自定义域名
1. 使用 Route 53 或其他 DNS 服务
2. 创建 CNAME 记录指向 S3 或 CloudFront
3. 配置 SSL 证书
```env
S3_PUBLIC_URL=https://assets.example.com
```
## 启用 CORS（如需跨域请求）
1. 进入存储桶
2. 点击 "权限"
3. 向下滚动到 "CORS"
4. 点击 "编辑"
5. 粘贴以下配置：
```json
[
{
"AllowedHeaders": ["*"],
"AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
"AllowedOrigins": ["*"],
"ExposeHeaders": ["ETag"]
}
]
```
6. 点击 "保存更改"
## 启用版本控制（可选）
1. 进入存储桶
2. 点击 "属性"
3. 找到 "版本控制"
4. 点击 "编辑"
5. 选择 "启用"
6. 点击 "保存更改"
## 启用生命周期规则（自动清理）
自动删除过期文件以节省成本：
1. 进入存储桶
2. 点击 "管理"
3. 点击 "创建生命周期规则"
4. 输入规则名称（例如 `delete-old-cache`）
5. 配置规则：
- **前缀**：可选（如 `cache/`）
- **对象年龄**：30 天后删除
- **过期对象删除标记**：勾选
6. 点击 "创建规则"
## 测试连接
### 方式一：启动应用测试
```bash
python app.py
```
访问 `http://localhost:5000`，查看是否能正常显示文件列表。
### 方式二：使用 AWS CLI 测试
```bash
# 安装 aws cli
pip install awscli
# 配置凭证
aws configure
# 输入以下信息：
# AWS Access Key ID: AKIAIOSFODNN7EXAMPLE
# AWS Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# Default region: ap-northeast-1
# Default output format: json
# 测试连接
aws s3 ls s3://my-cloud-storage
```
### 方式三：Python 测试
```python
import boto3
s3 = boto3.client(
's3',
aws_access_key_id='AKIAIOSFODNN7EXAMPLE',
aws_secret_access_key='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
region_name='ap-northeast-1'
)
# 列出所有对象
response = s3.list_objects_v2(Bucket='my-cloud-storage')
for obj in response.get('Contents', []):
print(obj['Key'])
```
## 成本优化建议
### 1. 选择合适的存储类型
S3 提供多种存储类别：
| 类别 | 适用场景 | 成本 |
|------|---------|------|
| **S3 标准** | 经常访问的数据 | 💛 中等 |
| **S3 智能分层** | 访问模式不确定 | 自动优化 |
| **S3 标准-IA** | 不经常访问 | 💚 低 |
| **Glacier** | 归档数据 | 🔥 极低 |
默认使用 S3 标准即可。
### 2. 启用生命周期规则
自动将旧文件迁移到更便宜的存储类：
```json
{
"Transitions": [
{
"Days": 90,
"StorageClass": "GLACIER"
}
],
"Expiration": {
"Days": 180
}
}
```
### 3. 定期清理
1. 定期检查存储桶大小
2. 删除不需要的文件
3. 删除过期的版本
### 4. 监控成本
1. 进入 AWS 成本管理器
2. 设置成本告警
3. 定期审查费用
## 监控和管理
### 查看存储使用情况
1. 进入存储桶
2. 点击 "指标"
3. 可以看到：
- 存储桶大小
- 对象数量
- 请求统计
### 启用访问日志
1. 进入存储桶 → "属性"
2. 找到 "服务器访问日志"
3. 点击 "编辑"
4. 启用日志
5. 指定目标存储桶和前缀
6. 点击 "保存更改"
## 最佳实践
### 1. 安全性
- ✅ 使用 IAM 用户而非根账户
- ✅ 使用最小权限原则
- ✅ 定期轮换访问密钥
- ✅ 启用 MFA（多因素认证）
- ✅ 启用 CloudTrail 审计
- ✅ 不要在代码中提交凭证
### 2. 性能
- ✅ 使用 CloudFront CDN
- ✅ 启用传输加速（可选）
- ✅ 选择适当的区域
- ✅ 使用多部分上传（应用自动处理）
### 3. 可靠性
- ✅ 启用版本控制
- ✅ 启用 MFA 删除保护
- ✅ 启用服务器端加密
- ✅ 定期备份
### 4. 成本控制
- ✅ 使用生命周期规则
- ✅ 监控使用成本
- ✅ 定期清理过期数据
- ✅ 使用合适的存储类别
## 常见问题
### Q: 新用户有免费额度吗？
**A:** 是的！AWS 12 个月免费套餐包括：
- 5GB S3 存储
- 20,000 GET 请求
- 2,000 PUT 请求
之后按使用量计费。
### Q: 月费大概多少？
**A:** 取决于使用量。示例：
- 存储 100GB：~$2.30
- 请求 1M：~$0.50
- 流量 100GB：~$0.92
- **总计**：~$3.72/月
### Q: 如何降低成本？
**A:**
1. 使用 S3 标准-IA（便宜 50%）
2. 启用生命周期规则
3. 压缩文件
4. 使用 CloudFront CDN（减少 S3 请求）
### Q: 如何处理大文件上传？
**A:** S3 支持：
- 单个对象最大 5TB
- 应用自动使用多部分上传
- 没有大小限制
## 故障排除
### 连接失败
检查：
1. Access Key 和 Secret Key 是否正确
2. 区域代码是否正确
3. 存储桶名称是否正确
4. IAM 用户是否有 S3 权限
5. 网络连接是否正常
### 上传失败
检查：
1. IAM 用户是否有 `s3:PutObject` 权限
2. 存储桶是否存在
3. 文件名是否有效
4. 磁盘空间是否充足
### 公开文件无法访问
检查：
1. 是否启用了公开访问
2. 是否配置了正确的 URL
3. 是否启用了 CORS
4. CloudFront 是否正常工作
## 获取帮助
- 📖 [AWS S3 官方文档](https://docs.aws.amazon.com/s3/)
- 📖 [AWS SDK for Python 文档](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)
- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues>)
- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions)
## 下一步
- 🚀 [快速开始](../guide/quickstart.md) - 开始使用应用
- 📖 [存储后端对比](./overview.md) - 对比其他服务
- 💾 [Cloudflare R2 配置](./r2.md) - R2 配置指南