Cloudreve 部署手册

Cloudreve 项目主要由两部分组成：后端主仓库 cloudreve/Cloudreve，以及前端仓库 cloudreve/frontend。编译 Cloudreve 后端前，需要先构建 assets 目录下的前端子模块，然后使用 embed 嵌入到后端的可执行文件。

第一章：源码编译与打包

从源代码进行修改和编译，然后构建为自定义的 Docker 镜像。

1.1 前置条件：构建环境准备

在本地Windows开发机上，您需要准备好 Cloudreve 项目所需的编译环境：

1.2 源码修改与预编译

获取源码：从 Cloudreve 的官方 GitHub 仓库克隆或下载指定版本的源代码。

# 克隆仓库
git clone --recurse-submodules https://github.com/cloudreve/Cloudreve.git

# 进入项目目录
cd Cloudreve

# 签出您要编译的版本
git checkout 4.x.x

替换静态资源：进入前端源码目录 /assets/public/static/，找到 img 文件夹。用您自己设计好的、符合所有目标尺寸和格式（.svg, .ico, .png）的 Logo 文件，替换掉原有的文件。
编译前端：进入项目根目录，打开右键菜单，点击 open git bash here执行构建命令。
```
chmod +x ./.build/build-assets.sh

# 构建前端
./.build/build-assets.sh 4.x.x
```
说明：构建后的前端资源压缩包位于 application/statics/assets.zip，如提示 zip: command not found 可于此处下载，下载下来的是一个 zip-3.0-bin.zip 文件，解压它，进入解压后的 bin 目录，找到 zip.exe 这个文件。将 zip.exe 文件复制粘贴到 Git 的安装目录下的 usr\bin 文件夹里。这个路径通常是 C:\Program Files\Git\usr\bin。重启 Git Bash 窗口。

编译后端并嵌入前端资源：继续在 Git Bash 窗口进行操作。

# 设定目标为 Linux 系统
export GOOS=linux
export GOARCH=amd64

# 从 Git 获取版本信息
export COMMIT_SHA=$(git rev-parse --short HEAD)
export VERSION=$(git describe --tags)

# 执行交叉编译，输出名为 cloudreve 的文件
go build -a -o cloudreve \
    -ldflags "-s -w -X 'github.com/cloudreve/Cloudreve/v4/application/constants.BackendVersion=$VERSION' -X 'github.com/cloudreve/Cloudreve/v4/application/constants.LastCommit=$COMMIT_SHA'"

说明：执行成功后，项目根目录下会生成一个名为 cloudreve 的二进制可执行文件，这个文件已经包含了您自定义的前端界面。

1.3 构建自定义 Docker 镜像

在完成了上述预编译步骤后，现在回到项目根目录来构建 Docker 镜像。

构建命令(CMD)：

# 假设新镜像标记为 my-cloudreve:latest
docker build -t my-cloudreve:latest .

1.4 镜像的离线打包与安全分发

为应对服务器网络环境不佳或安全策略限制，我们将镜像打包为 TAR 文件进行离线部署。

打包镜像：

docker save my-cloudreve:latest -o my-cloudreve.tar

安全上传至服务器：使用 scp 命令并通过 SSH 密钥进行身份验证，将镜像包上传至服务器。

# 语法: scp -i <私钥路径> <本地文件> <用户@IP>:<目标路径>
scp -i "C:\path\to\your\private_key.pem" .\my-cloudreve.tar user@<your_server_ip>:~/

第二章：服务器部署与容器化运行

2.1 加载镜像并启动容器

SSH 登录服务器：

ssh -i "C:\path\to\your\private_key.pem" user@<your_server_ip>

从 TAR 文件加载镜像：
```
docker load -i my-cloudreve.tar
```
使用 docker images 确认 my-cloudreve:latest 已成功加载。

启动容器：

sudo docker run -d --name cloudreve -p 5212:5212 -p 6888:6888 -p 6888:6888/udp -v ~/cloudreve/data:/cloudreve/data --restart=always my-cloudreve:latest

第三章：配置 Nginx 网关与服务优化

3.1 Nginx 安装与多站点配置

安装 Nginx:

sudo apt update && sudo apt install nginx

为 Cloudreve 创建专属配置文件:

sudo nano /etc/nginx/sites-available/cloudreve.conf

粘贴以下经过优化的配置:

server {
    listen 80;
    server_name your-domain.com; # 替换为您的域名

    # 为 Let's Encrypt 证书验证提供明确的网站根目录
    root /var/www/html;
    location /.well-known/acme-challenge/ {
        allow all;
    }

    location / {
        proxy_pass http://127.0.0.1:5212; # 转发流量给本地的 Cloudreve 容器

        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_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 大文件与流媒体传输优化
        client_max_body_size 0;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_set_header Range $http_range;
        proxy_set_header If-Range $http_if_range;
    }
}

启用配置并避免冲突:

# 启用新配置
sudo ln -s /etc/nginx/sites-available/cloudreve.conf /etc/nginx/sites-enabled/
# 移除默认欢迎页配置，防止冲突
sudo rm /etc/nginx/sites-enabled/default
# 测试并重载 Nginx
sudo nginx -t && sudo systemctl reload nginx

3.2 内部检查：确保网站正常访问

检查站点 URL 配置：登录 Cloudreve 管理后台，进入 参数设置 -> 站点信息，确保“站点 URL”与当前的访问协议和域名完全一致（例如 http://your-domain.com）。
检查服务器防火墙配置。
检查服务商安全组/防火墙配置。