Cloud-Index/docs/guide/configuration.md

title, createTime, permalink

title	createTime	permalink
配置指南	2025/11/09 00:26:55	/guide/configuration

配置说明

本文档详细说明了 Cloud Index 的各种配置选项。

配置方式

Cloud Index 通过环境变量进行配置，有两种主要方式：

1. 环境变量文件 (.env)

在项目根目录创建 .env 文件：

cp .env.example .env

编辑 .env 文件，添加需要的配置。

2. 系统环境变量

直接在系统中设置环境变量（适用于 Docker、Serverless 等环境）。

存储后端配置

STORAGE_TYPE（必需）

选择要使用的存储后端：

# 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 时，需要配置以下环境变量：

# ===== 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 控制面板
2. 进入 R2 → API Tokens
3. 创建新 Token，复制 ID 和 Secret
4. 记录你的 Account ID（在 R2 仓库页面显示）

Amazon S3 配置

当 STORAGE_TYPE=s3 时，需要配置以下环境变量：

# ===== 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 时，需要配置以下环境变量：

# ===== 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 - 官方（无加速）

应用配置

缓存配置

# 缩略图缓存过期时间（秒），默认 3600（1小时）
THUMB_TTL_SECONDS=3600

应用服务器配置

# Flask 调试模式（开发环境推荐启用）
FLASK_ENV=development
FLASK_DEBUG=1

# 应用监听地址
FLASK_RUN_HOST=0.0.0.0

# 应用监听端口
FLASK_RUN_PORT=5000

日志配置

# 日志级别
LOG_LEVEL=INFO

# 日志文件路径
LOG_FILE=/var/log/Cloud Index/app.log

完整配置示例

R2 + 国内代理

# 存储配置
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 + 加速代理

# 存储配置
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

# 存储配置
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. 代码中的默认值（最低）

配置验证

启动应用后，检查日志输出确保配置正确：

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（如有）已配置

下一步

• 环境变量详解 - 每个环境变量的详细说明
• 部署指南 - 生产环境部署
• 存储后端指南 - 详细的后端配置指南