From 641a7295921c3a329ee1556674b0b30276b2be8d Mon Sep 17 00:00:00 2001 From: RhenCloud Date: Sun, 9 Nov 2025 16:00:44 +0800 Subject: [PATCH] =?UTF-8?q?refactor(docs):=20=E9=87=8D=E6=9E=84=E5=AF=BC?= =?UTF-8?q?=E8=88=AA=E6=A0=8F=E9=85=8D=E7=BD=AE=E5=B9=B6=E8=B0=83=E6=95=B4?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将导航栏中的“安装指南”、“配置指南”和“部署指南”进行重新组织，并调整相关文档路径和内容，使其更加清晰和合理。 - 在 `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`，同上，便于统一管理部署相关文档。 --- docs/.vuepress/navbar.ts | 5 +- docs/.vuepress/plume.config.ts | 17 +- docs/guide/configuration.md | 334 ------------------ docs/guide/configuration/configuration.md | 89 +++++ docs/guide/{ => configuration}/environment.md | 2 +- docs/guide/{ => deployment}/docker.md | 0 docs/guide/deployment/overview.md | 125 +++++++ docs/guide/{ => deployment}/server.md | 0 docs/guide/{ => deployment}/vercel.md | 0 9 files changed, 226 insertions(+), 346 deletions(-) delete mode 100644 docs/guide/configuration.md create mode 100644 docs/guide/configuration/configuration.md rename docs/guide/{ => configuration}/environment.md (95%) rename docs/guide/{ => deployment}/docker.md (100%) create mode 100644 docs/guide/deployment/overview.md rename docs/guide/{ => deployment}/server.md (100%) rename docs/guide/{ => deployment}/vercel.md (100%) diff --git a/docs/.vuepress/navbar.ts b/docs/.vuepress/navbar.ts index 35b9e2d..3ad3d5a 100644 --- a/docs/.vuepress/navbar.ts +++ b/docs/.vuepress/navbar.ts @@ -13,9 +13,8 @@ export default defineNavbarConfig([ items: [ { text: "项目介绍", link: "/guide/introduction" }, { text: "快速开始", link: "/guide/quickstart" }, - { text: "安装指南", link: "/guide/installation" }, - { text: "配置指南", link: "/guide/configuration" }, - { text: "部署指南", link: "/guide/deployment" }, + { text: "部署指南", link: "/guide/deployment/overview" }, + { text: "配置指南", link: "/guide/configuration/configuration" }, ], }, { diff --git a/docs/.vuepress/plume.config.ts b/docs/.vuepress/plume.config.ts index 1f6ba3e..3a5e953 100644 --- a/docs/.vuepress/plume.config.ts +++ b/docs/.vuepress/plume.config.ts @@ -72,23 +72,24 @@ export default defineThemeConfig({ items: [ { text: "项目介绍", link: "/guide/introduction" }, { text: "快速开始", link: "/guide/quickstart" }, - { - text: "配置", - collapsed: false, - items: [ - { text: "配置指南", link: "/guide/configuration" }, - { text: "环境配置", link: "/guide/environment" }, - ], - }, { text: "部署", collapsed: false, items: [ + { text: "部署指南", link: "/guide/deployment/overview" }, { text: "服务器部署", link: "/guide/deployment/server" }, // { text: "Docker 部署", link: "/guide/deployment/docker" }, { text: "Vercel 部署", link: "/guide/deployment/vercel" }, ], }, + { + text: "配置", + collapsed: false, + items: [ + { text: "基础配置", link: "/guide/configuration/configuration" }, + { text: "环境配置", link: "/guide/configuration/environment" }, + ], + }, ], }, ], diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md deleted file mode 100644 index a3b4ca6..0000000 --- a/docs/guide/configuration.md +++ /dev/null @@ -1,334 +0,0 @@ ---- -title: 配置指南 -createTime: 2025/11/09 00:26:55 -permalink: /guide/configuration ---- -# 配置说明 - -本文档详细说明了 Cloud Index 的各种配置选项。 - -## 配置方式 - -Cloud Index 通过环境变量进行配置，有两种主要方式： - -### 1. 环境变量文件 (.env) - -在项目根目录创建 `.env` 文件： - -```bash -cp .env.example .env -``` - -编辑 `.env` 文件，添加需要的配置。 - -### 2. 系统环境变量 - -直接在系统中设置环境变量（适用于 Docker、Serverless 等环境）。 - -## 存储后端配置 - -### STORAGE_TYPE（必需） - -选择要使用的存储后端： - -```env -# 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` 时，需要配置以下环境变量： - -```env -# ===== 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 控制面板](https://dash.cloudflare.com) -2. 进入 R2 → API Tokens -3. 创建新 Token，复制 ID 和 Secret -4. 记录你的 Account ID（在 R2 仓库页面显示） - -## Amazon S3 配置 - -当 `STORAGE_TYPE=s3` 时，需要配置以下环境变量： - -```env -# ===== 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` 时，需要配置以下环境变量： - -```env -# ===== 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 - 官方（无加速） -``` - -## 应用配置 - -### 缓存配置 - -```env -# 缩略图缓存过期时间（秒），默认 3600（1小时） -THUMB_TTL_SECONDS=3600 -``` - -### 应用服务器配置 - -```env -# Flask 调试模式（开发环境推荐启用） -FLASK_ENV=development -FLASK_DEBUG=1 - -# 应用监听地址 -FLASK_RUN_HOST=0.0.0.0 - -# 应用监听端口 -FLASK_RUN_PORT=5000 -``` - -### 日志配置 - -```env -# 日志级别 -LOG_LEVEL=INFO - -# 日志文件路径 -LOG_FILE=/var/log/Cloud Index/app.log -``` - -## 完整配置示例 - -### R2 + 国内代理 - -```env -# 存储配置 -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 + 加速代理 - -```env -# 存储配置 -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 - -```env -# 存储配置 -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. 代码中的默认值（最低） - -## 配置验证 - -启动应用后，检查日志输出确保配置正确： - -```bash -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（如有）已配置 - -## 下一步 - -- [环境变量详解](./environment.md) - 每个环境变量的详细说明 -- [部署指南](./deployment.md) - 生产环境部署 -- [存储后端指南](../storage/) - 详细的后端配置指南 diff --git a/docs/guide/configuration/configuration.md b/docs/guide/configuration/configuration.md new file mode 100644 index 0000000..795ab1b --- /dev/null +++ b/docs/guide/configuration/configuration.md @@ -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) +- 📧 diff --git a/docs/guide/environment.md b/docs/guide/configuration/environment.md similarity index 95% rename from docs/guide/environment.md rename to docs/guide/configuration/environment.md index 24e73a0..c7aa8d4 100644 --- a/docs/guide/environment.md +++ b/docs/guide/configuration/environment.md @@ -1,7 +1,7 @@ --- title: 环境配置 createTime: 2025/11/09 00:26:55 -permalink: /guide/environment +permalink: /guide/configuration/environment --- # 环境变量完整参考 diff --git a/docs/guide/docker.md b/docs/guide/deployment/docker.md similarity index 100% rename from docs/guide/docker.md rename to docs/guide/deployment/docker.md diff --git a/docs/guide/deployment/overview.md b/docs/guide/deployment/overview.md new file mode 100644 index 0000000..ff7740b --- /dev/null +++ b/docs/guide/deployment/overview.md @@ -0,0 +1,125 @@ +--- +title: 部署指南 +createTime: 2025/11/09 +permalink: /guide/deployment/overview +--- + +选择适合您需求的部署方式，快速将 Cloud Index 部署到生产环境。 + +## 快速选择 + +根据您的需求选择最适合的部署方案： + +### 🚀 我想快速上线（< 5 分钟） + +**→ [Vercel 部署](/guide/deployment/vercel)** + +- ✅ 完全免费（前 100GB/月） +- ✅ 一键部署，无需运维 +- ✅ 自动 HTTPS 和 CDN +- ✅ GitHub 集成自动部署 +- ⏱️ 部署时间：5 分钟 + +**最适合**：快速演示、个人项目、原型开发 + +--- + +### 💼 我需要生产级部署 + +**→ [服务器部署](/guide/deployment/server)** + +- ✅ 完全自主可控 +- ✅ 无运营商限制 +- ✅ 支持完整定制化 +- ✅ 性能和成本可预测 +- ⏱️ 部署时间：15-30 分钟 + +**最适合**：企业应用、生产环境、大规模部署 + +--- + +### 🐳 我使用 Docker/容器编排 + +**→ [Docker 部署](/guide/deployment/docker)** + +- ✅ 标准化部署 +- ✅ 支持 Kubernetes +- ✅ 易于横向扩展 +- ✅ 团队开发友好 +- ⏱️ 部署时间：10-20 分钟 + +**最适合**：容器编排、微服务架构、CI/CD 流程 + +--- + +## 部署方案详细对比 + +### 功能对比 + +| 功能特性 | Vercel | 服务器 | Docker | +|---------|--------|--------|--------| +| **部署难度** | ⭐ 最简单 | ⭐⭐ 中等 | ⭐⭐ 中等 | +| **运维成本** | ⭐ 无 | ⭐⭐⭐ 需要 | ⭐⭐ 中等 | +| **自定义** | ⭐⭐ 有限 | ⭐⭐⭐ 完整 | ⭐⭐⭐ 完整 | +| **性能控制** | ⭐⭐ 自动 | ⭐⭐⭐ 完全 | ⭐⭐⭐ 完全 | +| **扩展性** | ⭐⭐⭐ 自动 | ⭐⭐ 有限 | ⭐⭐⭐ 优秀 | +| **成本** | ⭐⭐⭐ 最低 | ⭐⭐ 中等 | ⭐⭐ 中等 | + +### 成本对比（月均） + +| 方案 | 小流量 | 中流量 | 大流量 | +|-----|--------|--------|--------| +| **Vercel** | $0 免费 | $0-20 | $20-100+ | +| **服务器** | $5-10 | $10-50 | $50-200+ | +| **Docker** | $10-20 | $20-100 | $100-500+ | + +### 性能指标 + +| 指标 | Vercel | 服务器 | Docker | +|-----|--------|--------|--------| +| **响应时间** | 100-500ms | 50-200ms | 50-200ms | +| **冷启动** | < 1s | N/A | 5-30s | +| **吞吐量** | 自动扩展 | 取决于配置 | 取决于配置 | +| **CDN 加速** | 全球 | 需单独配置 | 需单独配置 | + +--- + +## 部署前准备 + +### 必须准备 + +1. **存储后端** - 选择并配置一个： + - ☁️ [Cloudflare R2](/storage/r2) - 推荐（成本最低） + - ☁️ [Amazon S3](/storage/s3) + - 📦 [GitHub](/storage/github) + +2. **环境变量** - 准备好存储后端的凭证 + - Access Key ID + - Secret Access Key + - 端点 URL 或仓库信息 + +3. **GitHub 账户** - Vercel 和 Docker 部署都需要 + +### 可选准备 + +- 🌐 自定义域名 +- 🔒 SSL 证书（Vercel 自动提供） +- 📊 性能监控工具 +- 📝 日志收集方案 + +--- + +## 下一步 + +选择您的部署方案开始： + +1. **[Vercel 部署](/guide/deployment/vercel)** - 最快上线 +2. **[服务器部署](/guide/deployment/server)** - 生产级部署 +3. **[Docker 部署](/guide/deployment/docker)** - 容器化部署 + +或者先： + +4. **[配置指南](/guide/configuration)** - 学习所有配置选项 +5. **[存储后端](/storage/overview)** - 了解存储配置 + +**现在就开始吧！** 🚀 diff --git a/docs/guide/server.md b/docs/guide/deployment/server.md similarity index 100% rename from docs/guide/server.md rename to docs/guide/deployment/server.md diff --git a/docs/guide/vercel.md b/docs/guide/deployment/vercel.md similarity index 100% rename from docs/guide/vercel.md rename to docs/guide/deployment/vercel.md