第8章 Cloudreve 配置指南
配置 Cloudreve 的配置分为两部分：程序运行所需的核心配置存储在配置文件中，而其他应用层面的配置则保存在数据库里。本章主要介绍配置文件的结构。
Cloudreve 默认使用 data/conf.ini 作为配置文件。启动时，你可以通过命令行参数指定配置文件路径： ```bash ./cloudreve -c /path/to/conf.ini ```
配置文件结构 Cloudreve 的配置文件结构如下： ```ini [System] ; 运行模式，可选值：master/slave Mode = master ; HTTP 监听端口，默认 5212 Listen = :5212 ; 是否启用 Debug 模式，默认 false Debug = false ; 用于获取客户端 IP 的 Header，默认为空。如果该 Header 包含由逗号分隔的多个 IP，Cloudreve 将使用第一个作为客户端 IP ; 对于反向代理后的部署，可以设置为 X-Forwarded-For。但请注意，由于存在 XFF 注入风险，仅在确认可信时使用 ProxyHeader = ; 安全退出时的最大缓冲时间，默认 0 表示无限制 GracePeriod = 0 ; 日志级别，可选值：debug/info/warning/error，默认 info LogLevel = info ; pprof 监听地址，例如 "localhost:6060"。留空则禁用。详见 https://pkg.go.dev/net/http/pprof Pprof =
; SSL 相关 [SSL] ; SSL 监听端口，默认 443 Listen = :443 ; 证书路径，默认为空 CertPath = ; 私钥路径，默认为空 KeyPath =
; 启用 Unix Socket 监听 [UnixSocket] ; Unix Socket 监听路径，默认为空 Listen = /run/cloudreve/cloudreve.sock ; 设置生成的 socket 文件权限，默认为空 Perm = 0666
; 数据库相关，如果仅使用内置的 SQLite 数据库，可以删除此部分 [Database] ; 数据库类型，当前支持 sqlite/mysql/postgres/mariadb，默认 sqlite Type = sqlite ; 数据库端口，默认 3306 Port = 3306 ; 用户名，默认为空 User = ; 密码，默认为空 Password = ; 数据库地址，默认为空 Host = 127.0.0.1 ; 数据库名称，默认为空 Name = cloudreve ; 连接字符集，默认 utf8mb4 Charset = utf8mb4 ; SQLite 数据库文件路径，默认 data/cloudreve.db DBFile = cloudreve.db ; 是否使用 Unix Socket 连接数据库，默认 false。若启用，请在 Host 中指定 Unix Socket 路径 UnixSocket = false ; 数据库连接字符串。若设置此值，其他数据库配置将被忽略，但仍需指定 Type。 ; 例如 MySQL: root:123456@tcp(127.0.0.1:3306)/cloudreve?charset=utf8mb4&parseTime=True&loc=Local DatabaseURL =
; Slave 模式配置 [Slave] ; 通信密钥，默认为空 Secret = ; 回调请求超时时间（秒），默认 20 CallbackTimeout = 20 ; 签名有效期（秒），默认 600 SignatureTTL = 600
; CORS 配置 [CORS] AllowOrigins = * AllowMethods = OPTIONS,GET,POST AllowHeaders = * AllowCredentials = false
; Redis 相关 [Redis] ; 连接类型，默认 tcp Network = tcp ; 服务器地址，默认为空，表示未启用 Server = 127.0.0.1:6379 ; 密码，默认为空 Password = ; 数据库索引，默认 0 DB = 0 ; 用户名，默认为空 User = ; 是否使用 TLS 连接 Redis，默认 false UseTLS = false ; 是否跳过 TLS 验证，默认 false TLSSkipVerify = false
; Slave 配置覆盖 [OptionOverwrite] ; 直接使用 `配置项 = 值` 格式进行覆盖 queue_slave_worker_num = 50 ```
提示：如果配置值中包含 # 或 ;，其后的字符将被视为注释而不生效。你可以使用反引号包裹配置值，例如： ```ini Password = `#123456` ```
通过环境变量覆盖配置 任何配置文件中的值都可以通过以 CR_CONF_ 为前缀的环境变量进行覆盖。这在容器化部署等不方便挂载配置文件的场景中非常有用。
默认格式为 CR_CONF_
TOML 安全分隔符 某些部署平台会将环境变量名中的 . 解释为嵌套键路径（例如 Fly.io 的 fly.toml [env] 部分，或旧版本的 Docker Compose YAML 变体）。在这些平台上，点号格式要么被拒绝，要么在到达 Cloudreve 进程之前被静默丢弃。
为了解决这个问题，Cloudreve 也接受双下划线 __ 作为等效分隔符： ```toml # fly.toml [env] CR_CONF_System__Listen = ":8080" CR_CONF_Database__Type = "mysql" ``` CR_CONF_System.Listen 和 CR_CONF_System__Listen 都解析为相同的设置。格式错误的条目（没有节/键分隔符，或节/键为空）会被记录为警告并跳过，而不会导致启动失败。
如果使用 Docker 部署，配置文件位于容器内的 /cloudreve/data/conf.ini。你可以在宿主机的对应挂载目录中找到该文件。如果不确定具体路径，请在主机上执行以下命令： ```bash ## 列出容器并找到 Cloudreve 容器 ID docker container ls | grep cloudreve
# 输出示例： # aaronliu@AarondeMacBook-Pro ~ % docker container ls | grep cloudreve # 43acd4c97d4b cloudreve/cloudreve:latest "sh ./entrypoint.sh" About a minute ago Up About a minute 443/tcp, 0.0.0.0:5212->5212/tcp, :::5212->5212/tcp cloudreve
# 查看容器挂载信息
docker inspect --format="{{.Mounts}}"
# 例如： docker inspect --format="{{.Mounts}}" 43acd4c97d4b
# 输出示例： # aaronliu@AarondeMacBook-Pro ~ % docker inspect --format="{{.Mounts}}" 43acd4c97d4b # [{volume cloudreve_backend_data /var/lib/docker/volumes/cloudreve_backend_data/_data /cloudreve/data local rw true }] ``` 在上述示例中，你可以在宿主机的 /var/lib/docker/volumes/cloudreve_backend_data/_data 目录下找到配置文件。修改配置文件后，需要重启容器才能生效。
Debug 模式 将 Debug 设置为 true 即可启用 Debug 模式。启用后，Cloudreve 会记录更多日志信息以帮助你排查问题： ```ini [System] Mode = master Listen = :5212 Debug = true ``` 在 Debug 模式下： - 日志级别强制设为 debug，忽略配置文件中的设置； - 启动时打印所有可用路由； - 所有数据库查询都会打印详细日志。注意，这可能包含一些敏感信息。 - 向用户显示的错误消息将包含原始错误信息。
Slave 节点配置覆盖 Slave 节点可以覆盖 Master 的配置。你可以通过 Slave 节点配置文件中的 [OptionOverwrite] 部分来覆盖 Master 的配置。例如，修改 Slave 任务队列配置： ```ini [OptionOverwrite] ; 最大工作线程数 queue_slave_worker_num = 15 ; 最大执行时间（秒） queue_slave_max_execution = 2800 ; 重试退避因子 queue_slave_backoff_factor = 4 ; 最大重试等待时间（秒） queue_slave_backoff_max_duration = 3600 ; 最大重试次数 queue_slave_max_retry = 5 ; 重试延迟（秒） queue_slave_retry_delay = 5 ```
