快速開始

本章目標

辨識三個獨立專案，啟動適合自己任務的服務，並知道什麼才算啟動成功。本章命令已對照原始碼與 scripts，沒有在本輪執行業務環境啟動。

前置條件

後端需要可用的 Docker daemon 與 Docker Compose（後端 README 列出 Docker 29+、Compose v2.40+）。業務前端的連線設定以 .env.example 為範本；真實登入另需已開通的帳號，不要自行編造環境值或憑證。

三個目錄，三種用途

office/
├── nexus-pro-be-plus/     # Go 後端；本文僅唯讀核實
├── nexus-pro-web-plus/    # 業務前端；本文僅唯讀核實
└── nexuspro-dev-guide/    # 目前閱讀的開發指南網站

以下每段命令都註明工作目錄。不要在文件站執行後端命令；pnpm dev 在不同專案代表不同服務。

後端啟動

以下在 nexus-pro-be-plus 根目錄執行。後端有兩套本機 stack，用途不同，不可互相取代：

手動啟動根目錄 Compose 時，Keycloak 同樣綁 127.0.0.1:38081，與 dev-local 衝突；先確認哪一套在跑，不要停止別人的 stack。

日常開發：dev-local 外部依賴

# 只起外部依賴（冪等）；會等 Keycloak 健康後套用 realm，新建容器首次啟動約需 5 分鐘
./deploy/dev-local/stack.sh up -d
./deploy/dev-local/stack.sh ps

# 應用程式不讀 .env，先匯出成環境變數再執行
set -a; . ./.env; set +a
go run ./cmd/api

API 監聽 HTTP_ADDR（.env.example 預設 :8080），也就是前端 .env.example 中 NEXUS_API_BASE_URL 的預設目標。worker 以 nexus_worker 角色在本機執行 cmd/worker；資料庫佈建、migration、租戶開通與 Keycloak issuer 的注意事項見後端 deploy/dev-local/README.md。

完整容器 stack：根目錄 Compose

compose-env 會在根 .env（權限 0600）建立或補齊 6 個 COMPOSE_* 秘密值，因此這不是唯讀檢查。--exec 會從子命令的環境移除所有 COMPOSE_* 變數，避免 ambient environment 覆蓋 .env；要改 COMPOSE_HTTP_PORT 等 port 必須寫進 .env，在 shell 設定不會生效。

# 僅在你有權建立本機環境、套用 migration 時執行
go run ./cmd/compose-env
go run ./cmd/compose-env --exec docker compose config -q
go run ./cmd/compose-env --exec docker compose up -d --build --wait api worker

依賴順序是 PostgreSQL → 角色佈建（db-provision）→ migrate；API 另外等待 Keycloak（匯入 realm nexus）與 Redis 健康，worker 等待 Keycloak。--build 用來確保執行的不是舊映像；--wait 等待健康狀態，不代表所有業務行為都驗收通過。這個 stack 不會自動開通租戶：ops 服務屬於 tooling profile，up 不會啟動它；需要時經同一個 wrapper 執行 docker compose run --rm ops provision-tenant（必填 -slug、-name、-admin-email、-actor）。

# 查詢實際映射，不猜測本機 port
go run ./cmd/compose-env --exec docker compose port api 8080

手動啟動的預設映射是 API 127.0.0.1:38080、Keycloak 127.0.0.1:38081，以查詢結果為準。這套 stack 的 Keycloak issuer 固定為容器內位址 http://keycloak:8080，與前端 .env.example 預設的 http://127.0.0.1:38081 不同；前端聯調請用 dev-local 路線。

確認存活與就緒

以實際 API 位址驗證 /healthz 與 /readyz。前者只檢查 process liveness；後者執行已註冊的 readiness checks，critical failure 回傳 503，非 critical 失敗仍回 200、但該項標為 degraded，所以要檢視 checks。

前端啟動

以下在 nexus-pro-web-plus 根目錄執行。先使用 .nvmrc 與 packageManager 指定的工具鏈，再安裝依賴。

nvm install && nvm use
corepack enable
pnpm install
pnpm dev

預設站台是 http://localhost:3000。連線設定寫在 .env.local，首次以 .env.example 為範本建立（已有檔案時不要覆寫）：NEXUS_API_BASE_URL 指向後端（範本預設 http://127.0.0.1:8080），Keycloak 使用 KEYCLOAK_BASE_URL（範本預設 http://127.0.0.1:38081）、KEYCLOAK_REALM、KEYCLOAK_CLIENT_ID。

瀏覽器只呼叫同源 /v1/**，由 proxy.ts 在 server 端轉發並從 httpOnly cookie 注入 access token；NEXT_PUBLIC_API_BASE_URL 保持留空，不要把 private credentials 寫入 NEXT_PUBLIC_*。未設定 NEXUS_API_BASE_URL 時，/v1/** 直接回 503（code 10500，訊息指出後端位址未設定）。開啟 /api/readyz 可確認前端是否連到後端的 /readyz；回應的 backend 為 not_configured 代表尚未設定後端位址。

沒有後端或登入環境時，repository 提供 development-only 模式：

pnpm dev:mock

此 script 只設定 NEXT_PUBLIC_MSW=true 與 NEXT_PUBLIC_MOCK_AUTH=true。MSW 只攔截有 handler 的 /v1/**，其餘請求照常送出；假會話要開啟 /api/auth/dev-login 才會寫入 cookie，否則 proxy.ts 仍會導向 /login。畫面上的 MOCK 徽章代表本次沒有使用真實服務。它可驗證 UI 操作，不能證明真實登入、授權、資料庫或租戶隔離正確。

啟動本文件站

以下僅在 nexuspro-dev-guide 根目錄執行，不需要業務 .env。

pnpm install --frozen-lockfile
pnpm dev

本站 script 預設綁定 loopback 的 http://127.0.0.1:3210，不暴露到區域網路。正式建置驗證可執行：

pnpm typecheck
pnpm test
pnpm build

預期結果與驗證

常見錯誤

• 服務啟動但行為沒改：先確認 listener 所屬目錄、映像與版本，不只看終端機是否有程序。
• Keycloak port 被佔用：根目錄 Compose 與 dev-local 預設都綁 127.0.0.1:38081；先確認哪一套 stack 在跑，不停止別人的服務。
• 401 或登入轉址：先區分 mock 與真實模式；mock 模式先開 /api/auth/dev-login，真實模式核對已授權的登入環境。不要用硬編碼 token 繞過。
• 後端 README 與程式碼不一致：README 開頭仍是 P0 階段描述；「本機 Runtime」一節寫四個 secret（實際 6 個）、啟動圖未列 Keycloak 與 Redis，也沒有提到 deploy/dev-local。工具鏈、路由、Compose 及功能狀態以實際檔案為準。

相關文件

閱讀技術架構理解依賴邊界；遇到異常時依常見問題的排查順序收集證據。