README + README_zh-CN now describe the fork's actual state: purpose and upstream attribution, monorepo layout, shipped fork features (share collaboration, OIDC, yt-dlp, quotas), real build/test commands, and an honest status scorecard instead of upstream marketing copy. CONTRIBUTING updated for the fork workflow (no CLA, feature-branch PRs, pre-push gate). ROADMAP marks the PR #144 batch and the completed desloppify pass. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>pull/3582/head
Tomas Dvorak
2 weeks ago
parent
ee55d2006b
commit
0ce5c7514f
@ -1,26 +1,35 @@
|
||||
# Contributing to Cloudreve
|
||||
# Contributing
|
||||
|
||||
Thank you for your interest in contributing to Cloudreve!
|
||||
This is an actively maintained community fork of Cloudreve. Contributions are welcome — the goal is
|
||||
a complete, fully open-source distribution, so Pro-class features land here as free software rather
|
||||
than behind a license key.
|
||||
|
||||
The full contributing guide — including project structure, development environment
|
||||
setup, how to pick a task, how to submit a PR, and our AIGC (AI-generated code)
|
||||
policy — is maintained in our documentation site:
|
||||
## Before you start
|
||||
|
||||
**👉 https://docs.cloudreve.org/api/contributing**
|
||||
- **Check the issue tracker first.** Migrated upstream issues are labeled by group
|
||||
(`group:*`, `pro-free`, `security`, `revisit`, `epic`); each carries an honest status note.
|
||||
[ROADMAP.md](ROADMAP.md) describes the phase plan (B.2 storage policies, B.4 VAS, B.5 system
|
||||
extensions, Phase D desktop, Phase E Android).
|
||||
- **One change per PR.** Split large features into reviewable increments.
|
||||
- **No CLA.** Unlike upstream there is no contributor agreement — contributions are GPL-3.0 like
|
||||
the project itself. Do not submit code copied from Cloudreve Pro sources.
|
||||
|
||||
A few key points to keep in mind before you open a PR:
|
||||
## Workflow
|
||||
|
||||
- Cloudreve is dual-licensed. We only accept contributions to the **community
|
||||
edition**, and all contributors must sign the
|
||||
[CLA](https://cla-assistant.io/cloudreve/cloudreve) before a PR can be merged.
|
||||
- **PRs must be linked to an issue labeled with `Backlog`.** We do not accept
|
||||
new features proposed directly through a PR. If you have a new idea, please
|
||||
open an issue first and wait for it to be triaged and labeled.
|
||||
- **Each PR should correspond to a single change.** Please split large features
|
||||
or refactors into multiple smaller PRs whenever possible.
|
||||
- If you use AI tools to help write code, please read the
|
||||
[AIGC Guidelines](https://docs.cloudreve.org/api/contributing#aigc-guidelines)
|
||||
first. We are not against AI, but we do not accept pure "vibe-coded" PRs.
|
||||
1. Branch from `master` — never push to `master` directly.
|
||||
2. Keep changes idiomatic: Gin + ent on the backend, React + MUI + Redux conventions in `frontend/`,
|
||||
existing provider/interface seams over new abstractions.
|
||||
3. Run the pre-push gate, all of it:
|
||||
- `go build ./... && go vet ./... && go test ./...`
|
||||
- `cd frontend && yarn tsc --noEmit && yarn build` (use `NODE_OPTIONS=--max-old-space-size=6144`
|
||||
if Vite hits the default heap limit)
|
||||
- Boot the binary and smoke the endpoints you touched.
|
||||
4. Open the PR against `Dvorinka/cloudreve` `master` and wait for all CI jobs (backend, frontend,
|
||||
desktop matrix) to go green.
|
||||
|
||||
For discussion and support, join the `development` channel on our
|
||||
[Discord community](https://discord.com/channels/1343585183047094367/1343585679585579018).
|
||||
## Style notes
|
||||
|
||||
- Security-relevant changes (auth, SSRF, process execution, file paths, secrets) get extra scrutiny —
|
||||
say so in the PR description.
|
||||
- Comments only where they carry information; Go doc conventions for exported symbols.
|
||||
- AI-assisted contributions are fine — you are responsible for what you submit.
|
||||
|
||||
@ -1,76 +1,119 @@
|
||||
[中文版本](https://github.com/cloudreve/cloudreve/blob/master/README_zh-CN.md)
|
||||
|
||||
<h1 align="center">
|
||||
<br>
|
||||
<a href="https://cloudreve.org/" alt="logo" ><img src="https://raw.githubusercontent.com/cloudreve/frontend/master/public/static/img/logo192.png" width="150"/></a>
|
||||
<br>
|
||||
Cloudreve
|
||||
Cloudreve — Community Fork
|
||||
<br>
|
||||
</h1>
|
||||
<h4 align="center">Self-hosted file management system with multi-cloud support.</h4>
|
||||
<h4 align="center">Self-hosted file management and sharing platform — fully open source, actively maintained.</h4>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://dev.azure.com/abslantliu/cloudreve/_build?definitionId=6">
|
||||
<img src="https://img.shields.io/github/check-runs/cloudreve/cloudreve/master"
|
||||
alt="Azure pipelines">
|
||||
</a>
|
||||
<a href="https://github.com/cloudreve/cloudreve/releases">
|
||||
<img src="https://img.shields.io/github/v/release/cloudreve/cloudreve?include_prereleases" />
|
||||
</a>
|
||||
<a href="https://github.com/cloudreve/cloudreve/releases">
|
||||
<img src="https://badgen.net/static/release%20size/34%20MB/blue"/>
|
||||
</a>
|
||||
<a href="https://hub.docker.com/r/cloudreve/cloudreve">
|
||||
<img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/cloudreve/cloudreve" />
|
||||
</a>
|
||||
<a href="https://github.com/Dvorinka/cloudreve/actions"><img src="https://img.shields.io/github/actions/workflow/status/Dvorinka/cloudreve/ci.yml?branch=master" alt="CI"></a>
|
||||
<a href="https://github.com/Dvorinka/cloudreve/releases"><img src="https://img.shields.io/github/v/release/Dvorinka/cloudreve?include_prereleases" alt="Release"></a>
|
||||
<a href="LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-blue" alt="GPL-3.0"></a>
|
||||
</p>
|
||||
<p align="center">
|
||||
<a href="https://cloudreve.org">Homepage</a> •
|
||||
<a href="https://demo.cloudreve.org">Try it</a> •
|
||||
<a href="https://github.com/cloudreve/cloudreve/discussions">Discussion</a> •
|
||||
<a href="https://docs.cloudreve.org">Documents</a> •
|
||||
<a href="https://github.com/cloudreve/cloudreve/releases">Download</a> •
|
||||
<a href="https://t.me/cloudreve_official">Telegram</a> •
|
||||
<a href="https://discord.com/invite/WTpMFpZT76">Discord</a>
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
## :sparkles: Features
|
||||
|
||||
- :cloud: Support storing files into Local, Remote node, OneDrive, S3 compatible API, Qiniu Kodo, Aliyun OSS, Tencent COS, Huawei Cloud OBS, Kingsoft Cloud KS3, Upyun.
|
||||
- :outbox_tray: Upload/Download in directly transmission from client to storage providers.
|
||||
- 💾 Integrate with Aria2/qBittorrent to download files in background, use multiple download nodes to share the load.
|
||||
- 📚 Compress/Extract/Preview archived files, download files in batch.
|
||||
- 💻 WebDAV support covering all storage providers.
|
||||
- :zap:Drag&Drop to upload files or folders, with parallel resumable upload support.
|
||||
- :card_file_box: Extract media metadata from files, search files by metadata or tags.
|
||||
- :family_woman_girl_boy: Multi-users with multi-groups.
|
||||
- :link: Create share links for files and folders with expiration date.
|
||||
- :eye_speech_bubble: Preview videos, images, audios, ePub files online; edit texts, diagrams, Markdown, images, Office documents online.
|
||||
- :art: Customize theme colors, dark mode, PWA application, SPA, i18n.
|
||||
- :rocket: All-in-one packaging, with all features out of the box.
|
||||
- 🌈 ... ...
|
||||
|
||||
## :hammer_and_wrench: Deploy
|
||||
|
||||
To deploy Cloudreve, you can refer to [Getting started](https://docs.cloudreve.org/overview/quickstart) for a quick local deployment to test.
|
||||
|
||||
When you're ready to deploy Cloudreve to a production environment, you can refer to [Deploy](https://docs.cloudreve.org/overview/deploy/) for a complete deployment.
|
||||
|
||||
## :gear: Build
|
||||
|
||||
Please refer to [Build](https://docs.cloudreve.org/overview/build/) for how to build Cloudreve from source code.
|
||||
|
||||
## :rocket: Contributing
|
||||
|
||||
If you're interested in contributing to Cloudreve, please refer to [Contributing](https://docs.cloudreve.org/api/contributing/) for how to contribute to Cloudreve.
|
||||
|
||||
## :alembic: Stacks
|
||||
|
||||
- [Go](https://golang.org/) + [Gin](https://github.com/gin-gonic/gin) + [ent](https://github.com/ent/ent)
|
||||
- [React](https://github.com/facebook/react) + [Redux](https://github.com/reduxjs/redux) + [Material-UI](https://github.com/mui-org/material-ui)
|
||||
|
||||
## :scroll: License
|
||||
|
||||
GPL V3
|
||||
> **This is an actively maintained fork of [cloudreve/cloudreve](https://github.com/cloudreve/cloudreve).**
|
||||
> All original work is by the Cloudreve authors (cloudreve.org). This fork exists because upstream
|
||||
> development had slowed: it continues the project as a **complete, fully open-source distribution** —
|
||||
> backend, web frontend, desktop clients for Windows/macOS/Linux, and a native Android app — with every
|
||||
> "Pro"-class feature reimplemented as free software. See [NOTICE](NOTICE) for attribution.
|
||||
|
||||
## What this fork does differently
|
||||
|
||||
- **No Pro tier.** The upsell UI (`ProChip`/`ProDialog`) is removed. Pro-class capabilities are being
|
||||
reimplemented as open features: share collaboration (upload/edit/preview-only/drop-box shares),
|
||||
OIDC SSO, delegated admin roles — already shipped.
|
||||
- **Upstream issue backlog triaged and fixed.** All 137 migrated upstream issues are tracked in this
|
||||
repo's issue tracker; ~70% are closed. WebDAV mounts/read-only/collision handling, stuck uploads,
|
||||
recycle-bin fail-safes, SQLite WAL, MySQL `parseTime`, unix-socket migrations, and dozens more.
|
||||
- **Security hardening on top of upstream's fixes.** OAuth public clients no longer ship hardcoded
|
||||
secrets (PKCE only, per RFC 8252); SSRF validation on remote-download URLs; delegated-admin access
|
||||
is audit-logged; auth endpoints are rate-limited; the downloader layer was reviewed for process
|
||||
execution and path-safety.
|
||||
- **One monorepo.** Backend + frontend + desktop + Android live here; no submodules.
|
||||
- **Tests and CI are real.** GitHub Actions run backend tests, frontend typecheck/build, and the
|
||||
desktop matrix (Windows/macOS/Linux) on every PR.
|
||||
|
||||
## Repository layout
|
||||
|
||||
```
|
||||
. Go backend — Gin + ent ORM (SQLite/MySQL/PostgreSQL)
|
||||
frontend/ Web SPA — React + TypeScript + Vite + MUI (vendored, no submodule)
|
||||
desktop/ Desktop client — Tauri/Rust sync engine (Windows cfapi today;
|
||||
macOS/Linux hydration providers on the roadmap)
|
||||
android/ Native Android client — Kotlin + Jetpack Compose (scaffolded, Phase E)
|
||||
.github/workflows/ CI (backend, frontend, desktop matrix) + release pipeline
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
- Storage providers: local, remote node, S3-compatible, OneDrive, OSS, COS, Qiniu, Upyun, KS3, OBS.
|
||||
- Direct upload/download between client and storage; chunked, resumable, parallel uploads.
|
||||
- Remote download: aria2, qBittorrent, **and yt-dlp** providers, multi-node with per-node settings,
|
||||
group-level concurrent/size quotas.
|
||||
- Share links with expiration — plus fork additions: upload-only drop boxes, edit-in-place,
|
||||
preview-only mode, anonymous upload, IP-restricted views.
|
||||
- Archive compress/extract, media metadata extraction, metadata/tag search.
|
||||
- WebDAV across all storage providers (read-only group enforcement fixed in this fork).
|
||||
- SSO: generic OIDC inbound consumer (auth-code + nonce, JWKS-verified, auto-provisioning),
|
||||
OAuth public clients with PKCE, passkeys, TOTP 2FA.
|
||||
- Multi-user, multi-group; admin task list with CIDR-capable creator-IP filtering; per-user trash
|
||||
retention; per-group remote-download quotas.
|
||||
- Preview: image (progressive thumbnail→full-res), video, audio, ePub, Markdown, diagrams,
|
||||
Office documents (WOPI), 3D models.
|
||||
- PWA, dark mode, i18n (en-US, zh-CN, and more), theme customization, custom HTML injection.
|
||||
|
||||
## Build from source
|
||||
|
||||
Prereqs: Go ≥ 1.24, Node ≥ 20 + Yarn, (desktop) Rust + platform Tauri deps.
|
||||
|
||||
```bash
|
||||
# Frontend
|
||||
cd frontend && yarn install
|
||||
NODE_OPTIONS=--max-old-space-size=6144 yarn build # emits build/ consumed by the Go embed
|
||||
|
||||
# Backend (repo root) — the binary serves frontend + API on :5212
|
||||
go build -o cloudreve .
|
||||
./cloudreve
|
||||
```
|
||||
|
||||
Desktop client: see `desktop/CLAUDE.md` (`cargo tauri build`, Windows-first; other platforms WIP).
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
go build ./... && go vet ./... && go test ./... # backend gate
|
||||
cd frontend && yarn tsc --noEmit && yarn build # frontend gate
|
||||
```
|
||||
|
||||
`docker-compose.dev.yml` brings up postgres + redis + a source-built backend; `yarn dev` gives
|
||||
frontend hot reload. PRs land via feature branches — never push to `master` — and must pass all CI
|
||||
jobs before merge.
|
||||
|
||||
## Status scorecard
|
||||
|
||||
| Area | State |
|
||||
|---|---|
|
||||
| Backend / frontend | Stable — 4.19.1 line, all CI green |
|
||||
| Upstream issues | ~70% of the 137 migrated issues closed; remainder are feature-scale, Pro-surface, or device-bound |
|
||||
| Code health | desloppify strict score 77.1 (was 18.9); 73 review items dispositioned |
|
||||
| Desktop client | Windows functional (cfapi sync + shell integration); macOS/Linux providers planned |
|
||||
| Android client | Scaffolded — Kotlin/Compose skeleton, Phase E in [ROADMAP.md](ROADMAP.md) |
|
||||
| Pro-free features | Share collaboration ✓, OIDC SSO ✓, delegated admins ✓; storage-policy migration, VAS/billing, audit surface in progress |
|
||||
|
||||
Known limitations and the full plan: [ROADMAP.md](ROADMAP.md) · issue tracker has honest per-issue status.
|
||||
|
||||
## Security
|
||||
|
||||
Report vulnerabilities privately via GitHub's "Report a vulnerability" on this repo — do not open a
|
||||
public issue. All 16 published upstream GHSAs are patched at our baseline; our own additions are
|
||||
reviewed for SSRF, path traversal, process execution, and session entropy before merge.
|
||||
|
||||
## Credits
|
||||
|
||||
Cloudreve was created by **Aaron Liu and the Cloudreve contributors** (cloudreve.org). This fork is
|
||||
an independent continuation under the same GPL-3.0 license — attribution, not endorsement. See
|
||||
[NOTICE](NOTICE) for the full attribution statement.
|
||||
|
||||
## License
|
||||
|
||||
[GPL-3.0](LICENSE) — same as upstream. Contributions are licensed identically.
|
||||
|
||||
Loading…
Reference in new issue