<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by krownsh on Medium]]></title>
        <description><![CDATA[Stories by krownsh on Medium]]></description>
        <link>https://medium.com/@bgkong1205?source=rss-3278bd6eeabe------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*v28d0niap4Lw0REH</url>
            <title>Stories by krownsh on Medium</title>
            <link>https://medium.com/@bgkong1205?source=rss-3278bd6eeabe------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 12:43:47 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@bgkong1205/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Canvas 的 1px 線為什麼發灰：從 path 邊界到高 DPI 座標系的繪圖契約]]></title>
            <link>https://medium.com/@bgkong1205/canvas-%E7%9A%84-1px-%E7%B7%9A%E7%82%BA%E4%BB%80%E9%BA%BC%E7%99%BC%E7%81%B0-%E5%BE%9E-path-%E9%82%8A%E7%95%8C%E5%88%B0%E9%AB%98-dpi-%E5%BA%A7%E6%A8%99%E7%B3%BB%E7%9A%84%E7%B9%AA%E5%9C%96%E5%A5%91%E7%B4%84-ba4c14f6a715?source=rss-3278bd6eeabe------2</link>
            <guid isPermaLink="false">https://medium.com/p/ba4c14f6a715</guid>
            <category><![CDATA[2d]]></category>
            <category><![CDATA[front-end-development]]></category>
            <category><![CDATA[canvas]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[idp]]></category>
            <dc:creator><![CDATA[krownsh]]></dc:creator>
            <pubDate>Thu, 24 Sep 2026 02:12:56 GMT</pubDate>
            <atom:updated>2026-09-24T02:12:56.761Z</atom:updated>
            <content:encoded><![CDATA[<p>Canvas 畫出來的 1px 線不是一定要加 0.5。那只是特定座標系、特定線寬下的結果。把它當成萬用修法，一接上 devicePixelRatio、縮放或互動座標換算，畫面就會開始飄：線條變粗、hit test 偏移，或在不同螢幕上時清楚時模糊。</p><p>問題的核心是：Canvas 的 drawing buffer 用裝置像素記錄，CSS 尺寸則是版面尺寸；stroke() 又是以 path 為中心向兩側擴張。要穩定處理它，先把「設計座標」「CSS pixel」「device pixel」三個座標系分開。</p><h3>問題入口與本文目標：Retina 修好畫質後，為什麼筆刷反而偏掉</h3><p>想像一個簽名板或流程編輯器。第一版只在桌機開發，canvas.width = 800、CSS 也設 width: 800px，畫一條 1px 分隔線大致沒有問題。上線後有人拿 MacBook 或 Windows 125% 縮放使用，於是團隊加上 DPR：buffer 變成 1600×1200。畫面銳利了，游標落點卻和筆刷差一截；有人再在所有座標加 0.5，拖曳選取又開始偏。</p><p>本文處理的就是這種「畫質修正與互動修正互相打架」的場景。目標不是背熟 Canvas API，而是建立一個約定：應用層的圖形資料、pointer 事件與命中測試都使用 CSS pixel；只有 raster buffer 和 context transform 知道 DPR。讀完後，你應能判斷一條線為何模糊、一次 resize 為何把圖畫大兩倍，以及一個 pointer 座標是否被錯誤地當成 buffer 座標。</p><p>本文不討論 WebGL、字型 hinting 或跨瀏覽器抗鋸齒演算法差異。它們確實會影響最後一點視覺差別，但不是一般編輯器出現整體模糊與互動偏移的第一個排查點。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XbhMxfzBgOnyewVdQuR9dg.png" /></figure><h3>失敗模式：先加 0.5，再把每一條線畫歪</h3><p>lineWidth = 1 時，ctx.moveTo(10, 0); ctx.lineTo(10, 100) 的中心線在 x=10。描邊範圍會落在 9.5 到 10.5 之間，覆蓋到相鄰兩欄像素的一半；抗鋸齒把兩個半覆蓋像素混色後，看起來就像灰線。把中心移到 10.5，描邊範圍才對齊 10 到 11 的完整像素欄。</p><p>這也解釋了原始筆記中「補 0.5」的現象，但條件不能省略：奇數寬線要讓中心落在 half pixel；偶數寬線的兩側本來就可落在整數邊界。MDN 以 1px rectangle 說明，同樣的原理會讓名義 50×50 的描邊實際覆蓋到 52×52；要得到銳利且尺寸正確的框，需要同時平移與扣除線寬。<a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_shapes">MDN：Drawing shapes with canvas</a></p><pre>function strokeCrisp1px(ctx, x, y, width, height) {<br>  ctx.lineWidth = 1;<br>  ctx.strokeRect(x + 0.5, y + 0.5, width - 1, height - 1);<br>}</pre><pre>function strokeCrisp2px(ctx, x, y, width, height) {<br>  ctx.lineWidth = 2;<br>  ctx.strokeRect(x + 1, y + 1, width - 2, height - 2);<br>}</pre><p>這段不是視覺魔法，而是把可見描邊的外緣納入幾何尺寸。若圖形刻意需要半透明或次像素位移，例如資料視覺化動畫，反而不該強行 snap。</p><p>最常見的錯誤是把 half-pixel 規則套到每一個圖形：文字 baseline、2px selection outline、填滿矩形、影像與動畫中的小數位移，都被硬塞 0.5。結果是原本已經對齊的偶數線寬反而跨到半像素，或 hit region 和可見圖形不再共享幾何資料。正確順序是先決定「path 的中心線」與「可見外緣」哪一個才是產品規格，再依 line width 推導位置。</p><p>例如選取框的產品規格若是「外緣落在 x=10 到 x=110」，1px 描邊的 path 應落在 10.5 到 109.5；若規格是「中心線經過 x=10」，那麼兩側半覆蓋是預期行為，不能再宣稱它是 bug。這個區分讓設計座標和 raster 化結果各有責任，而不是讓某個神祕常數流進整個程式。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*n0TEKPR7neJgVwwo5nMvBg.png" /></figure><h3>技術模型：CSS box、drawing buffer 與 context matrix 各管一件事</h3><p>只設 CSS 的 width: 800px，沒有把 canvas.width 同步成對應 buffer 寬度，瀏覽器會把原本較小的點陣圖拉大。這不是 vector 繪圖，線條和文字自然會糊。反過來只放大 buffer 而不調整 transform，所有座標又會被放大兩次。</p><p>穩定做法是讓 API 對呼叫端維持 CSS pixel 座標，但將 buffer 乘上 DPR，再一次性建立轉換矩陣：</p><pre>export function resizeCanvas(canvas, cssWidth, cssHeight) {<br>  const dpr = Math.max(1, window.devicePixelRatio || 1);<br>  canvas.style.width = `${cssWidth}px`;<br>  canvas.style.height = `${cssHeight}px`;<br>  canvas.width = Math.round(cssWidth * dpr);<br>  canvas.height = Math.round(cssHeight * dpr);</pre><pre>  const ctx = canvas.getContext(&#39;2d&#39;);<br>  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);<br>  return ctx;<br>}</pre><p>setTransform() 先重設矩陣再套入 DPR；這比 resize 後連續 scale(dpr, dpr) 安全，因為後者在重繪、ResizeObserver 或 hot reload 時很容易累乘。Canvas 2D context 的 transform 是狀態的一部分，scale()、translate() 與 rotate() 都會影響之後建立與繪製的 path。<a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D">MDN：CanvasRenderingContext2D</a></p><p>有一個容易被忽略的副作用：每次設定 canvas.width 或 canvas.height，context state 都會重設。也就是 line dash、font、clip、transform 都會回到預設值。把 resize 寫成「只改 style，再繼續畫」會同時留下模糊 buffer 與失效 state；把 resize 寫成「改 buffer → 建立 transform → 從 scene model 全量重繪」，代價是重繪成本，換來狀態不會靠歷史操作存活。</p><p>這也是為何可編輯 canvas 應保存圖形資料而非只保存像素。畫布是一張結果圖，不能替你回答某條線原本的資料座標是多少。保存 shape、style、z-index 與 selection state 後，resize、undo、匯出與 hit test 才能從同一個資料模型推導。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Sx_p9Q0XAkxyCFhmckhYVQ.png" /></figure><h3>實作：互動座標要走反向換算</h3><p>如果繪圖 API 接受 CSS pixel，pointer event 也應轉成同一套座標；不要直接拿 clientX 當 canvas 座標。頁面捲動、canvas 在容器中的位置、CSS scale 都會讓它失準。</p><pre>function pointerToCanvas(event, canvas) {<br>  const rect = canvas.getBoundingClientRect();<br>  return {<br>    x: (event.clientX - rect.left) * (canvas.clientWidth / rect.width),<br>    y: (event.clientY - rect.top) * (canvas.clientHeight / rect.height),<br>  };<br>}</pre><p>上述函式以 CSS 座標回傳值，正好可直接餵給已用 setTransform(dpr, …) 的 context。若另外對 canvas 使用 CSS transform: scale()，rect.width 已包含視覺縮放，必須保留這個比例；否則筆刷位置與游標會分離。</p><h3>另一個失敗模式：把 context 當成無狀態繪圖函式</h3><p>原始筆記提到不同顏色線段應使用 beginPath()，方向正確，但原因比「設定互相吃掉」更精確。Canvas 維護一份 current path；strokeStyle 是 paint state。呼叫第二次 stroke() 時，會以當下的 style 對 current path 的所有 sub-path 再描一次。沒有 beginPath()，前一條線也可能被後一個顏色重描。</p><pre>ctx.beginPath();<br>ctx.moveTo(20.5, 20.5);<br>ctx.lineTo(220.5, 20.5);<br>ctx.strokeStyle = &#39;#d23&#39;;<br>ctx.stroke();</pre><pre>ctx.beginPath();<br>ctx.moveTo(20.5, 50.5);<br>ctx.lineTo(220.5, 50.5);<br>ctx.strokeStyle = &#39;#1769aa&#39;;<br>ctx.stroke();</pre><p>beginPath() 會清空 sub-path 清單；closePath() 會嘗試把目前 sub-path 的終點連回起點。fill() 會自動閉合開放區域，但 stroke() 不會，因此「形狀填得起來、邊框卻少一段」通常是 closePath() 遺漏，而不是座標算錯。<a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_shapes">MDN：path 建立與閉合規則</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ofD6VsKEDM_Ei-PNvfWpLg.png" /></figure><h3>填洞、橡皮擦與圖層不是同一件事</h3><p>多個 sub-path 的填色預設採 non-zero winding rule。內外輪廓若方向相反，環繞數可抵銷而形成洞；若方向相同，內部可能被填滿。需要的是「奇偶次交叉就算洞」時，直接指定 ctx.fill(&#39;evenodd&#39;)，比靠手動反轉每個 path 的點序可靠。</p><p>globalCompositeOperation 也常被誤當成圖層系統。它只決定 source 如何和現有 destination bitmap 合成，例如 destination-out 可作為橡皮擦；它不會替你保存可編輯物件。若需求是撤銷、選取或重排，應維護 scene model 後重繪，或使用離屏 canvas 做快取。合成模式的語意由 context state 決定，使用後應以 save() / restore() 收束，避免漏回預設的 source-over。<a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation">MDN：globalCompositeOperation</a></p><p>在高頻筆刷場景，完全重繪未必便宜。可以把不常變的背景格線放到 offscreen canvas，主畫布只重繪動態 layer；但不要把快取當成唯一真相。scene model 仍是資料來源，offscreen bitmap 是可丟棄的衍生物。這是效能與可維護性的取捨：資料模型讓狀態可追蹤，快取讓 render 不必每幀重算。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0br9q7E1AUMfBv0H50OYXg.png" /></figure><h3>驗證與取捨：把「看起來清楚」變成可重現測試</h3><p>把模糊問題留在肉眼判斷，通常會在下一次螢幕或瀏覽器更新後重現。至少應驗證這幾件事：</p><p>1. 以 DPR 1、1.25、2、3 截圖，比對細線與文字是否因 buffer 拉伸而發糊。</p><p>2. 對 1px 與 2px 邊框量測 getImageData()，確認預期的完整／半覆蓋像素分布；讀像素時留意隱私保護模式可能加入微小雜訊。<a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/getImageData">MDN：getImageData()</a></p><p>3. 對縮放過的 canvas 做 pointer drag 測試，檢查游標、hit test 與繪圖結果使用同一座標系。</p><p>4. 將兩條不同 style 的 path 依序重繪，確認先畫的線不會被後一個 stroke() 改色。</p><p>除了視覺截圖，還應對 scene data 做單元測試：在 CSS 800×600、DPR 2 下，一條從 (10, 20) 到 (110, 20) 的線資料不應變成 (20, 40)；pointer 在視覺中心點回傳的座標也應維持 (400, 300)。這些斷言抓得到 scale() 累乘和 client/buffer 混用，而不必等待真人在 Retina 螢幕上說「好像怪怪的」。</p><p>也要承認限制。非整數 DPR、瀏覽器縮放、CSS transform 和文字 rasterization 不一定能讓每條線在每塊螢幕都變成同樣濃黑；MDN 也指出 CSS pixel 無法精準映射到非整數 device pixel 時，會出現不均勻像素。此時目標應是座標一致與可接受的視覺品質，不是追求不可能的逐像素一致。</p><h3>一個可維護的 render loop 長什麼樣子</h3><p>上述規則只有放進 render loop 才能避免下一位維護者又把座標系混回去。實務上我會把畫布包成三個明確的函式：resize() 只處理 CSS box、buffer 和 DPR；render(scene) 只讀 scene model、完整設定 context state 後繪製；toScenePoint(event) 只把瀏覽器事件轉回 scene 座標。任何圖形工具都不直接讀 canvas.width，任何 UI event handler 都不直接把 clientX 傳給 lineTo()。</p><pre>function render(canvas, scene) {<br>  const ctx = resizeCanvas(canvas, scene.viewport.width, scene.viewport.height);<br>  ctx.clearRect(0, 0, scene.viewport.width, scene.viewport.height);</pre><pre>  for (const shape of scene.shapes) {<br>    ctx.save();<br>    ctx.strokeStyle = shape.stroke;<br>    ctx.lineWidth = shape.width;<br>    ctx.lineCap = shape.cap;<br>    ctx.beginPath();<br>    ctx.moveTo(shape.from.x, shape.from.y);<br>    ctx.lineTo(shape.to.x, shape.to.y);<br>    ctx.stroke();<br>    ctx.restore();<br>  }<br>}</pre><p>這段刻意在每個 shape 前後用 save()、restore()。它多了一點函式呼叫成本，卻把 style、transform、composite operation 等狀態侷限在單一物件裡。若畫面有數萬個物件，當然要改用批次繪製與 layer 快取；但優化前先有能正確重繪的基準版本，否則快取只會把舊 bug 烤進 bitmap。</p><p>還有一個常被忽略的約束：resize 會使 bitmap 清空。不要在 ResizeObserver callback 裡只呼叫 resizeCanvas() 然後期待畫面留下來；應該讓 callback 更新 viewport state，再排程一次 render。若拖拉視窗造成 callback 密集觸發，可以用 requestAnimationFrame 合併同一 frame 的多次 resize。這是效能問題，但也關係正確性：若某次 resize 用到舊 viewport，下一次 render 的 transform 就會和 CSS box 不一致。</p><h3>何時該 snap，何時應接受抗鋸齒</h3><p>像素對齊適合格線、游標、表格邊界、像素畫和需要讀取單一像素的編輯器。它不適合所有線條。地圖、手寫筆刷、自由縮放的圖表或動畫軌跡，本來就可能落在小數座標；強制 rounding 會讓慢速移動變成跳格，也會累積幾何誤差。</p><p>選擇的依據不是「哪個看起來比較黑」，而是資料語意。若資料表示離散格點，snap 是語意的一部分；若資料表示連續座標，保留浮點位置，讓 rasterizer 抗鋸齒才比較正確。以折線圖為例，資料點可以是 13.27px，軸線則可獨立採對齊策略。把兩者都四捨五入，可能讓資料誤差比視覺收益更大。</p><p>影像也有自己的規則。放大照片通常需要 interpolation；放大 sprite 或掃描到的簽章 mask，可能需要 imageSmoothingEnabled = false 或 CSS image-rendering: pixelated。但後者在非整數 DPR 下仍可能不均勻，不能拿來修正 layout 尺寸與座標換算錯誤。先確認 source bitmap 的大小、destination rectangle 和 transform，再決定平滑策略。</p><h3>把問題縮小的診斷順序</h3><p>當使用者回報「畫布糊了」時，我不會先改 stroke 座標，而是依序看四個觀察值。第一，瀏覽器 DevTools 裡 canvas 的 CSS width/height 與 attribute width/height 各是多少；兩者的比值是否等於預期 DPR。第二，context 的 getTransform() 是否只含一份 DPR，沒有因 resize 累乘。第三，將一個固定的 CSS point 印到畫面與 console，確認 pointer 換算回來的 scene point 相同。第四，才對一條已知 line width 的線檢查中心與可見外緣。</p><p>這個順序能把問題分層。例如 attribute 是 800、CSS box 是 1600，畫面糊但 pointer 正常，原因多半是 bitmap 被放大；attribute 是 1600、transform 又被 scale(2)，畫面與 pointer 都大一倍，原因是 transform 累乘；兩者都對但只有一條 1px 格線灰，才值得回到 half-pixel。把診斷寫成這種可觀察判斷，團隊才能在 issue 裡提供足夠資訊，而不是只附一張不一定顯示 DPR 的截圖。</p><h3>交付前的實測案例</h3><p>以簽名板為例，可以準備一個固定場景：畫 1px 與 2px 格線、可拖曳的矩形、可自由畫的筆刷和一張縮放影像。測試不應只在開發者的主螢幕跑一次。至少要在 DPR 1、2 與瀏覽器 125% 縮放下重放同一組 pointer 序列：按下 (100, 100)，移動到 (300, 200)，放開。重放後的 scene data 應相同；只有輸出的 bitmap 密度不同。</p><p>若產品支援匯出，還要明確選一種匯出語意。toDataURL() 或 toBlob() 匯出的是 drawing buffer，不是 CSS box。因此同一份 scene 在 DPR 2 的螢幕上若直接匯出，會得到兩倍解析度的檔案。這可能正是使用者要的高解析簽名，也可能是意外把檔案大小放大四倍。不要把 export 交給當前螢幕的 DPR 偶然決定；匯出函式應接受目標像素尺寸，建立暫時 canvas，用該尺寸重繪 scene，再輸出。</p><pre>async function exportPng(scene, width, height) {<br>  const canvas = document.createElement(&#39;canvas&#39;);<br>  canvas.width = width;<br>  canvas.height = height;<br>  const ctx = canvas.getContext(&#39;2d&#39;);<br>  drawScene(ctx, scene, { width, height });<br>  return new Promise(resolve =&gt; canvas.toBlob(resolve, &#39;image/png&#39;));<br>}</pre><p>這裡的 drawScene 不應偷偷讀 window.devicePixelRatio。螢幕 render 與 export render 共用圖形資料，卻有不同 raster target；把 target 當成明確參數，才能在測試中比較輸出，也能在 server-side 或 worker 環境重用同一套幾何邏輯。</p><p>最後，別用 getImageData() 當成唯一的視覺斷言。它適合檢查已知小區域的 alpha 或色值，卻會讓測試綁死抗鋸齒實作。對產品行為而言，scene 座標、命中結果、輸出尺寸和視覺 regression 截圖通常更穩定。像素值測試留給格線、橡皮擦或 blend mode 這類真的以 bitmap 結果為規格的功能。</p><h3>這套契約如何影響 API 設計</h3><p>當 canvas 功能從一個 component 長成編輯器，最容易出事的不是 lineTo()，而是函式參數沒有單位。drawLine(x1, y1, x2, y2) 看起來簡單，卻沒有說明它收的是 scene unit、CSS pixel 或 bitmap pixel。某個 call site 從 pointer event 傳入 CSS pixel，另一個匯出流程傳入 buffer pixel，兩者在 DPR 1 時巧合相同，直到高解析螢幕才爆炸。</p><p>比較可靠的方式是把單位放在資料邊界：scene 中的 Point 永遠是 CSS pixel；render target 附帶 cssSize 與 bitmapSize；只有 renderer 可以建立 transform。即使 JavaScript 沒有型別系統，也能用命名和小型 adapter 降低混用機率，例如 eventToScenePoint、sceneToBitmapMatrix，而不是通用的 toCanvasPoint。這些名稱不會讓 bug 消失，卻讓 code review 有機會問出正確問題：這個座標從哪裡來、要在哪裡被縮放？</p><p>同一原則也適用於 hit test。若 hit test 依賴 raster bitmap，例如讀 alpha 值，它會受 DPR、anti-aliasing 與 export size 影響；一般選取工具應優先在 scene 幾何上算距離，例如比較 pointer 到線段的最短距離是否小於以 CSS pixel 表示的 tolerance。畫面怎麼 rasterize 可以改，選取的產品語意不應跟著改。</p><p>把這個約定寫進測試與函式名稱後，Canvas 的問題才會從「某台電腦看起來糊」變成可以定位、重現並回歸驗證的工程問題。</p><p>真正需要避免的不是任何一個 API，而是沒有單位、沒有資料來源、也沒有驗收條件的修補。當這三件事被固定下來，顯示密度改變就只是 render target 的變化，不會改寫使用者操作的幾何事實。</p><h3>結語：把 0.5 留在推導結果，不要留在產品規則裡</h3><p>開頭那個簽名板的修正不是再加一層 offset，而是把責任拆開：scene 和 pointer 一律使用 CSS pixel；resize 時建立一次 DPR transform；描邊對齊只依可見邊界與線寬推導；context state 在每次 render 明確設定。這樣新增縮放、選取框、橡皮擦或匯出功能時，團隊仍能回答每個數值在哪一個座標系，而不是追一串不知道誰加上的 0.5。</p><h3>延伸閱讀</h3><p>- <a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D">MDN：Canvas 2D API</a></p><p>- <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_shapes">MDN：Drawing shapes with canvas</a></p><p>- <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Compositing">MDN：Compositing and clipping</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ba4c14f6a715" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[自架 ComfyUI 的可重現排錯：別把 Python、GPU、模型與網路曝露混成一個問題]]></title>
            <link>https://medium.com/@bgkong1205/%E8%87%AA%E6%9E%B6-comfyui-%E7%9A%84%E5%8F%AF%E9%87%8D%E7%8F%BE%E6%8E%92%E9%8C%AF-%E5%88%A5%E6%8A%8A-python-gpu-%E6%A8%A1%E5%9E%8B%E8%88%87%E7%B6%B2%E8%B7%AF%E6%9B%9D%E9%9C%B2%E6%B7%B7%E6%88%90%E4%B8%80%E5%80%8B%E5%95%8F%E9%A1%8C-a5ef8f1351aa?source=rss-3278bd6eeabe------2</link>
            <guid isPermaLink="false">https://medium.com/p/a5ef8f1351aa</guid>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[self-hosting]]></category>
            <category><![CDATA[comfy-ui]]></category>
            <category><![CDATA[mlops]]></category>
            <category><![CDATA[pytorch]]></category>
            <dc:creator><![CDATA[krownsh]]></dc:creator>
            <pubDate>Thu, 24 Sep 2026 02:04:36 GMT</pubDate>
            <atom:updated>2026-09-24T02:04:36.161Z</atom:updated>
            <content:encoded><![CDATA[<p>ComfyUI 跑不起來時，最浪費時間的做法是一次重裝所有東西。Torch not compiled with CUDA enabled、節點找不到 checkpoint、服務啟動了但外網打不開，分別屬於 runtime、模型索引與網路邊界；把它們一起改，最後很難知道是哪個修正真正生效。</p><p>這篇整理一套以「可觀察的邊界」切分的自架流程：先讓單一 Linux 使用者以固定 virtual environment 跑起來，再決定是否使用 GPU，最後才加 systemd 與反向代理。它以原始安裝紀錄為起點，但不把特定 CUDA wheel、IP 或網域當成可複製的常數。</p><h3>問題入口與本文目標：手動能跑，不等於服務可維運</h3><p>一個常見情境是：SSH 進主機、source venv/bin/activate 後執行 python main.py，瀏覽器可以開到 ComfyUI；改成 systemd 後卻看到 ModuleNotFoundError，修完 interpreter 又遇到 Torch not compiled with CUDA enabled，最後下載完模型，workflow 的 loader 下拉選單還是空的。若同時把 port 8188 開到公網，還多了一個沒有保護的管理介面。</p><p>這不是一個「ComfyUI 安裝失敗」問題，而是四個邊界被混在同一輪修改：runtime、加速器、模型契約和網路入口。本文的目標是建立可重現的診斷序列：每次只證明一個邊界，並留下能交接給下一位維運者的觀察結果。本文不提供某張顯卡或某個模型的唯一安裝指令；那些隨版本改變，應回到官方相容性矩陣和實際硬體。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iP3srKdIlwJuLwNlCVPOiA.png" /></figure><h3>失敗模式：在 shell 成功後，誤以為 systemd 也會成功</h3><p>把 ComfyUI clone 到固定路徑後，virtual environment 應和專案同層，讓 Python、套件與 systemd 的 ExecStart 指向同一個解譯器：</p><pre>git clone https://github.com/Comfy-Org/ComfyUI.git ~/ComfyUI<br>cd ~/ComfyUI<br>python3 -m venv venv<br>./venv/bin/python -m pip install --upgrade pip<br>./venv/bin/python -m pip install -r requirements.txt<br>./venv/bin/python main.py --listen 127.0.0.1 --port 8188</pre><p>先在 loopback 介面測通，比一開始就 --listen 0.0.0.0 好得多。這一步只回答兩個問題：程式能否用這個 interpreter import 依賴？本機 HTTP 能否回應？它還沒有證明 GPU、模型或 DNS 正常。</p><p>ComfyUI 是 node-based inference engine；模型與節點的組合才決定 workflow 是否可執行。<a href="https://docs.comfy.org/essentials/core-concepts/links">ComfyUI 官方文件：Core concepts</a></p><p>手動成功的 shell 有三項 systemd 沒有的隱含條件：目前使用者、目前目錄與已啟用的環境變數。source venv/bin/activate 本質上是修改這個 shell 的 PATH；它不會寫進服務程序。若 unit 的 ExecStart=python main.py，systemd 可能選到 /usr/bin/python3，而手動測試使用的是 ~/ComfyUI/venv/bin/python。兩邊版本相同也不能當作相同環境，依賴、CUDA build 和 custom node 都可能不同。</p><p>因此第一個驗收不是「瀏覽器看得到畫面」，而是以服務預計使用的完整命令跑一次：/home/ubuntu/ComfyUI/venv/bin/python /home/ubuntu/ComfyUI/main.py --listen 127.0.0.1 --port 8188。這個命令成功後，才能把它原封不動放進 ExecStart。若失敗，先在這個邊界排錯，不要讓 systemd 的 restart log 疊在真正錯誤上面。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*y1a3eK76YRgj0OWI9_gXuQ.png" /></figure><h3>技術模型：nvidia-smi 不是 pip 安裝指令</h3><p>原始筆記以 nvidia-smi 顯示的 CUDA version 選 wheel；這能當相容性線索，卻不能直接推導唯一的 PyTorch 安裝字串。NVIDIA driver、Python 版本、PyTorch release 與 wheel index 必須一起相容；官方 selector 才是每次安裝應取得的指令來源。<a href="https://pytorch.org/get-started/locally/">PyTorch：Start Locally</a></p><p>先在同一個 venv 驗證，而不是等 ComfyUI 失敗後再猜：</p><pre>./venv/bin/python - &lt;&lt;&#39;PY&#39;<br>import torch<br>print(&#39;torch:&#39;, torch.__version__)<br>print(&#39;cuda available:&#39;, torch.cuda.is_available())<br>print(&#39;cuda runtime:&#39;, torch.version.cuda)<br>PY</pre><p>torch.cuda.is_available() 為 false 時，可能是 CPU wheel、driver 不可用、容器沒有透傳 GPU，或 Python 根本不是你以為的 venv。Torch not compiled with CUDA enabled 則明確指出目前這個 torch build 沒有 CUDA；不要用「再裝一個 CUDA toolkit」掩蓋它。若目標機就是 CPU，應在啟動參數明示 CPU 模式，並接受吞吐量取捨，而不是讓 workflow 隨節點行為碰運氣。</p><p>CPU 模式不是低成本的 GPU 替代品。它適合先驗證 workflow、節點與模型路徑，也適合低頻、低解析度任務；一旦 queue 需要服務多人、使用高解析度或 video workflow，排隊時間與 RAM 壓力會改變部署設計。GPU 模式則增加 driver、wheel、VRAM 和升級相容性的維護成本。文章的決策點不是「GPU 一定比較好」，而是先量到同一個 interpreter 內的能力，再依吞吐需求選擇。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0xD89U0F8Eff7j7FdrhoQw.png" /></figure><h3>失敗模式：模型檔存在，卻沒有符合 loader 的契約</h3><p>模型目錄是 workflow 與檔案系統的契約。checkpoint、VAE、text encoder、LoRA 與 ControlNet 不是同一種輸入；將檔案都丟進 models/checkpoints/，在簡單 workflow 也許暫時看似可用，換一個 loader node 就會找不到。</p><p>先依節點要求建立明確目錄，再看 ComfyUI UI 中的下拉選單是否出現檔名。官方範例會將 checkpoint 放在 ComfyUI/models/checkpoints/；其他 loader 可能讀取不同子目錄，例如 DualCLIPLoader 會搜尋 models/text_encoders/。<a href="https://docs.comfy.org/zh/tutorials/3d/hunyuan3D-2">ComfyUI：模型放置範例</a> <a href="https://docs.comfy.org/built-in-nodes/DualCLIPLoader">ComfyUI：DualCLIPLoader</a></p><pre>find ~/ComfyUI/models -maxdepth 2 -type f -printf &#39;%p\n&#39; | sort<br>./venv/bin/python main.py --listen 127.0.0.1 --port 8188</pre><p>排查時要記錄「節點類型、期待的模型類別、實際路徑、載入錯誤」。只看副檔名 .safetensors 不足以證明相容；它是容器格式，不是模型架構宣告。</p><p>可把這份紀錄放進部署說明：workflow 使用哪個 checkpoint、哪個 VAE、哪個 text encoder；每個檔案的檔名、來源版本、sha256 和預期子目錄。這樣模型更新後出問題，才知道是 node、檔案、路徑或相容性改變。直接用「最新模型」覆寫原檔最難回復，也會讓一張成功輸出的圖無法被重現。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*v3sB-CDj4F4iDSRK9LdirQ.png" /></figure><h3>實作與驗證：systemd 的責任是重啟，不是替你啟用 venv</h3><p>手動 shell 裡的 source venv/bin/activate 不會傳給 systemd。服務單元必須使用 venv 裡的絕對路徑，且把 working directory 固定下來：</p><pre>[Unit]<br>Description=ComfyUI<br>After=network-online.target<br>Wants=network-online.target</pre><pre>[Service]<br>User=ubuntu<br>WorkingDirectory=/home/ubuntu/ComfyUI<br>Environment=PYTHONUNBUFFERED=1<br>ExecStart=/home/ubuntu/ComfyUI/venv/bin/python /home/ubuntu/ComfyUI/main.py --listen 127.0.0.1 --port 8188<br>Restart=on-failure<br>RestartSec=3</pre><pre>[Install]<br>WantedBy=multi-user.target</pre><p>修改 unit 後的固定驗證序列是：</p><pre>sudo systemctl daemon-reload<br>sudo systemctl restart comfyui<br>systemctl status comfyui --no-pager<br>sudo journalctl -u comfyui -n 100 --no-pager<br>curl -fsS http://127.0.0.1:8188/ &gt;/dev/null &amp;&amp; echo ok</pre><p>最後一行把「process 存在」和「HTTP 服務可用」拆開。若 journal 顯示 ModuleNotFoundError，先比對 ExecStart 和手動成功的 which python；若 port 已占用，找出殘留的手動程序，不要只把 Restart=always 調得更激進。</p><p>Restart=on-failure 比無條件重啟更容易觀察問題；對於設定錯誤，無限 restart 只會洗掉第一個 traceback。部署時也應設定記錄輪替與磁碟告警，因為模型載入失敗或 GPU OOM 的重複 log 可以很快塞滿小型 VM。服務健康檢查可以從 curl 開始，但若反向代理會處理 WebSocket 或大檔上傳，也要在 proxy 層做實際請求驗證。</p><h3>先畫出部署拓撲，才知道 log 應去哪裡找</h3><p>一個合理的長期部署通常有五個位置：使用者瀏覽器、公開 proxy 或 Tunnel、loopback 上的 ComfyUI HTTP server、systemd service、模型所在的磁碟卷。請求從左往右走，診斷則反向走。外網 502 時先看 proxy 是否連得到 127.0.0.1:8188；proxy 可通、UI 仍報模型錯誤時，再看 service journal；journal 顯示 loader 找不到檔案時，最後才查模型磁碟。這比直接在瀏覽器、Nginx 與 ComfyUI 三處來回改設定可靠。</p><p>服務帳號也屬於這張圖的一部分。模型若由 root 下載，ComfyUI 卻由 ubuntu 執行，檔案可能存在但不可讀；若 output 目錄由不同帳號建立，使用者又會看到儲存失敗。與其遇到錯誤就遞迴 chmod 777，應固定一個服務使用者與群組，確認模型、input、output 目錄的擁有權和 umask。權限過寬只會把一個部署錯誤變成可被其他本機帳號利用的資料曝露。</p><h3>以一個錯誤序列示範分層判斷</h3><p>假設 journal 顯示 Torch not compiled with CUDA enabled。先執行服務同一個 Python 的 capability snippet；若 torch.version.cuda 是 None，問題在目前 wheel，不在 ComfyUI workflow。此時要嘛依官方 selector 安裝相容 GPU build，要嘛明確選 CPU mode。若 capability 顯示 CUDA 可用、ComfyUI 卻在載入模型時 OOM，這是另一類問題：模型尺寸、batch size、resolution 或其他 process 使用 VRAM，不能用重裝 torch 處理。</p><p>再假設 UI 中 checkpoint 選單沒有檔案。先以服務帳號執行 find models -type f，再對照 loader node 文件所列的目錄，而不是再次下載同一個檔案。檔案存在且位置正確卻仍沒出現，才需要看啟動 log 是否掃描了不同 working directory，或 custom node 是否要求另一種模型家族。每一步都應保留命令、輸出和結論；這使問題能被重現，也讓升級後可以比較變更前後的狀態。</p><h3>升級、回退與容量不是附錄</h3><p>ComfyUI 與 custom nodes 變動快，直接在已工作的目錄 git pull 再 pip install -r requirements.txt，很容易把可用 workflow 改成不可用。較穩妥的流程是記錄目前 commit、requirements lock 或至少 pip freeze、workflow JSON 與模型 manifest；先在複本或維護時段升級，跑一個固定 smoke workflow，確認輸出和 log，再切換 service。失敗時回到已知 commit 和 venv，比在 production 主機猜哪個依賴壞掉快得多。</p><p>模型容量也應提早算。checkpoint、VAE、LoRA、輸入輸出與 pip cache 都在同一台機器累積；磁碟滿時可能表現成下載截斷、寫檔失敗或服務重啟。將模型目錄設在可監控的 volume，保留足夠的暫存空間，並在 runbook 中寫明清理規則。不要用不明來源的自動清理工作刪模型；它可能剛好刪掉某個 workflow 的唯一相依檔案。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AzxjYsAzfpdcN04CppkYPQ.png" /></figure><h3>取捨：對外發布時，8188 應留在內網邊界</h3><p>直接監聽 0.0.0.0:8188 加 UFW 規則可以快速測試，但它把沒有完整存取控管的圖形介面直接暴露出去。長期使用時，讓 ComfyUI 僅聽 127.0.0.1:8188，由反向代理負責 TLS、認證與 request limit；外部防火牆只需放行 proxy 所在的 80/443。</p><p>反向代理若承接 WebSocket，Upgrade 與 Connection header 不能省略。也不要為了「先通」把 authentication 拿掉：生成服務可能暴露 workflow、輸入輸出檔與昂貴的 GPU queue。若使用 Cloudflare Tunnel，先確認 tunnel 的 ingress 規則實際指向 loopback origin，並以 cloudflared tunnel ingress validate 驗證規則；不要把不通的 tunnel 與 ComfyUI runtime 問題混在一輪重裝裡。<a href="https://developers.cloudflare.com/tunnel/features/locally-managed-tunnels/configuration-file/">Cloudflare：驗證 ingress 規則</a></p><p>子網域通常比子路徑穩定，因為不少 node 前端資源、WebSocket 路由和 callback 預設假設服務在根路徑。子路徑不是不能做，但應把 base path、proxy rewrite、靜態資源與 WebSocket 都列進驗收。若服務只供維運者偶爾使用，SSH port forwarding 反而比公開域名簡單且安全；不必為了看起來正式而引入一套沒有人會維護的 TLS 和帳密系統。</p><p>公開入口的選擇也改變責任分工。SSH forwarding 將身分驗證留在既有 SSH 金鑰與主機帳號；reverse proxy 需要維護 TLS、帳密或 SSO、header 與上傳大小；Tunnel 減少入站防火牆設定，卻增加 connector、DNS 與 Zero Trust policy 的觀察面。沒有一種永遠較好。選擇應由使用者數量、是否有外部協作者、主機網路條件與維運能力決定。</p><p>無論哪種方式，都應限制可以排隊的工作量。ComfyUI 是耗資源的服務，一個公開端點若沒有認證、rate limit 或 queue 上限，別人不必取得 shell 就能耗盡 GPU、磁碟和頻寬。即使只放 basic auth，也至少要將它視為最小保護，而不是把它誤認成多租戶授權模型。若工作流包含私有圖片或商業模型，input、output 和 history 的保存期限同樣需要明確規則。</p><h3>可操作的驗收紀錄</h3><p>部署完成時，建議把以下輸出存入私有 runbook，而不是只留下「已成功」：服務的 systemctl status 摘要、使用的 Python 路徑與 torch 版本、CUDA 可用性、主要 workflow 的模型 manifest、curl loopback 結果、proxy 或 Tunnel 的健康結果，以及磁碟可用空間。它們能讓下一次故障從比較差異開始，而不是從頭猜環境。</p><p>這份紀錄不該包含 service key、SSH 私鑰、完整公開 IP 或模型下載 token。診斷資料與秘密要分開管理；把 .env、systemd environment 或 shell history 直接貼進 issue，是自架服務另一個比模型載入更昂貴的事故來源。</p><h3>讓排錯可以被別人接手</h3><p>最後要避免的是把所有知識留在某個人的終端機 history。將啟動命令、服務單元、proxy 設定、模型 manifest 和 smoke workflow 放進受版本控制的部署資料夾；私密值則由部署環境注入。每一次變更寫下「改了哪個邊界、預期觀察什麼、實際觀察什麼」。這個格式看似樸素，卻能防止最常見的維運失憶：兩週後有人只知道「之前把某個 flag 加上就好了」，卻不知道它是 CPU fallback、listen address，還是為了繞過一個已經消失的相容性問題。</p><p>故障時也應先保留證據再修。複製第一個 traceback、記下 service 使用的 commit 和模型版本、保存 nvidia-smi 與磁碟空間摘要，然後才嘗試 restart 或升級。這些資料讓你能區分偶發資源壓力與確定的版本回歸。對個人主機來說，這已經足夠；不需要把單機 ComfyUI 偽裝成 Kubernetes 平台，但也不該讓它只靠一次成功的手動指令存活。</p><p>當上述邊界都有明確的擁有者與驗收，新的模型、不同 GPU 或公開入口變更都只是局部調整。若任何一步無法回答「輸入是什麼、預期輸出是什麼、失敗要看哪份證據」，就先補 runbook，不要急著再加一個旗標。</p><p>這種紀律也降低成本。比起發生問題後重建 venv、重新下載模型、重設網域，先保存可重現設定只需要少量文件與一次 smoke test。對需要長期保留 workflow 的團隊，這份投入通常比追查一個不可重現的「昨天還可以」便宜得多。</p><p>如果是多人共用機器，還要把 queue 的擁有權說清楚：誰可以取消工作、誰負責清理 output、模型更新誰批准。技術設定只解決程序如何跑；沒有這些操作規則，昂貴資源仍會在「先跑一張看看」的累積下失控。把服務當成有成本的共享系統，才會自然需要限額、日誌與回復程序。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PuOKlV5QMOkQQIy7fN5kcw.png" /></figure><h3>驗證與收束：每次變更只跨一個邊界</h3><p>建議的排查順序如下：</p><p>1. ./venv/bin/python main.py 能否在 127.0.0.1:8188 啟動。</p><p>2. torch 在同一 interpreter 內是否真的可用 CUDA；否則明確使用 CPU 模式。</p><p>3. loader node 所需的模型是否位於正確目錄，並且 workflow 使用相容的模型家族。</p><p>4. systemd 是否使用完全相同的 Python、working directory 與啟動參數。</p><p>5. proxy 或 Tunnel 是否能從本機 origin 取得回應，並且外部入口有 TLS 與認證。</p><p>這個順序沒有保證生成會更快，卻能保證每一次修正都有可觀察的範圍。ComfyUI 自架的維運成本主要來自模型與 runtime 的組合變化；先把責任邊界畫清楚，升級、換 GPU 或新增 workflow 時才不會回到「整台重裝看看」的循環。</p><p>交付前可以用一張簡短 runbook 收尾：固定 venv 命令可啟動、服務 unit 使用同一命令、torch capability 已記錄、workflow 所需模型清單可核對、loopback origin 有 HTTP 回應、公開入口有認證與 TLS。這些不是形式上的 checklist；它們正好對應開頭那幾種互相偽裝的症狀。讀者遇到錯誤時，現在可以先判斷它屬於哪個邊界，再選對 log、命令或設定檔，而不是重裝全部。</p><h3>結語：把可啟動改成可定位、可回復</h3><p>自架 ComfyUI 最危險的狀態不是報錯，而是「偶爾能跑」卻沒有人知道它用了哪個 Python、哪個模型和哪個公開入口。將 runtime、GPU、模型與網路拆開後，升級失敗可以回退到已知模型版本，服務故障可以從 journal 定位，公開風險也不必靠把 8188 暴露到網際網路來換取便利。這才是部署流程真正要交付的結果。</p><h3>延伸閱讀</h3><p>- <a href="https://docs.comfy.org/essentials/core-concepts/links">ComfyUI 官方文件</a></p><p>- <a href="https://pytorch.org/get-started/locally/">PyTorch 安裝選擇器</a></p><p>- <a href="https://developers.cloudflare.com/tunnel/features/locally-managed-tunnels/configuration-file/">Cloudflare Tunnel ingress configuration</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a5ef8f1351aa" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[1Panel 顯示 OpenResty 異常時：從雜訊 log 找到 80/443 埠衝突的根因]]></title>
            <link>https://medium.com/@bgkong1205/1panel-%E9%A1%AF%E7%A4%BA-openresty-%E7%95%B0%E5%B8%B8%E6%99%82-%E5%BE%9E%E9%9B%9C%E8%A8%8A-log-%E6%89%BE%E5%88%B0-80-443-%E5%9F%A0%E8%A1%9D%E7%AA%81%E7%9A%84%E6%A0%B9%E5%9B%A0-92d95fb4ff75?source=rss-3278bd6eeabe------2</link>
            <guid isPermaLink="false">https://medium.com/p/92d95fb4ff75</guid>
            <category><![CDATA[proxy]]></category>
            <category><![CDATA[nginx]]></category>
            <category><![CDATA[troubleshooting]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[docker]]></category>
            <dc:creator><![CDATA[krownsh]]></dc:creator>
            <pubDate>Fri, 18 Sep 2026 01:29:54 GMT</pubDate>
            <atom:updated>2026-09-18T01:29:54.151Z</atom:updated>
            <content:encoded><![CDATA[<p>按下重啟後 OpenResty 顯示異常，未必是最近改過的網站設定。這次根因是主機的 system Nginx 已監聽 :80，而 1Panel 管理的 OpenResty 容器也要發布同一個 host port。兩個 process 不可能同時佔用同一組 IP、protocol、port。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pwCiWO6ylKyoPQlkrBJLgA.png" /></figure><h3>container port 與 host port 是兩層</h3><p>container 內的 80 與 host 的 80 不在同一個命名空間；衝突發生在 Docker 把 container port 發布到 host 的那一步。未指定 host IP 的 -p 80:80 會綁定所有介面，因此常看到 bind() to 0.0.0.0:80 failed (98: Address already in use)。<a href="https://docs.docker.com/reference/cli/docker/container/run">Docker 文件</a></p><pre>client → host :80 / :443 → Docker published port → OpenResty container → upstream<br>                    ↑ system nginx 也可能在此監聽</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xAXTi-wjFMgZVu3-pCokXQ.png" /></figure><h3>先驗證誰真的在聽</h3><pre>sudo ss -ltnp &#39;( sport = :80 or sport = :443 )&#39;<br>docker ps -a --format &#39;table {{.Names}}\t{{.Status}}\t{{.Ports}}&#39;<br>docker port &lt;openresty-container&gt;<br>docker logs --tail 200 &lt;openresty-container&gt;</pre><p>第一個問題是 host listener 的 PID／process 是誰；第二個問題是 container 在重啟、exited，或已 running 卻不健康。docker ps -a、docker port 與 logs 把這幾種狀態分開。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*o-Tosr9uJAdAUPU_aumiJA.png" /></figure><h3>把 blocker 與雜訊分開</h3><p>缺少 access.log 可能要修，但它不會釋放 :80。若 OpenResty 在 bind 階段就退出，啟動後才會用到的設定不是當前 blocker。nginx -t 會檢查設定且嘗試開啟引用檔案；Permission denied 也可能只是執行檢查的帳號不具權限。<a href="https://nginx.org/en/docs/switches.html">NGINX 文件</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kYF_xDonc_8Ny7-vz9j9Lw.png" /></figure><h3>先決定誰擁有 public entrypoint</h3><p>不要看到衝突就隨便停一個服務。若所有網站都由 1Panel 管理，可在確認沒有未遷移站點後，停止多餘的 host Nginx，再重啟具名的 OpenResty container。若 host Nginx 是既有入口，就讓 OpenResty 使用不衝突的 host port，由 Nginx 明確反向代理。多個站點可共用一個 reverse proxy；多個 reverse proxy 不能直接共用同一個 listener。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*BpMyc9w0A7lwY_GRZmF4ZQ.png" /></figure><h3>修復後驗證</h3><pre>sudo ss -ltnp &#39;( sport = :80 or sport = :443 )&#39;<br>docker ps --format &#39;table {{.Names}}\t{{.Status}}\t{{.Ports}}&#39;<br>curl -I --resolve example.com:80:127.0.0.1 http://example.com/<br>curl -Ik --resolve example.com:443:127.0.0.1 https://example.com/</pre><p>確認 listener owner、container 狀態、Host routing 與 TLS，再從外部網路測試。雲端環境還要把安全群組、主機防火牆與 Docker published port 分開檢查。<a href="https://1panel.cn/docs/v2/user_manual/hosts/firewall/">1Panel 文件</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=92d95fb4ff75" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Google 登入接到 credential 之後：ID token 的伺服器驗證、Origin 排障與帳號模型]]></title>
            <link>https://medium.com/@bgkong1205/google-%E7%99%BB%E5%85%A5%E6%8E%A5%E5%88%B0-credential-%E4%B9%8B%E5%BE%8C-id-token-%E7%9A%84%E4%BC%BA%E6%9C%8D%E5%99%A8%E9%A9%97%E8%AD%89-origin-%E6%8E%92%E9%9A%9C%E8%88%87%E5%B8%B3%E8%99%9F%E6%A8%A1%E5%9E%8B-1583e15093e3?source=rss-3278bd6eeabe------2</link>
            <guid isPermaLink="false">https://medium.com/p/1583e15093e3</guid>
            <category><![CDATA[google]]></category>
            <category><![CDATA[react]]></category>
            <category><![CDATA[web-security]]></category>
            <category><![CDATA[google-oauth]]></category>
            <category><![CDATA[authentication]]></category>
            <dc:creator><![CDATA[krownsh]]></dc:creator>
            <pubDate>Wed, 16 Sep 2026 02:22:08 GMT</pubDate>
            <atom:updated>2026-09-16T02:22:08.775Z</atom:updated>
            <content:encoded><![CDATA[<p>@react-oauth/google 的按鈕能叫出來，並不代表登入功能已經完成。瀏覽器 callback 拿到的 credential 是 Google 簽發的 ID token；前端把它 decode 後看到 email、姓名與頭像，只能用來更新畫面，不能當成後端的身分驗證結果。真正的信任邊界在 API：伺服器必須驗證簽章、issuer、audience 與到期時間，再把 Google 的 sub 映射到自己的帳號。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JTdOW9cL5umGJAweJfHd9A.png" /></figure><h3>先釐清資料流：Google 證明什麼，後端又必須做什麼</h3><p>Google Identity Services 在 popup callback 回傳 CredentialResponse；其中的 credential 是 JWT 型態的 ID token。瀏覽器端的 Base64 decode 不會驗證簽章，也不會限制 token 是不是簽給自己的應用程式。</p><pre>Google Identity Services<br>  → browser receives credential (ID token)<br>  → HTTPS POST /auth/google { credential }<br>  → backend verifies signature + iss + aud + exp<br>  → lookup / link local user by Google sub<br>  → backend issues its own session cookie or access token</pre><p>Google 官方驗證流程要求後端指定 web client ID 作為 audience；官方 client library 會驗證 JWT 簽章、aud、iss 與 exp。<a href="https://developers.google.com/identity/gsi/web/guides/verify-google-id-token">Google：Verify the Google ID token on your server side</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5xvnj5bCREXa489mxvJBMw.png" /></figure><h3>decode 是觀察工具，不是驗證器</h3><p>用 jwt.io 或前端程式 decode token，適合排查 callback 有沒有拿到預期欄位；它不應出現在授權判斷中。攻擊者可以自行組一段 payload，或將簽給別的 client ID 的真 token 送到 API。只看 email 時，後端沒有證據能判斷這是 Google 對本服務簽發。</p><h3>React callback 只負責交付 credential</h3><pre>const response = await fetch(&#39;/api/auth/google&#39;, {<br>  method: &#39;POST&#39;,<br>  headers: { &#39;content-type&#39;: &#39;application/json&#39; },<br>  credentials: &#39;include&#39;,<br>  body: JSON.stringify({ credential }),<br>});</pre><p>Client ID 本來就是公開識別子；不能進前端 bundle 的是 client secret、資料庫權限或內部 session 簽章金鑰。也不要在 console 印出完整 credential：它仍然是 bearer credential，可能被開發者工具、集中式日誌與 error reporting 留得比預期久。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YMVJwjKLnyOetS-4OhcYfA.png" /></figure><h3>後端驗證與帳號關聯</h3><pre>const ticket = await google.verifyIdToken({<br>  idToken: credential,<br>  audience: process.env.GOOGLE_WEB_CLIENT_ID,<br>});<br>const claims = ticket.getPayload();</pre><pre>return findOrCreateUser({<br>  provider: &#39;google&#39;,<br>  providerSubject: claims.sub,<br>  email: claims.email,<br>});</pre><p>verifyIdToken() 已處理簽章與標準 claims 的驗證；若系統只允許特定 Google Workspace 成員，還要明確比對 hd，不能用 email 網域取代它。帳號關聯應以穩定、唯一的 sub 為鍵，將登入方式拆成 external_identities(provider, provider_subject)，而不是以可變的 email 當外部身分主鍵。首次登入是否可自動合併到舊帳號，是產品風險決策；高風險系統應要求既有登入態或其他所有權證據。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*d92BH1ISBGVVvxyWroIfBg.png" /></figure><h3>localhost 和 127.0.0.1 不可互換：Origin 是三元組</h3><p>開發頁面是否與 http://localhost:3000 同一 originhttp://localhost:3000是http://localhost:5173否，port 不同http://127.0.0.1:3000否，host 不同https://localhost:3000否，scheme 不同</p><p>Authorized JavaScript origins 必須和實際瀏覽器 origin 完全相同。不要只改 Vite 設定讓錯誤消失；把實際使用的 scheme、host、port 與 Cloud Console 註冊值逐一對上。採用 CSP 或 popup 時，也依 Google 文件檢查 GIS 的 CSP 來源與 COOP 設定。<a href="https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid">Google：設定 client ID 與 Authorized JavaScript origins</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Fg9S0unMXzSbkHluO_vBWA.png" /></figure><h3>上線前的最小驗收</h3><ol><li>API 拒絕竄改 token、過期 token、錯誤 aud 與錯誤 iss。</li><li>前端不記錄完整 credential；傳輸走 HTTPS，登入端點有 rate limit。</li><li>本地、staging、production 的 origin 清單逐一測過。</li><li>帳號連結、解除連結、衝突 email 與帳號合併都有測試。</li><li>服務自己的 session 設定好 HttpOnly、Secure、SameSite。</li></ol><h3>延伸閱讀</h3><ul><li><a href="https://developers.google.com/identity/gsi/web/guides/integrate">Google Identity Services：Integration considerations</a></li><li><a href="https://developers.google.com/identity/gsi/web/guides/display-button">Google Identity Services：Display the Sign In With Google button</a></li><li><a href="https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html">OWASP Authentication Cheat Sheet</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1583e15093e3" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[MySQL 聚合查詢的正確性與效能：JOIN fan-out、基數契約與 EXPLAIN ANALYZE]]></title>
            <link>https://medium.com/@bgkong1205/mysql-%E8%81%9A%E5%90%88%E6%9F%A5%E8%A9%A2%E7%9A%84%E6%AD%A3%E7%A2%BA%E6%80%A7%E8%88%87%E6%95%88%E8%83%BD-join-fan-out-%E5%9F%BA%E6%95%B8%E5%A5%91%E7%B4%84%E8%88%87-explain-analyze-9af9560d7142?source=rss-3278bd6eeabe------2</link>
            <guid isPermaLink="false">https://medium.com/p/9af9560d7142</guid>
            <category><![CDATA[performance]]></category>
            <category><![CDATA[database]]></category>
            <category><![CDATA[sql]]></category>
            <category><![CDATA[mysql]]></category>
            <category><![CDATA[query-optimization]]></category>
            <dc:creator><![CDATA[krownsh]]></dc:creator>
            <pubDate>Wed, 16 Sep 2026 01:53:43 GMT</pubDate>
            <atom:updated>2026-09-16T01:53:43.309Z</atom:updated>
            <content:encoded><![CDATA[<p>多表 JOIN 後再 COUNT，最危險的錯不是語法，而是結果集在聚合前已經膨脹。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*A36i5JV7JNFHhgMYCkt24w.png" /></figure><h3>先決定要保留哪張表</h3><pre>SELECT h.address, COUNT(l.hid) AS resident_count<br>FROM house AS h LEFT JOIN live AS l ON l.hid = h.hid<br>GROUP BY h.hid, h.address;</pre><p>COUNT(l.hid) 只數非 NULL 的居住紀錄；COUNT(*) 會計入外連接補出的列。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*n5cvego4bH4wcGNxTjhzsg.png" /></figure><h3>GROUP BY、COUNT 與排序</h3><pre>SELECT u.cname, COUNT(l.hid) AS address_count<br>FROM userinfo AS u LEFT JOIN live AS l ON l.uid = u.uid<br>GROUP BY u.uid, u.cname ORDER BY address_count DESC;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wCIYH334DpwJ2v91yekIFg.png" /></figure><h3>WHERE 篩列，HAVING 篩群組</h3><pre>SELECT h.address, COUNT(l.hid) AS resident_count<br>FROM house AS h LEFT JOIN live AS l ON l.hid = h.hid<br>GROUP BY h.hid, h.address HAVING COUNT(l.hid) &gt; 0;</pre><p>原始欄位條件放 WHERE；聚合條件放 HAVING。右表條件放到 WHERE 可能把 LEFT JOIN 收窄成 INNER JOIN；保留左表時，條件應放 ON 或預先過濾的 CTE。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rEN4lXbhepHujEeOmA1O3Q.png" /></figure><h3>用 View 重用查詢</h3><pre>CREATE VIEW address_resident_count AS<br>SELECT h.hid, h.address, COUNT(l.hid) AS resident_count<br>FROM house AS h LEFT JOIN live AS l ON l.hid = h.hid<br>GROUP BY h.hid, h.address;</pre><p>View 是可重用的查詢介面；權限仍需另外規劃。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HqB2E9iShdtlHUH_g0j-3A.png" /></figure><h3>JOIN fan-out：先聚合，再 JOIN</h3><p>住址同時接上多筆 live 與多筆 payment 時，直接三表 JOIN 會把列數相乘。先把每個一對多分支聚合回主鍵粒度，再 JOIN，才能避免重複計數與重複加總。</p><pre>WITH residents AS (<br>  SELECT hid, COUNT(DISTINCT uid) AS resident_count<br>  FROM live WHERE ended_at IS NULL GROUP BY hid<br>), payments AS (<br>  SELECT hid, SUM(amount) AS paid_amount FROM payment GROUP BY hid<br>)<br>SELECT h.hid, r.resident_count, p.paid_amount<br>FROM house AS h<br>LEFT JOIN residents AS r ON r.hid = h.hid<br>LEFT JOIN payments AS p ON p.hid = h.hid;</pre><h3>效能驗證</h3><p>索引是讀寫取捨。用 EXPLAIN ANALYZE 比較估計與實際 rows、loops 和時間；估計失真時先檢查統計資訊。</p><pre>EXPLAIN ANALYZE<br>SELECT h.hid, COUNT(l.uid)<br>FROM house AS h<br>LEFT JOIN live AS l ON l.hid = h.hid AND l.ended_at IS NULL<br>GROUP BY h.hid;</pre><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9af9560d7142" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[React 登入頁的 SCA 資料流告警：先追真實密碼流向，再判斷是不是誤判]]></title>
            <link>https://medium.com/@bgkong1205/react-%E7%99%BB%E5%85%A5%E9%A0%81%E7%9A%84-sca-%E8%B3%87%E6%96%99%E6%B5%81%E5%91%8A%E8%AD%A6-%E5%85%88%E8%BF%BD%E7%9C%9F%E5%AF%A6%E5%AF%86%E7%A2%BC%E6%B5%81%E5%90%91-%E5%86%8D%E5%88%A4%E6%96%B7%E6%98%AF%E4%B8%8D%E6%98%AF%E8%AA%A4%E5%88%A4-64a7979bc7f1?source=rss-3278bd6eeabe------2</link>
            <guid isPermaLink="false">https://medium.com/p/64a7979bc7f1</guid>
            <category><![CDATA[react]]></category>
            <category><![CDATA[弱點掃描]]></category>
            <category><![CDATA[passwords]]></category>
            <category><![CDATA[ca]]></category>
            <dc:creator><![CDATA[krownsh]]></dc:creator>
            <pubDate>Mon, 14 Sep 2026 09:18:31 GMT</pubDate>
            <atom:updated>2026-09-14T09:18:31.950Z</atom:updated>
            <content:encoded><![CDATA[<p>React 登入頁的「顯示／隱藏密碼」按鈕，也可能被 SCA Data Flow 掃描報成 Privacy Violation／Critical。這種告警很刺眼，卻不能只看元件名稱或告警嚴重度就下結論。真正要回答的是：使用者輸入的密碼值，有沒有從 Source 經過程式傳遞到不該去的 Sink？</p><p>這篇整理一次實際排查：掃描器把 onTogglePassword、React state、render() 與 DOM 串成路徑；但實際進入 state 的只是控制畫面的 boolean，不是密碼內容。這是值得檢查的保守告警，卻不等於已證實密碼外洩。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SgU8ZT3nltmbJZ7V2VOYrQ.png" /></figure><h3>告警長什麼樣子</h3><p>這次的掃描報告大意如下：</p><pre>Source: Read this.onTogglePassword<br>From: Login.render<br>File: Login.jsx:73</pre><pre>Sink: Assignment to textContent<br>Enclosing Method: render()<br>File: Login.jsx:55<br>Taint Flags: PRIVATE</pre><p>原本的功能很單純：點眼睛按鈕後，切換 showPassword，React 重新渲染，再依狀態改變輸入框的 type、按鈕的 aria-label 與圖示。</p><pre>this.state = {<br>  showPassword: false,<br>};</pre><pre>onTogglePassword = () =&gt; {<br>  this.setState((previous) =&gt; ({<br>    showPassword: !previous.showPassword,<br>  }));<br>};</pre><pre>// render()<br>const { showPassword } = this.state;</pre><pre>&lt;input type={showPassword ? &#39;text&#39; : &#39;password&#39;} /&gt;<br>&lt;button<br>  type=&quot;button&quot;<br>  aria-label={showPassword ? &#39;隱藏密碼&#39; : &#39;顯示密碼&#39;}<br>  onClick={this.onTogglePassword}<br>&gt;<br>  {showPassword ? &lt;VisibilityOff /&gt; : &lt;Visibility /&gt;}<br>&lt;/button&gt;</pre><p>從 React 的角度，這是正常的 render 驅動 UI：showPassword 會影響 JSX，所以用 state 保存是合理的。React 也將 type、aria-label 與圖示轉成 DOM 更新；掃描器看到 state 最後抵達 DOM，並不奇怪。問題是它是否把「控制 UI 的資料」誤當成「密碼值」。</p><h3>先把兩種資料拆開</h3><p>排查時最容易混在一起的是名稱與語意。showPassword 含有 password 字樣，但它的值只有 true 或 false；它說的是「目前要不要露出文字」，不是「使用者輸入了什麼」。</p><p>資料內容是否該出現在一般 DOM 文案showPasswordtrue / false 的 UI 狀態可以，用來決定 type、圖示或無障礙標籤this.pwd.current.value使用者輸入的密碼字串不可以；不得渲染、記錄或送往不必要的地方</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FcncH8YHBv2ZZQzP0KsKJA.png" /></figure><p>這兩條資料流應該長得不一樣：</p><pre>UI 狀態<br>onTogglePassword()<br>  → setState(showPassword)<br>  → render()<br>  → input type / aria-label / icon</pre><pre>真正的密碼資料<br>password input<br>  → this.pwd.current.value<br>  → SignIn(account, password, code)<br>  → action payload<br>  → saga<br>  → sign_in(param)<br>  → 登入 API</pre><p>原始登入流程會在送出時讀取 this.pwd.current.value：</p><pre>SignIn(<br>  this.act.current.value,<br>  this.pwd.current.value,<br>  this.code.current.value,<br>);</pre><p>這不是問題本身；登入功能本來就得把密碼送到登入 API。要查的是它有沒有在途中分支到 console.log、DOM 文字、URL query string、瀏覽器儲存空間、錯誤回報或分析服務。OWASP 特別提醒不要把敏感資料放進瀏覽器本地儲存，也要求日誌排除密碼等機密欄位。<a href="https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html">OWASP HTML5 Security Cheat Sheet</a>、<a href="https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html">OWASP Logging Cheat Sheet</a></p><h3>為什麼掃描器仍然值得被認真對待</h3><p>SCA／靜態分析工具通常不會理解產品需求，它做的是保守的 taint propagation：從可能敏感的 Source 出發，追蹤變數、state 與函式呼叫，最後標示碰到的 Sink。</p><p>如果程式真的是這樣，告警就完全正確：</p><pre>this.setState({<br>  password: this.pwd.current.value,<br>});</pre><pre>// render()<br>&lt;div&gt;{this.state.password}&lt;/div&gt;</pre><p>這條路徑會把密碼顯示為文字節點。即便只是為了除錯，也不應存在。</p><p>本案的可疑處在於，掃描器可能以登入頁位置、handler 名稱含有 Password、handler 控制 password input、state 參與 render，以及 DOM sink 等訊號，推得一條過寬的路徑。這是合理的「請人工核對」，不是可以直接忽略的「工具壞掉」。</p><h3>這次怎麼驗證告警</h3><p>我會依 Source、Propagation、Sink 三段逐一對照，而不是從修程式開始。</p><ol><li><strong>確認 Source。</strong>搜尋 this.pwd.current.value、password 和表單 submit；確認 toggle handler 沒有讀取密碼值。</li><li><strong>確認 Propagation。</strong>沿著密碼變數、action payload、Saga 與 API client 追蹤；分開標記 boolean UI state 與 password string。</li><li><strong>確認 Sink。</strong>搜尋 textContent、innerHTML、JSX interpolation、console.*、storage、URL 與 telemetry；確認密碼只進入必要的登入請求。</li><li><strong>做回歸測試。</strong>實際切換可見性、送出登入、檢查瀏覽器 console、Network request 與錯誤回報；同時確認無障礙標籤和鍵盤操作沒有退化。</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NtRANZcABd75nukP9ZdSiA.png" /></figure><h3>以 ref 直接改 input.type：可作為降噪手段，但不是預設解</h3><p>這次專案最後把切換功能改成直接修改 input ref 的 type：</p><pre>onTogglePassword = () =&gt; {<br>  const input = this.pwd.current;<br>  input.type = input.type === &#39;password&#39; ? &#39;text&#39; : &#39;password&#39;;<br>};</pre><p>這樣會讓 UI boolean 不再參與 render，掃描器也不容易把 toggle 串成 state → DOM 的資料流。若這個 input 沒有同時由 JSX 的 type prop 控制，且每個更新點都能維護一致，這是可行的局部處理。</p><p>不過它不是一條通用的 React 最佳實務。React 將 ref 視為 escape hatch，並提醒手動改動 React 管理的 DOM 可能和後續 render 衝突；若 JSX 仍會重新指定 type，下一次 render 就可能覆蓋直接修改的結果。<a href="https://react.dev/learn/manipulating-the-dom-with-refs">React：Manipulating the DOM with Refs</a>、<a href="https://react.dev/learn/referencing-values-with-refs">React：Referencing Values with Refs</a></p><p>因此，採用這種改法前至少確認三件事：</p><ul><li>type 不再由 JSX 或其他 state 同時控制。</li><li>handler 不讀取、不複製、不記錄密碼值。</li><li>已補上切換、重新渲染、登入送出與無障礙行為的測試。</li></ul><p>若掃描規則支援追蹤精度調整、註解抑制或誤判申覆，完成上述證據後也可以保留宣告式 state 寫法，並在告警處留下精準說明。目標不是把掃描壓到綠燈，而是讓報告與真實風險對得上。</p><h3>結語：Critical 是起點，不是判決</h3><p>這次的重點不是「showPassword 放 state 對不對」，而是不要讓名字與畫面結構取代資料流證據。密碼真正從哪裡被讀取？中間被誰帶走？最後抵達哪個 Sink？把這三個問題答清楚，才能把真正的外洩風險抓出來，也能有根據地處理誤判。</p><h3>延伸閱讀</h3><ul><li><a href="https://react.dev/reference/react-dom/components/input">React &lt;input&gt; 參考文件</a></li><li><a href="https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html">OWASP Authentication Cheat Sheet</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=64a7979bc7f1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI 產品開發工作流：把一個 idea 收斂成可執行的 MVP]]></title>
            <link>https://medium.com/@bgkong1205/ai-%E7%94%A2%E5%93%81%E9%96%8B%E7%99%BC%E5%B7%A5%E4%BD%9C%E6%B5%81-%E6%8A%8A%E4%B8%80%E5%80%8B-idea-%E6%94%B6%E6%96%82%E6%88%90%E5%8F%AF%E5%9F%B7%E8%A1%8C%E7%9A%84-mvp-a640321e1cfe?source=rss-3278bd6eeabe------2</link>
            <guid isPermaLink="false">https://medium.com/p/a640321e1cfe</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[vibe-coding]]></category>
            <category><![CDATA[web3]]></category>
            <category><![CDATA[vibe]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[krownsh]]></dc:creator>
            <pubDate>Mon, 31 Aug 2026 08:04:32 GMT</pubDate>
            <atom:updated>2026-08-31T08:04:32.299Z</atom:updated>
            <content:encoded><![CDATA[<p>產品 idea 很容易被模型擴成一長串功能，難的是把它變成下一個人或 Agent 能執行的規格。這套流程讓 AI 協助展開與整理，產品取捨仍由人決定。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_r5Gon3QM8fRM51O4jjvsA.png" /></figure><h3>先把問題寫成可驗證的假設</h3><p>先寫一句話定位、目標使用者、核心問題、使用情境、必備功能和 anti-scope。Anti-scope 會告訴團隊這一版明確不做什麼。</p><h3>讓功能清單接受取捨</h3><p>讓客戶與工程師 PM 用同一份草案討論，每輪都更新功能決議快照：保留、刪除、延後或尚有爭議，並標示 P0、P1、P2。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*yWLsah5G_gNmwBp2iTKVAg.png" /></figure><h3>把共識回寫成可交接文件</h3><p>把決議拆成 main、使用流程、頁面、資料模型、Agent 指引和任務清單。不要把所有內容塞進單一提示；拆開後才容易同步更新與檢查矛盾。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TdwJzhnP_I51Oy7Af0Betw.png" /></figure><h3>執行順序</h3><ol><li>概念與 anti-scope</li><li>高層架構草案</li><li>雙角色取捨與功能快照</li><li>最新版架構與 MVP 摘要</li><li>實作文件，再開始 coding</li></ol><p>AI 很適合找缺漏與整理共識；是否做、先做什麼、能承受多少成本，仍是產品負責人的工作。</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a640321e1cfe" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Supabase 自架 Storage 排錯：從 JWT、公開 URL 到容器重建]]></title>
            <link>https://medium.com/@bgkong1205/supabase-%E8%87%AA%E6%9E%B6-storage-%E6%8E%92%E9%8C%AF-%E5%BE%9E-jwt-%E5%85%AC%E9%96%8B-url-%E5%88%B0%E5%AE%B9%E5%99%A8%E9%87%8D%E5%BB%BA-648047540da8?source=rss-3278bd6eeabe------2</link>
            <guid isPermaLink="false">https://medium.com/p/648047540da8</guid>
            <category><![CDATA[web3]]></category>
            <category><![CDATA[jwt]]></category>
            <category><![CDATA[deployment]]></category>
            <category><![CDATA[supabase]]></category>
            <category><![CDATA[vibe-coding]]></category>
            <dc:creator><![CDATA[krownsh]]></dc:creator>
            <pubDate>Mon, 31 Aug 2026 08:01:15 GMT</pubDate>
            <atom:updated>2026-08-31T08:01:15.506Z</atom:updated>
            <content:encoded><![CDATA[<p>Storage bucket 消失或上傳回 403，未必是 RLS。先依驗證、路由、容器設定、最後才是 Storage policy 的順序檢查。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XQo_Ncn0U4w84bssI0D26Q.png" /></figure><h3>先判斷在哪一層失敗</h3><p>Invalid Compact JWS 或 403 Unauthorized 先看 JWT。舊式 API key 的 JWT secret 與 anon、service-role key 必須相容；啟用新 API key 時，所有驗證服務必須取得對應 JWKS。</p><h3>公開 URL 必須讓瀏覽器抵達</h3><p>SUPABASE_PUBLIC_URL 是外部可連的 base URL，不是遠端使用者的 localhost。同時檢查 API_EXTERNAL_URL、SITE_URL、反向代理 header，以及 Network 面板中的實際請求 URL。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7z-86778YzECBq4eTZcuOw.png" /></figure><h3>改 .env 後重建容器</h3><p>新版官方 Docker 專案可用 sh run.sh recreate [service]；舊專案依其 compose 流程強制 recreate。之後從容器內驗證有效環境變數，且不要輸出完整 secret。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*soeO8c1JSBPXf1tnUFwvGg.png" /></figure><h3>最小檢查清單</h3><ol><li>確認實際 URL、status 與 response body。</li><li>比對 gateway、Auth、Storage、REST 的 JWT／JWKS 設定。</li><li>確認三個外部 URL 設定。</li><li>重建容器並檢查容器內環境。</li><li>最後檢查 bucket、RLS、CORS 與反向代理。</li></ol><p>官方參考：自架 Docker、API key 與 JWT、Storage 設定文件。</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=648047540da8" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Cloudflare Tunnel 免費公網 IP 與多網域 HTTPS 路由實戰]]></title>
            <link>https://medium.com/@bgkong1205/cloudflare-tunnel-%E5%85%8D%E8%B2%BB%E5%85%AC%E7%B6%B2-ip-%E8%88%87%E5%A4%9A%E7%B6%B2%E5%9F%9F-https-%E8%B7%AF%E7%94%B1%E5%AF%A6%E6%88%B0-1841f2d74af2?source=rss-3278bd6eeabe------2</link>
            <guid isPermaLink="false">https://medium.com/p/1841f2d74af2</guid>
            <category><![CDATA[cloudflare]]></category>
            <category><![CDATA[ssh-tunnel]]></category>
            <category><![CDATA[web3]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[front-end-development]]></category>
            <dc:creator><![CDATA[krownsh]]></dc:creator>
            <pubDate>Fri, 28 Aug 2026 06:02:58 GMT</pubDate>
            <atom:updated>2026-08-28T06:02:58.790Z</atom:updated>
            <content:encoded><![CDATA[<p>在雲端主機（如 Oracle Cloud 充當自建伺服器或家用舊電腦）架設服務時，過去最令人頭痛的問題莫過於：電信業者沒有提供固定公網 IPv4、防火牆 Port 沒開，或是手動設定 Nginx 反向代理配合 Let’s Encrypt 憑證，每隔幾個月就要擔心更新失敗。</p><p>Cloudflare Tunnel（先前稱為 Argo Tunnel）徹底改變了這個邏輯。它不需要你在主機上對外開放任何 80 或 443 通訊埠，而是透過主機端的守護進程 cloudflared，自動向 Cloudflare 邊界節點建立一條出站（Outbound）的加密長連線。</p><p>這意味著：即使你的伺服器藏在 NAT、家用寬頻或嚴格的防火牆後方，只要主機可以連上網際網路，就能安全地將本地運行的 HTTP 服務（如 n8n、Web 應用、API 介面）綁定到自訂域名，並自動享有免費的 HTTPS 證書與 DDoS 防護。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Atrw4Ff-w-MV5TR-KOCrxg.png" /><figcaption><em>Cloudflare Tunnel 透過出站加密長連線對接內網服務與 Cloudflare 邊界</em></figcaption></figure><h3>前置條件與架構設計</h3><p>開始前，請準備好以下環境：</p><ol><li><strong>Cloudflare 帳號</strong>：註冊並登入 Cloudflare（免費方案即足夠使用）。</li><li><strong>託管網域</strong>：擁有一個自訂網域（例如 example.com），且 DNS 解析已託管至 Cloudflare。</li><li><strong>本地 HTTP 服務</strong>：已在伺服器上運行的本地服務（如 n8n: http://localhost:5678, API: http://localhost:8080）。</li><li><strong>安裝 </strong><strong>cloudflared 伺服器</strong>：在主機上下載並安裝 Cloudflare 官方 CLI 工具。</li></ol><h3>步驟一：安裝並授權 cloudflared</h3><p>在 Linux 伺服器終端機中執行以下指令進行安裝：</p><pre># 以 Ubuntu / Debian 為例下載最新版 deb 套件<br>wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb</pre><pre># 安裝套件<br>sudo dpkg -i cloudflared-linux-amd64.deb</pre><pre># 確認版本號以驗證安裝成功<br>cloudflared --version</pre><p>安裝完成後，執行授權綁定：</p><pre>cloudflared tunnel login</pre><p>開啟瀏覽器完成授權，主機會在 ~/.cloudflared/cert.pem 生成全域憑證檔案。</p><h3>步驟二：建立命名 Tunnel 與 DNS 紀錄</h3><p>建立專屬命名 Tunnel：</p><pre>cloudflared tunnel create my-services</pre><p>記下回傳的 Tunnel UUID，並至 Cloudflare DNS Dashboard 設定 CNAME 紀錄：</p><ul><li><strong>Type</strong>: CNAME</li><li><strong>Name</strong>: 子網域名稱（如 n8n）</li><li><strong>Target</strong>: &lt;Tunnel-UUID&gt;.cfargotunnel.com</li><li><strong>Proxy Status</strong>: 開啟代理（橘色雲朵）</li></ul><h3>步驟三：配置 Ingress Rules 實現多服務多子網域路由</h3><p>利用單一 Tunnel 根據不同 Hostname 進行 Port 轉發。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Fhs3yMVKO3VDiHQpWjShfw.png" /><figcaption><em>Cloudflare Tunnel Ingress Rules 根據 Hostname 將請求路由至不同本地 Ports</em></figcaption></figure><h3>設定檔關鍵路徑說明</h3><p>系統層級服務建議使用路徑 /etc/cloudflared/config.yml：</p><pre>sudo mkdir -p /etc/cloudflared<br>sudo nano /etc/cloudflared/config.yml</pre><p>編輯設定檔範例：</p><pre>tunnel: 5581abd4-1e32-4535-a944-4bc5b76aca63<br>credentials-file: /etc/cloudflared/5581abd4-1e32-4535-a944-4bc5b76aca63.json</pre><pre>ingress:<br>  - hostname: n8n.example.com<br>    service: <a href="http://localhost:5678/">http://localhost:5678</a><br>  - hostname: api.example.com<br>    service: <a href="http://localhost:8080/">http://localhost:8080</a><br>  - hostname: dashboard.example.com<br>    service: <a href="http://localhost:3000/">http://localhost:3000</a><br>  - service: http_status:404</pre><blockquote><em>注意：Ingress Rules 結尾必須包含 </em><em>- service: http_status:404 預設規則。</em></blockquote><h3>步驟四：將 cloudflared 設定為 Systemd 開機自啟服務</h3><pre># 安裝 systemd 服務<br>sudo cloudflared service install</pre><pre># 啟動服務與設定開機自啟<br>sudo systemctl start cloudflared<br>sudo systemctl enable cloudflared</pre><pre># 檢查運行狀態<br>sudo systemctl status cloudflared</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gjn2Vj9fp41sJz21kuzMKQ.png" /><figcaption><em>Systemd 服務設定與 config.yml 路徑檢查清單</em></figcaption></figure><h3>SSL/TLS 與常見排錯指南</h3><h3>1. SSL/TLS 加密模式設定</h3><p>前往 Cloudflare Dashboard 的 SSL/TLS 設定頁面，建議設定為 Full 並啟用 Always Use HTTPS。</p><h3>2. 踩坑排查清單</h3><ul><li><strong>502 Bad Gateway</strong>：本地服務未開啟，或端口設定錯誤。</li><li><strong>404 Not Found</strong>：DNS CNAME 與 config.yml 內的 hostname 未完全符合。</li><li><strong>Service failed to start</strong>：請檢查憑證 JSON 檔案讀取權限。</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1841f2d74af2" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Notion API 與 Node.js 整合實戰：從 SDK 操作到自訂開發工具]]></title>
            <link>https://medium.com/@bgkong1205/notion-api-%E8%88%87-node-js-%E6%95%B4%E5%90%88%E5%AF%A6%E6%88%B0-%E5%BE%9E-sdk-%E6%93%8D%E4%BD%9C%E5%88%B0%E8%87%AA%E8%A8%82%E9%96%8B%E7%99%BC%E5%B7%A5%E5%85%B7-0d338ece4eac?source=rss-3278bd6eeabe------2</link>
            <guid isPermaLink="false">https://medium.com/p/0d338ece4eac</guid>
            <category><![CDATA[notion]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[frontend]]></category>
            <category><![CDATA[sdk]]></category>
            <category><![CDATA[web-development]]></category>
            <dc:creator><![CDATA[krownsh]]></dc:creator>
            <pubDate>Fri, 28 Aug 2026 05:57:51 GMT</pubDate>
            <atom:updated>2026-08-28T05:57:51.120Z</atom:updated>
            <content:encoded><![CDATA[<p>Notion 不僅是一款強大的筆記工具，更是全端開發者組織專案、管理知識庫與建立輕量 CMS 的好幫手。許多開發者手邊累積了大量優秀的程式碼片段、踩坑紀錄或開發心得，但手動複製貼上到 Notion 往往耗時且中斷思考。</p><p>透過 Notion 官方提供的官方 SDK @notionhq/client，配合 Node.js，我們能夠以程式碼輕鬆對 Notion 的 Database 與 Page 進行建立、查詢與更新。</p><p>這篇文章將帶你從 API 集成設定開始，深入剖析 Notion API 的資料模型，並展示如何將這套機制封裝進 Node.js 或自訂 VS Code 擴充套件，打造一鍵同步程式碼至 Notion 的個人自動化工作流。</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Y9aWxYGzPjVro8zIsnJKLg.png" /><figcaption><em>Notion API 與 Node.js SDK 架構機制</em></figcaption></figure><h3>前置準備：建立 Integration 與 Database 授權</h3><p>在開始寫程式碼前，必須先在 Notion 開發者平臺完成權限設定：</p><ol><li><strong>建立 Internal Integration</strong>：建立完成後，複製產出的 Internal Integration Secret。</li><li><strong>連結 Integration 至目標 Database</strong>：在 Database 頁面選單中新增 Connections 授權，並取得 Database ID。</li></ol><h3>安裝 SDK 與建立 Client</h3><pre>npm install @notionhq/client dotenv</pre><p>初始化 Client 實例：</p><pre>const { Client } = require(&#39;@notionhq/client&#39;);<br>require(&#39;dotenv&#39;).config();</pre><pre>const notion = new Client({<br>  auth: process.env.NOTION_API_KEY,<br>});</pre><pre>const databaseId = process.env.NOTION_DATABASE_ID;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vTLd5O_q1vlDqgJoSv75fw.png" /><figcaption><em>Notion Database Properties 與 Block Children 結構拆解</em></figcaption></figure><h3>核心資料模型剖析：Properties vs Children Blocks</h3><h3>1. properties（頁面屬性欄位）</h3><p>對應 Database 頂部欄位（Title、Rich Text、Checkbox、Date 等）。</p><h3>2. children（頁面內文區塊）</h3><p>代表頁面內文中的 Block 陣列（Heading、Paragraph、Code 等）。</p><h3>完整實戰：建立包含程式碼區塊的 Notion 頁面</h3><pre>async function addNoteToNotion({ title, description, codeContent, language = &#39;javascript&#39; }) {<br>  try {<br>    const response = await notion.pages.create({<br>      parent: { database_id: databaseId },<br>      properties: {<br>        &#39;Title&#39;: { type: &#39;title&#39;, title: [{ type: &#39;text&#39;, text: { content: title } }] },<br>        &#39;Description&#39;: { type: &#39;rich_text&#39;, rich_text: [{ type: &#39;text&#39;, text: { content: description } }] },<br>        &#39;Reviewed&#39;: { type: &#39;checkbox&#39;, checkbox: true },<br>        &#39;Created Date&#39;: { type: &#39;date&#39;, date: { start: new Date().toISOString().split(&#39;T&#39;)[0] } },<br>      },<br>      children: [<br>        { object: &#39;block&#39;, type: &#39;heading_2&#39;, heading_2: { rich_text: [{ text: { content: &#39;程式碼片段與備註&#39; } }] } },<br>        { object: &#39;block&#39;, type: &#39;code&#39;, code: { language, rich_text: [{ text: { content: codeContent } }] } },<br>      ],<br>    });<br>    return response;<br>  } catch (error) {<br>    console.error(&#39;Error creating Notion page:&#39;, error);<br>  }<br>}</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*L_BysU0mDGBqs573RiMwYg.png" /><figcaption><em>VS Code 擴充套件搭配 Notion API 一鍵同步程式碼</em></figcaption></figure><h3>進階應用：打造 VS Code 一鍵同步擴充套件</h3><p>將 SDK 邏輯封裝至 VS Code Extension 的 editor/context 右鍵選單，實現選取代碼一鍵傳送至 Notion。</p><h3>常見排錯與最佳實踐</h3><ul><li><strong>Could not find database</strong>：未在 Database 右上角 Connections 新增 Integration。</li><li><strong>validation_error</strong>：欄位名稱或型別與 Notion 定義不相符。</li><li><strong>2000 字元限制</strong>：單一 Rich Text 文字塊最大限制 2000 字元，過長程式碼需分塊傳送。</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=0d338ece4eac" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>