本地開發與驗證

準備依賴、保護本地狀態、啓動 Core-first 服務以及區分質量檢查和完整運行測試。

適用前提

本頁供已持有經維護者檢查的原始碼副本的開發者使用。當前原始碼獲取鏈接仍受限制；不要從舊資料庫備份或歷史環境檔案恢復開發設定。全部命令在原始碼根目錄執行。

需要 Node.js 20+、Corepack、鎖定的 pnpm 9.7.0、Docker Engine 和 Compose 2.24.4+。Compose 開發覆蓋檔案使用 !override，更舊版本不能保證正確解析。先用 node --version、corepack pnpm --version、docker info、docker compose version 核對環境。

準備與啓動

./manage-services.sh setup
./manage-services.sh config
./manage-services.sh start
./manage-services.sh status

setup 準備權限受限的 .state/core-dev.env 並安裝凍結依賴；config 校驗合併模型並列服務名稱。啓動固定 Compose project mywebdrive-core-dev，入口為 http://127.0.0.1:8080。同名項目可能與另一份開發副本衝突，不要併發啓動多個副本來隔離測試。

開發棧包括資料庫、Redis、對象存儲、遷移、Core、Analytics Worker、郵件適配器、Storage API/Worker、Prometheus、Web 和 Nginx。只有入口及開發郵件端口向本機暴露；不能只啓動前端就認為整個檔案流程可用。

開發郵箱的特別限制

開發設定把郵件適配器替換成 fake-email，監聽本機 8025；它不向真實郵箱投遞。/v1/test/mailboxes/latest 要求設定 FAKE_EMAIL_TEST_TOKEN 並使用收件人和 X-Test-Mailbox-Token 讀取；默認開發 overlay 沒有設定這個測試讀取 token，打開 8025 也不是可直接看驗證碼的網頁。

因此默認 start 成功並不構成登入閉環。需要登入測試時使用倉庫的隔離 smoke/瀏覽器測試設定，或由維護者設定私有測試郵箱讀取契約。不要公開 fake mailbox 或將測試 token 復用於生產，也不要從資料庫推算驗證碼。

每日管理命令

| 命令 | 用途 | | --- | --- | | ./manage-services.sh logs core-api | 查看指定有效服務最近 200 行日誌 | | ./manage-services.sh logs | 查看整棧最近日誌 | | ./manage-services.sh stop | 停止容器，保留卷和本地密鑰 | | ./manage-services.sh config | 校驗設定，不打印完整秘密設定 | | ./manage-services.sh reset --confirm | 刪除本地容器和卷，保留狀態檔案；僅在資料可丟棄時執行 |

狀態檔案異常時管理器拒絕覆蓋，應先核對檔案類型、權限和保留需求。不要把 reset 當作普通重啓。

運行驗證

./manage-services.sh quality
./manage-services.sh smoke

quality 覆蓋當前活躍工作區的構建、類型、lint、測試、生成物和文件合同，不啓動容器；smoke 構建隔離棧、使用臨時卷並清理。pnpm run test:docs 與 pnpm run verify:docs 檢查文件/OpenAPI 權威，不能替代實際收信和檔案往返。

瀏覽器 smoke 要檢查登入、上傳完成、下載內容、管理權限及桌面/移動端狀態。Linux 是上游視覺基線權威，不應在 macOS 重寫 Linux 基線。舊 legacy:help 和 legacy:status 僅觀察；其他 legacy 命令退出 64。舊 split-service 遷移循環不屬於當前啓動流程。