Cloudreve 配置参数详解

目标：以 Cloudreve 4.19.1（当前最新稳定版）实测环境为基准，讲清 v4 的三层配置体系——conf.ini 文件参数、数据库内设置键（管理面板对应项）、用户组与存储策略参数——的查看方式、修改通道与逐项含义，并给出可直接落地的生产配置模板。全部默认值与回显均在 Ubuntu 22.04.5 LTS 实测取得，官方文档溯源日期 2026-10-22。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS x86_64
• Cloudreve 版本：4.19.1（Commit #a8becb9，Pro=false 社区版，2026-10-22 GitHub Releases 最新稳定版）
• 部署形态：官方二进制 + systemd 托管（/opt/cloudreve，服务名 cloudreve，安装过程见《Ubuntu 22.04 安装 Cloudreve 指南》）
• 数据库：默认 SQLite（/opt/cloudreve/data/cloudreve.db，502,784 字节实测）
• 配置文件：/opt/cloudreve/data/conf.ini（首次启动自动生成）
• 设置键规模：settings 表实测 208 个键（SELECT COUNT(*) FROM settings → 208）
• 管理员账号：admin@quzuo.net / q1w2e3r4

二、前置条件

阅读与操作本章需要：

1. 一台已按《Ubuntu 22.04 安装 Cloudreve 指南》完成部署的 Cloudreve 4.x 实例；
2. 服务器 root 或 sudo 权限（修改 conf.ini 与重启服务）；
3. 管理员账号（修改管理面板参数）；
4. 服务器上安装 sqlite3 客户端（仅「直查数据库取证」一节需要，不影响生产）：

apt-get install -y sqlite3

实测输出（节选）：

Setting up sqlite3 (3.37.2-2ubuntu0.8) ...

三、参数查看与修改方式

3.1 三层配置体系总览

v4 与 v3 的最大差异在于配置体系重构：v3 把几乎所有参数塞在一个 conf.ini 里，v4 拆成三层。先给全景，再逐层展开：

💡 说明：① 是「程序怎么跑起来」的最小集合，② ③ 是「业务怎么运转」的主体。这解释了 v4 首次生成的 conf.ini 只有 5 行参数——其余几百项都在数据库里，通过管理面板调整，改面板不需要重启服务。

3.2 conf.ini：查看与修改（重启生效）

查看当前生效的 conf.ini：

cat /opt/cloudreve/data/conf.ini

实测输出：

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

（HashIDSalt 原始自动生成值为 {HashIDSalt} 占位符，本环境已按第四章 4.1 节建议替换为随机串。）

修改流程统一为「编辑 → 重启 → 验证」。以修改监听端口为实测样例：

sed -i 's/Listen = :5212/Listen = :5213/' /opt/cloudreve/data/conf.ini
systemctl restart cloudreve
sleep 5
curl -s -o /dev/null -w "5213 -> %{http_code}\n" http://127.0.0.1:5213/

实测输出：

5213 -> 200

改回默认端口：

sed -i 's/Listen = :5213/Listen = :5212/' /opt/cloudreve/data/conf.ini
systemctl restart cloudreve

3.3 管理面板与 API：修改业务设置（即时生效）

Web 管理面板（管理员登录 → 左侧「管理面板」→ 各设置分页）保存即生效。接口级对应端点为 PATCH /api/v4/admin/settings（读取为 POST /api/v4/admin/settings）。以修改站点名称为实测样例：

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 PATCH http://127.0.0.1:5212/api/v4/admin/settings \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"settings":{"siteName":"Quzuo 网盘"}}'

实测输出：

{"code":0,"data":{"siteName":"Quzuo 网盘"},"msg":""}

不改服务、直接请求公开配置接口验证生效：

curl -s http://127.0.0.1:5212/api/v4/site/config/basic \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['title'])"

实测输出：

Quzuo 网盘

公开 API 已即时返回新站点名，确认「面板/接口改设置 → 无需重启即生效」。改回原值：

curl -s -X PATCH http://127.0.0.1:5212/api/v4/admin/settings \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"settings":{"siteName":"Cloudreve"}}'

实测输出：

{"code":0,"data":{"siteName":"Cloudreve"},"msg":""}

⚠️ 注意：请求体的设置键必须包在 "settings" 对象里。直接传扁平键（如 {"siteName":"..."}）会报 {"code":40001,"msg":"Settings cannot be empty"}（实测）。

3.4 直查数据库：设置键的取证方式

排查「面板上改了但行为不符」时，可直查 settings 表确认实际落库值（只读操作，不影响服务）：

sqlite3 /opt/cloudreve/data/cloudreve.db "SELECT name,value FROM settings WHERE name IN ('siteName','siteURL','register_enabled');"

实测输出：

register_enabled|1
siteName|Cloudreve
siteURL|http://localhost:5212

全量键名清单导出：

sqlite3 /opt/cloudreve/data/cloudreve.db "SELECT DISTINCT name FROM settings ORDER BY name;" | wc -l

实测输出：

208

⚠️ 注意：直接 UPDATE settings 表不受支持（绕过校验与缓存刷新），仅用于只读取证；修改一律走管理面板或 PATCH 接口。

四、conf.ini 参数详解（第①层）

4.1 [System] 段

首次启动自动生成该段 5 个参数（默认值均为实测回显）：

SessionSecret 与 HashIDSalt 的加固实测（生成 40 位随机串并写入）：

NEW=$(head -c 32 /dev/urandom | base64 | tr -d '=+/\n')
sed -i "s|HashIDSalt = {HashIDSalt}|HashIDSalt = $NEW|" /opt/cloudreve/data/conf.ini
grep HashIDSalt /opt/cloudreve/data/conf.ini
systemctl restart cloudreve && sleep 5 && systemctl is-active cloudreve

实测输出：

HashIDSalt = VzHf3UToNJyKGUtKCpafkph0HFoNqRN5daa68AIE
active

4.2 [Database] 段

不配置该段时默认使用 SQLite（官方部署文档明确，2026-10-22 查阅）。可选参数全表（官方文档口径）：

外接 MySQL 的官方示例（节选自官方 Supervisor 部署文档，2026-10-22 查阅）：

[Database]
Type = mysql
Port = 3306
User = cloudreve
Password = cloudreve
Host = 127.0.0.1
Name = cloudreve

连接失败时的真实报错（本环境实测：配置指向不存在的 MySQL 时启动直接 panic）：

[Panic]  2026-10-22 04:20:57 [...] Fatal error in dependency initialization: failed to migrate database: Failed creating schema resources: mysql: querying mysql version dial tcp 127.0.0.1:3306: connect: connection refused
panic: Fatal error in dependency initialization: failed to migrate database: Failed creating schema resources: mysql: querying mysql version dial tcp 127.0.0.1:3306: connect: connection refused

⚠️ 注意：数据库参数错误会让服务启动失败（进程退出），排查先看 journalctl -u cloudreve 或前台运行的报错段。首次以外接数据库启动时，Cloudreve 自动建表并写入默认设置；SQLite → MySQL 迁移需借助备份恢复或官方迁移工具，不能只改配置直接换库（已有数据不会自动搬移）。

4.3 [Redis] 段

Redis 非必需（官方文档：不配置时使用内存缓存，正常退出时持久化到 data/cache_persist.bin，2026-10-22 查阅）。参数全表（官方文档口径）：

官方示例（节选自官方部署文档，2026-10-22 查阅）：

[Redis]
Server = 127.0.0.1:6379
Password = your_redis_password
DB = 0

多 worker 并发、多节点部署建议启用 Redis，把签名直链校验、会话等热点缓存外移。

五、数据库设置参数详解（第②层：settings 表 208 键）

5.1 设置域总览

208 个键按前缀/语义可归为 14 个设置域（键名清单由 SELECT DISTINCT name FROM settings 实测导出，官方在管理面板中按域分页展示）。总览：

5.2 关键键实测值与调参要点

站点信息域（实测当前值）：

siteName|Cloudreve
siteTitle|Cloud storage for everyone
siteDes|Cloudreve
siteURL|http://localhost:5212

要点：siteName 决定公开 API 的 title 字段（3.3 节实测：PATCH siteName 后 GET /api/v4/site/config/basic 的 title 立即变为新值）；siteURL 决定签名直链的域名前缀——生产必须改为公网可达地址，否则生成的直链指向 localhost 外部无法访问（本文 4.19.1 默认安装生成的直链即 http://localhost:5212/...，实测现象与该设置吻合）。

注册与认证域（实测当前值）：

register_enabled|1
authn_enabled|1

要点：register_enabled=1 允许开放注册（B1 安装指南的「首个注册账号即管理员」依赖该开关开启；若生产想关闭注册，在面板置 0 或 PATCH 同名键）。ban_time 控制登录失败封禁时长。

令牌有效期域（实测当前值）：

sqlite3 /opt/cloudreve/data/cloudreve.db "SELECT name,value FROM settings WHERE name LIKE '%token_ttl';"

实测输出：

access_token_ttl|3600
refresh_token_ttl|1209600

要点：访问令牌 3600 秒（1 小时）、刷新令牌 1209600 秒（14 天），与《Ubuntu 22.04 安装 Cloudreve 指南》登录实测回显的 access_expires/refresh_expires 完全吻合，面板中可调。

队列域：5 类队列（io_intense / media_meta / recycle / remote_download / thumb）各有 6 个键（worker 数、重试、退避、最大执行时长），与首次启动日志实测的 worker 数对应（MediaMetadataQueue 30、EntityRecycleQueue 5、IoIntenseQueue 30、RemoteDownloadQueue 5、ThumbQueue 15）。批量上传/大量缩略图场景优先调大对应 _worker_num。

缩略图域：内置生成器默认开启（thumb_builtin_enabled）， ffmpeg/vips/libraw/libreoffice 四类外部生成器各有 enabled/exts/max_size/path 四件套，装了对应组件后在面板启用即可（官方 Docker 镜像即内置这些组件；二进制部署需自装依赖）。

5.3 修改示例：关闭开放注册

以「生产环境关闭自助注册」为例给出完整 PATCH 实测（先改 1 再改回 0，观察落库）：

curl -s -X PATCH http://127.0.0.1:5212/api/v4/admin/settings \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"settings":{"register_enabled":"0"}}'
sqlite3 /opt/cloudreve/data/cloudreve.db "SELECT value FROM settings WHERE name='register_enabled';"

实测输出：

{"code":0,"data":{"register_enabled":"0"},"msg":""}
0

恢复开放：

curl -s -X PATCH http://127.0.0.1:5212/api/v4/admin/settings \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"settings":{"register_enabled":"1"}}'

实测输出：

{"code":0,"data":{"register_enabled":"1"},"msg":""}

六、用户组与存储策略参数（第③层）

6.1 用户组参数（groups 表）

用户组决定「谁能做什么、能用多少」，实测默认三组：

sqlite3 /opt/cloudreve/data/cloudreve.db "SELECT id,name,max_storage FROM groups;"

实测输出：

1|Admin|1099511627776
2|User|1073741824
3|Anonymous|

解读：Admin 组配额 1099511627776 字节（1 TB）、User 组 1073741824 字节（1 GB）、Anonymous（匿名组）无配额（不可上传）。组的能力开关（是否可分享、WebDAV 读写、外链打包等）以权限位存储（实测 Admin 组权限位十六进制 FD1A01），在管理面板「用户组」中以勾选项呈现，无需手工算位。

组的增改走管理面板或 API（实测管理端点：PUT /api/v4/admin/group 创建、PUT /api/v4/admin/group/:id 更新、POST /api/v4/admin/group 列表查询）。

6.2 存储策略参数（storage_policies 表）

实测默认策略全文：

sqlite3 /opt/cloudreve/data/cloudreve.db "SELECT id,name,type,dir_name_rule,file_name_rule FROM storage_policies;"
sqlite3 /opt/cloudreve/data/cloudreve.db "SELECT settings FROM storage_policies WHERE id=1;"

实测输出：

1|Default storage policy|local|/opt/cloudreve/data/uploads/{uid}/{path}|{uid}_{randomkey8}_{originname}
{"token":"","file_type":null,"chunk_size":26214400,"s3_path_style":false,"pre_allocate":true,"native_media_processing":false}

逐项说明：

策略管理端点实测（列表）：POST /api/v4/admin/policy（body {"page":1,"page_size":10}），创建/更新为 PUT /api/v4/admin/policy[/:id]。新增 S3/云存储策略建议在 Web 管理面板向导中完成（含直传参数与 CORS 生成）。

6.3 从机节点参数（nodes 表）

主从架构下从机以记录形式存于 nodes 表（管理端点 PUT /api/v4/admin/node 创建、POST /api/v4/admin/node/test 连通性测试）。从机节点服务器侧的 conf.ini 需设 Mode = slave 并配置与主节点一致的从机通信密钥；这是横向扩展存储与离线下载带宽的路径，单机部署无需配置。

七、生产配置模板

7.1 模板一：单机轻量（SQLite，≤2 GB 内存，个人/小团队）

适用：单台 1–2 GB 内存 VPS 或家用 NAS，10 人以内，无高并发诉求。conf.ini 保持自动生成状态即可，仅建议调整：

[System]
Debug = false
Mode = master
Listen = 127.0.0.1:5212
SessionSecret = <保持自动生成的 64 位随机串>
HashIDSalt = <替换为 32+ 位随机串>

配套动作：反代启用 HTTPS；面板中把 siteURL 改为公网域名；不需要注册则 register_enabled=0。SQLite 读写锁在低并发下完全够用。

7.2 模板二：生产推荐（MySQL/PostgreSQL + Redis，8 GB+ 内存，中大型）

适用：8 GB+ 内存、NVMe SSD、数十人以上团队或对外服务（官方文档明确：SQLite 不支持高并发，生产环境强烈建议外接数据库，2026-10-22 查阅）。conf.ini 示例（值按实际环境替换）：

[System]
Debug = false
Mode = master
Listen = 127.0.0.1:5212
SessionSecret = <64 位随机串>
HashIDSalt = <32+ 位随机串>

[Database]
Type = mysql
Host = 127.0.0.1
Port = 3306
User = cloudreve
Password = <数据库密码>
Name = cloudreve

[Redis]
Server = 127.0.0.1:6379
Password = <Redis 密码>
DB = 0

配套动作：数据库与 Redis 与应用同机时用 Unix Socket/本机地址并加防火墙；为 cloudreve 库用户授权 CREATE/ALTER/INSERT/SELECT/UPDATE/DELETE（首次启动要建表）；面板中调大上传/缩略图队列 worker；启用全文搜索需另部署 Meilisearch/Tika 并在面板 fts_* 域填写端点。

7.3 模板三：主从扩展（多节点分流存储/离线下载）

适用：单出口带宽不足或容量需跨机扩展。主节点按模板二部署；每台从机以 Mode = slave 运行，Listen 对主节点可达；在主节点管理面板「节点」中添加从机（API/通信密钥来自从机侧配置）并执行连通性测试（POST /api/v4/admin/node/test）。从机可单独作为存储策略或离线下载节点挂载。

八、常见问题（FAQ）

Q1：改了 conf.ini 不生效？ conf.ini 是第①层文件参数，必须 systemctl restart cloudreve 后生效（3.2 节实测流程）；管理面板改的是第②层数据库设置，两者不要混淆。判断某个行为属于哪一层：站点名/注册/邮件/队列类去面板，监听/角色/数据库连接类在 conf.ini。

Q2：服务起不来，日志报 Fatal error in dependency initialization？ 依赖初始化失败，常见于数据库连接参数错误（4.2 节实测报错：... dial tcp 127.0.0.1:3306: connect: connection refused 后进程 panic）。核对 [Database] 段五要素（Type/Host/Port/User/Password/Name），确认数据库实例可达、账号有建表权限，再启动。

Q3：HashIDSalt = {HashIDSalt} 需要改吗？ 建议改。这是自动生成的占位符，不影响功能，但生产环境应替换为长随机串（4.1 节有实测加固命令）。⚠️ 更换后旧签名直链会失效。

Q4：直链 URL 是 http://localhost:5212/...，外部打不开？ 直链域名取自设置键 siteURL（默认 http://localhost:5212，5.2 节实测）。在管理面板把 siteURL 改为公网地址（如 https://pan.example.com）后新生成的直链即为公网可达。

Q5：如何查某个设置当前实际值？ 优先管理面板；需要精确取证时用 sqlite3 只读查询 settings 表（3.4 节实测方法），键名清单用 SELECT DISTINCT name FROM settings 导出，共 208 键。

Q6：PATCH 接口报 Settings cannot be empty？ 请求体格式问题：设置键值必须包在 "settings" 对象内（3.3 节实测对照：{"settings":{"siteName":"..."}} 成功，{"siteName":"..."} 报错）。

九、参考链接

1. 官方部署文档（数据库/Redis 参数来源）：https://docs.cloudreve.org/en/overview/deploy/supervisor （2026-10-22 查阅）
2. 官方部署总览（SQLite 高并发限制与 Redis 说明）：https://docs.cloudreve.org/en/overview/deploy （2026-10-22 查阅）
3. 站内关联文档：《Cloudreve 介绍与选型指南》、《Ubuntu 22.04 安装 Cloudreve 指南》、《Cloudreve 常用 CLI 命令详解》