mirror of
https://github.com/RhenCloud/Cloud-Index.git
synced 2025-12-06 15:26:10 +08:00
初始化文档
This commit is contained in:
358
docs/guide/environment.md
Normal file
358
docs/guide/environment.md
Normal 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/) - 各后端详细配置
|
||||
Reference in New Issue
Block a user