Cloudreve 4.18 部署实录：从下载到 API 全链路 | 服务器

给博客配了文件下载功能，用了 Cloudreve 4.x（自托管网盘/下载站程序）。部署过程踩了不少坑，尤其是 4.x 相比 3.x 重构了很多，网上教程大多还停留在 3.x，这里把 4.18 的实际经验写清楚。

部署 Cloudreve

1. 下载（国内服务器走镜像）

Cloudreve 是 Go 写的单文件程序，直接下载解压就能跑。服务器在国内，GitHub 直连很慢，用加速镜像：

mkdir -p /www/cloudreve && cd /www/cloudreve
wget https://ghproxy.net/https://github.com/cloudreve/Cloudreve/releases/download/4.18.0/cloudreve_4.18.0_linux_amd64.tar.gz
tar -xzf cloudreve_4.18.0_linux_amd64.tar.gz
chmod +x cloudreve

2. 首次运行

./cloudreve

首次运行会创建数据库（SQLite）和配置，监听 5212 端口。日志会提示注册方式：4.x 不再自动生成管理员密码，第一个注册的账号自动成为管理员（3.x 是会打印随机密码的，别搞混）。

3. systemd 守护

# /etc/systemd/system/cloudreve.service
[Unit]
Description=Cloudreve
After=network.target

[Service]
WorkingDirectory=/www/cloudreve
ExecStart=/www/cloudreve/cloudreve
Restart=on-abnormal
RestartSec=5s
KillMode=mixed

[Install]
WantedBy=multi-user.target

systemctl daemon-reload && systemctl enable --now cloudreve

4. Nginx 反代 + HTTPS

server {
    listen 80;
    server_name kkdays.top www.kkdays.top;
    client_max_body_size 0;   # 不限上传大小

    location / {
        proxy_pass http://127.0.0.1:5212;
        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;
    }
}

证书用 certbot 一键签（Let’s Encrypt，自动续期）：

apt install -y certbot python3-certbot-nginx
certbot --nginx -d kkdays.top -d www.kkdays.top --redirect

4.x API 踩坑记录

Cloudreve 4.x 的 API 前缀是 /api/v4，和 3.x 完全不同，这里记录几个关键点：

路径（URI）格式

4.x 的文件路径是带 scheme 的 URI，根目录是 cloudreve://my，不是 /！

// 创建上传会话（PUT /api/v4/file/upload）
{"uri": "cloudreve://my/测试文件.zip", "size": 1024}

认证流程

# 登录拿 token（POST /api/v4/session/token）
curl -X POST http://127.0.0.1:5212/api/v4/session/token \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"xxxxxx"}'

返回的 access_token 加在 Authorization: Bearer <token> 头里调用其他接口。

上传三件套

PUT /api/v4/file/upload 创建会话 → 拿 session_id
POST /api/v4/file/upload/{session_id}/ 上传分片（二进制 body）
最后一个分片上传完自动完成（不用额外调完成接口）

下载需要签名

直接 GET 文件内容会 403（expire timestamp is missing），要先申请带签名的下载 URL：

// POST /api/v4/file/url
{"uris": ["cloudreve://my/测试文件.zip"], "download": true}

返回的 URL 自带 sign 和过期时间，任何人都能下载（适合做分享链接）。

其他配置

主题色：4.x 支持多主题色方案，存数据库 settings 表的 theme_options / defaultTheme，改完重启生效
存储策略：默认本地存储，后台可以加 COS / S3 / 远程等

整体体验：Cloudreve 4.x 功能比 3.x 强很多（多用户、分享、离线下载、WebDAV），但 API 变化大，文档偏少，折腾时多翻源码最靠谱。