diff --git a/README.ENG.md b/README.ENG.md new file mode 100644 index 0000000..c028259 --- /dev/null +++ b/README.ENG.md @@ -0,0 +1,28 @@ +--- +description: At present, the document is still being improved! +--- + +# welcome + +## What is Cloudreve? + +Cloudreve allows you to quickly build a public and private network disk system. Cloudreve supports different cloud storage platforms at the bottom layer, and users do not need to care about the physical storage method in actual use. You can use Cloudreve to build a personal network disk, a file sharing system, or a public cloud system for large and small groups. + +## feedback + +If you find any defects during use, or have new requirements proposals, please check the previous documents, [issue](https://github.com/cloudreve/Cloudreve/issues), [discussion community]( https://forum.cloudreve.org/) mentioned. + +If you suspect a bug or a feature proposal, please create an [issue](https://github.com/cloudreve/Cloudreve/issues) to track the problem; + +If you have questions about daily use, please go to [Discussion Community](https://forum.cloudreve.org/) to create a new topic and describe the problem you encounter in detail. + +## connect + +You can join the following groups to communicate with other users who are using Cloudreve: + +* [Telegram group](https://t.me/cloudreve\_official) +* [QQ group](https://qm.qq.com/cgi-bin/qm/qr?k=pjwJ2pi\_V4LN\_JdPZk\_HMwJv\_x8zuCPX\&jump\_from=webapi) + +Or contact the developer: + + Email: [abslant.liu@gmail.com](mailto:abslant.liu@gmail.com) diff --git a/README.md b/README.md index 5035c23..4bd9e8f 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ description: 目前文档仍在陆续完善中！ --- +![ENGLISH version](README.ENG.md) + # 欢迎 ## Cloudreve 是什么？ diff --git a/SUMMARY.ENG.md b/SUMMARY.ENG.md new file mode 100644 index 0000000..a9a2244 --- /dev/null +++ b/SUMMARY.ENG.md @@ -0,0 +1,31 @@ +# Table of contents + +* [Welcome](README.ENG.md) + +## Getting Started + +* [Quick start](getting-started/install.ENG.md) +* [configuration file](getting-started/config.ENG.md) +* [Build](getting-started/build.ENG.md) + +## Use + +* [Storage Policy](use/policy/README.ENG.md) + * [Compare](use/policy/compare.ENG.md) + * [S3 compatible](use/policy/s3.ENG.md) +* [WebDAV](use/webdav.ENG.md) +* [Offline download](use/aria2.ENG.md) +* [Custom front end](use/zi-ding-yi-qian-duan.ENG.md) +* [Extended Documentation Preview/Edit](use/wopi.ENG.md) +* [Contribution version related](use/pro/README.ENG.md) + * [Introduction](use/pro/jie-shao.ENG.md) + * [iOS client bulk authorization](use/pro/vo-l.ENG.md) + * [Custom payment channel](use/pro/pay.ENG.md) + +## Maintain + +* [Database script](manage/db-script.ENG.md) +* [Update](manage/update/README.ENG.md) + * [upgrade from 3.x.x](manage/update/cong-3.x.x-sheng-ji.ENG.md) + * [upgrade from 2.x.x](manage/update/upgrade.ENG.md) + * [Upgrade to Contribution Version](manage/update/update-from-os.ENG.md) diff --git a/getting-started/build.ENG.md b/getting-started/build.ENG.md new file mode 100644 index 0000000..e7fb22e --- /dev/null +++ b/getting-started/build.ENG.md @@ -0,0 +1,80 @@ +# Construct + +The Cloudreve project is mainly composed of two parts: the back-end main warehouse [cloudreve/Cloudreve](https://github.com/cloudreve/Cloudreve), and the front-end warehouse [cloudreve/frontend](https://github.com/cloudreve/ front end). Before compiling the Cloudreve backend, you need to build the frontend submodule in the `assets` directory and embed it into the backend repository using [statik](https://github.com/rakyll/statik). + +## Environment preparation + +1. Refer to [Getting Started - The Go Programming Language](https://golang.org/doc/install) to install and configure the Go language development environment (>=1.18); +2. Refer to [Download | Node.js](https://nodejs.org/zh-cn/download/) to install Node.js; +3. Refer to [Install | Yarn](https://classic.yarnpkg.com/zh-Hans/docs/install#windows-stable) to install Yarn; + +## start building + +### Clone code + +```bash +# Clone repository +git clone --recurse-submodules https://github.com/cloudreve/Cloudreve.git + +# Checkout the version you want to compile +git checkout 3.x.x +``` + +### Build static resources + +```bash +# Enter the front terminal module +cd assets +# install dependencies +yarn install +# start building +yarn run build +# Delete the mapping file after the build is complete +cd build +find . -name "*.map" -type f -delete +# Return to the main directory of the project to package static resources +cd ../../ +zip -r -assets/build >assets.zip +``` + +After completion, the built static resource files are located in the `assets/build` directory. + +You can rename this directory to the `statics` directory, place it in the same directory as the main Cloudreve program and restart Cloudreve, Cloudreve will use the static resource files in this directory instead of the built-in ones. + +### Compile the project + +```bash +# Return to the project main directory +cd ../ + +# Get the current version number, Commit +export COMMIT_SHA=$(git rev-parse --short HEAD) +export VERSION=$(git describe --tags) + +# start compiling +go build -a -o cloudreve -ldflags " -X 'github.com/cloudreve/Cloudreve/v3/pkg/conf.BackendVersion=$VERSION' -X 'github.com/cloudreve/Cloudreve/v3/pkg/conf.LastCommit =$COMMIT_SHA'" +``` + +{% hint style="info" %} +When compiling for the first time, Go will download related dependent libraries. If your network environment is not good, this step may be too slow or fail. You can use [GOPROXY.IO](https://goproxy.io/zh/) to speed up module downloading. +{% endhint %} + +After the compilation is complete, the final executable file `cloudreve` will be generated in the project root directory. + +## Build helpers + +You can use [goreleaser](https://goreleaser.com/intro/) to quickly complete operations such as building and packaging, as follows: + +```bash +# install goreleaser +go install github.com/goreleaser/goreleaser@latest + +# Build the project +goreleaser build --clean --single-target --snapshot +``` + +Or cross compile all available versions: + +```sh +goreleaser build --clean --snapshot +``` diff --git a/getting-started/config.ENG.md b/getting-started/config.ENG.md new file mode 100644 index 0000000..e58f2bd --- /dev/null +++ b/getting-started/config.ENG.md @@ -0,0 +1,198 @@ +# configuration file + +## configuration file + +When starting for the first time, Cloudreve will create a configuration file named `conf.ini` in the same directory. You can modify this file to configure some parameters. After saving, you need to restart Cloudreve to take effect. + +You can also add the `-c` parameter to specify the configuration file path at startup: + +``` +./cloudreve -c /path/to/conf.ini +``` + +An example of a complete configuration file is as follows: + +{% code title="conf.ini" %} +```ini +[System] +; run mode +Mode = master +; listening port +Listen = :5212 +; Whether to enable Debug +Debug = false +; Session key, usually automatically generated at first startup +SessionSecret = 23333 +; Hash plus salt, usually automatically generated at the first startup +HashIDSalt = something really hard to guss +; Header to use when presenting client IP +ProxyHeader = X-Forwarded-For + +; SSL related +[SSL] +; SSL listening port +Listen = :443 +; certificate path +CertPath = C:\Users\i\Documents\fullchain.pem +; private key path +KeyPath = C:\Users\i\Documents\privkey.pem + +; Enable Unix Socket listening +[UnixSocket] +Listen = /run/cloudreve/cloudreve.sock +; Set the permissions of the generated socket file +Perm = 0666 + +; Database related, if you only want to use the built-in SQLite database, delete this part directly +[Database] +; Database type, currently supports sqlite/mysql/mssql/postgres +Type = mysql +; MySQL port +Port = 3306 +; username +User = root +; password +Password = root +; database address +Host = 127.0.0.1 +; Name database +Name = v3 +; data table prefix +TablePrefix = cd_ +; character set +Charset = utf8mb4 +; SQLite database file path +DBFile = cloudreve.db +; The buffer time to safely close the database connection before the process exits +GracePeriod = 30 +; Connect to database using Unix Socket +UnixSocket = false + +; Configuration in slave mode +[Slave] +; communication key +Secret = 1234567891234567123456789123456712345678912345671234567891234567 +; Callback request timeout (s) +CallbackTimeout = 20 +; signature validity period +SignatureTTL = 60 + +; Cross domain configuration +[CORS] +AllowOrigins = * +AllowMethods = OPTIONS,GET,POST +AllowHeaders = * +AllowCredentials = false +SameSite = Default +Secure = lse + +; Redis related +[Redis] +Server=127.0.0.1:6379 +Password = +DB = 0 + +; Slave configuration override +[OptionOverwrite] +; Can be overridden directly using `setting name=value` format +max_worker_num = 50 +``` +{% endcode %} + +## Configuration example + +### Using MySQL + +By default, Cloudreve will use the built-in SQLite database and create a database file `cloudreve.db` in the same directory. If you want to use MySQL, please add the following content to the configuration file and restart Cloudreve. Note that Cloudreve only supports MySQL versions greater than or equal to 5.7. + +```ini +[Database] +; Database type, currently supports sqlite/mysql/mssql/postgres +Type = mysql +; MySQL port +Port = 3306 +; username +User = root +; password +Password = root +; database address +Host = 127.0.0.1 +; Name database +Name = v3 +; data table prefix +TablePrefix = cd +; character set +Charset = utf8 +``` + +{% hint style="info" %} +After changing the database configuration, Cloudreve will re-initialize the database, and the original data will be lost. +{% endhint %} + +### Using Redis + +You can add Redis related settings in the configuration file: + +```ini +[Redis] +Server=127.0.0.1:6379 +Password = your password +DB = 0 +``` + +{% hint style="info" %} +Please specify a DB that is not used by other businesses for Cloudreve to avoid conflicts. +{% endhint %} + +After restarting Cloudreve, you can pay attention to the console output to determine whether Cloudreve successfully connected to the Redis server. After using Redis, the following will be taken over by Redis: + +* User sessions (login sessions are no longer lost after restarting Cloudreve) +* Data table high-frequency record query cache (such as storage strategy, setting items) +* callback session +* OneDrive Credentials + +### Enable HTTPS + +{% hint style="info" %} +If you are using the web server as a reverse proxy to Cloudreve, it is recommended that you configure SSL on the web server. The enabling method described in this section is only valid for the scenario of using Cloudreve's built-in web server. +{% endhint %} + +Add to the configuration file: + +```ini +[SSL] +Listen = :443 +CertPath = C:\Users\i\Documents\fullchain.pem +KeyPath = C:\Users\i\Documents\privkey.pem +``` + +Where `CertPath` and `KeyPath` are the SSL certificate and private key path respectively. After saving, restart Cloudreve to take effect. + +### Override the configuration items of the slave node + +Some configuration items of Cloudreve are stored in the database, but the slave node does not connect to the database, you can override the corresponding configuration items in the configuration file. + +For example, when the slave node is running as a storage node, you can set the thumbnail specification generated by the slave through the following configuration: + +```ini +[OptionOverwrite] +thumb_width = 400 +thumb_height = 300 +thumb_file_suffix = ._thumb +thumb_max_task_count = -1 +thumb_encode_method = jpg +thumb_gc_after_gen = 0 +thumb_encode_quality = 85 +``` + +If the slave node is used as an offline download node, you can override the default retry and timeout parameters through the following configuration to avoid file transfer failure due to the default value being too conservative: + +```ini +[OptionOverwrite] +; The maximum number of tasks that can be executed in parallel in the task queue +max_worker_num = 50 +; The maximum number of parallel coroutines when the task queue transfers tasks +max_parallel_transfer = 10 +; The maximum number of retries after the upload of intermediate parts fails +chunk_retries = 10 +``` diff --git a/getting-started/install.ENG.md b/getting-started/install.ENG.md new file mode 100644 index 0000000..722bb77 --- /dev/null +++ b/getting-started/install.ENG.md @@ -0,0 +1,404 @@ +# quick start + +## Get Cloudreve + +You can get the main program that has been built and packaged on the [GitHub Release](https://github.com/cloudreve/Cloudreve/releases) page. Each version provides the main program available under the common system architecture, and the naming rule is `cloudreve_version number_operating system_CPU architecture.tar.gz`. For example, to deploy version 3.0.0 on an ordinary 64-bit Linux system, you should download `cloudreve_3.0.0_linux_amd64.tar.gz`. + +If you want to experience the latest features, you can download the development version built after each commit in [GitHub Actions](https://github.com/cloudreve/Cloudreve/actions). Note that the development version is not stable, cannot be used for production use, and is not guaranteed to be fully usable. + +If you want to build from source yourself, see the following sections: + +{% content-ref url="build.md" %} +[build.md](build.md) +{% endcontent-ref %} + +## Start Cloudreve + +{% tabs %} +{% tab title="Linux" %} +Under Linux, just decompress and execute the main program directly: + +```bash +#Unzip the obtained main program +tar -zxvf cloudreve_VERSION_OS_ARCH.tar.gz + +# Give execute permission +chmod +x ./cloudreve + +# start Cloudreve +./cloudreve +``` + +{% endtab %} + +{% tab title="Windows" %} +Under Windows, directly decompress the obtained zip archive and start `cloudreve.exe`. +{% endtab %} +{% endtabs %} + +When Cloudreve starts for the first time, it will create an initial administrator account. Please keep the administrator password safe, this password will only appear when it is started for the first time. If you forget the initial administrator password, you need to delete `cloudreve.db` in the same directory and restart the main program to initialize a new administrator account. + +Cloudreve listens on `5212` port by default. You can access `http://serverIP:5212` in your browser to enter Cloudreve. + +After the above steps are completed, the simplest deployment is completed. You may need some more specific configurations to make Cloudreve work better. Please refer to the configuration process below for specific procedures. + +## Optional deployment process + +### reverse proxy + +In the scenario of self-use or small-scale use, you can use Cloudreve's built-in web server. But if you need to use HTTPS, or need to coexist with other web services on the server, you may need to use the mainstream web server reverse proxy Cloudreve to get richer extensions. + +You need to create a new virtual host in the web server, complete the required configurations (such as enabling HTTPS), and then add anti-generation rules to the website configuration file: + +{% tabs %} +{% tab title="NGINX" %} +In the `server` field of the website add: + +``` +location / { + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header Host $http_host; + proxy_redirect off; + proxy_pass http://127.0.0.1:5212; + + # If you want to use the local storage strategy, please delete the comment on the next line and change the size to the theoretical maximum file size + # client_max_body_size 20000m; +} +``` + +{% endtab %} + +{% tab title="Apache" %} +Add the anti-generation configuration item `ProxyPass` under the `VirtualHost` field, for example: + +```markup + + ServerName myapp.example.com + ServerAdmin webmaster@example.com + DocumentRoot /www/myapp/public + + # The following are the key parts + AllowEncodedSlashes NoDecode + ProxyPass "/" "http://127.0.0.1:5212/" nocanon + + +``` + +{% endtab %} + +{% tab title="IIS" %} + +#### 1. Install IIS URL Rewrite and ARR modules + +- URL Rewrite: [Click to download](https://www.iis.net/downloads/microsoft/url-rewrite#additionalDownloads) +- ARR: [Click to download](https://www.iis.net/downloads/microsoft/application-request-routing#additionalDownloads) + +If it is already installed, please skip this step. + +#### 2. Enable and configure ARR + +Open IIS, enter **Application Request Routing Cache** on the home page, then enter **Server Proxy Settings...** on the right, check **Enable proxy** on the top, and uncheck the ** below Reverse rewrite host in response headers**. Click Apply on the right to save the changes. + +Enter **Configuration Editor** at the bottom of the home page, go to `system.webServer/proxy` node, adjust **preserveHostHeader** to **True** and click Apply on the right to save the changes. + +If you do not uncheck the reverse rewrite host header, the Cloudreve API will not be able to return the correct address, resulting in the inability to preview pictures and videos. + +#### 3. Configure anti-generation rules + +This is the content of the `web.config` file, just place it in the root directory of the target website. This example includes two rules and one restriction: + +- HTTP to HTTPS redirect (mandatory HTTPS, you need to configure SSL before you can use it, please delete this rule if you don’t use it) +- Rerwite (reverse generation) +- `60000000` in `requestLimits` is the transfer file size limit, the unit is byte, if you want to use the local storage strategy, please change the size to the theoretical maximum file size + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +{% endtab %} +{% endtabs %} + +### Process daemon + +You can choose one of the following two ways. + +#### Systemd + +```bash +# edit configuration file +vim /usr/lib/systemd/system/cloudreve.service +``` + +Replace `PATH_TO_CLOUDREVE` below with the directory where the program is located: + +```bash +[Unit] +Description=Cloudreve +Documentation=https://docs.cloudreve.org +After=network.target +After=mysqld.service +Wants=network.target + +[Service] +Working Directory=/PATH_TO_CLOUDREVE +ExecStart=/PATH_TO_CLOUDREVE/cloudreve +Restart=on-abnormal +RestartSec=5s +KillMode=mixed + +StandardOutput=null +StandardError=syslog + +[Install] +WantedBy=multi-user.target +``` + +```bash +# update configuration +systemctl daemon-reload + +# start the service +systemctl start cloudreve + +# set boot +systemctl enable cloudreve +``` + +Management commands: + +```bash +# start the service +systemctl start cloudreve + +# Out of service +systemctl stop cloudreve + +# restart service +systemctl restart cloudreve + +# check status +systemctl status cloudreve +``` + +#### Supervisor + +First install `supervisor`, you can skip the ones already installed. + +```bash +# install supervisor +sudo yum install python-setuptools +sudo easy_install supervisor + +# Initialize the global configuration file +sudo touch /etc/supervisord.conf +sudo echo_supervisord_conf > /etc/supervisord.conf +``` + +Edit the global configuration file: + +```bash +sudo vim /etc/supervisord.conf +``` + +Delete the `[include]` partition comment symbol `;` at the bottom of the file, and add a new configuration file to include the path: + +```bash +[include] +files = /etc/supervisor/conf/*.conf +``` + +Create the file directory where the Cloudreve application configuration is located, and create an open configuration file: + +```bash +sudo mkdir -p /etc/supervisor/conf +sudo vim /etc/supervisor/conf/cloudreve.conf +``` + +Fill in the following content according to the actual situation and save: + +```bash +[program: cloudreve] +directory=/home/cloudreve +command=/home/cloudreve/cloudreve +autostart=true +autorestart=true +stderr_logfile=/var/log/cloudreve.err +stdout_logfile=/var/log/cloudreve.log +environment=CODENATION_ENV=prod +``` + +The following configuration items need to be changed according to the actual situation: + +- `directory`: The directory where the Cloudreve main program is located +- `command`: absolute path of Cloudreve main program +- `stderr_logfile`: error log path +- `stdout_logfile`: usual log path + +Start supervisor via the global configuration file: + +```bash +supervisord -c /etc/supervisord.conf +``` + +In the future you can manage the Cloudreve process with the following commands: + +```bash +# start up +sudo supervisorctl start cloudreve + +# stop +sudo supervisorctl stop cloudreve + +# check status +sudo supervisorctl status cloudreve +``` + +## Docker +> Before using, please make sure you know the working mechanism of docker. In general, the above deployment process can already cover most usage scenarios. + +We provide official docker image, which supports three architectures `armv7`, `arm64` and `amd64`, you can use the following command to deploy + +### Create directory structure + +Please **make sure** before running: + +> 1. Manually create an empty `conf.ini` file or a `conf.ini` that conforms to the Cloudreve configuration file specification, and replace `` with the path +> 2. Manually create `cloudreve.db` empty file and replace `` with this path +> 3. Manually create `uploads` folder and replace `` with the path +> 4. Manually create the `avatar` folder and replace `` with the path + +Alternatively, create it directly with the following command: + +```bash +mkdir -vp cloudreve/{uploads,avatar} \ +&& touch cloudreve/conf.ini \ +&& touch cloudreve/cloudreve.db +``` + +### run + +Then, run the docker container: + +```bash +docker run -d \ +-p 5212:5212 \ +--mount type=bind,source=,target=/cloudreve/conf.ini\ +--mount type=bind,source=,target=/cloudreve/cloudreve.db\ +-v :/cloudreve/uploads\ +-v :/cloudreve/avatar \ +cloudreve/cloudreve:latest +``` + +## Docker Compose + +In addition, we also provide `docker compose` deployment and integrate offline download service +Before that, you need to create a `data` directory as a temporary staging directory for offline downloads + +### Create directory structure + +```bash +mkdir -vp cloudreve/{uploads,avatar} \ +&& touch cloudreve/conf.ini \ +&& touch cloudreve/cloudreve.db\ +&& mkdir -p aria2/config \ +&& mkdir -p data/aria2 \ +&& chmod -R 777 data/aria2 +``` + +### run + +Then save the following file as `docker-compose.yml`, place it in the current directory, at the same level as cloudreve, and modify `RPC_SECRET` in the file + +```yml +version: "3.8" +services: + cloudreve: + container_name: cloudreve + image: cloudreve/cloudreve:latest + restart: unless-stopped + ports: + - "5212:5212" + volumes: + - temp_data:/data + - ./cloudreve/uploads:/cloudreve/uploads + - ./cloudreve/conf.ini:/cloudreve/conf.ini + - ./cloudreve/cloudreve.db:/cloudreve/cloudreve.db + - ./cloudreve/avatar:/cloudreve/avatar + depends_on: + - aria2 + aria2: + container_name: aria2 + image: p3terx/aria2-pro + restart: unless-stopped + environment: + -RPC_SECRET=your_aria_rpc_token + -RPC_PORT=6800 + volumes: + - ./aria2/config:/config + - temp_data:/data +volumes: + temp_data: + driver: local + driver_opts: + type: none + device: $PWD/data + o: bind +``` + +run mirror + +```bash +# Background operation mode, you can get the default administrator account username and password from the docker/docker-compose log +docker-compose up -d + +# Or, run it directly, the log will be output directly in the current console, please note that the current container is running after exiting +docker-compose up +``` + +In the subsequent control panel, configure as follows + +1. **[Unmodifiable]** RPC server address => `http://aria2:6800` +2. **[Can be modified, must be consistent with the docker-compose.yml file]** RPC authorization token => `your_aria_rpc_token` +3. **[Unmodifiable]** Absolute path on the node where Aria2 is used as temporary download directory => `/data` + +### renew + +Close the currently running container, this step will not delete the mounted configuration files and related directories +```bash +docker-compose down +``` + +If the docker image has been pulled before, use the following command to get the latest image +```bash +docker pull cloudreve/cloudreve +``` + +Just repeat the steps diff --git a/manage/db-script.ENG.md b/manage/db-script.ENG.md new file mode 100644 index 0000000..ee0f21a --- /dev/null +++ b/manage/db-script.ENG.md @@ -0,0 +1,23 @@ +# database script + +Cloudreve has built-in some commonly used database scripts, which can be used for daily maintenance, version upgrade and other operations. You can add the command line parameter `--database-script