跳到內容
CustodexaCustodexa
繁體中文

正式部署

這一頁解決什麼

Section titled “這一頁解決什麼”

把試跑用的部署變成可以交付的正式部署：該填的設定值、預設就生效的安全底線、 上線前要做完的檢核，以及一組可以逐條執行的驗證指令。 預設的 docker-compose.yml 產出的就是正式版，前端由 nginx 供應編譯後的靜態檔， 後端是精簡二進位映像，資料庫與圖形代理不對外開埠。

需要什麼

Section titled “需要什麼”
  • 一台 Linux x86_64 或 aarch64 主機，具備 Docker 與 Docker Compose，以及規劃給 DATA_PATH 的儲存空間。
  • 一個對外主機名，以及規劃好的憑證來源。系統預設自簽憑證並發布 https，換成機構憑證或交給既有 ingress 的做法見 TLS 與憑證。
  • 一台離機的 syslog 收集器，設定方式見日誌轉送與通知。
  • 目標主機不必安裝任何軟體，管控都發生在連線經過的閘道上。

安裝包部署先驗證 Release 的 SHA-256 清單與 Sigstore 資料，再執行 custodexa.sh install。映像可由對應架構的離線附件載入，或由安裝程序依序從本機、GHCR、Docker Hub 取得並驗證；需要時可從原始碼建置。詳細步驟見安裝包與離線安裝。

怎麼設定

Section titled “怎麼設定”

1. 必填的環境變數

Section titled “1. 必填的環境變數”
變數 說明
JWT_SECRET 正式版偵測到仍是範本預設值或長度不足即拒絕啟動，長度至少 32 位元組
KEK_PROVIDER 主金鑰模式，出貨預設為 ui，另可選 env 或 kms
ENCRYPTION_KEY 僅 KEK_PROVIDER=env 時填寫
DB_PASSWORD 正式版不給預設值，必填
ADMIN_INITIAL_PASSWORD 全新部署必填，至少 12 位元組且不得含空白
DATA_PATH 建議指向專用資料夾或磁碟，正式部署請用絕對路徑
DB_SSLMODE 資料庫在其他主機時設為 require 或 verify-full
CORS_ALLOWED_ORIGINS 跨來源部署時填寫，留空即僅同源
TLS_DOMAIN 對外主機名，會寫進憑證並帶入代理設定
TLS_MODE 憑證來源，出貨預設 selfsigned，用自己的憑證時設 provided
TRUSTED_PROXIES 部署在自家 ingress 後方時填寫，決定稽核記錄的來源位址與限流依據
PUBLIC_BASE_URL 對外的 https 網址，與 TLS_DOMAIN 同主機名，OIDC 的回呼位址由它組成

服務拓撲的常數（連接埠、資料庫主機、資料落點）由 compose 提供，不必自己填。

2. 出廠就生效的安全底線

Section titled “2. 出廠就生效的安全底線”

這些行為內建於部署流程，沒有關閉開關：

  • 對外連線預設就是 https：內建代理提供 TLS 1.2 以上、HSTS 與 WebSocket 轉發，明文請求一律導向 https。
  • 沒有內建的公開初始憑證，初始管理員密碼由部署者設定，首次登入強制改密。
  • 正式版偵測到 JWT 密鑰仍是範本預設值或長度不足即拒絕啟動。
  • 落庫的敏感資料採用分層信封加密，附金鑰清冊與換鑰治理。
  • 正式版映像移除固定的 shell 入口，資料庫與圖形代理不對外開埠。
  • 資料庫 schema 由單一基準定義，遇到不認識的既有版本會拒絕啟動而不是硬跑。

3. 交付前檢核

Section titled “3. 交付前檢核”
  1. 對生效中的政策組套用：在安全政策頁與存取管控頁從頁首選組、先看預覽再確認。已更嚴的鍵不動，組與組衝突留給管理員。按儲存才生效。
  2. 設定 syslog 離機收集器，確認測試訊息真的送達。
  3. 檢查 DATA_PATH 的目錄權限，建議 0750 或更嚴，擁有者為執行容器的使用者。
  4. 更換全部範本預設的機密值；資料庫初始化完成後把 ADMIN_INITIAL_PASSWORD 從 .env 移除。
  5. 建立備份程序，並記錄金鑰清冊上的四個指紋。
  6. 設定登入告示，內容由組織自訂。
  7. 啟用單一登入之前，保留至少一個以本地密碼登入的管理員帳號，給它強密碼並啟用雙因素認證。
  8. 換上機構或公開 CA 簽發的憑證，或把系統自簽的憑證授權單位派發到會連進來的機器。

4. 部署驗證五步

Section titled “4. 部署驗證五步”
Terminal window
docker compose ps
docker compose exec backend wget -qO- http://localhost:8080/health
curl -skI https://localhost/ | head -1
curl -sk -X POST https://localhost/api/v1/auth/login -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"<ADMIN_INITIAL_PASSWORD>"}'
docker compose logs backend | tail -30

全新部署的登入回應會帶 password_change_required，代表強制改密已經生效。 在開發機上驗證正式版時，指令一律加 -f docker-compose.yml 以指向正式版設定。

稽核看得到什麼

Section titled “稽核看得到什麼”
  • 安全政策的每一次變更都留一筆紀錄，含變更者、政策鍵、變更前後的值。
  • 登入事件記錄帳號、來源位址、結果；設定 TRUSTED_PROXIES 之後來源位址才會是真實的連線來源。
  • 部署形態、備份範圍與升級步驟屬於營運面的證據，見備份與還原與升級與回滾。