8.3 KiB
title, createTime, permalink
| title | createTime | permalink |
|---|---|---|
| 环境配置 | 2025/11/09 00:26:55 | /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 |
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 |
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 |
缓存配置
| 变量名 | 类型 | 必需 | 默认值 | 说明 |
|---|---|---|---|---|
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 R2s3- Amazon S3github- GitHub 仓库github-release- GitHub Release（开发中）
示例:
STORAGE_TYPE=r2
FLASK_ENV
类型: String
必需: No
默认: development
可选值:
development- 开发模式（启用自动重载、详细错误日志）production- 生产模式（性能优化、最小化日志）
示例:
FLASK_ENV=production
FLASK_DEBUG
类型: Integer (0 or 1)
必需: No
默认: 0
说明: 启用 Flask 调试器和代码热加载（仅用于开发）
示例:
FLASK_DEBUG=1
⚠️ 警告: 不要在生产环境启用调试模式！
FLASK_RUN_HOST
类型: String
必需: No
默认: 127.0.0.1
说明: 应用监听的 IP 地址
常用值:
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
说明: 应用监听的端口号
示例:
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 - ❌ 不要在日志中打印凭证
示例:
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 部分查看
示例:
R2_ENDPOINT_URL=https://a1b2c3d4e5f6g7h8i.r2.cloudflarestorage.com
R2_BUCKET_NAME
类型: String
必需: Yes（对于 R2）
说明: R2 存储桶名称
示例:
R2_BUCKET_NAME=my-storage
R2_PUBLIC_URL
类型: String
必需: No
说明: R2 公开访问 URL，用于生成可分享的文件链接
格式: https://pub-<bucket-name>.r2.dev
获取方式: 在 Cloudflare 控制面板 R2 存储桶设置中配置自定义域
示例:
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 中国（北京）
示例:
S3_REGION=ap-northeast-1
GITHUB_REPO_OWNER
类型: String
必需: Yes（对于 GitHub）
说明: GitHub 用户名或组织名
示例:
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/ 官方（无代理）
示例:
GITHUB_RAW_PROXY_URL=https://raw.ghproxy.com
THUMB_TTL_SECONDS
类型: Integer
必需: No
默认: 3600
说明: 生成的缩略图缓存过期时间（秒）
常用值:
3600 1 小时
86400 1 天
604800 1 周
2592000 30 天
示例:
THUMB_TTL_SECONDS=86400 # 缩略图缓存 1 天
LOG_LEVEL
类型: String
必需: No
默认: INFO
可选值: DEBUG, INFO, WARNING, ERROR, CRITICAL
示例:
LOG_LEVEL=DEBUG # 开发环境
LOG_LEVEL=WARNING # 生产环境
快速参考
最小配置（R2）
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）
STORAGE_TYPE=s3
ACCESS_KEY_ID=your_key
SECRET_ACCESS_KEY=your_secret
S3_BUCKET_NAME=mybucket
S3_REGION=us-east-1
最小配置（GitHub）
STORAGE_TYPE=github
GITHUB_REPO_OWNER=myusername
GITHUB_REPO_NAME=my-storage
GITHUB_ACCESS_TOKEN=ghp_xxx
验证配置
运行以下命令验证环境变量是否正确加载：
python -c "import os; from dotenv import load_dotenv; load_dotenv(); print('STORAGE_TYPE:', os.getenv('STORAGE_TYPE'))"