{
 "byKey": {
  "cover": [
   { "say": "大家好,歡迎回到 Linux A I 助理開發實戰。這一章要替助理做一個 Web 管理介面,讓團隊成員用瀏覽器就能看儀表板、跟助理聊天。我們會從架構和登入驗證開始,做出串流的聊天畫面,最後安全地部署上線。", "item": 0 }
  ],
  "Web 介面架構與 FastAPI 骨架#1": [
   { "say": "好,我們先來看 Web 介面的整體架構。", "item": 0 },
   { "say": "命令列很適合工程師,但是團隊裡其他成員,可能比較想用瀏覽器看儀表板、跟助理聊天。不過要先強調一個前提。做了 Web 介面,就等於把助理開放給網路上的人,所以安全設計,要在寫第一行程式之前就決定好。", "item": 1 }
  ],
  "Web 介面架構與 FastAPI 骨架#2": [
   { "say": "所以第一件事,是先立下安全底線,一共有六條。", "item": 0 },
   { "say": "第一,除了登入頁和健康檢查之外,所有的路由都必須驗證身分。", "item": 1 },
   { "say": "第二,驗證之後還要做授權,不同的角色,可以用的工具不一樣。", "item": 2 },
   { "say": "第三,全程使用 H T T P S。應用程式本身只監聽本機位址,對外的部分交給 Nginx 這類反向代理。", "item": 3 },
   { "say": "第四,要做速率限制和輸入驗證。", "item": 4 },
   { "say": "第五,絕對不可以有沒經過驗證、就能從遠端執行指令的入口,也不提供讓使用者輸入任意 shell 指令的功能。", "item": 5 }
  ],
  "Web 介面架構與 FastAPI 骨架#3": [
   { "say": "接著是最後一條底線,還有整體的架構。", "item": 0 },
   { "say": "第六,L L M 的 A P I 金鑰只存在伺服器端,前端永遠拿不到。", "item": 1 },
   { "say": "架構是這樣的。瀏覽器用 H T T P S 連到 Nginx,由它負責加密和限流。Nginx 再把請求轉給只監聽本機八千埠的 uvicorn 和 Fast A P I。", "item": 2 },
   { "say": "登入、授權和 C S R F 檢查都通過之後,才會呼叫助理的 Agent,由它去使用 L L M 和已經註冊的工具。", "item": 2 },
   { "say": "所以前端只是顯示層,負責送出使用者的問題、接收回答。真正呼叫 L L M、執行工具,都在伺服器端,而且沿用前面幾章的白名單、確認和稽核機制。", "item": 3 }
  ],
  "Web 介面架構與 FastAPI 骨架#4": [
   { "say": "再來看專案的結構。", "item": 0 },
   { "say": "在助理的專案目錄底下,新增一個 web 目錄。", "item": 1 },
   { "say": "裡面有四樣東西。主程式是 Fast A P I 的應用,一支負責密碼雜湊和角色的驗證模組,一個前端腳本,裡面不含任何金鑰,還有放頁面模板的目錄。", "item": 2 },
   { "say": "安裝的時候,記得在虛擬環境裡面進行。", "item": 3 },
   { "say": "畫面上用 pip 安裝了幾個套件,包括 Fast A P I、uvicorn,還有處理簽章、模板和表單需要的套件。", "item": 4 },
   { "say": "Fast A P I 需不需要額外的套件、各版本的 A P I 有什麼差異,請以官方文件為準。", "item": 5 }
  ],
  "Web 介面架構與 FastAPI 骨架#5": [
   { "say": "這一張只是再強調一次目錄的位置。", "item": 0 },
   { "say": "所有跟網頁有關的程式,都放在 web 這個目錄裡,跟原本助理的核心程式分開。", "item": 1 }
  ],
  "Web 介面架構與 FastAPI 骨架#6": [
   { "say": "我們來看最小的程式骨架。", "item": 0 },
   { "say": "最前面先匯入 Fast A P I 需要的元件,還有管理 session 的中介層。", "item": 1 },
   { "say": "建立應用程式的時候,把自動產生的文件頁關掉。接著加上 session 中介層,密鑰是從環境變數讀進來的一長串隨機字串。Cookie 只透過 H T T P S 傳送,同站政策設成最嚴格,有效時間是八小時。", "item": 2 },
   { "say": "第一個路由是健康檢查,只回覆一切正常,不洩漏任何系統資訊。", "item": 3 },
   { "say": "再來是取得目前使用者的函式。它從 session 裡找使用者,找不到就回覆四零一,請先登入。", "item": 4 },
   { "say": "最後是系統總覽的 A P I。它相依於剛剛那個函式,所以一定要登入才能呼叫,回傳的是唯讀的系統摘要。", "item": 5 }
  ],
  "Web 介面架構與 FastAPI 骨架#7": [
   { "say": "這段骨架有兩個重點要補充。", "item": 0 },
   { "say": "第一,關閉自動產生的 A P I 文件頁,是為了避免在正式環境暴露路由清單。第二,session 的密鑰可以用 Python 的 secrets 模組產生,放進有權限限制的環境檔,不要放進版本控制。", "item": 1 }
  ],
  "登入驗證、授權、CSRF 與 CORS#1": [
   { "say": "好,接下來這個單元非常重要。", "item": 0 },
   { "say": "我們要補上 Web 安全最核心的四件事,登入驗證、授權、C S R F,還有 CORS。", "item": 1 }
  ],
  "登入驗證、授權、CSRF 與 CORS#2": [
   { "say": "先從密碼怎麼儲存開始。", "item": 0 },
   { "say": "密碼不要存明文,也不要只用單純的 M D 五或 SHA 二五六。要用專門為密碼設計的慢雜湊。Python 標準函式庫裡的 scrypt 可以直接用,不用另外安裝。", "item": 1 },
   { "say": "程式先匯入幾個標準模組。", "item": 2 },
   { "say": "產生雜湊的函式,會先產生十六個位元組的隨機鹽,用 scrypt 算出結果,再把鹽和結果編碼之後存在一起。", "item": 3 },
   { "say": "驗證密碼的函式,則是把存下來的鹽取出來,用同樣的參數再算一次,最後用固定時間的比較方式,看兩邊是不是一樣。", "item": 4 },
   { "say": "scrypt 的參數,請依照硬體和官方建議來調整,也可以改用 Argon 二或 bcrypt 這類函式庫。帳號和雜湊可以放在 SQLite,或是有權限限制的設定檔。初期人數少,由管理員用腳本建立帳號就好,不要做公開註冊。", "item": 5 }
  ],
  "登入驗證、授權、CSRF 與 CORS#3": [
   { "say": "再來是登入的路由,還要防止暴力破解。", "item": 0 },
   { "say": "帳號和密碼是用表單送進來的。", "item": 1 },
   { "say": "登入函式先限制帳號和密碼的長度。接著檢查這個來源和帳號是不是失敗太多次,例如失敗五次就鎖十五分鐘。然後驗證密碼,失敗的話記錄一次,並且回覆帳號或密碼錯誤,不透露是哪一個錯。成功的話,先把舊的 session 清掉,再寫入使用者和角色,並且產生一個 C S R F token。", "item": 2 },
   { "say": "重點有三個,錯誤訊息一律模糊、限制輸入長度、登入成功後重建 session。如果條件允許,請加上多因素驗證,或是改接公司的單一登入。", "item": 3 }
  ],
  "登入驗證、授權、CSRF 與 CORS#4": [
   { "say": "第三是授權,也就是角色和工具權限。", "item": 0 },
   { "say": "登入只能證明你是誰,接下來還要決定你能做什麼。", "item": 1 },
   { "say": "畫面上定義了兩個角色。檢視者只能用系統總覽、服務狀態和日誌摘要。操作者多了遠端狀態和資安快速檢查。不認得的角色,就什麼工具都沒有。", "item": 2 },
   { "say": "聊天的時候,交給 L L M 的工具清單,是依照使用者角色過濾之後的結果。所以就算 L L M 被提示注入,也呼叫不到這個角色沒有的工具。至於變更類的動作,不開放在聊天裡直接執行,必須走獨立的確認流程,例如再輸入一次密碼,或是由管理員角色批准,並且寫入稽核紀錄。", "item": 3 }
  ],
  "登入驗證、授權、CSRF 與 CORS#5": [
   { "say": "第四是 C S R F,意思是別的網站借用你的登入狀態來送出請求。", "item": 0 },
   { "say": "因為瀏覽器會自動附上 Cookie,所以惡意網頁可以偷偷叫你的瀏覽器,對助理送出請求。防禦的方法,除了把 Cookie 的同站政策設成最嚴格之外,所有會改變狀態的請求,都要求在自訂的標頭裡帶上 C S R F token。", "item": 1 },
   { "say": "檢查的函式會把標頭裡送來的 token,跟 session 裡存的那一個比對,不一樣就回覆四零三,驗證失敗。", "item": 2 },
   { "say": "聊天的 A P I 就同時相依兩個檢查,一個確認已經登入,一個確認 C S R F。", "item": 3 },
   { "say": "這個 token 是伺服器在登入之後放進 session 的,前端透過一個查詢自己資料的路由拿到它,存在記憶體裡,送請求的時候再放進標頭。還要注意,GET 請求不應該有任何副作用。", "item": 4 }
  ],
  "登入驗證、授權、CSRF 與 CORS#6": [
   { "say": "第五是 CORS,原則是預設就不開放。", "item": 0 },
   { "say": "CORS 是瀏覽器的跨來源規則。如果前端和 A P I 在同一個網域,像這份教材的做法,就完全不需要設定,保持預設就好。", "item": 1 },
   { "say": "常見的錯誤,是為了讓程式先動起來,就寫成允許所有來源,同時又允許攜帶憑證。這是不安全的反例。", "item": 2 },
   { "say": "這樣的意圖,是讓任何網站都能帶著登入狀態,來呼叫你的 A P I。雖然瀏覽器規範其實不允許這種組合,但是很多人接著會改成,對方是什麼來源就回什麼來源,那才是真正的漏洞。", "item": 3 },
   { "say": "如果真的需要跨來源,就明確列出可以信任的來源,並且只允許需要的方法和標頭。", "item": 4 },
   { "say": "實際的行為,請以框架和瀏覽器規範的官方文件為準。", "item": 5 }
  ],
  "登入驗證、授權、CSRF 與 CORS#7": [
   { "say": "第六是輸入驗證。", "item": 0 },
   { "say": "用 Pydantic 模型來限制長度和型別,例如聊天訊息最少一個字,最多兩千個字。主機別名、服務名稱這些參數,一律走第十三章講的列舉,或是正規表示式白名單。", "item": 1 }
  ],
  "聊天介面與串流回應#1": [
   { "say": "好,這個單元來做聊天介面,重點是串流回應。", "item": 0 },
   { "say": "聊天體驗的關鍵就是串流。模型一邊產生文字,畫面就一邊顯示,不用等十幾秒才一次出現。不過串流也是容易出安全問題的地方,所以體驗和安全要兼顧。", "item": 1 },
   { "say": "L L M 供應商的 A P I 通常都支援串流模式,會一段一段回傳文字。每一家 S D K 的介面不一樣,請以你用的 S D K 官方文件為準。", "item": 2 },
   { "say": "所以我們在呼叫 L L M 的模組裡,包一層統一的介面,一次吐出一小段文字。這樣 Web 層就不需要知道供應商的細節。", "item": 3 },
   { "say": "Web 層再用 Server Sent Events,簡稱 S S E,把這些片段推給瀏覽器。它是單向的、建立在 H T T P 上面的文字串流,每個事件用 data 開頭,後面空一行。", "item": 4 }
  ],
  "聊天介面與串流回應#2": [
   { "say": "我們來看伺服器端的程式。", "item": 0 },
   { "say": "先匯入串流回應和資料驗證需要的元件。", "item": 1 },
   { "say": "接著定義聊天輸入的模型,訊息長度限制在一到兩千個字。", "item": 2 },
   { "say": "聊天路由一樣要通過登入和 C S R F 兩道檢查。進來之後先做速率限制,每個人每分鐘有上限,再依照角色過濾可以用的工具。", "item": 3 },
   { "say": "裡面的產生器,會把 Agent 產生的每一段文字包成一個事件送出去。全部結束就送一個完成事件。萬一中途出錯,只送出一個簡短的處理失敗。", "item": 4 },
   { "say": "最後用串流回應把它傳回去,類型設成事件串流,並且加上不要快取、不要緩衝的標頭。", "item": 5 }
  ],
  "聊天介面與串流回應#3": [
   { "say": "這裡有幾個細節要注意。", "item": 0 },
   { "say": "瀏覽器內建的 Event Source 只支援 GET,也不能自訂標頭。可是我們需要 POST 和 C S R F 標頭,所以前端改用 fetch 來讀取串流。", "item": 1 },
   { "say": "另外,錯誤訊息要保持簡短、一般化,詳細的例外只寫在伺服器日誌,避免洩漏內部資訊。而不要緩衝的那個標頭,是告訴 Nginx 不要把這個回應先存起來。", "item": 1 }
  ],
  "聊天介面與串流回應#4": [
   { "say": "接著看前端,用的是 fetch 加上可讀取的串流。", "item": 0 },
   { "say": "前端腳本裡有一個送出訊息的函式,它需要三樣東西,使用者輸入的文字、C S R F token,還有要顯示回答的那個頁面元素。", "item": 1 },
   { "say": "送出請求的時候,方法是 POST,Cookie 只在同一個來源才帶上,標頭裡放 C S R F token,內容則是包成 JSON 的訊息。", "item": 2 },
   { "say": "收到回應之後,就一塊一塊讀進來,解碼之後放進緩衝區。只要緩衝區裡湊齊一個完整的事件,就取出來解析,把裡面的文字接到畫面上。這裡的重點,是用 text content 來顯示。", "item": 3 },
   { "say": "一直讀到串流結束,函式就完成了。", "item": 4 }
  ],
  "聊天介面與串流回應#5": [
   { "say": "我們把前端程式分段再看一次。", "item": 0 },
   { "say": "第一步,用 fetch 對聊天的 A P I 送出請求。", "item": 1 },
   { "say": "請求的設定就是剛剛說的那幾項,到這裡結束。", "item": 2 },
   { "say": "第二步檢查回應。如果不成功,就在畫面上顯示請求失敗,並且附上狀態碼,然後直接結束。", "item": 3 },
   { "say": "第三步,從回應的內容取得一個讀取器,準備開始讀串流。", "item": 4 }
  ],
  "聊天介面與串流回應#6": [
   { "say": "後半段是讀取的迴圈。", "item": 0 },
   { "say": "先建立一個文字解碼器,把收到的位元組轉成文字。", "item": 1 },
   { "say": "再準備一個空的緩衝區。", "item": 2 },
   { "say": "然後進入一個不斷讀取的迴圈。每次讀到一塊資料,就接到緩衝區後面,再把完整的事件一個一個拆出來處理。", "item": 3 },
   { "say": "等到串流通知讀完了,迴圈就結束。", "item": 4 }
  ],
  "聊天介面與串流回應#7": [
   { "say": "最後要談 X S S,也就是跨站腳本攻擊。記住一句話,一定要用 text content。", "item": 0 },
   { "say": "L L M 的輸出屬於不可信內容。它可能夾帶 H T M L 或 JavaScript,例如日誌裡被植入的內容,經過模型又複述了一次。所以顯示的時候要用 text content,不要用 inner H T M L。", "item": 1 },
   { "say": "如果需要把 Markdown 轉成網頁格式,要用成熟的函式庫,並且搭配 H T M L 清理。再加上內容安全政策的標頭,限制只能載入自己網站的資源,就可以大幅降低 X S S 的風險。", "item": 1 }
  ],
  "部署:HTTPS、反向代理與速率限制#1": [
   { "say": "好,最後一個單元,要把 Web 介面安全地放上線。", "item": 0 },
   { "say": "內容包括 H T T P S、Nginx 反向代理、速率限制、安全標頭,還有用 system D 來管理服務。到了第十六章,我們會把它納入整體的部署。", "item": 1 }
  ],
  "部署:HTTPS、反向代理與速率限制#2": [
   { "say": "第一步是 H T T P S。", "item": 0 },
   { "say": "可以用 Let's Encrypt 的 certbot 來取得憑證。前提是你要有一個網域名稱,而且已經指向你的主機。", "item": 1 },
   { "say": "在 Ubuntu 上,先用 apt 安裝 Nginx、certbot 和它的 Nginx 外掛,再執行 certbot,指定你的網域,它就會幫你申請並設定憑證。", "item": 2 },
   { "say": "如果是內網使用,也可以用公司內部的憑證機構來簽發。不管是哪一種,都不要用明文的 H T T P 傳送登入資訊和對話內容。", "item": 3 }
  ],
  "部署:HTTPS、反向代理與速率限制#3": [
   { "say": "第二步是 Nginx 的設定,我們分兩張來看。", "item": 0 },
   { "say": "設定檔放在 Nginx 的設定目錄裡。憑證的路徑和網域,請換成你自己環境的值。", "item": 1 },
   { "say": "最前面先定義兩個限流區域,都是依照來源 I P 計算。登入用的區域,每分鐘最多五次。A P I 用的區域,每分鐘最多六十次。", "item": 2 },
   { "say": "第一個 server 區塊監聽八十埠,只做一件事,把所有請求轉址到 H T T P S。", "item": 3 },
   { "say": "第二個 server 區塊監聽四四三埠,啟用加密,並且指定憑證和私鑰的位置。", "item": 4 },
   { "say": "接著加上四個安全標頭。作用分別是強制瀏覽器之後都用 H T T P S、禁止瀏覽器自己猜測內容類型、禁止網頁被嵌進別人的頁框,還有內容安全政策,只允許載入自己網站的資源。", "item": 5 }
  ],
  "部署:HTTPS、反向代理與速率限制#4": [
   { "say": "繼續看設定的後半段。", "item": 0 },
   { "say": "先限制請求內容的大小,最多六十四 K。", "item": 1 },
   { "say": "然後是三個路徑。登入的路徑套用登入的限流。A P I 的路徑套用 A P I 的限流,還要關掉緩衝,讓 S S E 串流可以即時送出,讀取逾時設成一百二十秒。其他路徑,就單純轉給本機的八千埠。", "item": 2 },
   { "say": "設定改好之後,套用之前一定要先檢查。", "item": 3 },
   { "say": "先讓 Nginx 測試設定檔的語法,通過了,再重新載入服務。", "item": 4 },
   { "say": "還有一點要注意。uvicorn 在反向代理後面的時候,它看到的來源位址都會是本機。如果要用真實的 I P 來限流,就要設定可信任的代理,而且只信任本機。千萬不要相信任意來源送來的 X Forwarded For 標頭。", "item": 5 }
  ],
  "部署:HTTPS、反向代理與速率限制#5": [
   { "say": "第三步是應用層的速率限制。", "item": 0 },
   { "say": "Nginx 是依照 I P 來限流。應用層還要依照使用者來限流,順便限制成本。", "item": 1 },
   { "say": "講義示範的是一個簡單的記憶體版本,用一個字典記錄每個使用者最近的請求時間。這只適合單一行程,如果是多個行程,請改用 Redis 這類共享的儲存。", "item": 2 },
   { "say": "限流函式預設是六十秒之內最多二十次。它先把超過時間範圍的紀錄丟掉,如果剩下的次數已經到上限,就回覆四二九,請求過於頻繁。", "item": 3 },
   { "say": "你也可以用現成的限流套件,用法請查官方文件。別忘了,限流同時也保護了你的 L L M 費用。", "item": 4 }
  ],
  "部署:HTTPS、反向代理與速率限制#6": [
   { "say": "第四步,用 system D 把 Web 服務管理起來。", "item": 0 },
   { "say": "一樣在 system D 的系統設定目錄裡,建立一個服務檔。", "item": 1 },
   { "say": "第一段是描述,並且指定在網路就緒之後啟動。", "item": 2 },
   { "say": "第二段指定用專用的服務帳號執行、讀取環境變數檔,啟動指令是用 uvicorn 把應用程式跑起來,只監聽本機的八千埠。失敗的時候會自動重啟,後面同樣加上幾個沙箱選項。", "item": 3 },
   { "say": "第三段是安裝設定,讓它開機就自動啟動。", "item": 4 },
   { "say": "最後重新載入設定、啟用並啟動服務,再用防火牆開放四四三和八十這兩個埠。八千埠不對外開放。", "item": 5 }
  ],
  "部署:HTTPS、反向代理與速率限制#7": [
   { "say": "上線之前,請做四項自我檢查。", "item": 0 },
   { "say": "第一,用瀏覽器的開發者工具或 curl 確認,沒登入就呼叫系統總覽的 A P I,會得到四零一。", "item": 1 },
   { "say": "第二,確認回應和網頁原始碼裡,沒有任何 A P I 金鑰的字串。可以用金鑰的前綴去搜尋。", "item": 2 },
   { "say": "第三,確認從外部沒辦法直接連到八千埠。", "item": 3 },
   { "say": "第四,用 curl 只看回應標頭的方式,檢查安全標頭有沒有出現。再提醒一次,只對你自己擁有,或是取得授權的環境做測試和掃描。", "item": 4 }
  ],
  "closing": [
   { "say": "這一章就到這裡。我們做出了有登入、有授權的 Web 介面,完成串流聊天,也把它放在 H T T P S 和反向代理後面安全地上線。", "item": 0 },
   { "say": "請記得動手完成這一章的 Lab,再做章末小測驗,檢查自己學會了多少。我們下一章見!", "item": 1, "pause": 1 }
  ]
 }
}
