From 0ce5c7514f584bceb8f68cc282cb5f0b2d21ef61 Mon Sep 17 00:00:00 2001 From: Tomas Dvorak Date: Sat, 19 Sep 2026 10:12:48 +0200 Subject: [PATCH] docs: rewrite README and project docs for the community fork 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> --- CONTRIBUTING.md | 49 +++++++------ README.md | 179 ++++++++++++++++++++++++++++++------------------ README_zh-CN.md | 171 ++++++++++++++++++++++++++------------------- ROADMAP.md | 3 +- 4 files changed, 241 insertions(+), 161 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23c918b4..c70f122d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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). \ No newline at end of file +## 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. diff --git a/README.md b/README.md index ba75139c..b0dea751 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,119 @@ -[中文版本](https://github.com/cloudreve/cloudreve/blob/master/README_zh-CN.md) -


- -
- Cloudreve + Cloudreve — Community Fork

-

Self-hosted file management system with multi-cloud support.

+

Self-hosted file management and sharing platform — fully open source, actively maintained.

- - Azure pipelines - - - - - - - - - Docker Pulls - + CI + Release + GPL-3.0

-

- Homepage • - Try it • - Discussion • - Documents • - Download • - Telegram • - Discord -

- -![Screenshot](https://raw.githubusercontent.com/cloudreve/docs/master/images/homepage.png) - -## :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. diff --git a/README_zh-CN.md b/README_zh-CN.md index d0577d52..6a365632 100644 --- a/README_zh-CN.md +++ b/README_zh-CN.md @@ -1,77 +1,104 @@ -[English Version](https://github.com/cloudreve/cloudreve/blob/master/README.md) -


- -
- Cloudreve + Cloudreve — 社区维护分支

+

自托管文件管理与分享平台 — 完全开源，持续维护中。

+ +> 本仓库是 [cloudreve/cloudreve](https://github.com/cloudreve/cloudreve) 的积极维护分支。 +> 所有原始工作归属 Cloudreve 原作者（cloudreve.org）。由于上游开发放缓，本分支将项目延续为 +> **完整、完全开源的发行版**：后端、Web 前端、Windows/macOS/Linux 桌面客户端以及原生 Android +> 应用，并将所有 “Pro” 级功能以自由软件方式重新实现。署名说明见 [NOTICE](NOTICE)。 + +## 与上游的差异 + +- **无 Pro 分层。** 已移除付费引导 UI（`ProChip`/`ProDialog`）；Pro 级功能以开源方式重新实现： + 分享协作（可上传/可编辑/仅预览/投递箱分享）、OIDC SSO、委派管理员已落地。 +- **上游 issue 积压已分类修复。** 137 个迁移 issue 全部在本仓库跟踪，约 70% 已关闭，包括 + WebDAV 挂载/只读/冲突处理、上传卡死、回收站保护、SQLite WAL、MySQL `parseTime`、 + unix socket 迁移等。 +- **在上游修复之上的安全加固。** OAuth 公共客户端不再内置硬编码密钥（仅 PKCE，符合 RFC 8252）； + 离线下载 URL 做 SSRF 校验；委派管理员操作记入审计日志；认证端点限流。 +- **单仓 monorepo。** 后端、前端、桌面端、Android 端同仓管理，无 submodule。 +- **测试与 CI 真实运行。** 每个 PR 执行后端测试、前端类型检查/构建、桌面端三平台构建。 + +## 仓库结构 + +``` +. Go 后端 — Gin + ent ORM（SQLite/MySQL/PostgreSQL） +frontend/ Web 前端 — React + TypeScript + Vite + MUI（已内嵌，无 submodule） +desktop/ 桌面客户端 — Tauri/Rust 同步引擎（当前为 Windows cfapi； + macOS/Linux 待接入，见路线图） +android/ 原生 Android 客户端 — Kotlin + Jetpack Compose（脚手架阶段） +.github/workflows/ CI（后端、前端、桌面端矩阵）+ 发布流水线 +``` + +## 功能 + +- 存储端：本地、远程节点、S3 兼容、OneDrive、OSS、COS、Qiniu、Upyun、KS3、OBS。 +- 客户端与存储端直传；分块、断点续传、并行上传。 +- 离线下载：aria2、qBittorrent、**yt-dlp** 三种提供方，多节点、按节点配置， + 用户组级并发/体积配额。 +- 分享链接：过期时间、仅上传投递箱、在线编辑、仅预览、匿名上传、IP 限制访问。 +- 压缩包解压/打包、媒体元数据提取、元数据/标签检索。 +- 全存储端 WebDAV（本分支修复了只读用户组的权限执行问题）。 +- SSO：通用 OIDC 接入（授权码 + nonce、JWKS 校验、自动开户）、OAuth 公共客户端 PKCE、 + Passkey、TOTP 两步验证。 +- 多用户多用户组；管理员任务列表支持 CIDR 创建者 IP 过滤；按用户回收站保留期； + 按用户组离线下载配额。 +- 预览：图片（缩略图渐进加载到原图）、视频、音频、ePub、Markdown、图表、Office 文档、3D 模型。 +- PWA、深色模式、多语言、主题自定义、自定义 HTML 注入。 + +## 从源码构建 + +依赖：Go ≥ 1.24、Node ≥ 20 + Yarn、（桌面端）Rust + Tauri 平台依赖。 + +```bash +# 前端 +cd frontend && yarn install +NODE_OPTIONS=--max-old-space-size=6144 yarn build # 产物由 Go embed 打包 + +# 后端（仓库根目录）— 二进制同时托管前端与 API，监听 :5212 +go build -o cloudreve . +./cloudreve +``` + +桌面客户端见 `desktop/CLAUDE.md`（`cargo tauri build`，Windows 优先）。 + +## 开发 + +```bash +go build ./... && go vet ./... && go test ./... # 后端门禁 +cd frontend && yarn tsc --noEmit && yarn build # 前端门禁 +``` + +`docker-compose.dev.yml` 可启动 postgres + redis + 源码构建的后端；`yarn dev` 提供前端热更新。 +PR 一律走功能分支，禁止直接推送 `master`，合并前必须通过全部 CI。 + +## 状态一览 + +| 领域 | 状态 | +|---|---| +| 后端 / 前端 | 稳定 — 4.19.1 基线，CI 全绿 | +| 上游 issue | 137 个迁移 issue 约 70% 已关闭；其余为大型功能、Pro 表面或依赖设备 | +| 代码健康 | desloppify 严格分 77.1（原 18.9）；73 项评审全部处置 | +| 桌面客户端 | Windows 可用（cfapi 同步 + 外壳集成）；macOS/Linux 计划中 | +| Android 客户端 | 脚手架完成 — Kotlin/Compose 骨架，见 [ROADMAP.md](ROADMAP.md) Phase E | +| Pro 免费化 | 分享协作 ✓、OIDC SSO ✓、委派管理员 ✓；存储策略迁移、VAS/计费、审计界面进行中 | + +完整计划与已知限制见 [ROADMAP.md](ROADMAP.md)；issue 跟踪器中每项均有真实状态说明。 + +## 安全 + +请通过本仓库 GitHub 的 “Report a vulnerability” 私下报告漏洞，勿开公开 issue。 +上游已公布的 16 个 GHSA 在本基线均已修复；新增改动合并前均经 SSRF、路径穿越、 +进程执行与会话熵审查。 + +## 致谢 + +Cloudreve 由 **Aaron Liu 及 Cloudreve 贡献者** 创建（cloudreve.org）。本分支是在同一 +GPL-3.0 许可下的独立延续 — 署名而非背书。完整声明见 [NOTICE](NOTICE)。 + +## 许可证 -

支持多家云存储驱动的公有云文件系统.

- -

- - Azure pipelines - - - - - - - - - Docker Pulls - -

-

- 主页 • - 演示 • - 讨论 • - 文档 • - 下载 • - Telegram • - Discord -

- -![Screenshot](https://raw.githubusercontent.com/cloudreve/docs/master/images/homepage.png) - -## :sparkles: 特性 - -- :cloud: 支持本机、从机、七牛 Kodo、阿里云 OSS、腾讯云 COS、华为云 OBS、金山云 KS3、又拍云、OneDrive (包括世纪互联版) 、S3 兼容协议 作为存储端 -- :outbox_tray: 上传/下载 支持客户端直传，支持下载限速 -- 💾 可对接 Aria2/qBittorrent 离线下载，可使用多个从机节点分担下载任务 -- 📚 在线 压缩/解压缩/压缩包预览、多文件打包下载 -- 💻 覆盖全部存储策略的 WebDAV 协议支持 -- :zap: 拖拽上传、目录上传、并行分片上传 -- :card_file_box: 提取媒体元数据，通过元数据或标签搜索文件 -- :family_woman_girl_boy: 多用户、用户组、多存储策略 -- :link: 创建文件、目录的分享链接，可设定自动过期 -- :eye_speech_bubble: 视频、图像、音频、 ePub 在线预览，文本、Office 文档在线编辑 -- :art: 自定义配色、黑暗模式、PWA 应用、全站单页应用、国际化支持 -- :rocket: All-in-One 打包，开箱即用 -- 🌈 ... ... - -## :hammer_and_wrench: 部署 - -你可以参考 [快速开始](https://docs.cloudreve.org/overview/quickstart) 启动一个本地实例进行体验、测试。 - -当你准备好将 Cloudreve 部署到生产环境时，可以参考 [部署](https://docs.cloudreve.org/overview/deploy/) 进行完整部署。 - -## :gear: 构建 - -你可以参考 [构建](https://docs.cloudreve.org/overview/build/) 从源代码构建 Cloudreve。 - -## :rocket: 贡献 - -如果你有兴趣为 Cloudreve 贡献代码，请参考 [贡献](https://docs.cloudreve.org/api/contributing/) 了解如何贡献。 - -## :alembic: 技术栈 - -- [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: 许可证 - -GPL V3 +[GPL-3.0](LICENSE) — 与上游一致，贡献按同一许可提交。 diff --git a/ROADMAP.md b/ROADMAP.md index 652df88b..134f4d49 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -132,13 +132,14 @@ Order = user-visible value first; each ships with backend + UI + tests. - [ ] QQ Connect (non-OIDC protocol, separate integration), account linking UI for existing local accounts, group/role claim mapping 4. **VAS/monetization-free** — credits + redemption codes as *free* features (gift codes for admin use), storage/membership plan definitions; skip payment processor integration initially — YAGNI until a real user asks (fixes #3231) 5. **System extensions** — activity/audit log surfaced in admin, site announcements, report-abuse queue (fixes #3480, #3479 IP whitelist) + - [x] PR #144 — task `creator_ip` capture with CIDR-capable admin filter (#115 OSS half), group remote-download quotas per count + per volume (#16), yt-dlp downloader provider (#88), progressive image preview (#113), v3 migrator `DatabaseURL` passthrough (#42) ## 5. Phase C — security + quality - Own security review on top of upstream fixes: session/token entropy audit, SSRF guard re-test (NAT64 class), rate limiting on auth endpoints - Fix upstream bug backlog by impact: ~~#3574 OOM~~ (done — paged tree walk + batched delete), ~~#3118/#3005 WebDAV large-file~~ (done — Content-Range assembly into one session; non-local policies get honest 501; single-PUT giant-file 500s are proxy/client timeouts, not fixable server-side), ~~#3375 SMTP auth discovery~~ (done — `smtp_auth` setting) - #3454 (PG FK on upload) is **Pro-only** — `audit_logs` doesn't exist in this codebase. When B.5 adds our own audit log: insert the audit row in the same tx *after* the file row, never before. -- `desloppify` + `security-reviewer` passes; scorecard appended to README +- [x] `desloppify` pass — 73 review items dispositioned (46 fixed, 27 honestly skipped), strict score 77.1 (was 18.9); scorecard lives in README. `security-reviewer` pass done incrementally per batch (OAuth secrets, SSRF, process exec, path safety) ## 6. Phase D — desktop, all platforms