mirror of
https://github.com/RhenCloud/Cloud-Index.git
synced 2025-12-06 15:26:10 +08:00
refactor(docs): 重构导航栏配置并调整文档结构
将导航栏中的“安装指南”、“配置指南”和“部署指南”进行重新组织，并调整相关文档路径和内容，使其更加清晰和合理。 - 在 `navbar.ts` 中，将“部署指南”和“配置指南”的链接分别更新为 `/guide/deployment/overview` 和 `/guide/configuration/configuration`。 - 删除了旧的 `configuration.md` 文件，相关内容被拆分并移动到新的 `configuration/configuration.md` 和 `configuration/environment.md` 文件中。 - 重命名了 `environment.md` 文件为 `configuration/environment.md`，并更新了其 `permalink`。 - 新增了 `deployment/overview.md` 文件，概述了不同的部署方案，并提供了快速选择和详细对比。 - 将 `docker.md` 文件重命名为 `deployment/docker.md`，以便于统一管理部署相关文档。 - 将 `server.md` 文件重命名为 `deployment/server.md`，同上，便于统一管理部署相关文档。 - 将 `vercel.md` 文件重命名为 `deployment/vercel.md`，同上，便于统一管理部署相关文档。
This commit is contained in:
89
docs/guide/configuration/configuration.md
Normal file
89
docs/guide/configuration/configuration.md
Normal file
@@ -0,0 +1,89 @@
|
||||
---
|
||||
title: 基础配置
|
||||
createTime: 2025/11/09
|
||||
permalink: /guide/configuration/configuration
|
||||
---
|
||||
|
||||
配置 Cloud Index 以满足您的特定需求。
|
||||
|
||||
## 概述
|
||||
|
||||
Cloud Index 使用环境变量进行配置，支持多种存储后端和自定义选项。本章节包含了所有配置相关的文档。
|
||||
|
||||
## 配置内容
|
||||
|
||||
### 1. [基础配置](/guide/configuration/configuration)
|
||||
|
||||
了解 Cloud Index 的基本配置方式：
|
||||
|
||||
- 配置文件和环境变量
|
||||
- 存储后端选择
|
||||
- 核心参数设置
|
||||
- 快速入门配置
|
||||
|
||||
**适合**：初次使用者，想要快速配置应用
|
||||
|
||||
### 2. [环境变量完整参考](/guide/configuration/environment)
|
||||
|
||||
所有环境变量的详细参考文档：
|
||||
|
||||
- **核心配置** - 基础应用设置
|
||||
- **R2 配置** - Cloudflare R2 存储后端
|
||||
- **S3 配置** - Amazon S3 存储后端
|
||||
- **GitHub 配置** - GitHub 仓库存储后端
|
||||
- **缓存配置** - 缩略图和性能优化
|
||||
- **日志配置** - 日志输出和调试
|
||||
|
||||
**适合**：需要详细参考的开发者，高级配置需求
|
||||
|
||||
---
|
||||
|
||||
## 快速配置
|
||||
|
||||
### 最小配置（Cloudflare R2）
|
||||
|
||||
```env
|
||||
STORAGE_TYPE=r2
|
||||
ACCESS_KEY_ID=your_access_key
|
||||
SECRET_ACCESS_KEY=your_secret_key
|
||||
R2_ENDPOINT_URL=https://your-account-id.r2.cloudflarestorage.com
|
||||
R2_BUCKET_NAME=your-bucket-name
|
||||
R2_PUBLIC_URL=https://pub-your-bucket.r2.dev
|
||||
```
|
||||
|
||||
### 最小配置（Amazon S3）
|
||||
|
||||
```env
|
||||
STORAGE_TYPE=s3
|
||||
ACCESS_KEY_ID=your_access_key
|
||||
SECRET_ACCESS_KEY=your_secret_key
|
||||
S3_BUCKET_NAME=your-bucket-name
|
||||
S3_REGION=us-east-1
|
||||
```
|
||||
|
||||
### 最小配置（GitHub）
|
||||
|
||||
```env
|
||||
STORAGE_TYPE=github
|
||||
GITHUB_REPO_OWNER=your-username
|
||||
GITHUB_REPO_NAME=your-repo-name
|
||||
GITHUB_ACCESS_TOKEN=your_github_token
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
- 📖 参考 [环境变量完整参考](/guide/configuration/environment) 了解所有选项
|
||||
- 🚀 查看 [部署指南](/guide/deployment/) 了解如何部署应用
|
||||
|
||||
---
|
||||
|
||||
## 获取帮助
|
||||
|
||||
遇到配置问题？
|
||||
|
||||
- 📖 [完整参考文档](/guide/configuration/environment)
|
||||
- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues)
|
||||
- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions)
|
||||
- 📧 <i@rhen.cloud>
|
||||
358
docs/guide/configuration/environment.md
Normal file
358
docs/guide/configuration/environment.md
Normal file
@@ -0,0 +1,358 @@
|
||||
---
|
||||
title: 环境配置
|
||||
createTime: 2025/11/09 00:26:55
|
||||
permalink: /guide/configuration/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