Naly 工程筆記：機器 Cron 鎖與可觀測的發布管線

摘要

TL;DRNaly 將機器 cron 作為一個小型但刻意設計的排程器：帶時間戳的包裝器啟動發布與分發作業， flock 防止重疊執行，精簡執行階段啟動讓環境明確化，而外部日誌加上決定性產物，則把每一次執行轉化為證據。核心論點是：當並行性、可重放性與可觀測性被設計為一等輸出，而不是 shell 事後補強時，簡單的主機層級自動化也能達到生產等級。

機器 cron 不是工作流程引擎。它不知道一篇文章是否已發布、blob 是否已上傳、資料庫寫入是否具備冪等性，或下游通知是否可以安全發送。它的工作更窄：在可預測的時間醒來並執行一個命令。Naly 的設計讓這份契約保持小而清楚，並在其周圍建立可靠性層。

有用的模式是 schedule -> locked wrapper -> explicit runtime -> observable artifact。Cron 提供時鐘。 flock 提供單次執行保護。包裝器提供環境載入、模式選擇、日誌記錄與退出碼紀律。應用程式腳本提供領域行為。產物目錄提供稽核軌跡。

它在 Naly 中的位置

Naly 的每日發布管線是用戶成長系統的一部分：它支援週期性文章、分發檢查，以及應能創造獲客或留存價值工作的煙霧模式驗證。排程本身刻意放在 Next.js 請求路徑之外。頁面渲染不應負責判斷今天是否存在發布作業。

從高層次來看，這條管線有五個邊界：

crontab 條目包含排程，並指定一個包裝器。
包裝器建立 run id，選擇完整模式或煙霧模式，並綁定日誌與產物位置。
flock 保護關鍵區段，讓一次緩慢執行不會與下一個排程時段重疊。
TypeScript 執行階段透過明確的環境載入來執行已簽入的作業。
作業會在儲存庫執行階段樹之外寫入決定性產物、狀態與日誌。

外部日誌根目錄的選擇很重要。Naly 將執行階段日誌保留在 repo 外部，預設使用 NALY_LOG_ROOT=/tmp/logs ，持久環境則使用 /data/logs 。這讓儲存庫保有原始碼與持久專案記憶的角色，而日誌則存在於為輪替、保留與檢查而設計的營運命名空間中。

決定性產物目錄是可觀測性的另一半。日誌行說明發生了什麼；產物路徑證明產出了什麼輸出。對每日文章作業而言，產物目錄應依作業名稱、日期標籤、排程時段與 run id 建立索引，並包含開始中繼資料、最終中繼資料、stdout/stderr、內容輸出、煙霧測試輸出，以及任何發布識別碼。

技術機制

Linux crontab(5) 契約很直接：crontab 包含指示 cron daemon 在符合時間執行命令的說明。手冊也記錄了生產環境中重要的細節：cron 會設定稀疏環境，例如 SHELL、 HOME和 LOGNAME； CRON_TZ 可以定義排程解讀方式；命令中的百分號字元具有特殊的 stdin 行為；日光節約時間轉換可能跳過或重複符合條件的作業；而 cron 條目需要正確的換行結尾。

這就是為什麼 Naly 把 cron 行視為狹窄的啟動器，而不是應用程式邏輯。命令部分應該無聊：指向包裝器，不寫行內 TypeScript，不做脆弱的引號雜技，並把應用程式行為交給已簽入的腳本。

一個有用的心智模型是：

cron tick
  -> wrapper starts with sparse runtime
  -> run_id and artifact_dir are assigned
  -> log files are opened under NALY_LOG_ROOT
  -> local file lock is acquired
  -> environment is loaded explicitly
  -> checked-in TypeScript job runs
  -> manifest, status, outputs, and exit code are finalized

flock(1) 是並行原語。它的手冊描述了一個從 shell 腳本管理檔案鎖、並包裝另一個命令執行的命令列工具。它預設支援排他鎖，支援以 -n進行非阻塞取得，以 -w進行有界等待，以 -E設定衝突退出碼，並在被包裝命令執行時傳遞子程序退出碼。這些細節足以編碼政策：跳過、等待，或明確失敗。

對 Naly 而言，鎖鍵應映射到冪等性領域。如果每日文章發布器和分發發送器可以安全獨立執行，它們可能需要不同的鎖。兩個會寫入相同日期標籤輸出的文章發布器則需要相同的鎖。鎖名應穩定且本機化，不應存放在 NFS 或 CIFS 路徑上，因為 flock 手冊指出某些網路檔案系統上的行為有限。

接著，可觀測性即使在實作比完整 collector 更輕量時，也遵循 OpenTelemetry 的形狀。OpenTelemetry 將 signals 定義為用來觀察底層活動的系統輸出，包括 traces、metrics、logs 和 baggage。對 cron 發布而言，trace 是執行生命週期，metrics 是持續時間與計數，logs 是事件紀錄，而類似 baggage 的脈絡則是貫穿每一步的 run id、模式、排程時段、產物目錄與版本中繼資料。

文獻怎麼說

近期 arXiv 研究直指 cron 風格自動化的風險。Agrawal 和 Jain 於 2026 年關於韌性 ELT 管線的論文指出，包括 cron 作業在內的臨時 ingestion 腳本會產生靜默失敗與資料缺口，進而侵蝕信任。他們提出的補救方案是更重的 DAG 編排、不可變原始歷史，以及基於狀態的依賴管理。Naly 不需要為每個每日發布作業採用所有這些機械，但它採納核心教訓：排程管線必須留下持久狀態，讓沉默本身變得可疑。

Albuquerque 和 Correia 於 2025 年關於 tracing 與 metrics 設計模式的研究主張，隨著可觀測性碎片化，分散式系統會變得更難診斷。他們將分散式追蹤、應用程式指標和基礎架構指標區分為不同設計模式。對 Naly 的 cron 包裝器而言，這轉化為一條實務規則：不要讓 stdout 成為唯一證據。一次發布執行需要 run trace、應用層計數器與主機層脈絡。

AgentTrace 具有相關性，因為 Naly 的發布管線包含 AI 輔助元件。AlSayyad、Huang 和 Pal 將結構化日誌定位為 agent 系統的執行階段問責層，捕捉操作與脈絡行為，使非決定性執行可以被稽核。Naly 的版本應避免洩漏私有推理，但應記錄 prompt 類別、來源集識別碼、模型/執行階段中繼資料、安全模式、產物雜湊與發布決策。

OpsAgent 於 2026 年 5 月修訂，從事件管理角度強化了同一個營運重點：當 metrics、logs 和 traces 被轉換成結構化、可稽核的描述時，會更有用。這對一條小型 cron 管線同樣重要。目標不是收集更多文字，而是讓下一次診斷比閱讀終端機逐字紀錄更快。

設計取捨

Cron 加檔案鎖是刻意保持樸素的設計。它比工作流程平台少了許多移動零件，沒有中央排程資料庫、沒有 web UI，也沒有內建 DAG 語義。當作業是一個具清楚執行階段契約的單機每日發布器時，這是優勢。當作業變成分散式、依賴繁重，或需要高基數重試政策時，這就是弱點。

檔案鎖本質上也是本機的。它們很適合一台主機和一個檔案系統。如果多台機器都能執行同一個發布器，它們就不是資料庫 advisory locks、queue leases 或編排狀態的良好替代品。Naly 目前的用途是主機層級自動化；如果發布變成多 runner，鎖定邊界應移入共享的持久狀態。

外部日誌是用便利性換取營運衛生。把日誌寫進 repo 讓本機除錯感覺容易，但會污染版本控制並掩蓋輪替問題。使用 /tmp/logs 或 /data/logs 會迫使系統宣告哪些日誌是可丟棄的，哪些是持久的。

煙霧模式是另一個取捨。煙霧執行必須便宜且非破壞性，但它必須運行與完整執行相同的包裝器、鎖、環境載入和產物程式碼。如果煙霧模式繞過困難部分，它就成了安慰劑。

決定性產物會消耗磁碟空間並增加清理工作。回報是可重放性：操作員可以比較兩次執行、找到精確的生成輸出，並在不靠記憶重建狀態的情況下，區分發布失敗與分發失敗。

失敗模式

第一種失敗模式是重疊。某個通常花三分鐘的作業最終花了三十分鐘，而下一個 cron tick 又啟動了另一份副本。 flock 只有在每個條目都使用相同鎖鍵、鎖涵蓋完整關鍵區段，且不會意外讓背景子程序在受保護生命週期之外繼續執行時，才能防止這件事。

第二種失敗模式是誤導性的排程。日光節約時間轉換可能跳過或重複作業。欄位步進語法可能被誤讀。百分號字元可能改變命令 stdin。缺少換行可能讓 crontab 部分損壞。防禦姿態是使用 UTC 排程、最少化 cron 命令文字，並在包裝器層記錄排程時段。

第三種失敗模式是稀疏執行階段漂移。Cron 的非互動式 shell 可能沒有與互動式 session 相同的 PATH、Node 版本、套件管理器路徑、secrets 或 locale。Naly 的精簡執行階段 bootstrap 讓這點明確化：在包裝器中載入必要環境，然後透過 tsx執行已簽入的 TypeScript 腳本，而不是行內程式碼。

第四種失敗模式是靜默成功。腳本可能以零退出，同時產生零個可發布產物。包裝器應把預期輸出數量、最終 manifest 是否存在，以及發布識別碼視為完成檢查。成功不只是沒有例外；成功是一個一致的最終狀態。

第五種失敗模式是部分發布。資料庫列可以存在但沒有 blob，blob 可以存在但沒有公開文章，或者分發訊息可能引用尚未發布的 URL。決定性 manifest 透過區分 prepared、committed、published 和 distributed 狀態來提供幫助。

第六種失敗模式是可觀測性本身失敗。如果日誌根目錄不存在、已滿或不可寫，包裝器應在不可逆工作之前失敗。如果產物最終化失敗，即使內容步驟成功，也應視為失敗執行，因為稽核軌跡是產品表面的一部分。

實作筆記

每個營運作業家族使用一個包裝器。crontab 條目應表達排程、時區與包裝器路徑；包裝器則應擁有所有其他關切。這包括 run_id、 mode、 artifact_dir、 log_path、鎖取得、環境載入、執行階段啟動與最終狀態。

每個冪等性邊界使用一把鎖。每日文章作業不應與無關維護工作共用鎖，但每條可能發布同一篇每日文章的路徑都應共用同一把鎖。偏好有界等待或非阻塞退出，而不是無界排隊，然後記錄該次執行是已執行、已跳過，還是逾時。

讓產物目錄具決定性。一個實務形狀是 job/YYYY-MM-DD/schedule-slot/run-id/。在開頭放入 started.json ，在結尾放入 finished.json 。包含模式、日期標籤、可用時的 commit 或 build 識別碼、套件/執行階段家族、持續時間、退出碼、輸出數量與發布識別碼。

讓煙霧模式和完整模式走同一條軌道。煙霧模式可以寫入 dry-run 命名空間並抑制公開分發，但它仍應取得鎖、載入環境、在需要時初始化 Drizzle 或 Neon 存取、在相關時驗證 blob 寫入假設，並透過相同內容路徑渲染 markdown。

即使寫入純文字檔，也使用結構化日誌。每個重要事件都應包含 job、run id、mode、schedule slot、artifact directory、duration 或 timestamp，以及 result。這讓日誌檔日後可查詢，並在 Naly 後續加入 collector 時，讓設計相容於 OpenTelemetry 風格的 ingestion。

目前的執行階段堆疊符合這個模式。 tsx 和 TypeScript 支援已簽入的營運腳本。Drizzle ORM 和 Neon 支援持久資料庫狀態。Vercel Blob 支援持久發布產物。 marked 支援 markdown 渲染路徑。Next.js 和 React 呈現結果，但 cron 應保持在請求生命週期之外。

更廣泛的教訓是：cron 只有在不被要求記憶時才安全。Naly 讓 cron 喚醒系統， flock 序列化高風險區域，並讓產物記住發生了什麼。