Puter 后端架構(gòu)深度解析Controller–Service–Store 分層、依賴注入與可插拔擴(kuò)展機(jī)制【免費(fèi)下載鏈接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/pu/puter本文圍繞 doc/architecture.md 展開(kāi)結(jié)合 Puter 開(kāi)源倉(cāng)庫(kù)的 后端啟動(dòng)器、分層注冊(cè)表、擴(kuò)展 API、請(qǐng)求上下文 與 路由選項(xiàng)類型 等源碼完整拆解其分層架構(gòu)、啟動(dòng)裝配流程、基于 AsyncLocalStorage 的請(qǐng)求上下文以及擴(kuò)展機(jī)制讓讀者既能按圖索驥地定位某類代碼應(yīng)該放哪一層也能理解一個(gè) HTTP 請(qǐng)求從進(jìn)入網(wǎng)關(guān)到落庫(kù)的完整鏈路并掌握編寫(xiě)一個(gè)合規(guī)擴(kuò)展Extension所需的全部 API 細(xì)節(jié)。Puter 是一個(gè)自托管的開(kāi)源互聯(lián)網(wǎng)計(jì)算機(jī)The Internet Computer它的后端被組織成一個(gè)每一層只依賴其下層的洋蔥狀分層棧并由PuterServer在啟動(dòng)時(shí)按固定順序?qū)嵗⑼ㄟ^(guò)構(gòu)造函數(shù)逐層注入依賴。這種設(shè)計(jì)與經(jīng)典 Controller–Service–Repository 模式形似而神似同時(shí)引入了一套與核心棧平行生長(zhǎng)的擴(kuò)展體系讓非關(guān)鍵能力縮略圖、服務(wù)器信息、開(kāi)發(fā)者熱重載等可以像插件一樣干凈地掛在任意一層之上。一、總體設(shè)計(jì)分層與依賴注入的基本原則文檔開(kāi)宗明義整個(gè)后端松散地受 Controller–Service–Repository 模式啟發(fā)配合依賴注入DI。核心組織方式是把后端疊成一摞層stack of layers并立下兩條鐵律每一層只依賴它下面的層絕不反向引用、也絕不橫向跨層調(diào)用所有依賴都通過(guò)構(gòu)造函數(shù)注入由唯一的引導(dǎo)者PuterServer按順序?qū)嵗鲗硬严聦訉?shí)例遞給上層。這兩條規(guī)則共同保證了依賴關(guān)系是顯式、可追溯的——從 PuterServer 源碼 出發(fā)可以沿著構(gòu)造鏈完整畫(huà)出任意組件的依賴圖。1.1 七層棧全景下圖為文檔中給出的官方分層示意block-beta1.2 各層職責(zé)速查表層代碼位置職責(zé)Controllerssrc/backend/controllers/路由處理器。負(fù)責(zé)解析 校驗(yàn)輸入、施加每條路由的 gate鑒權(quán)、子域、限流、body 解析等見(jiàn)RouteOptions、調(diào)用 service、格式化響應(yīng)。Driverssrc/backend/drivers/可選層。暴露在/drivers/*表面的 RPC 風(fēng)格處理器puter-kvstore、puter-chat-completion等。Driver 是一層薄殼校驗(yàn) RPC 輸入后調(diào)用 services/stores當(dāng) Controller 需要在 HTTP 上復(fù)用同一邏輯時(shí)可以持有對(duì) driver 的類型化引用。Servicessrc/backend/services/業(yè)務(wù)邏輯層。默認(rèn)調(diào)用方已完成鑒權(quán)/授權(quán)——Service 自身不再跑鑒權(quán) gate。Storessrc/backend/stores/持久化與存儲(chǔ)邏輯。把 Client 包裝成 Service 消費(fèi)的領(lǐng)域形態(tài)行、實(shí)體、KV 命名空間。Clientssrc/backend/clients/外部/內(nèi)部服務(wù)的適配器sql、redis、s3、dynamodb、email、事件總線……。只懂協(xié)議不懂領(lǐng)域概念。Configconfig.*.json→IConfig啟動(dòng)時(shí)每個(gè)層都收到的扁平化、帶類型的配置對(duì)象倉(cāng)庫(kù)內(nèi)可參考 config.template.jsonc。1.3 代碼組織上的強(qiáng)制約束每層通過(guò)構(gòu)造函數(shù)接收它下面的層因此從PuterServer出發(fā)依賴是顯式且可追蹤的Controller 不得直接伸手去夠 Client如果某個(gè) Controller 確實(shí)需要 Client 的能力正確的做法通常是經(jīng)由 ServiceService 之間不得為了代碼復(fù)用而互相調(diào)用——需要復(fù)用就向上抽取成 util/helper詳見(jiàn)后文約定一節(jié)。二、入口點(diǎn)PuterServer的啟動(dòng)裝配流程src/backend/server.ts 中的PuterServer是整個(gè)后端的 bootstrap。其#setupServer流程清晰對(duì)應(yīng)文檔中的四步描述2.1 加載擴(kuò)展目錄在實(shí)例化之前// 從 config.extensions 讀取目錄逐個(gè) import 目錄下的入口文件 const extensionDirs this.#config.extensions; await this.#importExtensions(extensionDirs);config.extensions是字符串?dāng)?shù)組例如 config.template.jsonc 中默認(rèn)配置// ── Extensions ────────────────────────────────────────────────────── // Directories scanned for extension entrypoints (*.ts / subdirs). extensions: [ ./extensions ],#importExtensionsserver.ts的掃描規(guī)則值得注意目錄下單個(gè).ts/.js文件直接動(dòng)態(tài)import()但會(huì)跳過(guò)*.test.*與*.d.ts子目錄優(yōu)先讀其package.json的main字段否則回退到index.js/index.mjs/index.cjs兩者都沒(méi)有的數(shù)據(jù)型 sidecar 目錄會(huì)被靜默跳過(guò)不會(huì)導(dǎo)致啟動(dòng)崩潰之所以必須先于實(shí)例化加載是因?yàn)閿U(kuò)展通過(guò)模塊級(jí)副作用把注冊(cè)內(nèi)容寫(xiě)入內(nèi)存注冊(cè)表隨后PuterServer裝配各層時(shí)要把這些注冊(cè)內(nèi)容合并進(jìn)對(duì)應(yīng)層見(jiàn)下一節(jié)。倉(cāng)庫(kù)內(nèi) extensions/package.json 只有一行{type: commonjs}說(shuō)明擴(kuò)展模塊本身保持 CommonJS 形態(tài)運(yùn)行時(shí)依賴編譯產(chǎn)物。2.2 按序?qū)嵗鲗硬⒑喜U(kuò)展注冊(cè)代碼中實(shí)際執(zhí)行順序?yàn)閏lients → stores → services → rate-limiter 裝配 → drivers → controllers。每類實(shí)例的構(gòu)造參數(shù)都只給下層的引用被實(shí)例化對(duì)象構(gòu)造函數(shù)注入的依賴Client(config)Store(config, clients, stores)Service(config, clients, stores, services)Driver(config, clients, stores, services)Controller(config, clients, stores, services, drivers)源碼中對(duì)每個(gè)層都寫(xiě)了兩遍循環(huán)第一遍遍歷內(nèi)置注冊(cè)表如 puterControllers第二遍遍歷extensionStore.xxx——這正是合并進(jìn)擴(kuò)展已注冊(cè)的東西的實(shí)現(xiàn)方式。此外值得留意的一個(gè)關(guān)鍵次序細(xì)節(jié)Drivers 先于 Controllers 實(shí)例化因此 Controller 構(gòu)造時(shí)就能拿到類型化的drivers引用而/drivers/*這個(gè) HTTP 表面本身由普通 Controller 中的 DriverController 承擔(dān)它從this.drivers讀取目標(biāo)——也就是文檔中不再有單獨(dú)的 driver 注冊(cè)表對(duì)象的含義。內(nèi)置 driver 注冊(cè)表見(jiàn) src/backend/drivers/index.ts包含kvStoreKV 存儲(chǔ)、aiChat/aiImage/aiTts/aiVideo/aiSpeech2Speech/aiSpeech2Txt/aiOcr各 AI 能力、apps、subdomains、notifications、workers等。類似的services/index.ts 通過(guò)declare module聲明合并生成IPuterServiceInstances內(nèi)含auth、token、fs、metering、events、permission等stores/index.ts 同樣生成IPuterStoreInstances內(nèi)含kv、user、fsEntry、session等。2.3 裝配 Express 全局中間件實(shí)例化完成后#setupServer創(chuàng)建 Express app 并設(shè)定兩個(gè)會(huì)影響所有子域路由的關(guān)鍵 app 級(jí)選項(xiàng)server.tstrust proxy必須在任何讀取req.ip/req.ips/req.protocol的中間件之前設(shè)置。默認(rèn)false部署在反向代理鏈后面時(shí)須設(shè)為跳數(shù)如單層 Cloudflare/nginx 設(shè)1生產(chǎn)環(huán)境絕不能設(shè)true那會(huì)信任每一跳使 XFF 可被偽造subdomain offset由subdomainOffsetForDomain(config.domain)算出讓部署在puter.example.com時(shí)不會(huì)把puter誤讀為活躍子域。隨后#installGlobalMiddleware以對(duì)次序極其講究的方式掛載全局中間件其中文檔沒(méi)有展開(kāi)、但源碼注釋里交代清楚的細(xì)節(jié)包括出口計(jì)量中間件最先注冊(cè)它在compression之前包裹res.write因此統(tǒng)計(jì)的是真實(shí)發(fā)出的字節(jié)而非 handler 產(chǎn)生的字節(jié)express.json必須在 auth probe 之前這樣req.body.auth_token才是可讀的authProbe永不 reject它只在存在合法 token 時(shí)填充req.actorHost 校驗(yàn)#installHostValidation維護(hù)一張由domain、static_hosting_domain、private_app_hosting_domain等拼接、帶緩存的允許域名表/healthcheck與自定義域名custom_domains_enabled例外放行CORS 中間件允許任意 Originputer.js設(shè)計(jì)上要被任意第三方站點(diǎn)消費(fèi)并僅在api子域反射 Origin 時(shí)允許攜帶憑據(jù)、為dav子域單獨(dú)暴露 WebDAV 需要的響應(yīng)頭集合認(rèn)證探測(cè)之后依次是指紋中間件打上req.networkFingerprint/req.deviceFingerprint與每請(qǐng)求 ALS 上下文中間件此時(shí)req.actor已被填充可安全快照進(jìn)上下文見(jiàn)第三節(jié)用戶自托管站點(diǎn)*.puter.site等由createPuterSiteMiddleware在路由匹配前短路處理擴(kuò)展注冊(cè)的全局中間件extensionStore.globalMiddlewares最后追加。2.4 路由裝配與終止中間件Controllers 與擴(kuò)展路由都收斂到同一個(gè)#materializeRoute細(xì)節(jié)見(jiàn)下節(jié)RouteOptions全部裝配完畢后最后才安裝 404 catch-all 與錯(cuò)誤處理中間件——保證 404 只對(duì)真正未匹配的請(qǐng)求觸發(fā)、錯(cuò)誤處理器能接住棧中任意位置拋出的錯(cuò)誤Express 5 會(huì)自動(dòng)把同步/異步 throw 轉(zhuǎn)發(fā)到錯(cuò)誤處理器因此 handler 里可以直接throw new HttpError(...)無(wú)需next(err)儀式。2.5 生命周期鉤子文檔提到PuterServer會(huì)觸發(fā)onServerStart/onServerPrepareShutdown/onServerShutdown。源碼server.ts顯示這些鉤子按clients → stores → services → controllers → drivers的順序在每一層上逐一遍歷觸發(fā)#runPrepareShutdownHooks有冪等保護(hù)只跑一次attachHttpServer則在 listen 之前被調(diào)用供 socket.io 等需要裸http.Server的服務(wù)掛接。start()還支持noHttpServer模式測(cè)試用與--server的 AuthMe 瀏覽器登錄流程。三、請(qǐng)求上下文基于 AsyncLocalStorage 的Context為了不在每個(gè)函數(shù)簽名里都穿針引線地傳遞每請(qǐng)求狀態(tài)后端在 src/backend/core/context.ts 中提供了由 NodeAsyncLocalStorage支撐的Context。3.1 設(shè)計(jì)要點(diǎn)承載能力既有帶類型的已知字段KnownContextFields又有開(kāi)放式的 key-value map。已知字段包括actor——auth probe 解析出的已認(rèn)證主體可能為undefinedreq——當(dāng)前 Express 請(qǐng)求對(duì)象requestId——每請(qǐng)求唯一 ID可用于結(jié)構(gòu)化日志/追蹤driverName——由 DriverController 在/drivers/call分發(fā)時(shí)寫(xiě)入drivers 據(jù)此挑選 providerabortSignal——客戶端提前斷開(kāi)時(shí)中止長(zhǎng)任務(wù)長(zhǎng)運(yùn)行 driver 輪詢它避免為沒(méi)人接收的工作繼續(xù)計(jì)量。傳播機(jī)制因?yàn)榛贏syncLocalStorage上下文能自動(dòng)穿過(guò)async/await、定時(shí)器與微任務(wù)。runWithContext(initial, fn)用于開(kāi)啟一個(gè)上下文作用域request-context 中間件在 auth probe 之后用它包裹整條中間件/處理器鏈。用法源碼注釋中的示例// 讀取類型化字段 const actor Context.get(actor); // 在任意位置讀取 express 請(qǐng)求 const req Context.get(req); // 存取臨時(shí)值 Context.set(myService.txId, txId); const txId Context.get(myService.txId);約束Context.set在請(qǐng)求作用域之外調(diào)用會(huì)直接拋錯(cuò)Context之外的調(diào)用無(wú) scope取值返回undefined。3.2 使用紀(jì)律寧可顯式傳參文檔給出的工程紀(jì)律非常明確優(yōu)先顯式參數(shù)只有當(dāng)值確實(shí)是請(qǐng)求級(jí)、且不通過(guò) Context 就得穿透很多層函數(shù)簽名時(shí)才使用Context。它被設(shè)計(jì)為有節(jié)制地使用mostly foractorandreq而不是一條隨手可用的隱形全局通道——濫用會(huì)悄悄破壞函數(shù)的純度與可測(cè)試性。一個(gè)真實(shí)的消費(fèi)端示例是 extensions/whoami.ts 的handleWhoamihandler 里直接Context.get(actor)取出當(dāng)前主體并據(jù)此判斷是否返回 401——這正是文檔任何請(qǐng)求 handler 內(nèi)可用Context.get(actor)/Context.get(req)替代層層傳參的落地形態(tài)。四、擴(kuò)展Extensions與核心棧平行的插件體系擴(kuò)展代碼放在倉(cāng)庫(kù)根的 extensions/文檔中的packages/puter/extensions/即該目錄中與分層棧平行。它們服務(wù)于系統(tǒng)中**非關(guān)鍵non-crucial**的部分——移除后 Puter 仍然能工作的功能。這是判斷該不該做成擴(kuò)展的第一把尺子。4.1 文檔給出的分類示范適合做擴(kuò)展thumbnails、serverInfo、devWatcher——干凈的外掛式可選功能其實(shí)更該進(jìn)核心metering、appTelemetry——客戶端已默認(rèn)它們存在擴(kuò)展的框架反而誤導(dǎo)人本不該做成擴(kuò)展whoami——它對(duì)每一個(gè)已認(rèn)證客戶端都是承重墻。文檔特意把它列為警世案例當(dāng)你猶豫某個(gè)東西是否屬于擴(kuò)展時(shí)想想 whoami。以 serverInfo 為例它就是一個(gè)典型的薄殼擴(kuò)展讀取os/fs系統(tǒng)信息后用extension.get注冊(cè)一個(gè)僅管理員可訪問(wèn)的端點(diǎn)extension.get( /serverInfo, { subdomain: api, adminOnly: true }, handleServerInfo, );而 thumbnails 則展示了另一種形態(tài)——不注冊(cè)路由而是通過(guò)extension.on訂閱文件系統(tǒng)事件thumbnail.created、thumbnail.upload.prepare、thumbnail.read、fs.copy.node、fs.remove.node把縮略圖落盤(pán)為帶thumbnails/前綴的 S3 對(duì)象并簽發(fā)預(yù)簽名 URL全程不碰核心棧的任何一行。4.2 擴(kuò)展 API 全貌extension全局對(duì)象定義在 src/backend/extensions.ts其底層是一個(gè)內(nèi)存注冊(cè)表extensionStoreextensions.ts擴(kuò)展模塊在模塊作用域執(zhí)行時(shí)把注冊(cè)寫(xiě)入其中PuterServer啟動(dòng)時(shí)再排干它。API 分三類1. 一等公民式的層注冊(cè)Layer registrationextension.registerClient(name, ClientClass)extension.registerStore(name, StoreClass)extension.registerService(name, ServiceClass)extension.registerDriver(name, DriverClass)extension.registerController(name, ControllerClass)另有extension.registerGlobalMiddleware(mw)追加全局中間件2. 輕量包裝Lightweight wrappers——當(dāng)為一個(gè)常用場(chǎng)景單獨(dú)寫(xiě)一個(gè)完整類不值得時(shí)extension.on(event, handler)——訂閱事件總線事件extension.get(path, opts?, handler)/.post/.put/.delete/.patch/.head/.options/.all/.use——注冊(cè)路由。opts就是 Controller 用的同一套R(shí)outeOptions所以subdomain、requireAuth、adminOnly、body 解析器等在擴(kuò)展路由上完全等價(jià)地生效兩種調(diào)用形態(tài)extension.get(/path, handler)與extension.get(/path, options, handler)實(shí)現(xiàn)見(jiàn) extensions.ts。3. 跨層訪問(wèn)Cross-layer accessextension.import(client | store | service | controller | driver)——返回對(duì)已實(shí)例化對(duì)象的惰性代理lazy proxyextension.config——暴露實(shí)時(shí)配置。import代理有兩處實(shí)現(xiàn)細(xì)節(jié)值得展開(kāi)extensions.ts惰性解析擴(kuò)展模塊在層實(shí)例化之前就被 import模塊頂層讀到名字通常是空的因此代理在每次屬性訪問(wèn)時(shí)都重新查容器模塊 import 時(shí)捕獲的extension.import(client).db在真正實(shí)例落地后依然可用方法綁定bindLayerMethods用 Proxy 讓取出即被 bind 到實(shí)例這樣const w svc.fs.write; w(...)這種剝離式調(diào)用不會(huì)因this丟失而在訪問(wèn)私有字段時(shí)炸掉代價(jià)是每次方法訪問(wèn)都返回新函數(shù)引用同一性不穩(wěn)定——對(duì)取一次、調(diào)用多次的 import 場(chǎng)景可接受代理對(duì)從未注冊(cè)的名字在首次屬性讀取時(shí)拋錯(cuò)而非返回undefined因此拼寫(xiě)錯(cuò)誤會(huì)在訪問(wèn)點(diǎn)立刻暴露而不是靜默變成 no-op想探測(cè)可選層條目需要 try/catch。文檔給出的示例代碼正是把上面三類 API 串起來(lái)的完整最小擴(kuò)展import { extension } from heyputer/backend/src/extensions; const services extension.import(service); extension.get(/healthcheck/deep, { subdomain: api, adminOnly: true }, async (_req, res) { res.json({ ok: await services.health.runDeepCheck() }); }); extension.on(user.signup, (_key, data) { console.log(new user, data.user.username); });真實(shí)倉(cāng)庫(kù)里可以對(duì)照 whoami 的完整路由聲明來(lái)驗(yàn)證它同時(shí)使用了subdomain: api、requireAuth: true、allowUnconfirmed: true以及一個(gè)key: user、scope: whoami、limit: 1_800、window: 60_000的限流配置——GUI 輪詢?cè)摱它c(diǎn)、且每次調(diào)用會(huì)扇出到所有whoami事件監(jiān)聽(tīng)器因此限流上限必須清掉最忙會(huì)話在做什么而不是按人點(diǎn)擊的節(jié)奏來(lái)定。extension.config的用法也出現(xiàn)在其中讀取feature_flags后按白名單CLIENT_VISIBLE_FEATURE_FLAGS過(guò)濾避免內(nèi)部標(biāo)記payment_bypass、staff_only_*等經(jīng)/whoami泄漏到客戶端。五、RouteOptions一條路由可聲明的全部護(hù)欄文檔把per-route gates歸入 Controllers 的職責(zé)而承載這些聲明的類型就是 src/backend/core/http/types.ts 中的RouteOptions。理解它就能理解Controller 層做輸入校驗(yàn)與 I/O 塑形究竟意味著什么。RouteMethod除了標(biāo)準(zhǔn)的 REST 動(dòng)詞還包含lock、unlock、propfind、proppatch、mkcol、copy、move等 WebDAV 動(dòng)詞對(duì)應(yīng) WebDAVController 的需求RoutePath接受字符串/正則/數(shù)組。RouteOptions的可聲明項(xiàng)含義見(jiàn)類型源碼中的長(zhǎng)注釋概覽如下類別選項(xiàng)說(shuō)明子域subdomain字符串或數(shù)組省略時(shí) verb 路由只匹配根域*顯式匹配任意子域use中間件默認(rèn)不加此閘門(mén)認(rèn)證requireAuth拒絕匿名與被封禁用戶僅放行 user 與 app 主體requireUserActor拒絕 app/access-token 主體蘊(yùn)含requireAuthnoUserSession拒絕裸會(huì)話 token要求委托憑據(jù)app/worker/API tokenworker 會(huì)話恒通過(guò)allowFullAccessToken配合requireUserActor放行用戶本人的全權(quán) PAT默認(rèn)拒絕adminOnly用戶名白名單默認(rèn)admin/system可加數(shù)組擴(kuò)展要求根 token且需 step-up 二次認(rèn)證可疊加allowedAppIdsallowedAppIdsapp-under-user 白名單蘊(yùn)含requireAuth驗(yàn)證allowUnconfirmed放行尚未完成注冊(cè)期驗(yàn)證郵箱/短信/卡片的賬號(hào)供登出、whoami、確認(rèn)類核心流使用requireVerified要求郵箱已驗(yàn)證是否生效取決于config.strict_email_verification_requiredrequirePhoneVerified/requireCardVerified各自要求確實(shí)完成過(guò)對(duì)應(yīng)因子驗(yàn)證captcha/antiCsrf驗(yàn)證碼閘門(mén) / 一次性 anti-CSRF token 消費(fèi)guiOriginOnly僅限本部署 GUI origin 的瀏覽器頁(yè)面用于發(fā)放會(huì)話憑據(jù)的路由配額與防護(hù)rateLimit單/數(shù)組key可為fingerprint默認(rèn)/ip/user/自定義函數(shù)scope隔離計(jì)數(shù)器backend選memory/redis/kvconcurrent并發(fā)在飛限制可bySubscription按訂閱檔覆蓋額度requireCredits余額不足 402insufficient_funds只用于替你花錢(qián)的路由requireSubscription計(jì)劃門(mén)檻true任一非免費(fèi)計(jì)劃數(shù)組指定SubscriptionPolicy.idrequireReputation信譽(yù)分檔位門(mén)檻檔位閾值在配置的reputationGate.tiers中定義請(qǐng)求體bodyJsonfalse或{limit, type}覆蓋全局 JSON 解析器bodyRaw/bodyText/bodyUrlencoded分別拿到 Buffer / string / 表單對(duì)象通用middleware額外的每路由中間件在門(mén)控與解析之后、handler 之前執(zhí)行在類型層面RouteOptions還通過(guò)AuthRequiredO與TypedRequestO做了類型收窄當(dāng)路由聲明了requireAuth或任何蘊(yùn)含它的選項(xiàng)時(shí)handler 中的req.actor會(huì)被窄化為Actor非空無(wú)需再寫(xiě)非空斷言。門(mén)控鏈的落地#materializeRoute每條路由無(wú)論來(lái)自 Controller 還是擴(kuò)展最終都流入 server.ts 的#materializeRoute。它把RouteOptions翻譯成一條有序的中間件鏈源碼注釋給出的順序是subdomain → origin gate → auth gates → requireUserActor → noUserSession → adminOnly(step-up) → allowedAppIds → requireVerified → reputation → subscription → rateLimit → requireCredits → concurrent → captcha → antiCsrf → body parsers → 調(diào)用方 middleware → 生命周期事件 → handler幾個(gè)由代碼佐證的語(yǔ)義細(xì)節(jié)蘊(yùn)含去重adminOnly、allowedAppIds、requireUserActor等都蘊(yùn)含requireAuth實(shí)現(xiàn)中只 push 一次requireAuthGate()默認(rèn)開(kāi)啟的待驗(yàn)證閘門(mén)任何需要認(rèn)證且未聲明allowUnconfirmed的路由都會(huì)被追加requireVerifiedAccount()這是讓低信譽(yù)注冊(cè)賬號(hào)在服務(wù)端就被擋在 AI/FS/driver 端點(diǎn)之外、而不只靠 GUI 彈窗的機(jī)制默認(rèn)拒絕 access token需要認(rèn)證且未聲明allowAccessToken的路由會(huì)追加requireNonAccessTokenGate()adminOnly疊加 step-up管理路由還要求最近的重認(rèn)證createStepUpGate除非 token 攜帶路由白名單中的 app idWebDAV 特例OPTIONS預(yù)檢對(duì)dav子域放行DAV 客戶端要靠它發(fā)現(xiàn)服務(wù)器能力其余子域直接回 200路由級(jí)生命周期每個(gè)端點(diǎn)use除外最后會(huì)注入createRouteLifecycleMiddleware使before/after鉤子在完整認(rèn)證的請(qǐng)求上觸發(fā)。Controller 端的聲明式注冊(cè)走的是同一套物料化管道PuterRouter 配合裝飾器元數(shù)據(jù)Controller(/prefix)等把前綴/路由存在 prototype 的PREFIX_METADATA_KEY/ROUTES_METADATA_KEY上#registerControllerRoutes在裝配時(shí)讀出并批量registerRoutes(router)同時(shí)支持 Controller 用isEnabled()在 config 層面關(guān)閉整組路由——關(guān)閉后其路徑表現(xiàn)為 404 而非存在但拒絕。六、架構(gòu)約定Conventions文檔在最后給出了四條團(tuán)隊(duì)編碼約定它們也是審閱任何 Puter 后端改動(dòng)時(shí)的檢查清單新代碼優(yōu)先 TypeScript在可行處存量 JS 可保留動(dòng)到該文件時(shí)順帶機(jī)會(huì)式遷移命名變量/函數(shù)用camelCase類、以及內(nèi)含類的文件AuthService.ts、KVStoreDriver.ts用PascalCase去重優(yōu)先兩個(gè) Service 需要同一段邏輯時(shí)把它提升到 util/helper而不是在同一層內(nèi)橫向互調(diào)——Service 不應(yīng)為復(fù)用代碼而依賴其他 Service絕不跨層伸手Controller 不直接捅 ClientService 不注冊(cè)路由。一旦發(fā)現(xiàn)自己想這么做通常意味著抽象本身出了問(wèn)題。七、快速定位指南想找某個(gè) HTTP 端點(diǎn)由誰(shuí)處理→ 從 controllers/index.ts 的puterControllers表出發(fā)再按需看對(duì)應(yīng) Controller 的registerRoutes想確認(rèn)某個(gè) driver 暴露了什么 RPC→ drivers/index.ts 是完整注冊(cè)表RPC 分發(fā)在 DriverController想理解路由可聲明哪些閘門(mén)/解析器→ core/http/types.ts 的RouteOptions注釋最權(quán)威想看擴(kuò)展能注冊(cè)什么、如何跨層取實(shí)例→ src/backend/extensions.ts 的extension對(duì)象與其文檔注釋想確認(rèn)啟動(dòng)順序與生命周期鉤子→ server.ts 的#setupServer、#fireOnServerStart、prepareShutdown/shutdown想寫(xiě)第一個(gè)擴(kuò)展 → 以 serverInfo極簡(jiǎn)路由型或 thumbnails事件訂閱型為模板并用 extensions/whoami.ts 對(duì)照承重型路由應(yīng)如何精細(xì)聲明RouteOptions。結(jié)語(yǔ)Puter 的后端不是一套玄虛的框架而是一組樸素卻強(qiáng)約束的工程決策層間只向下依賴 構(gòu)造注入 單一引導(dǎo)者按序裝配讓依賴圖完全可讀ALS 上下文只解決真正請(qǐng)求級(jí)狀態(tài)的穿透問(wèn)題擴(kuò)展體系則把錦上添花與承重墻清楚地分成兩堆用同一套R(shí)outeOptions物料化管道保證擴(kuò)展路由與核心路由享受完全一致的鑒權(quán)/限流/解析能力。理解這四件事你就能在 Puter 倉(cāng)庫(kù)中準(zhǔn)確定位任意功能的落點(diǎn)也能判斷一個(gè)新需求應(yīng)該寫(xiě)進(jìn)哪一層、或是否應(yīng)該以擴(kuò)展形態(tài)獨(dú)立存在?！久赓M(fèi)下載鏈接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/pu/puter創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考