Ubuntu 22.04 安装 Cloudreve 指南

Ubuntu 22.04 从零安装 Cloudreve 4.19.1 实战：在线/离线双方案、systemd 托管、管理员注册、上传下载与存储策略验证闭环，含升级实测与 6 条排障实录。

CloudreveCloudreve文件共享文件存储2026/10/22

Ubuntu 22.04 安装 Cloudreve 指南

目标：在 Ubuntu 22.04 服务器上从零安装并托管 Cloudreve 4.19.1（当前最新稳定版），覆盖「在线下载官方二进制 + systemd 托管」主方案与「离线包部署」备选方案，完成注册管理员、Web 登录、上传下载与存储策略验证闭环，并沉淀升级/降级与全部实测排障记录。全部命令与回显均在 Ubuntu 22.04.5 LTS（x86_64）上实测取得。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS x86_64（lsb_release -ds → Ubuntu 22.04.5 LTS）
  • Cloudreve 版本：4.19.1（GitHub Releases 最新稳定版，2026-10-22 实查；Commit #a8becb9，Pro=false 社区版）
  • 安装方式：官方预编译二进制（方案 A 在线下载 / 方案 B 离线包），systemd 托管
  • 安装目录：/opt/cloudreve（主程序与数据目录）
  • 数据目录：/opt/cloudreve/data（自动生成：conf.ini、cloudreve.db、uploads/）
  • 数据库：内置 SQLite（默认，零依赖）；生产可换 MySQL/PostgreSQL（配置方式见《Cloudreve 配置参数详解》）
  • 监听端口：5212（默认）
  • 管理员账号：admin@quzuo.net / q1w2e3r4（首个注册账号自动成为管理员）
  • 二进制包：cloudreve_4.19.1_linux_amd64.tar.gz，37,550,863 字节，MD5 9ff6345ddf1f4cdd641e41f5a6782c87（实测）

二、前置条件

2.1 基础工具

Ubuntu Server 22.04 最小安装默认不带下载工具，先补齐 wget/curl（后续下载与验证都依赖）：

apt-get update && apt-get install -y wget curl

实测输出（节选）：

Get:8 http://security.ubuntu.com/ubuntu jammy-security/main amd64 Packages [4430 kB]
Fetched 12.5 MB in 5s (2687 kB/s)
Reading package lists...
Running hooks in /etc/ca-certificates/update.d...
done.

验证：

wget --version | head -1

实测输出：

GNU Wget 1.21.2 built on linux-gnu.

2.2 端口规划

Cloudreve 默认监听 5212 端口。安装前确认端口未被占用：

ss -ltn | grep 5212 || echo "5212 空闲"

实测输出：

5212 空闲

💡 技术拓展：Web 服务监听地址在 Linux 有「仅本机 127.0.0.1:port」与「全部网卡 0.0.0.0:port（配置里简写 :port）」两种常见形态，对比——

形态配置写法访问范围适用场景
全部网卡Listen = :5212本机 + 局域网/公网标准部署，配合防火墙限源
仅本机Listen = 127.0.0.1:5212仅本机进程前置 Nginx/Caddy 反代时推荐

本文方案采用默认 :5212（全部网卡），生产环境建议反代后改为仅本机并启用 HTTPS。

2.3 目录规划

按 Linux 惯例将程序与数据集中于 /opt/cloudreve：

mkdir -p /opt/cloudreve

三、版本选型说明

3.1 版本线现状

Cloudreve 当前主线为 v4.x。2026-10-22 实查 GitHub Releases，最新稳定版为 4.19.1（修复部分场景邮件发送与 WOPI 应用失效问题）；4.16.1、4.13.0 为安全修复版本，其中 4.13.0 修复关键漏洞 CVE-2026-25726（官方 Release Notes 建议立即升级）。v3.x 已停止功能迭代，官方文档站 docsv3.cloudreve.org 标注为历史版本。

3.2 包命名与架构矩阵

官方包命名规则 cloudreve_<版本>_<OS>_<CPU架构>.tar.gz（官方 Quick Start 文档，2026-10-22 查阅）。常见组合：

操作系统架构包名
Linuxx86_64cloudreve_4.19.1_linux_amd64.tar.gz
LinuxARM64cloudreve_4.19.1_linux_arm64.tar.gz
LinuxARMv5/6/7cloudreve_4.19.1_linux_armv5/armv6/armv7.tar.gz
LinuxLoongArch64cloudreve_4.19.1_linux_loong64.tar.gz
Windowsx86_64 / ARM64cloudreve_4.19.1_windows_amd64/arm64.zip
macOSIntel / Apple Siliconcloudreve_4.19.1_darwin_amd64/arm64.zip

💡 说明：x86_64 服务器选 linux_amd64；树莓派 4/5、国产 ARM 服务器选 linux_arm64。下载前用 uname -m 确认本机架构（本文实测环境回显 x86_64）。

四、安装方案 A：官方二进制在线部署（主方案）

本章完成「下载 → 安装 → 初始化 → 管理员注册 → systemd 托管 → 全链路验证」的标准部署，是最推荐的部署方式。

4.1 下载官方二进制

cd /opt/cloudreve
wget "https://github.com/cloudreve/cloudreve/releases/download/4.19.1/cloudreve_4.19.1_linux_amd64.tar.gz"

实测输出（国际网络通畅时约 3 秒完成；境内直连慢时的处理见「十、常见问题」10.1 节）：

--2026-10-22 11:45:40--  https://github.com/cloudreve/cloudreve/releases/download/4.19.1/cloudreve_4.19.1_linux_amd64.tar.gz
HTTP request sent, awaiting response... 200 OK
Length: 37550863 (36M) [application/octet-stream]
Saving to: 'cloudreve_4.19.1_linux_amd64.tar.gz'
100 35.8M  100 35.8M    0     0  9371k      0  0:00:03  0:00:03 --:--:-- 14.8M

下载完成先校验完整性（记录下载文件 MD5，与官方发布页核对，并留存供离线分发复用）：

md5sum cloudreve_4.19.1_linux_amd64.tar.gz

实测输出：

9ff6345ddf1f4cdd641e41f5a6782c87  cloudreve_4.19.1_linux_amd64.tar.gz

4.2 解压安装

tar -zxvf cloudreve_4.19.1_linux_amd64.tar.gz
chmod +x cloudreve
ls -la /opt/cloudreve/

实测输出：

LICENSE
README.md
README_zh-CN.md
cloudreve
total 115004
drwxr-xr-x 2 root root     4096 Oct 22 11:46 .
drwxr-xr-x 3 root root     4096 Oct 22 03:47 ..
-rw-r--r-- 1 root root   35146 Jan 14  2026 LICENSE
-rw-r--r-- 1 root root    3728 Jan 28  2026 README.md
-rw-r--r-- 1 root root    3545 Jan 28  2026 README_zh-CN.md
-rwxr-xr-x 1 root root 80154786 Sep 18 20:38 cloudreve

主程序约 80 MB，Go 静态编译无运行时依赖。确认版本与帮助可用：

./cloudreve --help

实测输出：

Self-hosted file management and sharing system, supports multiple storage providers.
Complete documentation is available at https://docs.cloudreve.org/

Usage:
  cloudreve [flags]
  cloudreve [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  eject       Eject all embedded static files
  help        Help about any command
  master-key  Master encryption key management
  migrate     Migrate from v3 to v4
  server      Start a Cloudreve server with the given config file

Flags:
  -c, --conf string       Path to the config file (default "/opt/cloudreve/data/conf.ini")
  -h, --help              help for cloudreve
  -w, --use-working-dir   Use working directory, instead of executable directory

Use "cloudreve [command] --help" for more information about a command.

⚠️ 注意：v4 没有 --version 或 version 参数（实测 ./cloudreve --version 报 unknown flag: --version）。版本号以启动日志横幅 V4.19.1 Commit #a8becb9 为准。

4.3 首次启动与初始化

首次前台运行，观察初始化过程（生成配置与数据库后按 Ctrl+C 停止，改用 systemd 托管）：

./cloudreve

实测输出（初始化关键段落）：

   ___ _                 _
  / __\ | ___  _   _  __| |_ __ _____   _____
 / /  | |/ _ \| | | |/ _  | '__/ _ \ \ / / _ \
/ /___| | (_) | |_| | (_| | | |  __/\ V /  __/
\____/|_|\___/ \__,_|_|  \___| \_/ \___/

   V4.19.1  Commit #a8becb9  Pro=false
================================================

[Info]   2026-10-22 03:56:15 [...] Config file "/opt/cloudreve/data/conf.ini" not found, creating a new one.
[Info]   2026-10-22 03:56:15 [...] Logger initialized with LogLevel="info".
[Info]   2026-10-22 03:56:15 [...] Initializing database connection...
[Info]   2026-10-22 03:56:15 [...] Connect to SQLite database "/opt/cloudreve/data/cloudreve.db".
[Info]   2026-10-22 03:56:15 [...] Start initializing database schema...
[Info]   2026-10-22 03:56:15 [...] Creating basic table schema...
[Info]   2026-10-22 03:56:15 [...] Insert default settings...
[Info]   2026-10-22 03:56:15 [...] Insert default storage policy...
[Info]   2026-10-22 03:56:15 [...] Insert default admin group...
[Info]   2026-10-22 03:56:15 [...] Insert default user group...
[Info]   2026-10-22 03:56:15 [...] Insert default anonymous group...
[Info]   2026-10-22 03:56:15 [...] Insert default master node...
[Info]   2026-10-22 03:56:15 [...] Queue "MediaMetadataQueue" started with 30 workers.
[Info]   2026-10-22 03:56:15 [...] Queue "EntityRecycleQueue" started with 5 workers.
[Info]   2026-10-22 03:56:15 [...] Queue "IoIntenseQueue" started with 30 workers.
[Info]   2026-10-22 03:56:15 [...] Queue "RemoteDownloadQueue" started with 5 workers.
[Info]   2026-10-22 03:56:15 [...] Queue "ThumbQueue" started with 15 workers.
[Info]   2026-10-22 03:56:16 [...] Current running mode: Master.
[Info]   2026-10-22 03:56:16 [...] Listening to ":5212"

初始化完成后的目录结构：

ls -la /opt/cloudreve/data/

实测输出：

total 500
drwx------ 2 root root   4096 Oct 22 03:56 .
drwxr-xr-x 3 root root   4096 Oct 22 03:56 ..
-rw-r--r-- 1 root root   2644 Oct 22 03:56 cache_persist.bin
-rw-r--r-- 1 root root 495616 Oct 22 03:56 cloudreve.db
-rw-r--r-- 1 root root    159 Oct 22 03:56 conf.ini

自动生成的默认 conf.ini（cat /opt/cloudreve/data/conf.ini 实测全文）：

[System]
Debug = false
Mode = master
Listen = :5212
SessionSecret = JeV8nI3EPRGU2uBkHrin0vwG4OvmCkCCl10SPcmw5cVRg4KFNcdYX41eorR8TcT1
HashIDSalt = {HashIDSalt}

逐项说明：Debug 调试日志开关（false 生产用）；Mode 运行角色（master 主节点，从机节点设 slave）；Listen 监听地址与端口；SessionSecret 会话签名密钥（首次启动自动随机生成，泄露需更换）；HashIDSalt 对外 ID 哈希盐值，默认是 {HashIDSalt} 占位符，建议按 10.5 节手动设置为随机值。参数详解见《Cloudreve 配置参数详解》。

4.4 注册管理员账号

⚠️ 关键差异：v3 首次启动会在日志打印初始管理员密码；v4 不再打印，第一个注册的账号自动成为管理员（官方 Quick Start 明确说明，2026-10-22 查阅）。

浏览器访问 http://<服务器IP>:5212，进入登录页注册：邮箱 admin@quzuo.net、密码 q1w2e3r4、昵称 admin。提交后第一个账号即落入 Admin 用户组。

等价的接口级验证（便于脚本化检查，以下为服务器本机实测）：

curl -s -X POST http://127.0.0.1:5212/api/v4/user \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@quzuo.net","password":"q1w2e3r4"}'

实测输出：

{"code":0,"data":{"id":"dpTA","email":"admin@quzuo.net","nickname":"admin","status":"active","created_at":"2026-10-22T03:59:06.277013396Z"},"msg":""}

登录获取访问令牌（v4 密码登录端点为 /api/v4/session/token）：

curl -s -X POST http://127.0.0.1:5212/api/v4/session/token \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@quzuo.net","password":"q1w2e3r4"}'

实测输出（节选，JWT 令牌过长截断显示）：

{"code":0,"data":{"user":{"id":"dpTA","email":"admin@quzuo.net","nickname":"admin","status":"active","created_at":"2026-10-22T03:59:06.277013396Z","group":{"id":"7yT2","name":"Admin","permission":"/RoB","direct_link_batch_size":1000,"trash_retention":604800}},"token":{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...(175 字符)","refresh_token":"eyJhbGciOiJIUzI1NiIs...(更长)","access_expires":"2026-10-22T05:01:34.770834463Z","refresh_expires":"2026-11-05T04:01:34.7...","msg":""}}

回显确认两点：group.name: "Admin"（首号即管理员）；access_expires 距签发 1 小时、refresh_expires 14 天。

4.5 systemd 托管

创建服务单元 /etc/systemd/system/cloudreve.service：

cat > /etc/systemd/system/cloudreve.service <<'EOF'
[Unit]
Description=Cloudreve file management system
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/cloudreve
ExecStart=/opt/cloudreve/cloudreve
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

逐项说明：After=network.target 网络就绪后再启动；WorkingDirectory 指向安装目录（默认配置即解析到 /opt/cloudreve/data/conf.ini）；Restart=on-failure 仅异常退出（非零状态码）时 5 秒后自动拉起，正常 kill/systemctl stop 不会重启；User=root 为最简配置，生产可改为专用低权账户并相应调整数据目录属主。

加载并启动：

systemctl daemon-reload
systemctl enable cloudreve
systemctl start cloudreve

实测输出（enable 回显）：

Created symlink /etc/systemd/system/multi-user.target.wants/cloudreve.service → /etc/systemd/system/cloudreve.service.

状态验证：

systemctl status cloudreve --no-pager -l | head -12

实测输出：

● cloudreve.service - Cloudreve file management system
     Loaded: loaded (/etc/systemd/system/cloudreve.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-10-22 04:03:03 UTC; 5s ago
   Main PID: 3107 (cloudreve)
      Tasks: 15 (limit: 629145)
     Memory: 108.9M
        CPU: 316ms
     CGroup: /system.slice/cloudreve.service
             └─3107 /opt/cloudreve/cloudreve

Oct 22 04:03:03 cloudreve-server systemd[1]: Started Cloudreve file management system.

空载内存 108.9M，单进程 Tasks: 15，资源占用非常轻。

4.6 Web 登录验证

浏览器访问 http://<服务器IP>:5212，用 admin@quzuo.net / q1w2e3r4 登录即可进入网盘首页。服务器侧可达性验证：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:5212/

实测输出：

200

4.7 上传下载与存储策略验证闭环

（1）确认默认存储策略。 用管理令牌查询存储策略列表（管理端点 POST /api/v4/admin/policy）：

TOKEN=$(curl -s -X POST http://127.0.0.1:5212/api/v4/session/token \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@quzuo.net","password":"q1w2e3r4"}' \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['token']['access_token'])")
curl -s -X POST "http://127.0.0.1:5212/api/v4/admin/policy" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"page":1,"page_size":10}'

实测输出（关键字段节选）：

{"code":0,"data":{"pagination":{"page":0,"page_size":10,"total_items":1},"policies":[{"id":1,...,"name":"Default storage policy","type":"local","dir_name_rule":"/opt/cloudreve/data/uploads/{uid}/{path}","file_name_rule":"{uid}_{randomkey8}_{originname}","settings":{...,"chunk_size":262144...}}]},"msg":""}

解读：初始化已内置一条 Default storage policy（类型 local 本机存储），文件落盘目录规则 /opt/cloudreve/data/uploads/{uid}/{path}、物理文件名规则 {uid}_{randomkey8}_{originname}，分片 25 MB（chunk_size 实测为 26214400）。更多策略（S3/OSS/COS 等）在 Web 管理面板「存储策略」中添加。

（2）上传文件。 生成测试文件并上传到管理员根目录（v4 文件 URI 固定前缀 cloudreve://my/）：

echo "hello cloudreve 4.19.1 test file" > /tmp/test-upload.txt
curl -s -X PUT "http://127.0.0.1:5212/api/v4/file/content?uri=cloudreve://my/test-upload.txt" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: text/plain" \
  --data-binary @/tmp/test-upload.txt

实测输出：

{"code":0,"data":{"type":0,"id":"WbCA","name":"test-upload.txt","created_at":"2026-10-22T04:02:39.989199895Z","updated_at":"2026-10-22T04:02:39.99241641Z","size":33,"metadata":null,"path":"cloudreve://my/test-upload.txt","capability":"w8edAQ==","owned":true,"primary_entity":"kjTO"},"msg":""}

（3）列目录确认。

curl -s "http://127.0.0.1:5212/api/v4/file?uri=cloudreve://my/" -H "Authorization: Bearer $TOKEN"

实测输出（节选）：

{"code":0,"data":{"files":[{"type":0,"id":"WbCA","name":"test-upload.txt",...,"size":33,...,"path":"cloudreve://my/test-upload.txt",...}],"parent":{...}}}

（4）签名直链下载。

curl -s -X POST "http://127.0.0.1:5212/api/v4/file/url" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"uris":["cloudreve://my/test-upload.txt"],"download":false}'

实测输出：

{"code":0,"data":{"urls":[{"url":"http://localhost:5212/api/v4/file/content/kjTO/0/test-upload.txt?sign=HH_58qH-pvNxEwPXpuza4HSQmnVva7lyJZFYa9i3Hhc%3D%3A1792645371"}],"expires":"2026-10-22T05:02:51.219815047Z"},"msg":""}

curl -s "http://localhost:5212/api/v4/file/content/kjTO/0/test-upload.txt?sign=HH_58qH-pvNxEwPXpuza4HSQmnVva7lyJZFYa9i3Hhc%3D%3A1792645371"

实测输出：

hello cloudreve 4.19.1 test file

（5）落盘验证。 确认实体按文件名规则落盘：

find /opt/cloudreve/data/uploads -type f

实测输出：

/opt/cloudreve/data/uploads/1/1_QuYtpPzI_test-upload.txt

文件名 1_QuYtpPzI_test-upload.txt = {uid}(1)_{randomkey8}(QuYtpPzI)_{originname}(test-upload.txt)，与存储策略规则一致，闭环完成。

五、安装方案 B：离线包部署（内网隔离场景）

适用于服务器无法访问公网（内网隔离、安全域）的场景：在一台可上网的机器上下载安装包，校验后传入内网服务器安装。

5.1 在下载机获取并校验安装包

wget "https://github.com/cloudreve/cloudreve/releases/download/4.19.1/cloudreve_4.19.1_linux_amd64.tar.gz"
md5sum cloudreve_4.19.1_linux_amd64.tar.gz

实测输出：

9ff6345ddf1f4cdd641e41f5a6782c87  cloudreve_4.19.1_linux_amd64.tar.gz

5.2 传入服务器并校验

用任意安全通道（U 盘、scp、内部文件系统）将安装包复制到服务器，如：

scp cloudreve_4.19.1_linux_amd64.tar.gz root@<服务器IP>:/opt/cloudreve/

在服务器上复核 MD5，确保传输无损：

md5sum /opt/cloudreve/cloudreve_4.19.1_linux_amd64.tar.gz

实测输出（与下载机一致才可继续）：

9ff6345ddf1f4cdd641e41f5a6782c87  cloudreve_4.19.1_linux_amd64.tar.gz

5.3 安装与启动

cd /opt/cloudreve
tar -zxvf cloudreve_4.19.1_linux_amd64.tar.gz
chmod +x cloudreve
./cloudreve --help | head -3

实测输出：

Self-hosted file management and sharing system, supports multiple storage providers.
Complete documentation is available at https://docs.cloudreve.org/

Usage:
  cloudreve [flags]

后续的首次初始化（4.3 节）、管理员注册（4.4 节）、systemd 托管（4.5 节）与验证（4.6–4.7 节）步骤与方案 A 完全一致，不再重复。离线方案唯一的外部依赖差异：初始化本身不需要网络，但离线服务器上的后续运维（如对接 OneDrive OAuth、发送 SMTP 邮件、在线更新检查）需按内网出口策略放行相应域名。

六、方案对比与选择建议

维度方案 A：在线部署方案 B：离线包部署
是否需联网需（首次下载）不需（服务器侧）
版本控制直接取 Releases 最新自主锁定任意版本
完整性保障下载时校验 MD5双机 MD5 核对
适用场景公网服务器、云主机内网隔离、安全域、批量装机
升级方式在线重下新包替换需重新走离线分发流程

选择建议：可联网环境一律方案 A（步骤最少）；内网/受限环境用方案 B，并把「安装包 + MD5」纳入内部制品管理。源码构建方式见官方文档 Building from Source（https://docs.cloudreve.org/overview/build ，2026-10-22 查阅），需要 Go 与 Node.js 工具链，一般部署场景无需采用。

七、配置说明

方案 A/B 共用的关键配置项（首次部署后建议核对）：

配置项位置默认值说明
监听地址data/conf.ini [System] Listen:5212反代部署时改 127.0.0.1:5212
运行角色data/conf.ini [System] Modemaster从机节点改 slave 并配从机参数
会话密钥data/conf.ini [System] SessionSecret自动随机生成更换后所有登录态失效
哈希盐值data/conf.ini [System] HashIDSalt{HashIDSalt} 占位建议手动设为随机值（见 10.5）
数据库data/conf.ini [Database] 段默认 SQLite换 MySQL/PostgreSQL 见《Cloudreve 配置参数详解》
业务设置Web 管理面板（数据库内）出厂默认v4 大多数参数不在 conf.ini，在管理面板中调整

数据目录布局（实测）：

/opt/cloudreve/
├── cloudreve            # 主程序
├── cloudreve_4.19.1_linux_amd64.tar.gz   # 安装包（可清理）
└── data/
    ├── conf.ini         # 配置文件
    ├── cloudreve.db     # SQLite 数据库（换外部数据库后可移除）
    ├── cache_persist.bin # 持久化缓存
    └── uploads/         # 本机存储策略默认根目录（1/ 为 uid=1 管理员）

💡 说明：v4 与 v3 的配置哲学不同——v3 的 conf.ini 承载数十个业务参数，v4 精简为运行时骨架参数，业务参数（站点名、注册开关、用户组配额、存储策略等）迁移到数据库 + Web 管理面板，改面板即时生效无需重启。逐参数详解见《Cloudreve 配置参数详解》。

八、升级、降级与多版本管理

8.1 小版本升级（实测：4.18.0 → 4.19.1）

v4 升级流程 = 替换二进制 + 重启，数据库 schema 由新版自动迁移。以下为实测全过程（升级前 4.18.0 实例独立运行于 /opt/upgrade-test，其数据目录含 4.18.0 初始化的 SQLite 库）：

（1）确认旧版本运行。 旧版启动日志实测：

   V4.18.0  Commit #0bb0ab8  Pro=false
[Info]   ... Connect to SQLite database "/opt/upgrade-test/data/cloudreve.db".

（2）替换二进制（保留旧版备份）。

cd /opt/upgrade-test
cp /opt/cloudreve/cloudreve ./cloudreve-4191
mv cloudreve cloudreve-4180-bak
mv cloudreve-4191 cloudreve
chmod +x cloudreve

（3）以新版启动。

./cloudreve -c /opt/upgrade-test/data/conf.ini

实测输出（迁移日志节选）：

   V4.19.1  Commit #a8becb9  Pro=false
[Info]   2026-10-22 04:13:23 [...] Start initializing database schema...
[Info]   2026-10-22 04:13:23 [...] Creating basic table schema...
[Info]   2026-10-22 04:13:23 [...] Insert default settings...
[Info]   2026-10-22 04:13:23 [...] Default storage policy (ID=1) already exists, skip migrating.
[Info]   2026-10-22 04:13:23 [...] Default admin group (ID=1) already exists, skip migrating.
[Info]   2026-10-22 04:13:23 [...] Default user group (ID=2) already exists, skip migrating.
[Info]   2026-10-22 04:13:23 [...] Default anonymous group (ID=3) already exists, skip migrating.
[Info]   2026-10-22 04:13:23 [...] Listening to ":5212"

already exists, skip migrating 表明新版识别既有数据并跳过重建，既有数据保留。生产升级前务必先备份数据库与 uploads 目录。

⚠️ 注意：v3 → v4 是跨大版本迁移，不是替换二进制即可完成，需使用官方迁移命令 cloudreve migrate --v3-conf <v3配置文件路径>（实测 cloudreve migrate --help 回显含 --v3-conf string Path to the v3 config file 与 --force-reset 参数），并提前完整演练。详见《Cloudreve 常用 CLI 命令详解》。

8.2 降级注意

数据库 schema 迁移是前向单向的（新版首次启动即改表结构），回退旧版二进制可能因 schema 不兼容无法启动。因此降级正确姿势是「恢复升级前的数据库备份 + 旧版二进制」，而非直接换回旧程序。升级前备份清单：data/conf.ini、data/cloudreve.db（或外部数据库 dump）、data/uploads/。

8.3 多版本共存

不同版本目录隔离即可并存（本文升级实测即用此法）：每个版本独立目录（含各自的 data/），用 -c 指定各自配置、Listen 错开端口。管理上建议保留旧版二进制备份（如 cloudreve-4180-bak），升级窗口期结束再清理。

九、防火墙与安全基线

服务器启用防火墙时放行 5212（或自定义端口）：

ufw allow 5212/tcp

⚠️ 注意：对外服务建议在反代层启用 HTTPS（Nginx/Caddy + 证书），Cloudreve 本身不内置 TLS；SessionSecret 与 HashIDSalt 属于敏感值，泄露前者会导致登录态可被伪造，泄露后者会使对外 ID 可被推测，两者都应设置为长随机串并纳入配置备份。

十、常见问题（FAQ）

Q1：GitHub 下载极慢或超时怎么办？ 实测境内直连 GitHub 仅约 42 KB/s（wget 回显 9% 42.7K 18m41s，估计需 18 分钟）。处理方式按优先级：① 让 wget 走 HTTP 代理：wget -O cloudreve_4.19.1_linux_amd64.tar.gz -x http://<代理地址>:<端口> "https://github.com/..."（-O 显式指定文件名，避免 -x 代理模式按 URL 建目录树）；② 从国内镜像加速站下载同名安装包后照常校验 MD5；③ 用方案 B，在通畅的下载机取包再传入。

Q2：启动报 bind: address already in use？ 实测报错全文：

[Error]  2026-10-22 04:13:23 [...] Failed to start server: failed to listen to ":5212": listen tcp :5212: bind: address already in use

先用 ss -ltnp | grep 5212 找出占用进程；确认无冲突需求后修改 conf.ini 的 Listen（实测改为 :5213 后启动回显 Listening to ":5213"，curl http://127.0.0.1:5213/ 返回 200）。若确属旧实例残留，systemctl stop cloudreve 后再启动。

Q3：systemctl start 后手动 kill 进程为何不自动重启？ 实测以 kill（SIGTERM）结束进程后，systemctl status 显示：

Active: inactive (dead) since Thu 2026-10-22 04:14:31 UTC; 17s ago
Process: 3107 ExecStart=/opt/cloudreve/cloudreve (code=exited, status=0/SUCCESS)

进程收到 SIGTERM 后优雅退出，退出码 0，而本文 unit 配置 Restart=on-failure 只对「非正常退出」重启——这是预期行为而非故障。需要「无论如何都拉起」可将配置改为 Restart=always。生产环境停服务请用 systemctl stop，不要直接 kill。

Q4：v4 找不到初始管理员密码？ v4 不在日志打印管理员密码（v3 行为），第一个注册账号即管理员。若需脚本化确认账号身份，可登录后查返回的用户组：实测登录回显 "group":{"name":"Admin"...}。调试接口时可临时把 conf.ini 的 Debug 改为 true 重启，Gin 会输出完整路由表（实测 [GIN-debug] POST /api/v4/session/token --> ...controllers.UserIssueToken 等 170+ 条），便于定位端点；排查完记得改回 false。

Q5：HashIDSalt = {HashIDSalt} 是损坏了吗？ 不是。自动生成的 conf.ini 中该项就是占位符（实测原文 HashIDSalt = {HashIDSalt}），服务可正常运行，但建议部署完成后手动替换为长随机串（实测生成 40 位随机串 VzHf3UToNJyKGUtKCpafkph0HFoNqRN5daa68AIE 写入后 systemctl restart cloudreve，服务 active、Web 返回 200）。⚠️ 更换后旧的签名直链与分享链接会失效。

Q6：上传接口报 unknown uri / unknown file system？ v4 的文件 URI 必须带 cloudreve://my/ 前缀（my 代指当前用户根目录）。实测错误对照：uri=/test-upload.txt → {"code":40001,"msg":"unknown uri"}；uri=cloudreve://1/ → unknown file system "1"；uri=cloudreve://my/ → 正常。接口调用一律使用 cloudreve://my/<路径> 形态。

十一、卸载与清理

完整卸载（含数据，不可逆，先确认备份）：

systemctl stop cloudreve
systemctl disable cloudreve
rm -f /etc/systemd/system/cloudreve.service
systemctl daemon-reload
rm -rf /opt/cloudreve

实测回显（disable）：

Removed "/etc/systemd/system/multi-user.target.wants/cloudreve.service".

验证清理结果：

systemctl status cloudreve --no-pager 2>&1 | head -2
ls /opt/cloudreve 2>&1

实测输出：

Unit cloudreve.service could not be found.
ls: cannot access '/opt/cloudreve': No such file or directory

若使用外部数据库，还需另行删除对应库（SQLite 部署则随 /opt/cloudreve 目录一并移除）。

十二、参考链接

  1. 官方快速开始文档：https://docs.cloudreve.org/overview/quickstart （首个注册账号即管理员的依据，2026-10-22 查阅）
  2. 官方部署文档：https://docs.cloudreve.org/overview/deploy/
  3. GitHub Releases（版本下载）：https://github.com/cloudreve/cloudreve/releases （2026-10-22 实查最新稳定版 4.19.1）
  4. 官方构建文档（源码方式）：https://docs.cloudreve.org/overview/build
  5. 站内关联文档：《Cloudreve 介绍与选型指南》、《Cloudreve 配置参数详解》、《Cloudreve 常用 CLI 命令详解》