mirror of
https://github.com/RhenCloud/Cloud-Index.git
synced 2025-12-06 15:26:10 +08:00
359 lines
8.3 KiB
Markdown
359 lines
8.3 KiB
Markdown
---
|
||
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/) - 各后端详细配置
|