Slave Node {#slave-node} #
You can run Cloudreve in slave mode on other servers. The Cloudreve master can communicate with it, distribute tasks to slave nodes for execution, or use slave nodes as file storage nodes.
Configure a New Node {#configure-new-node} #
-
Go to
Admin Dashboard->Nodes->New nodeto get the slave configuration file shown in the popup window. -
On the server you want to use as a slave node, create a new configuration file
conf.iniand paste the content you got from the popup window. You can modify settings like the listening port according to your needs.# Create directory mkdir ~/cloudreve_slave cd ~/cloudreve_slave # Create data directory for configuration files mkdir ~/cloudreve_slave/data # Create configuration file nano ~/cloudreve_slave/conf.ini -
Copy the Cloudreve executable of the same version as the master node to
~/cloudreve_slaveand start it:./cloudreve::: tip You can also use the
-cparameter to specify the configuration file path:./cloudreve -c data/conf.ini:::
-
Return to the form for creating a new node in the admin panel, fill in the node's name and address, and test the node communication. If the communication test fails, you can save the node first and troubleshoot according to the FAQ.
-
Refer to Deploy Cloudreve with Process Supervisor to deploy the Cloudreve slave node with process supervision.
-
Refer to Configure Reverse Proxy to configure a reverse proxy for the slave node.
Enable Node Features {#enable-node-features} #
After adding a node, you can go to the node settings page to enable various features for the node.
Extract/Create Archive Files {#file-compression-decompression} #
When enabled, tasks for online file compression or decompression will be assigned to this node. File downloading, processing, and transfer will be performed on this node.
- When creating archive files, the node needs to compress files to a temporary directory and then transfer them. The required storage space equals the size of the archive files.
- When extracting archive files:
- For
zipformat archives, the complete archive needs to be downloaded to the temporary directory before decompression begins. The required storage space equals the size of the archive. - For other archive formats, no files will be written to disk during the entire decompression process.
- For
Remote Download {#remote-download} #
Please refer to Remote Download.
Storage Files {#storage-files} #
Please refer to Slave Storage.
Load Balancing #
If users don't explicitly select a node when creating tasks and multiple nodes are available, Cloudreve will use a weighted round-robin strategy to select a node. You can set the weight value in Node Settings -> Load balancing weight. For example: if Node A has a weight of 3 and Node B has a weight of 2, then in every 5 task requests, Node A will be selected 3 times and Node B will be selected 2 times.
Upstream Compatibility {#upstream-compatibility} #
This fork shares the same slave wire protocol as upstream Cloudreve (open-source edition): the same /api/v4/slave/* routes, HMAC request signing, and session payload format. As a result:
- An upstream slave node can serve this fork's master, and this fork's slave can serve an upstream master, as long as both sides speak the same protocol version. A version-number mismatch now produces a warning on the node communication test instead of a failure; the node remains fully operational.
- Compatibility with upstream Pro slave internals is best-effort, since Pro is closed-source.
Migrating an upstream deployment {#migrating-upstream-deployment} #
Existing files stored on upstream slave nodes remain accessible after migrating to this fork, because entity.source records store the physical blob path verbatim and node/policies records are schema-compatible:
- Back up the upstream database and the slave node's blob directories first.
- Migrate or reuse the existing database — the
nodes,storage_policiesandentitiesrecords carry over unchanged. Keep each node'sslave_keyand server address the same as before. - For blobs that exist on a node but have no database record (e.g. a partial migration), use the existing Import action (
Admin Dashboard->Files->Import) with the corresponding remote storage policy. It lists files on the node via the slave protocol and creates file records pointing at the existing physical paths — no data is transferred. - To keep new uploads in the original directory layout, adjust the storage policy's
dir_name_rule/file_name_rulenaming templates to match the old scheme.
FAQ {#faq} #
::: details Node communication failed Failed to connect to node: Post "xxx": connect: xxx
Check if the node URL you entered is correct and if the port you're using is open in the firewall.
If the error ends with status code: xxx, it means the node address you entered is not pointing to a Cloudreve slave node, but to another web service, or a WAF firewall has blocked the request.
:::
::: details Node communication failed Successfully connected to slave node, but slave returns: {specific error}
This means the master node can connect to the slave node, but the slave node returned an error. Please troubleshoot based on the {specific error} at the end of the error message.
- If it ends with
invalid sign, the slave node's signature verification failed. Please check:- Whether the
Secretconfiguration under[Slave]in the slave node's configuration file matches theSlave Keyconfiguration for that node in the admin panel. After making them consistent, restart the slave node. - Whether there's a significant time difference between the slave node and the master node. If so, please synchronize the time.
- Whether the
- If it ends with
Master: 4.x.x., Slave: 4.x.x., it means the Cloudreve versions on the slave and master nodes are inconsistent. Please change the slave's Cloudreve to the same version as the master node. On this fork, a version mismatch is reported as a warning instead of a failure — see Upstream Compatibility. - If it ends with
but slave returns: Get "xxx/api/v4/site/ping"orbut slave returns: invalid character '<' looking for beginning of value, it means the slave node cannot communicate with the master node. Please check:- Whether the
Mainsite URL in the master node'sSettings->Basic->Site URLis correct. The slave needs to be able to access this address. - Check the network communication between the slave and master for any firewall blocking.
- Whether the
:::
::: details Task execution fails or partially fails on slave nodes
There are many possible reasons for failures. You can find the specific cause by checking the slave's logs. First, locate the failed task in the master Cloudreve admin dashboard, then search for logs related to this task on the slave using the task's Request ID. Common causes include: task timeouts, network fluctuations, etc.
The default configuration for the slave node's task queue is as follows:
| Configuration Item | Value |
|---|---|
| Worker threads | 15 |
| Max execution time | 86400 seconds |
| Backoff factor | 4 |
| Max backoff time | 3600 seconds |
| Retry delay | 5 seconds |
| Max retry count | 5 |
If you believe the default configuration is causing task failures, please refer to the Slave Node Configuration Override section to modify the configuration.
:::