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:
545
docs/guide/deployment/docker.md
Normal file
545
docs/guide/deployment/docker.md
Normal file
@@ -0,0 +1,545 @@
|
||||
---
|
||||
title: Docker 部署
|
||||
createTime: 2025/11/09 00:26:55
|
||||
permalink: /guide/deployment/docker
|
||||
---
|
||||
# Docker 部署
|
||||
|
||||
详细的 Docker 部署指南。
|
||||
|
||||
## 前置要求
|
||||
|
||||
- Docker 已安装（[获取 Docker](https://docs.docker.com/get-docker/)）
|
||||
- Docker Compose 已安装（通常随 Docker Desktop 一同安装）
|
||||
- 基本的 Docker 命令行知识
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 构建镜像
|
||||
|
||||
```bash
|
||||
git clone https://github.com/RhenCloud/Cloud-Index.git
|
||||
cd Cloud Index
|
||||
|
||||
# 构建镜像
|
||||
docker build -t Cloud Index:latest .
|
||||
```
|
||||
|
||||
### 2. 运行容器
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name Cloud Index \
|
||||
-p 5000:5000 \
|
||||
-e STORAGE_TYPE=r2 \
|
||||
-e R2_ENDPOINT_URL=https://account.r2.cloudflarestorage.com \
|
||||
-e ACCESS_KEY_ID=your_key \
|
||||
-e SECRET_ACCESS_KEY=your_secret \
|
||||
-e R2_BUCKET_NAME=your_bucket \
|
||||
Cloud Index:latest
|
||||
```
|
||||
|
||||
### 3. 访问应用
|
||||
|
||||
打开浏览器访问 `http://localhost:5000`
|
||||
|
||||
## Docker Compose 部署
|
||||
|
||||
### 基础配置
|
||||
|
||||
创建 `docker-compose.yml`：
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
Cloud Index:
|
||||
build: .
|
||||
container_name: Cloud Index
|
||||
ports:
|
||||
- "5000:5000"
|
||||
environment:
|
||||
STORAGE_TYPE: r2
|
||||
R2_ENDPOINT_URL: https://account.r2.cloudflarestorage.com
|
||||
R2_BUCKET_NAME: your-bucket
|
||||
ACCESS_KEY_ID: your_key
|
||||
SECRET_ACCESS_KEY: your_secret
|
||||
FLASK_ENV: production
|
||||
volumes:
|
||||
- ./cache:/app/static/thumbs
|
||||
restart: always
|
||||
```
|
||||
|
||||
启动服务：
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
### 完整配置（含 Nginx）
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
app:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile
|
||||
container_name: Cloud Index-app
|
||||
environment:
|
||||
STORAGE_TYPE: r2
|
||||
R2_ENDPOINT_URL: ${R2_ENDPOINT_URL}
|
||||
R2_BUCKET_NAME: ${R2_BUCKET_NAME}
|
||||
ACCESS_KEY_ID: ${ACCESS_KEY_ID}
|
||||
SECRET_ACCESS_KEY: ${SECRET_ACCESS_KEY}
|
||||
FLASK_ENV: production
|
||||
THUMB_TTL_SECONDS: 86400
|
||||
volumes:
|
||||
- app-cache:/app/static/thumbs
|
||||
- app-logs:/app/logs
|
||||
restart: unless-stopped
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:5000/"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 10s
|
||||
networks:
|
||||
- r2-network
|
||||
|
||||
nginx:
|
||||
image: nginx:alpine
|
||||
container_name: Cloud Index-nginx
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- ./nginx.conf:/etc/nginx/nginx.conf:ro
|
||||
- ./ssl:/etc/nginx/ssl:ro
|
||||
- ./cache:/app/static/thumbs:ro
|
||||
depends_on:
|
||||
- app
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- r2-network
|
||||
|
||||
volumes:
|
||||
app-cache:
|
||||
app-logs:
|
||||
|
||||
networks:
|
||||
r2-network:
|
||||
driver: bridge
|
||||
```
|
||||
|
||||
## Dockerfile 详解
|
||||
|
||||
标准的 Dockerfile 配置：
|
||||
|
||||
```dockerfile
|
||||
# 使用官方 Python 运行时作为基础镜像
|
||||
FROM python:3.11-slim
|
||||
|
||||
# 设置工作目录
|
||||
WORKDIR /app
|
||||
|
||||
# 安装系统依赖
|
||||
RUN apt-get update && apt-get install -y \
|
||||
gcc \
|
||||
libjpeg-dev \
|
||||
zlib1g-dev \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# 复制依赖文件
|
||||
COPY requirements.txt .
|
||||
|
||||
# 安装 Python 依赖
|
||||
RUN pip install --no-cache-dir -r requirements.txt
|
||||
|
||||
# 复制应用代码
|
||||
COPY . .
|
||||
|
||||
# 设置环境变量
|
||||
ENV FLASK_APP=app.py
|
||||
ENV FLASK_ENV=production
|
||||
ENV FLASK_RUN_HOST=0.0.0.0
|
||||
|
||||
# 暴露端口
|
||||
EXPOSE 5000
|
||||
|
||||
# 健康检查
|
||||
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
|
||||
CMD curl -f http://localhost:5000/ || exit 1
|
||||
|
||||
# 启动应用
|
||||
CMD ["python", "app.py"]
|
||||
```
|
||||
|
||||
## 环境变量配置
|
||||
|
||||
### 方式一：直接在命令行指定
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name Cloud Index \
|
||||
-p 5000:5000 \
|
||||
-e STORAGE_TYPE=r2 \
|
||||
-e R2_ENDPOINT_URL=https://account.r2.cloudflarestorage.com \
|
||||
-e R2_BUCKET_NAME=my-bucket \
|
||||
-e ACCESS_KEY_ID=key123 \
|
||||
-e SECRET_ACCESS_KEY=secret456 \
|
||||
Cloud Index:latest
|
||||
```
|
||||
|
||||
### 方式二：使用环境文件
|
||||
|
||||
创建 `.env.docker`：
|
||||
|
||||
```env
|
||||
STORAGE_TYPE=r2
|
||||
R2_ENDPOINT_URL=https://account.r2.cloudflarestorage.com
|
||||
R2_BUCKET_NAME=my-bucket
|
||||
ACCESS_KEY_ID=key123
|
||||
SECRET_ACCESS_KEY=secret456
|
||||
FLASK_ENV=production
|
||||
THUMB_TTL_SECONDS=86400
|
||||
```
|
||||
|
||||
运行时指定：
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name Cloud Index \
|
||||
-p 5000:5000 \
|
||||
--env-file .env.docker \
|
||||
Cloud Index:latest
|
||||
```
|
||||
|
||||
### 方式三：Docker Compose 环境文件
|
||||
|
||||
创建 `.env`，`docker-compose.yml` 自动读取：
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# 编辑 .env 文件
|
||||
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## 数据卷管理
|
||||
|
||||
### 挂载缓存目录
|
||||
|
||||
```bash
|
||||
# 本地缓存
|
||||
docker run -d \
|
||||
--name Cloud Index \
|
||||
-p 5000:5000 \
|
||||
-v $(pwd)/cache:/app/static/thumbs \
|
||||
--env-file .env.docker \
|
||||
Cloud Index:latest
|
||||
|
||||
# 命名卷
|
||||
docker volume create r2-cache
|
||||
docker run -d \
|
||||
--name Cloud Index \
|
||||
-p 5000:5000 \
|
||||
-v r2-cache:/app/static/thumbs \
|
||||
--env-file .env.docker \
|
||||
Cloud Index:latest
|
||||
```
|
||||
|
||||
### 挂载日志目录
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name Cloud Index \
|
||||
-p 5000:5000 \
|
||||
-v $(pwd)/logs:/app/logs \
|
||||
-v $(pwd)/cache:/app/static/thumbs \
|
||||
--env-file .env.docker \
|
||||
Cloud Index:latest
|
||||
```
|
||||
|
||||
## 网络配置
|
||||
|
||||
### 单容器模式
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name Cloud Index \
|
||||
-p 5000:5000 \
|
||||
--env-file .env.docker \
|
||||
Cloud Index:latest
|
||||
```
|
||||
|
||||
### Docker Compose 网络
|
||||
|
||||
```yaml
|
||||
networks:
|
||||
r2-network:
|
||||
driver: bridge
|
||||
```
|
||||
|
||||
容器内相互通信：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
networks:
|
||||
- r2-network
|
||||
nginx:
|
||||
depends_on:
|
||||
- app
|
||||
networks:
|
||||
- r2-network
|
||||
```
|
||||
|
||||
访问 `http://app:5000` 时，Nginx 容器可以连接到应用容器。
|
||||
|
||||
## 常用命令
|
||||
|
||||
### 镜像操作
|
||||
|
||||
```bash
|
||||
# 列出镜像
|
||||
docker images
|
||||
|
||||
# 删除镜像
|
||||
docker rmi Cloud Index:latest
|
||||
|
||||
# 标记镜像
|
||||
docker tag Cloud Index:v1.0
|
||||
|
||||
# 推送到仓库
|
||||
docker push myrepo/Cloud Index:v1.0
|
||||
|
||||
# 构建带标签的镜像
|
||||
docker build -t Cloud Index:v1.0 .
|
||||
```
|
||||
|
||||
### 容器操作
|
||||
|
||||
```bash
|
||||
# 列出运行中的容器
|
||||
docker ps
|
||||
|
||||
# 列出所有容器
|
||||
docker ps -a
|
||||
|
||||
# 查看容器日志
|
||||
docker logs Cloud Index
|
||||
docker logs -f Cloud Index # 实时日志
|
||||
docker logs --tail 100 Cloud Index # 最后 100 行
|
||||
|
||||
# 进入容器
|
||||
docker exec -it Cloud Index bash
|
||||
|
||||
# 停止容器
|
||||
docker stop Cloud Index
|
||||
|
||||
# 启动容器
|
||||
docker start Cloud Index
|
||||
|
||||
# 重启容器
|
||||
docker restart Cloud Index
|
||||
|
||||
# 删除容器
|
||||
docker rm Cloud Index # 容器必须已停止
|
||||
|
||||
# 查看容器统计信息
|
||||
docker stats Cloud Index
|
||||
```
|
||||
|
||||
### Docker Compose 操作
|
||||
|
||||
```bash
|
||||
# 启动所有服务
|
||||
docker-compose up -d
|
||||
|
||||
# 停止所有服务
|
||||
docker-compose down
|
||||
|
||||
# 查看日志
|
||||
docker-compose logs -f
|
||||
|
||||
# 查看特定服务日志
|
||||
docker-compose logs -f app
|
||||
|
||||
# 重启服务
|
||||
docker-compose restart
|
||||
|
||||
# 构建镜像
|
||||
docker-compose build
|
||||
|
||||
# 删除卷
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
## 生产部署最佳实践
|
||||
|
||||
### 1. 使用数据卷持久化存储
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
app-cache:
|
||||
driver: local
|
||||
app-logs:
|
||||
driver: local
|
||||
|
||||
services:
|
||||
app:
|
||||
volumes:
|
||||
- app-cache:/app/static/thumbs
|
||||
- app-logs:/app/logs
|
||||
```
|
||||
|
||||
### 2. 设置资源限制
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1'
|
||||
memory: 512M
|
||||
reservations:
|
||||
cpus: '0.5'
|
||||
memory: 256M
|
||||
```
|
||||
|
||||
### 3. 配置健康检查
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:5000/"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 10s
|
||||
```
|
||||
|
||||
### 4. 日志驱动配置
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
logging:
|
||||
driver: "json-file"
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
```
|
||||
|
||||
### 5. 重启策略
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
restart: unless-stopped # 推荐值
|
||||
# unless-stopped: 容器异常退出时重启，停止后不重启
|
||||
# always: 总是重启
|
||||
# on-failure: 仅在非 0 退出码时重启
|
||||
# no: 不自动重启
|
||||
```
|
||||
|
||||
## 监控和维护
|
||||
|
||||
### 查看容器资源使用
|
||||
|
||||
```bash
|
||||
# 实时监控
|
||||
docker stats Cloud Index
|
||||
|
||||
# 查看完整统计信息
|
||||
docker stats --no-stream Cloud Index
|
||||
```
|
||||
|
||||
### 清理无用资源
|
||||
|
||||
```bash
|
||||
# 清理停止的容器
|
||||
docker container prune
|
||||
|
||||
# 清理无用的镜像
|
||||
docker image prune
|
||||
|
||||
# 清理无用的数据卷
|
||||
docker volume prune
|
||||
|
||||
# 一次性清理所有无用资源
|
||||
docker system prune -a
|
||||
```
|
||||
|
||||
### 备份数据卷
|
||||
|
||||
```bash
|
||||
# 备份名称为 r2-cache 的卷
|
||||
docker run --rm \
|
||||
-v r2-cache:/data \
|
||||
-v $(pwd):/backup \
|
||||
ubuntu \
|
||||
tar czf /backup/r2-cache.tar.gz -C /data .
|
||||
|
||||
# 恢复
|
||||
docker run --rm \
|
||||
-v r2-cache:/data \
|
||||
-v $(pwd):/backup \
|
||||
ubuntu \
|
||||
tar xzf /backup/r2-cache.tar.gz -C /data
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 容器无法启动
|
||||
|
||||
```bash
|
||||
# 查看详细错误日志
|
||||
docker logs Cloud Index
|
||||
|
||||
# 进入容器调试
|
||||
docker run -it --rm Cloud Index:latest bash
|
||||
```
|
||||
|
||||
### 端口已被占用
|
||||
|
||||
```bash
|
||||
# 查看占用端口的进程
|
||||
lsof -i :5000
|
||||
|
||||
# 使用其他端口
|
||||
docker run -d -p 8080:5000 Cloud Index:latest
|
||||
```
|
||||
|
||||
### 卷权限问题
|
||||
|
||||
```bash
|
||||
# 检查卷权限
|
||||
docker inspect r2-cache
|
||||
|
||||
# 修复权限（进入容器操作）
|
||||
docker exec Cloud Index chmod -R 755 /app/static/thumbs
|
||||
```
|
||||
|
||||
### 内存溢出
|
||||
|
||||
```bash
|
||||
# 设置内存限制
|
||||
docker run -d \
|
||||
--memory=512m \
|
||||
--memory-swap=1g \
|
||||
Cloud Index:latest
|
||||
|
||||
# 清理缓存
|
||||
docker exec Cloud Index rm -rf /app/static/thumbs/*
|
||||
```
|
||||
|
||||
## 参考资源
|
||||
|
||||
- [Docker 官方文档](https://docs.docker.com/)
|
||||
- [Docker Compose 文件参考](https://docs.docker.com/compose/compose-file/)
|
||||
- [Best practices for writing Dockerfiles](https://docs.docker.com/develop/dev-best-practices/dockerfile_best-practices/)
|
||||
125
docs/guide/deployment/overview.md
Normal file
125
docs/guide/deployment/overview.md
Normal file
@@ -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)** - 了解存储配置
|
||||
|
||||
**现在就开始吧！** 🚀
|
||||
678
docs/guide/deployment/server.md
Normal file
678
docs/guide/deployment/server.md
Normal file
@@ -0,0 +1,678 @@
|
||||
---
|
||||
title: 服务器部署
|
||||
createTime: 2025/11/09 00:26:55
|
||||
permalink: /guide/deployment/server
|
||||
---
|
||||
|
||||
在自有或云服务器上部署 Cloud Index 的完整指南。
|
||||
|
||||
## 优势
|
||||
|
||||
- ✅ 完全自主可控
|
||||
- ✅ 无运营商限制
|
||||
- ✅ 成本可预测
|
||||
- ✅ 性能稳定
|
||||
- ✅ 支持自定义配置
|
||||
- ✅ 适合生产环境
|
||||
|
||||
## 前置要求
|
||||
|
||||
- Linux 服务器（推荐 Ubuntu 20.04 LTS 或更新版本）
|
||||
- Python 3.9+ 已安装
|
||||
- pip 或 poetry 包管理器
|
||||
- 服务器可访问互联网
|
||||
- 存储后端配置（R2、S3 或 GitHub）
|
||||
- （可选）Nginx 反向代理
|
||||
- （可选）SSL 证书
|
||||
|
||||
## 快速开始（5 分钟）
|
||||
|
||||
### 第 1 步：连接到服务器
|
||||
|
||||
```bash
|
||||
ssh user@your-server-ip
|
||||
```
|
||||
|
||||
### 第 2 步：下载项目
|
||||
|
||||
```bash
|
||||
cd /opt
|
||||
git clone https://github.com/RhenCloud/Cloud-Index.git
|
||||
cd Cloud-Index
|
||||
```
|
||||
|
||||
### 第 3 步：安装依赖
|
||||
|
||||
```bash
|
||||
# 更新系统包
|
||||
sudo apt-get update && sudo apt-get upgrade -y
|
||||
|
||||
# 安装 Python 和必要工具
|
||||
sudo apt-get install -y python3 python3-pip python3-venv git
|
||||
|
||||
# 创建虚拟环境
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
|
||||
# 安装项目依赖
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 第 4 步：配置环境变量
|
||||
|
||||
创建 `.env` 文件：
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
nano .env
|
||||
```
|
||||
|
||||
编辑 `.env` 文件，配置你的存储后端：
|
||||
|
||||
```env
|
||||
# 基础配置
|
||||
STORAGE_TYPE=r2
|
||||
FLASK_ENV=production
|
||||
FLASK_RUN_HOST=0.0.0.0
|
||||
FLASK_RUN_PORT=5000
|
||||
|
||||
# R2 配置（选择一种）
|
||||
R2_ENDPOINT_URL=https://your-account-id.r2.cloudflarestorage.com
|
||||
R2_BUCKET_NAME=your-bucket-name
|
||||
ACCESS_KEY_ID=your_access_key
|
||||
SECRET_ACCESS_KEY=your_secret_key
|
||||
R2_PUBLIC_URL=https://pub-your-bucket.r2.dev
|
||||
```
|
||||
|
||||
### 第 5 步：启动应用
|
||||
|
||||
```bash
|
||||
python app.py
|
||||
```
|
||||
|
||||
访问 `http://your-server-ip:5000` 查看应用。
|
||||
|
||||
## 生产环境配置
|
||||
|
||||
### 使用 Gunicorn 和 Nginx
|
||||
|
||||
#### 1. 安装 Gunicorn
|
||||
|
||||
```bash
|
||||
source venv/bin/activate
|
||||
pip install gunicorn
|
||||
```
|
||||
|
||||
#### 2. 创建 Systemd 服务文件
|
||||
|
||||
创建 `/etc/systemd/system/cloud-index.service`：
|
||||
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/cloud-index.service
|
||||
```
|
||||
|
||||
写入以下内容：
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Cloud Index Application
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
User=www-data
|
||||
WorkingDirectory=/opt/Cloud-Index
|
||||
Environment="PATH=/opt/Cloud-Index/venv/bin"
|
||||
ExecStart=/opt/Cloud-Index/venv/bin/gunicorn \
|
||||
--workers 4 \
|
||||
--worker-class sync \
|
||||
--bind 127.0.0.1:5000 \
|
||||
--timeout 120 \
|
||||
--access-logfile /var/log/cloud-index/access.log \
|
||||
--error-logfile /var/log/cloud-index/error.log \
|
||||
app:app
|
||||
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
#### 3. 创建日志目录
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /var/log/cloud-index
|
||||
sudo chown www-data:www-data /var/log/cloud-index
|
||||
```
|
||||
|
||||
#### 4. 加载并启动服务
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl start cloud-index
|
||||
sudo systemctl enable cloud-index # 开机自启
|
||||
|
||||
# 查看状态
|
||||
sudo systemctl status cloud-index
|
||||
```
|
||||
|
||||
#### 5. 配置 Nginx 反向代理
|
||||
|
||||
安装 Nginx：
|
||||
|
||||
```bash
|
||||
sudo apt-get install -y nginx
|
||||
```
|
||||
|
||||
创建 Nginx 配置文件 `/etc/nginx/sites-available/cloud-index`：
|
||||
|
||||
```bash
|
||||
sudo nano /etc/nginx/sites-available/cloud-index
|
||||
```
|
||||
|
||||
写入以下内容：
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name your-domain.com; # 替换为你的域名
|
||||
|
||||
client_max_body_size 100M; # 允许大文件上传
|
||||
|
||||
# 重定向 HTTP 到 HTTPS（可选）
|
||||
# return 301 https://$server_name$request_uri;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:5000;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# 连接超时配置
|
||||
proxy_connect_timeout 60s;
|
||||
proxy_send_timeout 60s;
|
||||
proxy_read_timeout 60s;
|
||||
}
|
||||
|
||||
# 静态文件缓存配置
|
||||
location /static/ {
|
||||
alias /opt/Cloud-Index/static/;
|
||||
expires 30d;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
启用此配置：
|
||||
|
||||
```bash
|
||||
sudo ln -s /etc/nginx/sites-available/cloud-index /etc/nginx/sites-enabled/
|
||||
sudo nginx -t # 测试配置
|
||||
sudo systemctl restart nginx
|
||||
```
|
||||
|
||||
### 配置 HTTPS（SSL/TLS）
|
||||
|
||||
#### 使用 Let's Encrypt 免费证书
|
||||
|
||||
安装 Certbot：
|
||||
|
||||
```bash
|
||||
sudo apt-get install -y certbot python3-certbot-nginx
|
||||
```
|
||||
|
||||
申请证书：
|
||||
|
||||
```bash
|
||||
sudo certbot certonly --nginx -d your-domain.com
|
||||
```
|
||||
|
||||
更新 Nginx 配置为 HTTPS：
|
||||
|
||||
```bash
|
||||
sudo nano /etc/nginx/sites-available/cloud-index
|
||||
```
|
||||
|
||||
修改为：
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name your-domain.com;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name your-domain.com;
|
||||
|
||||
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
|
||||
|
||||
# SSL 安全配置
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
ssl_ciphers HIGH:!aNULL:!MD5;
|
||||
ssl_prefer_server_ciphers on;
|
||||
|
||||
client_max_body_size 100M;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:5000;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
proxy_connect_timeout 60s;
|
||||
proxy_send_timeout 60s;
|
||||
proxy_read_timeout 60s;
|
||||
}
|
||||
|
||||
location /static/ {
|
||||
alias /opt/Cloud-Index/static/;
|
||||
expires 30d;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
重启 Nginx：
|
||||
|
||||
```bash
|
||||
sudo systemctl restart nginx
|
||||
```
|
||||
|
||||
设置证书自动续期：
|
||||
|
||||
```bash
|
||||
sudo certbot renew --dry-run # 测试
|
||||
sudo systemctl enable certbot.timer # 启用自动续期
|
||||
```
|
||||
|
||||
## 环境变量配置
|
||||
|
||||
创建 `.env` 文件配置存储后端。参考 [环境配置](/guide/environment) 获取完整参数说明。
|
||||
|
||||
### R2 配置示例
|
||||
|
||||
```env
|
||||
STORAGE_TYPE=r2
|
||||
R2_ENDPOINT_URL=https://your-account-id.r2.cloudflarestorage.com
|
||||
R2_BUCKET_NAME=your-bucket-name
|
||||
ACCESS_KEY_ID=your_access_key
|
||||
SECRET_ACCESS_KEY=your_secret_key
|
||||
R2_PUBLIC_URL=https://pub-your-bucket.r2.dev
|
||||
FLASK_ENV=production
|
||||
THUMB_TTL_SECONDS=604800
|
||||
```
|
||||
|
||||
### S3 配置示例
|
||||
|
||||
```env
|
||||
STORAGE_TYPE=s3
|
||||
S3_BUCKET_NAME=your-bucket-name
|
||||
S3_REGION=us-east-1
|
||||
ACCESS_KEY_ID=your_access_key
|
||||
SECRET_ACCESS_KEY=your_secret_key
|
||||
FLASK_ENV=production
|
||||
```
|
||||
|
||||
### GitHub 配置示例
|
||||
|
||||
```env
|
||||
STORAGE_TYPE=github
|
||||
GITHUB_REPO_OWNER=your-username
|
||||
GITHUB_REPO_NAME=your-repo-name
|
||||
GITHUB_ACCESS_TOKEN=your_github_token
|
||||
GITHUB_RAW_PROXY_URL=https://raw.ghproxy.com
|
||||
FLASK_ENV=production
|
||||
```
|
||||
|
||||
## 自动部署（GitHub Actions）
|
||||
|
||||
### 配置 SSH 部署
|
||||
|
||||
1. 在服务器上创建部署用户（可选）：
|
||||
|
||||
```bash
|
||||
sudo useradd -m -s /bin/bash deploy
|
||||
sudo usermod -aG sudo deploy
|
||||
```
|
||||
|
||||
1. 生成 SSH 密钥对：
|
||||
|
||||
```bash
|
||||
ssh-keygen -t rsa -b 4096 -f ~/.ssh/github-deploy -N ""
|
||||
```
|
||||
|
||||
1. 将公钥添加到服务器 `authorized_keys`：
|
||||
|
||||
```bash
|
||||
cat ~/.ssh/github-deploy.pub | ssh deploy@your-server "cat >> ~/.ssh/authorized_keys"
|
||||
```
|
||||
|
||||
1. 在 GitHub 仓库中添加 Secret：
|
||||
|
||||
- `SERVER_HOST`: 服务器 IP 或域名
|
||||
- `SERVER_USER`: 部署用户名
|
||||
- `SERVER_SSH_KEY`: 私钥内容（`cat ~/.ssh/github-deploy`）
|
||||
- `DEPLOY_PATH`: 部署路径，如 `/opt/Cloud-Index`
|
||||
|
||||
### 创建部署脚本
|
||||
|
||||
创建 `.github/workflows/deploy-to-server.yml`：
|
||||
|
||||
```yaml
|
||||
name: Deploy to Server
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
workflow_dispatch: {}
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Deploy to server
|
||||
uses: appleboy/ssh-action@master
|
||||
with:
|
||||
host: ${{ secrets.SERVER_HOST }}
|
||||
username: ${{ secrets.SERVER_USER }}
|
||||
key: ${{ secrets.SERVER_SSH_KEY }}
|
||||
script: |
|
||||
cd ${{ secrets.DEPLOY_PATH }}
|
||||
git pull origin main
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
sudo systemctl restart cloud-index
|
||||
echo "✅ Deployment completed"
|
||||
```
|
||||
|
||||
每次推送到 `main` 分支，应用会自动部署到服务器。
|
||||
|
||||
## 监控和维护
|
||||
|
||||
### 查看日志
|
||||
|
||||
```bash
|
||||
# 查看实时日志
|
||||
sudo journalctl -u cloud-index -f
|
||||
|
||||
# 查看应用日志
|
||||
tail -f /var/log/cloud-index/error.log
|
||||
tail -f /var/log/cloud-index/access.log
|
||||
```
|
||||
|
||||
### 监控系统资源
|
||||
|
||||
```bash
|
||||
# 查看内存和 CPU 使用
|
||||
top
|
||||
|
||||
# 查看磁盘使用
|
||||
df -h
|
||||
|
||||
# 查看网络连接
|
||||
netstat -tulpn | grep 5000
|
||||
```
|
||||
|
||||
### 定期更新
|
||||
|
||||
```bash
|
||||
# 更新系统包
|
||||
sudo apt-get update && sudo apt-get upgrade -y
|
||||
|
||||
# 更新应用依赖
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt --upgrade
|
||||
```
|
||||
|
||||
### 备份重要文件
|
||||
|
||||
```bash
|
||||
# 定期备份环境配置
|
||||
sudo cp /opt/Cloud-Index/.env /backup/.env.backup.$(date +%Y%m%d)
|
||||
|
||||
# 定期备份缓存
|
||||
sudo tar -czf /backup/cache-$(date +%Y%m%d).tar.gz /opt/Cloud-Index/static/thumbs/
|
||||
```
|
||||
|
||||
## 性能优化
|
||||
|
||||
### 1. Gunicorn Worker 配置
|
||||
|
||||
根据服务器 CPU 核心数调整 Worker 数：
|
||||
|
||||
```bash
|
||||
# 查看 CPU 核心数
|
||||
nproc
|
||||
|
||||
# 推荐配置：(2 × CPU 核心数) + 1
|
||||
```
|
||||
|
||||
修改 `/etc/systemd/system/cloud-index.service` 中的 `--workers` 参数。
|
||||
|
||||
### 2. 启用缓存
|
||||
|
||||
增加缩略图缓存时间（`.env` 文件）：
|
||||
|
||||
```env
|
||||
THUMB_TTL_SECONDS=2592000 # 30 天
|
||||
```
|
||||
|
||||
### 3. 配置反向代理缓存
|
||||
|
||||
在 Nginx 配置中添加：
|
||||
|
||||
```nginx
|
||||
http {
|
||||
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m;
|
||||
|
||||
server {
|
||||
location /static/ {
|
||||
proxy_cache my_cache;
|
||||
proxy_cache_valid 200 30d;
|
||||
add_header X-Cache-Status $upstream_cache_status;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 数据库连接池
|
||||
|
||||
如果使用数据库，配置连接池以提高性能。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 应用无法启动
|
||||
|
||||
检查：
|
||||
|
||||
```bash
|
||||
# 查看错误日志
|
||||
sudo journalctl -u cloud-index -n 50
|
||||
|
||||
# 验证环境变量
|
||||
env | grep -E "STORAGE_|R2_|S3_|GITHUB_"
|
||||
|
||||
# 测试手动启动
|
||||
source venv/bin/activate
|
||||
python app.py
|
||||
```
|
||||
|
||||
### Nginx 502 错误
|
||||
|
||||
检查：
|
||||
|
||||
```bash
|
||||
# 验证应用是否运行
|
||||
sudo systemctl status cloud-index
|
||||
|
||||
# 查看 Nginx 错误日志
|
||||
sudo tail -f /var/log/nginx/error.log
|
||||
|
||||
# 检查 Nginx 配置
|
||||
sudo nginx -t
|
||||
```
|
||||
|
||||
### 内存不足
|
||||
|
||||
```bash
|
||||
# 查看内存使用
|
||||
free -h
|
||||
|
||||
# 调整 Gunicorn workers
|
||||
# 在 /etc/systemd/system/cloud-index.service 中减少 workers 数量
|
||||
```
|
||||
|
||||
### 存储无法连接
|
||||
|
||||
检查：
|
||||
|
||||
```bash
|
||||
# 验证环境变量设置
|
||||
grep -E "^(R2_|S3_|GITHUB_)" .env
|
||||
|
||||
# 测试连接
|
||||
python -c "from app import app; app.test_client()"
|
||||
```
|
||||
|
||||
## 安全建议
|
||||
|
||||
### 1. 防火墙配置
|
||||
|
||||
```bash
|
||||
# 只允许 HTTP/HTTPS
|
||||
sudo ufw allow 22/tcp # SSH
|
||||
sudo ufw allow 80/tcp # HTTP
|
||||
sudo ufw allow 443/tcp # HTTPS
|
||||
sudo ufw enable
|
||||
```
|
||||
|
||||
### 2. 定期备份
|
||||
|
||||
```bash
|
||||
# 创建备份脚本 backup.sh
|
||||
#!/bin/bash
|
||||
BACKUP_DIR="/backup/cloud-index"
|
||||
DATE=$(date +%Y%m%d_%H%M%S)
|
||||
|
||||
mkdir -p $BACKUP_DIR
|
||||
|
||||
# 备份 .env 文件
|
||||
cp /opt/Cloud-Index/.env $BACKUP_DIR/.env.$DATE
|
||||
|
||||
# 删除 7 天前的备份
|
||||
find $BACKUP_DIR -name ".env.*" -mtime +7 -delete
|
||||
|
||||
# 使用 crontab 定期运行
|
||||
# 0 2 * * * /path/to/backup.sh
|
||||
```
|
||||
|
||||
### 3. SSH 安全
|
||||
|
||||
```bash
|
||||
# 禁用密码登录
|
||||
sudo nano /etc/ssh/sshd_config
|
||||
# 设置 PasswordAuthentication no
|
||||
|
||||
# 更改 SSH 端口（可选）
|
||||
# 设置 Port 2222
|
||||
|
||||
sudo systemctl restart ssh
|
||||
```
|
||||
|
||||
### 4. 定期更新
|
||||
|
||||
```bash
|
||||
# 启用自动安全更新
|
||||
sudo apt-get install -y unattended-upgrades
|
||||
sudo dpkg-reconfigure -plow unattended-upgrades
|
||||
```
|
||||
|
||||
## 与 Docker 的对比
|
||||
|
||||
| 功能 | 直接部署 | Docker | Systemd |
|
||||
|-----|---------|--------|---------|
|
||||
| 部署难度 | 简单 | 中等 | 中等 |
|
||||
| 系统开销 | 最小 | 需要容器 | 最小 |
|
||||
| 隔离性 | 低 | 高 | 低 |
|
||||
| 自动重启 | 需要配置 | 自动 | 自动 |
|
||||
| 推荐用途 | 小型部署 | 团队开发 | 生产环境 |
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q: 如何更新应用代码？**
|
||||
|
||||
A: 使用 Git 拉取最新代码，然后重启服务：
|
||||
|
||||
```bash
|
||||
cd /opt/Cloud-Index
|
||||
git pull origin main
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
sudo systemctl restart cloud-index
|
||||
```
|
||||
|
||||
**Q: 如何处理长时间运行的大文件上传？**
|
||||
|
||||
A: 增加 Nginx 和 Gunicorn 的超时配置：
|
||||
|
||||
```nginx
|
||||
# Nginx 配置
|
||||
proxy_connect_timeout 300s;
|
||||
proxy_send_timeout 300s;
|
||||
proxy_read_timeout 300s;
|
||||
```
|
||||
|
||||
```bash
|
||||
# Gunicorn 配置
|
||||
--timeout 300
|
||||
```
|
||||
|
||||
**Q: 如何监控应用性能？**
|
||||
|
||||
A: 推荐安装监控工具：
|
||||
|
||||
```bash
|
||||
# 使用 htop 监控实时资源
|
||||
sudo apt-get install -y htop
|
||||
|
||||
# 使用 Prometheus 和 Grafana 构建完整监控（可选）
|
||||
```
|
||||
|
||||
**Q: 生产环境推荐配置是什么？**
|
||||
|
||||
A:
|
||||
|
||||
- 4+ CPU 核心
|
||||
- 8+ GB 内存
|
||||
- 50+ GB SSD 存储
|
||||
- 独立的存储后端（R2/S3）
|
||||
- HTTPS 证书
|
||||
- 定期备份策略
|
||||
|
||||
## 获取帮助
|
||||
|
||||
- 📖 [文档首页](/guide/introduction)
|
||||
- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues)
|
||||
- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions)
|
||||
- 📧 Email: <i@rhen.cloud>
|
||||
|
||||
## 总结
|
||||
|
||||
服务器部署提供了最大的灵活性和控制权。通过 Nginx 反向代理、Systemd 自动管理和 GitHub Actions 自动部署，可以构建一个生产级的、高可用的应用系统！🚀
|
||||
|
||||
---
|
||||
|
||||
**下一步**：
|
||||
|
||||
- 查看 [Docker 部署](/guide/docker) 了解容器化部署方案
|
||||
- 查看 [Vercel 部署](/guide/vercel) 了解 Serverless 部署方案
|
||||
- 查看 [环境配置](/guide/environment) 了解所有配置选项
|
||||
382
docs/guide/deployment/vercel.md
Normal file
382
docs/guide/deployment/vercel.md
Normal file
@@ -0,0 +1,382 @@
|
||||
---
|
||||
title: Vercel 部署
|
||||
createTime: 2025/11/09 00:26:55
|
||||
permalink: /guide/deployment/vercel
|
||||
---
|
||||
# Vercel 部署
|
||||
|
||||
在 Vercel 上快速部署 Cloud Index 的完整指南。
|
||||
|
||||
## 优势
|
||||
|
||||
- ✅ 零配置部署
|
||||
- ✅ 自动 HTTPS
|
||||
- ✅ 全球 CDN 加速
|
||||
- ✅ 自动扩展
|
||||
- ✅ 免费额度充足
|
||||
- ✅ 与 GitHub 无缝集成
|
||||
|
||||
## 前置要求
|
||||
|
||||
- GitHub 账户
|
||||
- Vercel 账户（[注册免费账户](https://vercel.com/signup)）
|
||||
- 存储后端配置（R2、S3 或 GitHub）
|
||||
|
||||
## 部署步骤
|
||||
|
||||
### 第 1 步：Fork 项目
|
||||
|
||||
访问 [Cloud Index GitHub 仓库](https://github.com/RhenCloud/Cloud-Index)，点击 "Fork" 按钮。
|
||||
|
||||
### 第 2 步：连接到 Vercel
|
||||
|
||||
1. 登录 [Vercel 控制台](https://vercel.com/dashboard)
|
||||
2. 点击 "Add New..." → "Project"
|
||||
3. 点击 "Import Git Repository"
|
||||
4. 连接 GitHub 账户
|
||||
5. 选择你 Fork 的仓库
|
||||
|
||||
### 第 3 步：配置项目
|
||||
|
||||
在 Import 页面：
|
||||
|
||||
1. **Project Name** - 输入项目名称（如 `cloud-index`）
|
||||
2. **Framework** - 选择 "Python" 或保持默认
|
||||
3. **Root Directory** - 保持默认（根目录）
|
||||
|
||||
### 第 4 步：配置环境变量
|
||||
|
||||
点击 "Environment Variables"，添加以下变量：
|
||||
|
||||
**基础配置：**
|
||||
|
||||
```
|
||||
STORAGE_TYPE = r2
|
||||
```
|
||||
|
||||
**R2 存储配置：**
|
||||
|
||||
```
|
||||
R2_ENDPOINT_URL = https://your-account-id.r2.cloudflarestorage.com
|
||||
R2_BUCKET_NAME = your-bucket-name
|
||||
ACCESS_KEY_ID = your_access_key
|
||||
SECRET_ACCESS_KEY = your_secret_key
|
||||
R2_PUBLIC_URL = https://pub-your-bucket.r2.dev
|
||||
```
|
||||
|
||||
或 **S3 存储配置：**
|
||||
|
||||
```
|
||||
STORAGE_TYPE = s3
|
||||
S3_BUCKET_NAME = your-bucket-name
|
||||
S3_REGION = us-east-1
|
||||
ACCESS_KEY_ID = your_access_key
|
||||
SECRET_ACCESS_KEY = your_secret_key
|
||||
```
|
||||
|
||||
或 **GitHub 存储配置：**
|
||||
|
||||
```
|
||||
STORAGE_TYPE = github
|
||||
GITHUB_REPO_OWNER = your-username
|
||||
GITHUB_REPO_NAME = your-repo-name
|
||||
GITHUB_ACCESS_TOKEN = your_github_token
|
||||
GITHUB_RAW_PROXY_URL = https://raw.ghproxy.com
|
||||
```
|
||||
|
||||
**应用配置：**
|
||||
|
||||
```
|
||||
FLASK_ENV = production
|
||||
THUMB_TTL_SECONDS = 604800
|
||||
```
|
||||
|
||||
### 第 5 步：部署
|
||||
|
||||
1. 检查配置无误
|
||||
2. 点击 "Deploy" 按钮
|
||||
3. 等待部署完成
|
||||
|
||||
部署完成后，Vercel 会提供一个 URL（如 `https://cloud-index.vercel.app`）
|
||||
|
||||
## 配置自定义域名
|
||||
|
||||
### 1. 添加域名
|
||||
|
||||
1. 进入项目设置 → "Domains"
|
||||
2. 输入你的域名（如 `cloud.example.com`）
|
||||
3. 点击 "Add"
|
||||
|
||||
### 2. 配置 DNS
|
||||
|
||||
Vercel 会提供 DNS 记录，按照说明在你的域名提供商处配置：
|
||||
|
||||
- **CNAME** 记录指向 Vercel
|
||||
- 或使用 **A** 记录指向 Vercel IP
|
||||
|
||||
### 3. 验证和启用
|
||||
|
||||
DNS 生效后（通常需要几分钟到几小时），Vercel 会自动验证并启用 HTTPS。
|
||||
|
||||
## 自动部署
|
||||
|
||||
当你推送代码到 GitHub 时，Vercel 会自动部署新版本。
|
||||
|
||||
### 触发部署
|
||||
|
||||
提交代码到 main 分支：
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Update configuration"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
Vercel 会自动开始部署。你可以在 Vercel Dashboard 中查看部署进度。
|
||||
|
||||
## 更新配置
|
||||
|
||||
### 方式一：通过 Vercel Dashboard
|
||||
|
||||
1. 进入项目设置
|
||||
2. 选择 "Environment Variables"
|
||||
3. 编辑相应变量
|
||||
4. 需要重新部署时，点击 Redeploy
|
||||
|
||||
### 方式二：通过代码
|
||||
|
||||
在项目根目录创建 `vercel.json` 文件（已包含）：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"builds": [
|
||||
{
|
||||
"src": "app.py",
|
||||
"use": "@vercel/python"
|
||||
},
|
||||
{
|
||||
"src": "/static/**",
|
||||
"use": "@vercel/static"
|
||||
}
|
||||
],
|
||||
"routes": [
|
||||
{
|
||||
"src": "/(.*)",
|
||||
"dest": "app.py"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
编辑后推送到 GitHub，Vercel 会自动重新部署。
|
||||
|
||||
## 日志查看
|
||||
|
||||
### 查看部署日志
|
||||
|
||||
1. 进入项目
|
||||
2. 点击 "Deployments" 选项卡
|
||||
3. 选择相应的部署
|
||||
4. 查看 "Logs" 中的详细信息
|
||||
|
||||
### 查看实时日志
|
||||
|
||||
1. 进入项目
|
||||
2. 点击 "Functions" 选项卡
|
||||
3. 选择 `app.py`
|
||||
4. 查看实时日志
|
||||
|
||||
### 使用 Vercel CLI
|
||||
|
||||
```bash
|
||||
# 安装 CLI
|
||||
npm i -g vercel
|
||||
|
||||
# 登录
|
||||
vercel login
|
||||
|
||||
# 查看日志
|
||||
vercel logs <project-url>
|
||||
|
||||
# 实时日志
|
||||
vercel logs <project-url> --follow
|
||||
```
|
||||
|
||||
## 性能优化
|
||||
|
||||
### 1. 启用 Edge Caching
|
||||
|
||||
在 `vercel.json` 中配置缓存头：
|
||||
|
||||
```json
|
||||
"routes": [
|
||||
{
|
||||
"src": "/static/(.*)",
|
||||
"headers": {
|
||||
"cache-control": "public, max-age=86400, immutable"
|
||||
},
|
||||
"dest": "app.py"
|
||||
},
|
||||
{
|
||||
"src": "/(.*)",
|
||||
"dest": "app.py"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 2. 优化缓存设置
|
||||
|
||||
增大缩略图缓存时间（在 Environment Variables）：
|
||||
|
||||
```
|
||||
THUMB_TTL_SECONDS = 2592000 # 30 天
|
||||
```
|
||||
|
||||
### 3. 使用 Vercel Analytics
|
||||
|
||||
1. 进入项目设置
|
||||
2. 选择 "Analytics"
|
||||
3. 启用 Vercel Analytics
|
||||
|
||||
可以实时监控应用性能和用户行为。
|
||||
|
||||
## 监控和告警
|
||||
|
||||
### Vercel Monitoring
|
||||
|
||||
在项目设置中配置告警：
|
||||
|
||||
1. 进入项目 → "Settings" → "Notifications"
|
||||
2. 设置部署失败时的通知
|
||||
3. 选择通知方式（Email、Slack 等）
|
||||
|
||||
### 错误追踪
|
||||
|
||||
Vercel 自动集成错误追踪。通过以下方式查看：
|
||||
|
||||
1. 进入 "Functions" 选项卡
|
||||
2. 查看错误率和详细错误信息
|
||||
|
||||
## 限制和配额
|
||||
|
||||
### 计算
|
||||
|
||||
- **免费版**: 100GB-Hours/月
|
||||
- 每次冷启动 < 10 秒
|
||||
- 单个函数最大执行时间 900 秒
|
||||
|
||||
### 存储
|
||||
|
||||
- **缓存**: 512MB（临时）
|
||||
- **函数空间**: 50MB 代码
|
||||
|
||||
### 带宽
|
||||
|
||||
- **免费版**: 100GB/月
|
||||
|
||||
### 费用估算
|
||||
|
||||
假设月均 1 万次请求，每次执行 500ms：
|
||||
|
||||
- 计算: 5,000 秒 / 1,000 = 5GB-Hours（远低于 100GB 免费额度）
|
||||
- **预计费用**: 免费 ✅
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 部署失败
|
||||
|
||||
检查：
|
||||
|
||||
1. `vercel.json` 配置是否正确
|
||||
2. `requirements.txt` 是否包含所有依赖
|
||||
3. Python 版本是否兼容（推荐 3.9+）
|
||||
|
||||
### 环境变量未生效
|
||||
|
||||
1. 确保在 Environment Variables 中正确配置
|
||||
2. 重新部署应用（Redeploy）
|
||||
3. 清理浏览器缓存
|
||||
|
||||
### 冷启动慢
|
||||
|
||||
- Vercel 自动缓存函数以加速启动
|
||||
- 增加使用频率会自动改善冷启动时间
|
||||
- 无需手动优化
|
||||
|
||||
### 存储无法连接
|
||||
|
||||
检查：
|
||||
|
||||
1. 环境变量是否正确
|
||||
2. 凭证是否有效
|
||||
3. 防火墙/安全组是否允许访问
|
||||
|
||||
### 缓存空间不足
|
||||
|
||||
清理或减少缓存：
|
||||
|
||||
1. 减小缩略图生成质量
|
||||
2. 减少缓存过期时间
|
||||
3. 定期手动清理
|
||||
|
||||
## 成本优化建议
|
||||
|
||||
1. **使用 Cloudflare R2** 而不是 S3（成本更低）
|
||||
2. **启用缓存** 减少存储访问次数
|
||||
3. **监控使用量** 避免超限
|
||||
4. **使用付费计划** 如果超过免费额度（$20/月 Pro 计划）
|
||||
|
||||
## 与本地开发保持同步
|
||||
|
||||
### 拉取最新变化
|
||||
|
||||
```bash
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
### 测试本地更改
|
||||
|
||||
```bash
|
||||
python app.py
|
||||
# 访问 http://localhost:5000
|
||||
```
|
||||
|
||||
### 推送到 Vercel
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Bug fix or feature"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
Vercel 会自动检测并部署。
|
||||
|
||||
## 回滚部署
|
||||
|
||||
如果新部署出现问题：
|
||||
|
||||
1. 进入项目 → "Deployments"
|
||||
2. 选择之前的稳定版本
|
||||
3. 点击 "Redeploy to Production"
|
||||
|
||||
应用会立即回滚到之前的版本。
|
||||
|
||||
## 获取帮助
|
||||
|
||||
- 📖 [Vercel 文档](https://vercel.com/docs)
|
||||
- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues>)
|
||||
- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions>)
|
||||
- 📧 Email: <i@rhen.cloud>
|
||||
|
||||
## 总结
|
||||
|
||||
| 功能 | 本地 | Docker | Vercel |
|
||||
|-----|------|--------|--------|
|
||||
| 部署难度 | 简单 | 中等 | 简单 |
|
||||
| 成本 | 自有服务器 | 中等 | 小 |
|
||||
| 性能 | 取决于服务器 | 好 | 优秀 |
|
||||
| 扩展性 | 有限 | 中等 | 自动 |
|
||||
| 推荐用途 | 开发测试 | 生产环境 | 中小型应用 |
|
||||
|
||||
Vercel 最适合需要快速部署、无需运维的应用！🚀
|
||||
Reference in New Issue
Block a user