添加 Vercel 部署工作流，更新 .gitignore，新增服务器部署文档

2025-12-06 15:26:10 +08:00 · 2025-11-09 15:07:42 +08:00
parent e97717dfe7
commit bdb3af1c79
4 changed files with 721 additions and 5 deletions
--- a/.github/workflows/deploy-to-vercel.yml
+++ b/.github/workflows/deploy-to-vercel.yml
@@ -0,0 +1,38 @@
+name: Deploy to Vercel
+
+on:
+    push:
+        branches:
+            - main
+    workflow_dispatch: {}
+
+jobs:
+    vercel-deploy:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: "20"
+
+            - name: Setup pnpm
+              uses: pnpm/action-setup@v4
+              with:
+                  version: "10.12.4"
+
+            - name: Install dependencies
+              run: pnpm install --frozen-lockfile
+
+            - name: Build documentation
+              run: pnpm run docs:build
+
+            - name: Deploy to Vercel
+              uses: amondnet/vercel-action@v25
+              with:
+                  vercel-token: ${{ secrets.VERCEL_TOKEN }}
+                  vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+                  vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+                  vercel-args: --prod
--- a/.gitignore
+++ b/.gitignore
@@ -1,10 +1,9 @@
 **/node_modules

-.github/
-
 docs/.vuepress/.cache
 docs/.vuepress/.temp
 docs/.vuepress/dist

 .DS_Store
-*.log
+*.log
+.vercel
--- a/docs/.vuepress/plume.config.ts
+++ b/docs/.vuepress/plume.config.ts
@@ -84,8 +84,9 @@ export default defineThemeConfig({
                        text: "部署",
                        collapsed: false,
                        items: [
-                            // { text: "Docker 部署", link: "/guide/docker" },
-                            { text: "Vercel 部署", link: "/guide/vercel" },
+                            { text: "服务器部署", link: "/guide/deployment/server" },
+                            // { text: "Docker 部署", link: "/guide/deployment/docker" },
+                            { text: "Vercel 部署", link: "/guide/deployment/vercel" },
                        ],
                    },
                ],
--- a/docs/guide/server.md
+++ b/docs/guide/server.md
@@ -0,0 +1,678 @@
+---
+title: 服务器部署
+createTime: 2025/11/09 00:26:55
+permalink: /guide/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) 了解所有配置选项