AI-NOW 正式環境部署 V2.3
技術架構總覽,以及與常見部署做法的比較
基準日期:2026 年 11 月 2 日
1. 根本差異
傳統網站部署,往往把重心放在把更新後的檔案直接複製進目前正在服務訪客的目錄。這種做法可能在傳輸過程中讓舊檔與新檔混在一起、讓已部署的版本難以辨識,並且在失敗之後仍需人工介入。
AI-NOW 把建置、驗證、上傳、隔離快照建立、發布、服務啟用、健康檢查,以及失敗復原拆成各自獨立的階段。它不把部署當成檔案搬運工作,而是用 Git commit 與發行清冊(release manifest)來識別並驗證每一個發行版本。
用一句話說:傳統部署著重的是把新檔案送到伺服器上;AI-NOW V2.3 著重的是證明「哪一個通過驗證的發行版本正在服務流量」,以及在啟用失敗時如何復原。
2. 架構總覽
Developer (Linux / Git)
|
| git push origin main
v
GitHub Repository
|
v
GitHub Actions CI
- 建置並驗證 Astro
- 符合條件的成功 CI 會觸發 CD
|
v
GitHub Actions CD
- 取出通過 CI 驗證的 commit
- 建置靜態網站
- 產生 release.json
- 上傳到 releases/<release-id>
|
v
DigitalOcean / Ubuntu 24.04
/srv/ai-now/web/
releases/ <- CI/CD 上傳區;不直接對外提供
verified/ <- 由 root 管理、已驗證的發行快照
current -> verified/<active-release>
|
v
ai-now-deploy V2.3
- 部署鎖定
- 檔案與路徑驗證
- 安全快照建立
- 以原子方式發布並切換 symlink
- 重建 Nginx 容器
- HTTPS 健康檢查
- 在符合條件的失敗階段嘗試回滾
|
v
Nginx(靜態內容) -> Caddy(HTTPS 反向代理)
|
v
https://ai-now.tech
Astro 產生靜態資產。Nginx 提供這些資產,Caddy 擔任對外的 HTTPS 反向代理,Docker Compose 管理容器。
3. 傳統部署與 AI-NOW V2.3 的比較
| 面向 | 常見的直接覆寫部署 | AI-NOW V2.3 |
|---|---|---|
| 發布方式 | FTP、SFTP、rsync,或手動替換線上檔案 | GitHub Actions CI/CD,加上受控的伺服器端部署腳本 |
| 版本識別 | 檔名、時間戳記,或人工筆記 | 唯一的發行 ID、完整 Git commit SHA,以及 release.json |
| 建置驗證 | 可能直接上傳本機建置的網站 | 先做 CI 驗證,CD 只由符合條件的成功 CI 觸發 |
| 發行暫存 | 檔案可能直接覆寫線上目錄 | 先上傳到 releases/,再驗證並發布到 verified/ |
| 啟用 | 訪客可能在複製過程中看到新舊混雜的檔案 | 以原子方式切換發行 symlink,再重建 Nginx |
| 權限分離 | 上傳帳號可能直接修改線上檔案 | 把可寫入的上傳區,與由 root 管理的已驗證發行版本分開 |
| 重用同一個發行名稱 | 既有目錄可能被覆寫 | RENAME_NOREPLACE 會拒絕覆寫既有的已驗證發行版本 |
| 並行部署 | 多次部署可能互相干擾 | flock 讓部署腳本序列化執行 |
| 部署後驗證 | 常常只是人工檢查首頁 | 以本機 HTTPS 檢查驗證預期的 release.json |
| 失敗復原 | 人工還原備份或手動修復 | V2.3 會在符合條件的失敗階段嘗試自動回滾 |
| 可追溯性 | 取決於操作紀錄 | Git commit、GitHub Actions run ID,以及發行清冊 |
範圍說明:這裡的「傳統部署」指的是常見的直接覆寫做法。成熟的傳統部署系統同樣可以提供版本管理、原子發布與回滾。
4. 核心工程設計
4.1 CI 與 CD 分開
AI-NOW 不會只因為某個 GitHub Actions workflow 成功,就進行部署。CD 是透過 workflow_run 觸發的,並且會檢查發起的 CI 執行已成功、來自對 main 的 push,而且屬於預期的儲存庫。
這能降低「手動叫起的 CI」或「普通的 pull request 驗證」無意中部署到正式環境的風險。
4.2 每一個發行版本都有可驗證的身分
發行 ID 範例:
gh-56c84c953ede-41495582692
對應的 HTTPS 清冊:
{
"release": "gh-56c84c953ede-41495582692",
"commit": "56c84c953edebb775a805e20917e1e088d4eb7c9"
}
維運人員可以比對 GitHub 的 commit、伺服器上的 current symlink,以及公開的 /release.json 端點。這有助於查出一種常見的操作失誤:以為 Git push 成功,就代表同一個版本已經在線上。
4.3 上傳區與已驗證的正式發行版本隔離
/srv/ai-now/web/
├── releases/ # 傳入的發行上傳區
├── verified/ # 已驗證的發行快照
│ ├── gh-4703838fa7ad-41493485863/
│ └── gh-56c84c953ede-41495582692/
└── current -> verified/gh-56c84c953ede-41495582692
releases/ 目錄並不是對外的文件根目錄。部署腳本會先驗證檔案與清冊,再把內容複製進受保護的快照。未經驗證的上傳內容,不會自動變成正式環境的內容。
4.4 更安全的檔案系統操作
V2.3 的安全快照流程包括:
- 使用
O_NOFOLLOW,在存取檔案時不跟隨符號連結。 - 拒絕不允許的 symlink、hardlink,以及非常規檔案。
- 在複製前後檢查檔案狀態,降低被替換競速的風險。
- 對受保護目錄進行擁有者與寫入權限檢查。
- 以
RENAME_NOREPLACE原子發布快照,而不覆寫既有發行版本。 - 以
flock避免部署腳本同時執行。
這些控制能降低檔案系統競速、路徑混淆與權限誤用的風險。它們並不能保證防禦所有供應鏈攻擊或伺服器遭入侵的情況。
4.5 原子化的發行選擇與容器重建
直接覆寫線上檔案,可能讓訪客看到只更新到一半的網站。
AI-NOW 會先準備好完整、已驗證的快照,再以原子方式更改 current symlink。接著 Docker Compose 會強制重建 Nginx 容器,讓它的 bind mount 指向所選的發行目錄。
這裡的「原子」指的是切換發行指標。它並不構成容器重建期間嚴格的零停機保證。V2.3 優先考量的是發行一致性、可驗證的啟用,以及可復原性。
4.6 自動回滾
切換發行版本之後,部署腳本會檢查 HTTPS 發行清冊是否與預期版本相符。若啟動或健康檢查失敗,且該階段已建立回滾處理,V2.3 會嘗試:
- 把
currentsymlink 還原到前一個發行版本。 - 重建 Nginx 容器。
- 驗證前一個發行版本已重新對外服務。
這項行為已在隔離環境中通過故障注入與復原測試。自動回滾不能取代異地備援、備份,或完整的災難復原計畫。
5. 已觀察到的正式環境驗證
截至 2026 年 11 月 2 日,記錄到的證據如下:
| 項目 | 觀察結果 |
|---|---|
| GitHub CI | 成功;run ID 41495512006 |
| CD | run ID 41495582692;查詢時仍在執行,其後觀察到新發行版本已上線 |
| 正式環境發行版本 | gh-56c84c953ede-41495582692 |
| 正式環境 commit | 56c84c953edebb775a805e20917e1e088d4eb7c9 |
current symlink |
指向該發行版本 |
HTTPS release.json |
發行版本與 commit 相符 |
| 對外 HTTPS | HTTP/2 200 |
| Caddy / Nginx | 兩個容器都回報為運行中 |
| 部署操作手冊 | docs/operations/deployment-runbook.md,128 行,已提交並推送 |
證據邊界:這些觀察可以確立新發行版本當時已生效、清冊相符,且網站可經由 HTTPS 回應。所提供的紀錄並未包含另一次最終查詢,顯示 CD 執行 41495582692 已處於「完成且成功」;因此,該結果不以獨立確認的方式主張。
6. 工程與業務價值
降低手動部署風險
工程師不必再為每一次發行登入伺服器、親手覆寫檔案,或猜測線上到底是哪個版本。受控的流程讓正式環境的變更更一致。
加快事件調查
問題發生時,維運人員可以把發行 ID、commit SHA、Actions run ID,以及伺服器上正在使用的發行版本對起來,縮小調查範圍。
降低復原成本
保留已驗證的發行版本,並在符合條件的部署失敗後嘗試回滾,會比在事故中翻找舊檔更可靠。復原仍然取決於失敗模式,以及是否還有一個可用的前一發行版本。
一套可重用的發行工程模式
這項好處不只限於企業網站。AI-NOW 現在有一套可供未來服務參考的模式:可追溯性、權限分離、發布前驗證、啟用後確認,以及可復原性。
有狀態或分散式的應用,仍需要另外設計資料庫遷移、備份、服務相容性與資料復原。靜態網站的回滾機制,不能自動回滾整個有狀態系統。
7. 已知限制與未來改進
V2.3 是已驗證的正式環境基準。尚未實作的功能,不應被描述成既有能力:
- 僅限文件變更的部署防護:尚未設定;只改文件的 push 仍可能觸發正式環境部署。
- 自動的發行保留策略:尚未啟用自動清理,或已核可的保留政策。
- 持續監控與告警:部署當下的健康檢查,並不等於獨立的全天候監控。
- 完整的災難復原:主機故障、網路中斷、憑證問題與備份還原,需要另外規劃。
- 嚴格的零停機 SLA:容器重建尚未被證明能滿足零停機保證。
這些是未來維運工作的候補項目,不是承認目前這個已驗證發行版本作為穩定基準的前提條件。
8. 結語
AI-NOW 的部署之所以不同於常見的直接覆寫流程,重點不在用了多少工具。而是工程紀律:每一個發行版本都有身分,關鍵階段都經過驗證,上傳的產物與正式環境快照彼此隔離,並且在啟用失敗時有一條明確的復原路徑。
傳統部署問的是:「新的網站檔案上傳了嗎?」
AI-NOW V2.3 問的是:「哪一個通過驗證的發行版本正在服務使用者?我們要如何證明?如果啟用失敗,我們要如何復原?」
這就是從基本的網站維護,走向正式環境發行工程的轉變。
專案:AI-NOW Website
部署:V2.3
正式環境:https://ai-now.tech
儲存庫:https://github.com/AI-Now-Inc/ai-now-web
文件狀態:技術架構總覽/已驗證基準