簡(jiǎn)介這是一套基于 C# 與 Windows 前端技術(shù)實(shí)現(xiàn)的原創(chuàng)私人博客云盤系統(tǒng)源碼面向具備一定 C# 桌面開發(fā)基礎(chǔ)、希望研究客戶端與云盤結(jié)合場(chǎng)景的開發(fā)者。系統(tǒng)同時(shí)支持博客與文件管理兩條主線博客側(cè)可發(fā)表、刪除、點(diǎn)贊、收藏后臺(tái)提供資料修改、第三方綁定、安全驗(yàn)證政策與賬號(hào)注銷文件側(cè)覆蓋上傳、下載、斷點(diǎn)續(xù)傳、刪除、重命名、空間管理及單文件大小限制適合作為課程設(shè)計(jì)、畢業(yè)設(shè)計(jì)或二次開發(fā)底座。壓縮包共 875 個(gè)文件約 255.56MB以 png 界面素材、cs 源碼、resources 資源、dll 依賴庫與 js 腳本為主另含 resx、xml、config、csproj、sln 等工程配置目錄結(jié)構(gòu)完整可直接用 Visual Studio 打開編譯。目前已有 149 人學(xué)習(xí)下載讀者可借此理清客戶端分層架構(gòu)、文件續(xù)傳與空間配額等實(shí)現(xiàn)思路并在此基礎(chǔ)上擴(kuò)展為公共博客平臺(tái)。1. 博客系統(tǒng) Windows 客戶端 v1.2.6把寫作流從瀏覽器里拽回桌面如果你每天要在瀏覽器里開七八個(gè)標(biāo)簽頁寫博客后臺(tái)、預(yù)覽、圖床、Markdown 編輯器來回切那你大概率想過一個(gè)問題能不能有一個(gè) Windows 客戶端把「寫、存、傳、發(fā)」四件事收進(jìn)一個(gè)窗口。博客系統(tǒng) Windows 客戶端 v1.2.6 就是沖這個(gè)場(chǎng)景來的——它不是把網(wǎng)頁套個(gè)殼而是把本地草稿、離線編輯、圖片處理和發(fā)布鏈路重新編排了一遍。適合誰適合長(zhǎng)期用 Markdown 寫作、對(duì)本地文件有掌控欲、又不想每次發(fā)布都手動(dòng)復(fù)制粘貼的獨(dú)立博主和小團(tuán)隊(duì)內(nèi)容維護(hù)者。這一版把重點(diǎn)放在草稿同步和發(fā)布前校驗(yàn)上下面按「能跑起來、能配好、能排錯(cuò)」的順序拆開講。2. 先定架構(gòu)再動(dòng)手客戶端到底該管哪幾層2.1 為什么不做純 WebView 套殼很多桌面客戶端的第一反應(yīng)是套一個(gè) WebView把網(wǎng)頁直接塞進(jìn)去。這個(gè)做法在 v1.0 階段能快速出東西但到了 v1.2.6 這種要處理本地草稿、圖片壓縮、斷網(wǎng)續(xù)寫的版本套殼的代價(jià)就暴露了文件系統(tǒng)訪問要繞橋接本地緩存和遠(yuǎn)端狀態(tài)容易打架編輯器光標(biāo)位置在刷新后丟失。我一般會(huì)把客戶端拆成三層——渲染層負(fù)責(zé)編輯和預(yù)覽本地服務(wù)層負(fù)責(zé)草稿落盤和圖片處理同步層負(fù)責(zé)和博客系統(tǒng)后端對(duì)接口。三層之間用明確的 JSON 消息通信而不是讓渲染層直接調(diào)系統(tǒng) API。這樣做的直接好處是斷網(wǎng)時(shí)你還能寫圖片先在本地排隊(duì)恢復(fù)網(wǎng)絡(luò)后再補(bǔ)傳。2.2 本地草稿的存儲(chǔ)結(jié)構(gòu)怎么定草稿不能只存一份。常見做法是「工作副本 快照」兩級(jí)工作副本是當(dāng)前正在編輯的文件快照是每次保存時(shí)按時(shí)間戳留的版本。目錄結(jié)構(gòu)建議這樣組織避免文件名沖突和跨盤符問題# 草稿根目錄結(jié)構(gòu)示例Windows 路徑 D:\BlogClient\drafts\ ├── index.json # 草稿索引id、標(biāo)題、更新時(shí)間、遠(yuǎn)端狀態(tài) ├── 2024-06-01\ │ ├── post-a.md # 工作副本 │ └── post-a.snap\ # 快照目錄 │ ├── 1717200000.md │ └── 1717286400.md └── assets\ └── pending\ # 待上傳圖片隊(duì)列index.json是同步層的唯一真相來源每次啟動(dòng)先讀它再和遠(yuǎn)端拉一次列表做 diff?？煺漳夸浻?Unix 時(shí)間戳命名避免中文標(biāo)題和特殊字符帶來的路徑問題。pending目錄里的圖片在上傳成功后會(huì)移到uploaded失敗則保留并記錄重試次數(shù)。2.3 同步層的最小接口約定同步層不需要一開始就做得很復(fù)雜但接口要定清楚。我一般會(huì)約定四個(gè)動(dòng)作拉取遠(yuǎn)端列表、推送本地草稿、上傳單張圖片、拉取單篇正文。每個(gè)動(dòng)作都帶一個(gè)client_version字段后端可以據(jù)此做兼容。下面是一個(gè)推送草稿的請(qǐng)求體示例{ action: push_draft, client_version: 1.2.6, draft_id: local-20240601-001, title: 示例文章, content_md: # 正文..., updated_at: 1717286400, assets: [assets/pending/img-001.png] }draft_id用本地生成、遠(yuǎn)端回寫的方式避免兩端 ID 體系沖突。updated_at用秒級(jí)時(shí)間戳服務(wù)端比較后決定是否覆蓋。assets只傳相對(duì)路徑實(shí)際文件走單獨(dú)的上傳接口這樣正文推送不會(huì)被大圖拖慢。3. 把 v1.2.6 在本地跑起來環(huán)境、配置與首次發(fā)布3.1 運(yùn)行環(huán)境與依賴檢查在 Windows 上跑這個(gè)客戶端先確認(rèn)三件事系統(tǒng)版本、運(yùn)行時(shí)、以及本地端口占用。v1.2.6 常見做法是依賴 .NET 桌面運(yùn)行時(shí)或 Node 運(yùn)行時(shí)取決于你的技術(shù)棧這里以 Node 側(cè)為例。先檢查版本再裝依賴# 檢查運(yùn)行時(shí)版本建議 Node 18 LTS 以上 node -v # 進(jìn)入客戶端目錄安裝依賴 cd D:\BlogClient\app npm install # 啟動(dòng)本地服務(wù)層默認(rèn)監(jiān)聽 127.0.0.1:17800 npm run start:localstart:local會(huì)拉起本地服務(wù)層渲染層再連這個(gè)端口。如果 17800 被占用改config/local.json里的port字段不要直接殺進(jìn)程。依賴安裝失敗時(shí)先看是不是鏡像源問題再檢查node_modules是否有權(quán)限寫入。3.2 配置文件里必須改的四個(gè)參數(shù)配置文件是新手最容易跳過、老手最容易改錯(cuò)的地方。下面這張表列出 v1.2.6 里我建議逐個(gè)確認(rèn)的字段參數(shù)名作用建議值注意api_base博客系統(tǒng)后端地址你的實(shí)際接口域名末尾不要帶斜杠draft_root本地草稿根目錄非系統(tǒng)盤路徑避免中文和空格image.max_width圖片壓縮最大寬度1600超過會(huì)等比縮小sync.interval自動(dòng)同步間隔秒120太短會(huì)增加后端壓力api_base寫錯(cuò)是最常見的翻車點(diǎn)表現(xiàn)為「保存成功但遠(yuǎn)端看不到」。draft_root放在 C 盤用戶目錄下重裝系統(tǒng)容易丟建議單獨(dú)放一個(gè)數(shù)據(jù)盤。image.max_width設(shè)太大上傳慢設(shè)太小正文里的圖會(huì)糊。sync.interval設(shè)成 10 秒以下草稿多的時(shí)候后端會(huì)收到大量重復(fù)請(qǐng)求。3.3 首次發(fā)布從本地草稿到遠(yuǎn)端可見首次發(fā)布建議走一遍完整鏈路確認(rèn)每一環(huán)都通。步驟是新建草稿、插入一張本地圖、點(diǎn)發(fā)布、去遠(yuǎn)端確認(rèn)。下面是一個(gè)模擬發(fā)布流程的腳本片段用來驗(yàn)證同步層是否正常// verify_publish.js // 用途模擬一次草稿推送檢查返回狀態(tài) const payload { action: push_draft, client_version: 1.2.6, draft_id: local-test-001, title: 連通性測(cè)試, content_md: # 測(cè)試\n\n這是一條本地驗(yàn)證草稿。, updated_at: Math.floor(Date.now() / 1000), assets: [] }; fetch(http://127.0.0.1:17800/api/push, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(payload) }) .then((res) res.json()) .then((data) { // 期望返回 ok:true 和遠(yuǎn)端 draft_id console.log(push result:, data); }) .catch((err) { // 本地服務(wù)層沒起來時(shí)這里會(huì)報(bào)連接拒絕 console.error(push failed:, err.message); });這段腳本直接打本地服務(wù)層不經(jīng)過界面用來判斷問題出在「界面到本地」還是「本地到遠(yuǎn)端」。如果這里返回ok:true但遠(yuǎn)端列表里沒有就去查同步層的遠(yuǎn)端接口配置。如果這里就報(bào)連接拒絕說明本地服務(wù)層沒啟動(dòng)或端口不對(duì)。4. 避坑與排查v1.2.6 里最容易踩的五件事4.1 草稿保存成功但重啟后消失現(xiàn)象是編輯時(shí)提示已保存關(guān)掉客戶端再打開草稿列表空了。原因通常是draft_root指向了一個(gè)臨時(shí)目錄或者index.json寫入時(shí)被其他進(jìn)程占用導(dǎo)致內(nèi)容截?cái)?。解決方式是先確認(rèn)draft_root是固定路徑再檢查index.json是否完整。如果文件存在但內(nèi)容為空把快照目錄里最近的時(shí)間戳文件手動(dòng)恢復(fù)成工作副本能救回大部分內(nèi)容。4.2 圖片上傳卡在 pending 不動(dòng)現(xiàn)象是正文里圖片顯示正常但遠(yuǎn)端文章里圖片是裂的。原因是assets/pending里的文件沒有被同步層掃描到常見于文件名含特殊字符或圖片體積超過單次上傳限制。解決方式是先看pending目錄里文件是否還在再檢查同步日志里有沒有upload_skip記錄。把文件名改成純英文數(shù)字單張控制在 5MB 以內(nèi)基本能繞過。4.3 自動(dòng)同步把本地新改動(dòng)覆蓋了現(xiàn)象是剛寫的一段話過一會(huì)兒自己變回舊版本。原因是同步層在拉取遠(yuǎn)端時(shí)沒有做「本地更新時(shí)間更晚則保留本地」的判斷直接以遠(yuǎn)端為準(zhǔn)。解決方式是在同步邏輯里加一條比較本地updated_at大于遠(yuǎn)端時(shí)先推送再拉取。這個(gè)坑在多人協(xié)作或換設(shè)備時(shí)特別容易觸發(fā)血淚經(jīng)驗(yàn)是任何自動(dòng)同步都要有「本地優(yōu)先」的兜底。4.4 客戶端啟動(dòng)后界面白屏現(xiàn)象是進(jìn)程起來了窗口一片白。原因多半是渲染層連不上本地服務(wù)層或者本地服務(wù)層啟動(dòng)時(shí)報(bào)了端口占用但沒彈提示。解決方式是先看任務(wù)管理器里有沒有兩個(gè)客戶端進(jìn)程再手動(dòng)訪問http://127.0.0.1:17800/health返回非 200 就說明服務(wù)層有問題。改端口后記得同步改渲染層的配置兩邊不一致也會(huì)白屏。4.5 發(fā)布后正文里的換行全亂了現(xiàn)象是本地預(yù)覽正常遠(yuǎn)端文章段落擠在一起。原因是本地編輯器用的是\n而遠(yuǎn)端接口期望\r\n或做了 HTML 轉(zhuǎn)義。解決方式是在推送前統(tǒng)一做一次換行歸一化把\r\n和\r都轉(zhuǎn)成\n再由遠(yuǎn)端按 Markdown 規(guī)則渲染。這個(gè)坑不致命但很煩建議在同步層入口就處理掉不要留到渲染階段。5. 進(jìn)階技巧用快照和校驗(yàn)把發(fā)布風(fēng)險(xiǎn)壓到最低走到這里基本鏈路已經(jīng)通了。最后分享一個(gè)我一直在用的習(xí)慣發(fā)布前跑一次「快照 校驗(yàn)」而不是直接點(diǎn)發(fā)布。具體做法是在客戶端里加一個(gè)發(fā)布前鉤子先對(duì)當(dāng)前草稿做一次快照再檢查三件事——正文里有沒有本地絕對(duì)路徑、圖片是否全部上傳成功、標(biāo)題是否為空。這三項(xiàng)任何一項(xiàng)不過就攔住發(fā)布并給出提示。下面是一個(gè)校驗(yàn)函數(shù)的寫法// pre_publish_check.js // 發(fā)布前校驗(yàn)路徑、圖片、標(biāo)題 function prePublishCheck(draft, uploadedAssets) { const issues []; // 檢查正文里是否殘留本地絕對(duì)路徑 if (/[A-Z]:\\/i.test(draft.content_md)) { issues.push(正文里存在本地絕對(duì)路徑遠(yuǎn)端無法訪問); } // 檢查待上傳圖片是否都已成功 const pending draft.assets.filter((a) !uploadedAssets.includes(a)); if (pending.length 0) { issues.push(還有 ${pending.length} 張圖片未上傳); } // 標(biāo)題不能為空 if (!draft.title || draft.title.trim() ) { issues.push(標(biāo)題為空); } return issues; }這個(gè)函數(shù)返回空數(shù)組才允許發(fā)布否則把問題列給用戶。uploadedAssets由同步層維護(hù)每次上傳成功就往里加。路徑檢查用正則匹配盤符能攔住大部分從本地直接粘貼的圖片引用。標(biāo)題檢查看起來多余但實(shí)際用起來能避免不少「無標(biāo)題文章」發(fā)出去又回頭改的尷尬。另一個(gè)技巧是給快照加一個(gè)「保留策略」只保留最近 20 個(gè)版本超出的按時(shí)間刪掉。這樣既不會(huì)把磁盤寫滿又能在誤操作后找回最近的內(nèi)容。我一般會(huì)在客戶端啟動(dòng)時(shí)跑一次清理而不是每次保存都跑減少 IO 抖動(dòng)。發(fā)布這件事后悔藥就是快照而快照的關(guān)鍵是別讓它變成負(fù)擔(dān)。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取