mirror of
https://github.com/RhenCloud/Cloud-Index.git
synced 2025-12-06 15:26:10 +08:00
679 lines
14 KiB
Markdown
679 lines
14 KiB
Markdown
---
|
||
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) 了解所有配置选项
|