簡(jiǎn)介Cloudreve 個(gè)人網(wǎng)盤(pán)系統(tǒng)源碼基于 Go 框架開(kāi)發(fā)面向需要自建私有云盤(pán)的個(gè)人站長(zhǎng)、小型團(tuán)隊(duì)或開(kāi)發(fā)者解決主流網(wǎng)盤(pán)限速、漲價(jià)和數(shù)據(jù)自主管控等痛點(diǎn)。系統(tǒng)支持本地存儲(chǔ)及七牛、阿里云 OSS、騰訊云 COS、又拍云、OneDrive 等云存儲(chǔ)驅(qū)動(dòng)后端采用 Go 與 Gin前端采用 React、Redux 和 Material-UI具備文件管理、分享鏈接、訪問(wèn)密碼、有效期、下載次數(shù)限制、多用戶(hù)管理和權(quán)限控制等功能部署簡(jiǎn)單適合二次開(kāi)發(fā)。資源包為 zip 格式共 341 個(gè)文件大小約 594KB以 314 個(gè) Go 源碼文件為主另含 Dockerfile、YAML 配置、Markdown 說(shuō)明文檔和前端相關(guān)文件目錄覆蓋 API 測(cè)試、WebDAV 客戶(hù)端、管理模塊等結(jié)構(gòu)清晰便于按模塊學(xué)習(xí)。目前已有 656 人學(xué)習(xí)/下載適合具備一定 Go 基礎(chǔ)、對(duì)云存儲(chǔ)對(duì)接與網(wǎng)盤(pán)權(quán)限設(shè)計(jì)感興趣的開(kāi)發(fā)者通過(guò)閱讀源碼可以掌握多存儲(chǔ)驅(qū)動(dòng)接入方式、分享鏈接權(quán)限控制機(jī)制、用戶(hù)體系與文件管理模塊的實(shí)現(xiàn)思路也能參考其前后端組織方式用于個(gè)人網(wǎng)盤(pán)項(xiàng)目的擴(kuò)展與改造。1. Cloudreve 是什么一臺(tái)小機(jī)器就能撐起的個(gè)人網(wǎng)盤(pán)源碼背后是一套云存儲(chǔ)抽象層如果你手里有一臺(tái) 1 核 2G 的小服務(wù)器想把它變成能分享文件、能離線下載的個(gè)人網(wǎng)盤(pán)Cloudreve 大概是目前最省事的方案之一。它是一個(gè)基于 Go 框架開(kāi)發(fā)的開(kāi)源項(xiàng)目官方發(fā)布的是編譯好的單文件二進(jìn)制而標(biāo)題里的“源碼”意味著你還可以直接拉倉(cāng)庫(kù)自行構(gòu)建改邏輯、加存儲(chǔ)后端、做成私有化版本都不受限制。Cloudreve 最核心的思路不是把磁盤(pán)塞進(jìn)自己的程序里而是把存儲(chǔ)這件事抽象了一層本機(jī)磁盤(pán)、七牛、阿里云 OSS、騰訊云 COS、又拍云、OneDrive 都算“存儲(chǔ)策略”你只需在網(wǎng)盤(pán)里建策略上傳文件時(shí)選策略后端會(huì)自動(dòng)把數(shù)據(jù)寫(xiě)到對(duì)應(yīng)的對(duì)象存儲(chǔ)或云盤(pán)上。也就是說(shuō)你的服務(wù)器只是控制面和流量中轉(zhuǎn)數(shù)據(jù)本體不占本地磁盤(pán)擴(kuò)容也變成“給 Bucket 充值”而不是“給服務(wù)器加盤(pán)”。這套設(shè)計(jì)對(duì)我來(lái)說(shuō)最大的價(jià)值是小機(jī)器可以把內(nèi)存省給 PHP、OCR 這類(lèi)其他服務(wù)網(wǎng)盤(pán)本身的內(nèi)存占用長(zhǎng)期維持在 80MB 上下。接下來(lái)我把從源碼編譯、Docker 部署到對(duì)接各種云存儲(chǔ)后端的完整路徑拆開(kāi)講包括那些文檔里不寫(xiě)但一定會(huì)翻車(chē)的細(xì)節(jié)。2. 選型理由Go 單二進(jìn)制和存儲(chǔ)策略抽象為什么它適合個(gè)人網(wǎng)盤(pán)場(chǎng)景2.1 從源碼構(gòu)建為什么單二進(jìn)制能這么小以及編譯時(shí)需要關(guān)注什么Cloudreve 的前端是 Vue 寫(xiě)的構(gòu)建后被打包進(jìn) Go 的 embed 文件系統(tǒng)里。最終產(chǎn)物只有一個(gè)可執(zhí)行文件連靜態(tài)資源都不需要單獨(dú)放在磁盤(pán)上。這對(duì)服務(wù)器運(yùn)維的意義很大沒(méi)有 Node 運(yùn)行時(shí)依賴(lài)、沒(méi)有 PHP-FPM、沒(méi)有一堆配置文件兜底拷過(guò)去就能跑哪怕跑在 ARM 板子上也只是交叉編譯的事。從源碼構(gòu)建的常見(jiàn)做法是先拉倉(cāng)庫(kù)再按版本打 tag。Go 的構(gòu)建命令本身不復(fù)雜git clone --recurse-submodules https://github.com/cloudreve/Cloudreve.git cd Cloudreve # 編譯前端資源Cloudreve 需要先構(gòu)建靜態(tài)頁(yè)面再嵌入二進(jìn)制 cd frontend yarn install yarn build cd .. # 回到主目錄打包靜態(tài)資源和后端代碼 go build -o cloudreve -ldflags -s -w -tags embed參數(shù)說(shuō)明-tags embed是關(guān)鍵它告訴 Go 編譯器把frontend/dist目錄內(nèi)的內(nèi)容嵌進(jìn)二進(jìn)制的embed.FS如果不加這個(gè) tag程序能編譯過(guò)但跑起來(lái)首頁(yè)會(huì)白屏因?yàn)殪o態(tài)資源沒(méi)進(jìn)去。-ldflags -s -w是去掉符號(hào)表和調(diào)試信息的常用做法二進(jìn)制體積能縮減約 20%。另外建議編譯前先跑一遍go mod tidy確認(rèn)依賴(lài)完整Cloudreve 的依賴(lài)?yán)锇琯olang.org/x/crypto這類(lèi)基礎(chǔ)庫(kù)網(wǎng)絡(luò)環(huán)境不干凈時(shí)下載會(huì)卡住但我不展開(kāi)講這個(gè)。編譯好之后直接運(yùn)行./cloudreve首次啟動(dòng)會(huì)在當(dāng)前目錄生成conf.ini和cloudreve.db。需要注意Cloudreve 默認(rèn)使用 SQLite數(shù)據(jù)庫(kù)文件就一個(gè)備份非常方便但并發(fā)寫(xiě)入能力弱。如果你要跑公共分享站或小團(tuán)隊(duì)使用建議一開(kāi)始就切到 MySQL。2.2 存儲(chǔ)策略機(jī)制從“文件夾”到“存儲(chǔ)后端”的一層映射Cloudreve 里的存儲(chǔ)策略Storage Policy是整個(gè)網(wǎng)盤(pán)的地基。理解它之后多后端對(duì)接就不難了。策略的本質(zhì)是一個(gè) JSON 配置里面寫(xiě)著后端類(lèi)型、是否生成直鏈、URL 規(guī)則、上傳方式等。用戶(hù)創(chuàng)建目錄時(shí)可以給目錄指定某一個(gè)策略上傳文件時(shí)文件會(huì)被寫(xiě)入該策略對(duì)應(yīng)的存儲(chǔ)后端。同一個(gè)網(wǎng)盤(pán)里可以同時(shí)存在多個(gè)策略比如把個(gè)人文件放 OneDrive把分享出去的視頻放 OSS借此分?jǐn)偭髁砍杀?。策略有點(diǎn)像一個(gè)“轉(zhuǎn)賬接口”你決定數(shù)據(jù)落在哪個(gè)后端而不是數(shù)據(jù)怎么組織。Cloudreve 的驅(qū)動(dòng)器層會(huì)按照策略配置把本地文件、七牛/OSS/COS/又拍這類(lèi) S3 兼容對(duì)象存儲(chǔ)、OneDrive 這種網(wǎng)盤(pán)統(tǒng)一成一個(gè)接口。上層的文件表、分享表、用戶(hù)表都只記錄文件元數(shù)據(jù)和策略 ID不關(guān)心文件真實(shí)存儲(chǔ)位置。這帶來(lái)的好處是遷移存儲(chǔ)后端時(shí)不需要?jiǎng)尤魏斡脩?hù)數(shù)據(jù)——把策略改一下新上傳的文件就去了新地方老文件仍然留在原桶里通過(guò)調(diào)整策略的 URL 規(guī)則繼續(xù)訪問(wèn)。權(quán)限模型上Cloudreve 將用戶(hù)分組每個(gè)組能看到的存儲(chǔ)策略列表是可配置的。比如游客組只能用“下載”策略上傳組才能用“雨季大文件”策略。這塊配置在后臺(tái)管理面板里完成與源碼層面的策略 JSON 是兩個(gè)層次別搞混JSON 決定文件寫(xiě)到哪、用什么方式寫(xiě)后臺(tái)配置決定誰(shuí)能用哪個(gè)策略。從源碼角度去看策略實(shí)現(xiàn)會(huì)發(fā)現(xiàn) Cloudreve 把每個(gè)后端都實(shí)現(xiàn)了一套 driver 接口接口里定義了Put、Delete、Get、Thumb等方法。如果你要接一個(gè)新的私有存儲(chǔ)理論上只需新增一個(gè) driver 文件并注冊(cè)到drivers包里。這就是它作為可二次開(kāi)發(fā)項(xiàng)目的核心擴(kuò)展點(diǎn)。3. 跑通最小可用系統(tǒng)源碼構(gòu)建 Docker 編排把阿里云 OSS 掛成本地目錄3.1 兩種部署方式怎么選Docker Compose 更適合帶 MySQL 的正式環(huán)境Cloudreve 官方提供了 Docker 鏡像適合不想折騰編譯、想把網(wǎng)盤(pán)當(dāng)黑盒用的場(chǎng)景。我個(gè)人推薦用 Docker Compose 同時(shí)起cloudreve和mysql兩個(gè)容器因?yàn)?SQLite 在網(wǎng)盤(pán)使用量上來(lái)以后會(huì)頻繁地出現(xiàn)“database is locked”。下面是我常用的編排文件骨架version: 3.7 services: cloudreve: image: cloudreve/cloudreve:latest container_name: cloudreve ports: - 5212:5212 volumes: - ./data:/data - ./conf.ini:/data/conf.ini environment: - TZAsia/Shanghai depends_on: - db restart: unless-stopped db: image: mysql:8.0 container_name: cloudreve-db environment: MYSQL_ROOT_PASSWORD: rootpw MYSQL_DATABASE: cloudreve MYSQL_USER: cloudreve MYSQL_PASSWORD: cloudrevepw volumes: - ./mysql:/var/lib/mysql restart: unless-stopped這里的conf.ini是 Cloudreve 的主配置首次啟動(dòng)后容器會(huì)把默認(rèn)配置拷貝到掛載目錄。注意如果你把conf.ini也放進(jìn)./data下路徑要寫(xiě)成/data/conf.ini否則 Docker 不會(huì)自動(dòng)生成Cloudreve 啟動(dòng)會(huì)直接報(bào)錯(cuò)退出。而 MySQL 容器先于 Cloudreve 啟動(dòng)是因?yàn)?Cloudreve 啟動(dòng)時(shí)會(huì)檢查數(shù)據(jù)庫(kù)連通性連接失敗會(huì)直接退出不會(huì)自動(dòng)等待。3.2 conf.ini 里的關(guān)鍵參數(shù)session_secret、數(shù)據(jù)庫(kù)連接和監(jiān)聽(tīng)地址Cloudreve 的conf.ini是 INI 格式按[System]、[Database]、[Redis]分節(jié)。第一次啟動(dòng)后會(huì)自動(dòng)生成默認(rèn)值但有兩個(gè)參數(shù)必須手動(dòng)改一個(gè)是[System]下的session_secret默認(rèn)是隨機(jī)字符串容器重啟不會(huì)變但不改的話副作用是登錄態(tài)在進(jìn)程重啟后被重置所有人被迫重新登錄另一個(gè)是數(shù)據(jù)庫(kù)連接串如果你用 SQLite 就保持空著在 Docker 里換成 MySQL 時(shí)這樣寫(xiě)[System] ; 監(jiān)聽(tīng)地址和端口 Listen :5212 ; 登錄會(huì)話密鑰必須手動(dòng)改成隨機(jī)長(zhǎng)字符串 session_secret a-random-string-at-least-32-bytes-long ; 首次運(yùn)行后是否初始化管理員賬號(hào) ; 0 會(huì)要求命令行初始化建議保持 0 Initialized 0 [Database] ; 留空使用 SQLite Type mysql ; MySQL 連接參數(shù) Host 127.0.0.1 Port 3306 User cloudreve Password cloudrevepw Name cloudreve Charset utf8mb4參數(shù)說(shuō)明Listen端口默認(rèn) 5212如果前面有 Nginx務(wù)必讓 Nginx 把proxy_pass指向http://127.0.0.1:5212否則跨域和 WebSocket 都會(huì)出問(wèn)題。Initialized 0時(shí)進(jìn)程啟動(dòng)后會(huì)在控制臺(tái)輸出管理員賬號(hào)一次性密碼這個(gè)信息只會(huì)出現(xiàn)一次建議立即登錄后臺(tái)改掉。Docker 部署時(shí)容器日志同樣可以看到注意別把日志輸出到公網(wǎng)日志平臺(tái)。數(shù)據(jù)庫(kù)這部分我吃過(guò)虧Charset寫(xiě)成utf8而不是utf8mb4用戶(hù)上傳帶 emoji 的文件名時(shí)數(shù)據(jù)庫(kù)寫(xiě)入直接報(bào)錯(cuò)文件存進(jìn)去了但列表里看不到。后來(lái)統(tǒng)一用utf8mb4問(wèn)題就消失了。如果你接手一個(gè)已經(jīng)建好的表改完字符集后要手動(dòng)執(zhí)行ALTER TABLE轉(zhuǎn)換光改配置不生效。3.3 綁定阿里云 OSS創(chuàng)建存儲(chǔ)策略存下來(lái)直接可用接下來(lái)是真正把 OSS 掛進(jìn)來(lái)的步驟。后臺(tái)登錄后進(jìn)入“管理面板 → 存儲(chǔ)策略 → 創(chuàng)建新策略”。你需要準(zhǔn)備 OSS 的AccessKeyId和AccessKeySecretBucket 名、Region 和 Endpoint 是另一個(gè)概念別選錯(cuò)。{ base_url: https://your-custom-domain.example.com, UploadURL: https://oss-cn-hangzhou.aliyuncs.com, DownloadURL: https://your-custom-domain.example.com, AccessKeyId: xxxxxxxxxxxxxxxx, AccessKeySecret: yyyyyyyyyyyyyyyy, BucketName: my-cloudreve-files, Region: oss-cn-hangzhou, Endpoint: oss-cn-hangzhou.aliyuncs.com, IsPrivate: false, IsCNAME: true }這段 JSON 在 Cloudreve 的 OSS 策略配置里對(duì)應(yīng)字段。幾個(gè)容易出錯(cuò)的點(diǎn)BaseURL是文件對(duì)外服務(wù)的域名如果走自定義 CNAME 回源加速必須寫(xiě)https://your-domain.com并且該域名要在 OSS 控制臺(tái)綁定 BucketUploadURL和Endpoint很多人看成同一個(gè)東西但它們不一定相等——如果你的服務(wù)器和 OSS 在同地域可以用內(nèi)網(wǎng) Endpoint 走內(nèi)網(wǎng)上傳流量費(fèi)為零。IsCNAME表示是否使用自定義域名訪問(wèn)開(kāi)啟后 DownloadURL 里的域名才會(huì)生效否則文件直鏈會(huì)生成到 OSS 默認(rèn)域名隱私空間下會(huì)有防盜鏈問(wèn)題。配置完后回到云存儲(chǔ)根目錄新建一個(gè)文件夾給文件夾指定這個(gè)策略測(cè)試上傳。上傳驗(yàn)證的最快方法不是點(diǎn)網(wǎng)頁(yè)而是直接構(gòu)造一個(gè) PUT 請(qǐng)求curl -X PUT https://your-domain.com/upload/test.txt \ -H Authorization: Bearer 登錄后的 Cookie 或 Token \ -d hello cloudreve如果返回201或200且文件出現(xiàn)在 OSS 桶里策略就通了。如果返回 403優(yōu)先檢查IsPrivate字段私有 Bucket 需要 Cloudreve 每次生成帶簽名的 URLIsPrivate必須為true否則前端拿不到文件內(nèi)容。4. 存儲(chǔ)后端差異化接入七牛、騰訊云 COS、又拍云、OneDrive 的配置邊界4.1 各后端的選型對(duì)比哪些適合直傳哪些必須走回調(diào)Cloudreve 的存儲(chǔ)策略在底層對(duì)每個(gè)后端都做了適配但它們的行為差異很大。我整理了一張表按我自己的使用體驗(yàn)排了優(yōu)先級(jí)后端上傳模式外鏈與自定義域名典型問(wèn)題阿里云 OSS直傳客戶(hù)端直傳 Bucket支持 CNAME 自定義域名簽名 URL 支持跨域配置復(fù)雜私有讀下載要走簽名騰訊云 COS直傳支持自定義域名簽名 URL 支持Endpoint 多了個(gè)cos.前綴容易寫(xiě)錯(cuò)七牛云 Kodo直傳或回調(diào)上傳強(qiáng)制使用測(cè)試域名或綁定 CDN 域名測(cè)試域名有 30 天有效期正式用必須綁 CDN又拍云表單回調(diào)必須配置服務(wù)名和操作員依賴(lài)回調(diào)地址公網(wǎng)可達(dá)否則上傳后不落盤(pán)OneDrive授權(quán)后服務(wù)端中轉(zhuǎn)不支持自定義域名直鏈需要 Application 權(quán)限和定時(shí)刷新 Token選型建議如果想讓用戶(hù)上傳大文件時(shí)服務(wù)器內(nèi)存不炸優(yōu)先選支持“直傳”的 OSS、COS 和 Kodo。直傳模式下瀏覽器或客戶(hù)端直接把文件傳到 BucketCloudreve 只負(fù)責(zé)生成臨時(shí)憑證和記錄元數(shù)據(jù)。相反又拍云默認(rèn)是表單異步回調(diào)文件先到又拍服務(wù)器又拍再回調(diào)你的 Cloudreve 地址如果你的服務(wù)器沒(méi)有公網(wǎng) IP 或回調(diào)地址被防火墻擋了文件就永遠(yuǎn)不回記錄。4.2 OneDrive 授權(quán)流程從 Azure 注冊(cè)應(yīng)用到 Token 刷新難點(diǎn)全在“回調(diào)”O(jiān)neDrive 是這套方案里特殊的一環(huán)。它不提供對(duì)象存儲(chǔ)式的 Bucket而是直接操作微軟網(wǎng)盤(pán)。Cloudreve 需要拿到你 Azure AD現(xiàn)在叫 Entra ID應(yīng)用的 client_id、client_secret然后通過(guò) OAuth 授權(quán)獲取 access_token 和 refresh_token。授權(quán)完成后Cloudreve 會(huì)把文件寫(xiě)到這個(gè) OneDrive 賬號(hào)的固定目錄下。操作上需要先到 Azure Portal 注冊(cè)一個(gè)應(yīng)用設(shè)置 Redirect URI 為你的 Cloudreve 回調(diào)地址格式一般是https://你的域名/api/v3/oauth/onedrive。然后給應(yīng)用添加Files.ReadWrite和offline_access權(quán)限先拿到授權(quán)碼再換取 token。這里有個(gè)坑token 有效期短Cloudreve 會(huì)用 refresh_token 自動(dòng)續(xù)期但refresh_token在微軟側(cè)有最長(zhǎng)生命周期一旦超過(guò)有效期網(wǎng)盤(pán)會(huì)進(jìn)入“只讀”狀態(tài)上傳直接報(bào) 401。我的經(jīng)驗(yàn)是把 OneDrive 策略的“自動(dòng)刷新 Token”開(kāi)關(guān)打開(kāi)并且在服務(wù)器上用 cron 每 10 分鐘請(qǐng)求一次 Cloudreve 的/api/v3/oauth/onedrive狀態(tài)接口檢查 token 是否還有效。無(wú)效時(shí)的處理不是手工重新授權(quán)而是用 refresh_token 重新拉一次 token然后寫(xiě)回?cái)?shù)據(jù)庫(kù)的存儲(chǔ)策略表。更省心的方案是如果 OneDrive 只是個(gè)人備份用途干脆把它的優(yōu)先級(jí)放低不要讓它承擔(dān)大流量分享因?yàn)槲④?API 限流很快下載量大時(shí)接口會(huì)間歇性返回 429。4.3 自定義域名/CORS 配置直傳模式下最容易忽略的跨域和 Referer 防盜鏈直傳模式下瀏覽器從your-domain.com發(fā)起請(qǐng)求目標(biāo)卻是oss-cn-hangzhou.aliyuncs.com這一看就是跨域。OSS 控制臺(tái)里要給 Bucket 配置 CORS 規(guī)則允許的來(lái)源寫(xiě)上你的后臺(tái)域名允許的方法至少包含GET, PUT, POST, DELETE, HEADExposeHeaders里要加上ETag否則 Cloudreve 拿不到文件校驗(yàn)值上傳后可能顯示“校驗(yàn)失敗”。COS 和 Kodo 的 CORS 配置同理但它們默認(rèn)允許的規(guī)則比 OSS 寬松很多場(chǎng)景不配也能跑等到瀏覽器報(bào) Red Block 錯(cuò)誤時(shí)再回頭補(bǔ)。防盜鏈上OSS、COS 和七牛都支持“Referer 黑白名單”。如果你希望文件只能被自己的站點(diǎn)頁(yè)面引用可以把白名單填成*.your-domain.com。但要注意這個(gè)規(guī)則會(huì)誤傷 OneDrive 這種服務(wù)端下載模式因?yàn)榉?wù)端下載時(shí) Referer 可能是空的容易被規(guī)則攔截。所以防盜鏈建議只加在純直鏈的 Bucket 策略上別全局套用。5. 部署常見(jiàn)坑上傳卡 99%、離線下載失敗、回調(diào)驗(yàn)簽不過(guò)這幾件事5.1 上傳 99% 一直轉(zhuǎn)圈Nginx 默認(rèn)限制和表單大小上限現(xiàn)象小文件秒傳成功超過(guò) 100MB 的文件進(jìn)度條走到 99% 就停住過(guò)一會(huì)兒提示上傳失敗。原因Cloudreve 本身沒(méi)有限制上傳體積但 Nginx 默認(rèn)client_max_body_size只有 1MB超過(guò)后直接返回 413。另一種情況是反向代理沒(méi)有配置超時(shí)大文件上傳時(shí)間超過(guò)proxy_read_timeout的默認(rèn) 60 秒代理主動(dòng)斷開(kāi)連接。解決在 Nginx 的 server 塊中顯式調(diào)整server { listen 80; server_name pan.example.com; client_max_body_size 20g; proxy_read_timeout 600s; proxy_send_timeout 600s; location / { proxy_pass http://127.0.0.1:5212; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }client_max_body_size根據(jù)你的實(shí)際需求調(diào)整20g 是常見(jiàn)上限。同時(shí)如果是直傳 OSSNginx 這個(gè)值其實(shí)只影響 Cloudreve 的 API 轉(zhuǎn)發(fā)瀏覽器到 OSS 的直傳流量并不走你的 Nginx所以別以為調(diào)了 Nginx 就能解決所有上傳慢的問(wèn)題真正瓶頸可能在 OSS 公網(wǎng)帶寬或跨地域鏈路。5.2 文件傳上去了列表里看不到SQLite 鎖沖突與分庫(kù)建議現(xiàn)象上傳完成但刷新后文件不在目錄里管理后臺(tái)能看到記錄用戶(hù)端列表為空。原因最常見(jiàn)的是 SQLite 在并發(fā)寫(xiě)入時(shí)鎖沖突。Cloudreve 的文件記錄寫(xiě)入和其他查詢(xún)業(yè)務(wù)在同一數(shù)據(jù)庫(kù)文件上上傳高峰時(shí)多個(gè)寫(xiě)事務(wù)同時(shí)發(fā)生SQLite 會(huì)隨機(jī)拒掉一部分寫(xiě)入程序沒(méi)有重試機(jī)制最終導(dǎo)致文件未入庫(kù)。其次是列表中勾選了“只顯示已上傳完成”的狀態(tài)過(guò)濾上傳中斷剩下的臨時(shí)記錄被過(guò)濾掉。解決長(zhǎng)期方案是換 MySQL我前面給的 Compose 編排里直接帶 MySQL 就是為了避免這個(gè)坑。臨時(shí)方案是手動(dòng)去 SQLite 里查一下記錄狀態(tài)sqlite3 cloudreve.db select id, file_name, status, size from files;如果有status 0或upload_session_id存在但文件不完整把對(duì)應(yīng)記錄刪掉讓用戶(hù)重新上傳。記一條血淚經(jīng)驗(yàn)個(gè)人網(wǎng)盤(pán)前期用 SQLite 完全夠但一旦掛到公網(wǎng)并有幾十個(gè)人同時(shí)傳文件就必須提前換 MySQL否則某個(gè)周末流量高峰時(shí)你會(huì)收到一堆“傳不上去”的反饋。5.3 離線下載總是失敗提示超時(shí)或找不到下載器現(xiàn)象粘貼一個(gè)磁力鏈或 HTTP 下載鏈接任務(wù)在后臺(tái)停留幾分鐘后提示失敗。原因Cloudreve 本身不實(shí)現(xiàn)下載協(xié)議它依賴(lài)外部命令aria2或rclone。Docker 鏡像默認(rèn)不含這兩個(gè)組件所以你從鏡像直接啟動(dòng)離線下載面板就像個(gè)擺設(shè)。另外容器內(nèi)的aria2需要配置 RPC 地址默認(rèn)是http://localhost:6800/jsonrpc如果容器里沒(méi)起 aria2 服務(wù)Cloudreve 連不上。解決使用支持aria2的鏡像版本或者在宿主機(jī)裝好aria2后在 Cloudreve 管理后臺(tái)把 RPC 地址指向宿主機(jī)的 IP 和端口[aria2] rpc_server http://127.0.0.1:6800/jsonrpc rpc_secret your-secret同時(shí)確認(rèn) aria2 啟動(dòng)時(shí)開(kāi)啟 RPC 模式aria2c --enable-rpctrue --rpc-listen-alltrue --rpc-secretyour-secret --dir/downloads注意rpc-secret要和 Cloudreve 后臺(tái)填的一致否則任務(wù)提交后會(huì)被 aria2 拒絕。反過(guò)來(lái)說(shuō)如果你根本不需要離線下載可以無(wú)視這個(gè)報(bào)錯(cuò)因?yàn)榫W(wǎng)盤(pán)核心功能不受影響。5.4 用自定義域名訪問(wèn)后臺(tái)登錄后自動(dòng)退出Session 域校驗(yàn)問(wèn)題現(xiàn)象用 IP 訪問(wèn)一切正常換成域名登錄后一刷新就回到登錄頁(yè)。原因Cloudreve 的 Session Cookie 默認(rèn)綁定在 IP 或初始域名上。首次用 IP 啟動(dòng)后后來(lái)?yè)Q成域名Session Cookie 的 Domain 不匹配瀏覽器不發(fā)送 Cookie后端自然認(rèn)為未登錄。解決修改conf.ini里的session_domain為你的域名并保證前后訪問(wèn)方式一致。如果已經(jīng)用 IP 登錄過(guò)先清除瀏覽器 Cookie 再重新登錄。這個(gè)坑在本地調(diào)試時(shí)最容易踩本地用localhost:5212部署后改用pan.example.com不刷新 Cookie 就始終卡在登錄頁(yè)。6. 進(jìn)階技巧用定時(shí)備份與策略隔離把 Cloudreve 變成一臺(tái)可靠的家庭數(shù)據(jù)樞紐到這里部署和存儲(chǔ)對(duì)接基本收尾最后說(shuō)兩個(gè)讓這套系統(tǒng)長(zhǎng)期穩(wěn)定跑下去的維護(hù)手段都是我踩過(guò)坑之后才加上的。第一是數(shù)據(jù)庫(kù)備份。Cloudreve 的元數(shù)據(jù)都集中在cloudreve.dbSQLite或 MySQL 里文件本體分散在各存儲(chǔ)桶。備份時(shí)不要想著把文件也拷一份那是存儲(chǔ)后端的活。我習(xí)慣每天凌晨 3 點(diǎn)用sqlite3做在線備份而不是直接cp數(shù)據(jù)庫(kù)文件因?yàn)?SQLite 在寫(xiě)入時(shí)直接復(fù)制文件會(huì)得到損壞的備份sqlite3 /path/to/cloudreve.db .backup /backup/cloudreve_$(date \%F).dbSQLite 的.backup命令利用在線備份 API能保證一致性。如果跑 MySQL就用mysqldump加上單事務(wù)參數(shù)。備份文件保留 14 天配合云存儲(chǔ)的跨區(qū)域復(fù)制基本能做到任意一天故障可恢復(fù)。第二是離線下載目錄的定期清理。aria2 下載的文件會(huì)堆在/downloads不清理的話磁盤(pán)遲早被填滿。我一般在宿主機(jī)掛一個(gè)定時(shí)任務(wù)把超過(guò) 7 天沒(méi)被 Cloudreve 記錄引用的臨時(shí)文件刪掉find /downloads -type f -mtime 7 -delete這個(gè)做法的前提是Cloudreve 會(huì)把下載完成的文件轉(zhuǎn)移進(jìn)存儲(chǔ)策略轉(zhuǎn)移完成后/downloads里只剩臨時(shí)文件。如果你的策略沒(méi)有啟用“下載后自動(dòng)轉(zhuǎn)移”這個(gè)命令會(huì)把已下載文件一起刪掉所以務(wù)必先確認(rèn)策略配置里勾了“離線下載完成后自動(dòng)轉(zhuǎn)存”。我用 Cloudreve 已經(jīng)三年最大的感受是它把“網(wǎng)盤(pán)”拆成了清晰的兩層上層是文件和分享邏輯下層是可替換的云存儲(chǔ)驅(qū)動(dòng)。源碼級(jí)擴(kuò)展能力的價(jià)值在于當(dāng)你不滿足于內(nèi)置后端時(shí)可以照著 driver 接口寫(xiě)自己的私有實(shí)現(xiàn)。希望這些配置和踩坑記錄能幫到你——至少讓你在一開(kāi)始就避開(kāi)我當(dāng)年夜里爬起來(lái)?yè)Q配置的那些彎路。本文還有配套的精品資源點(diǎn)擊獲取