BlockPilotMC 會從專案根目錄的 .env 讀取啟動設定。公開 Repository 只應保留 .env.example；實際使用的 .env 可能包含管理員初始密碼、連線來源與主機設定，不得提交到 GitHub、Release 附件或公開問題回報中。
# 面板連接埠，範圍為 1–65535。
PORT=8787
# 0.0.0.0 允許本機與同網段裝置連線；127.0.0.1 僅允許本機。
HOST=0.0.0.0
# 僅在第一次建立管理員帳號時使用。
ADMIN_USERNAME=admin
ADMIN_PASSWORD=replace-with-a-long-random-password
# 前端與 API 分開部署時使用；多個來源以逗號分隔。
WEB_ORIGINS=http://localhost:8787,http://127.0.0.1:8787請將範例密碼替換為自行產生的高強度密碼。不要把真實密碼、Token、API Key、私人網域或內部 IP 寫入 .env.example。
管理員可在介面中調整：
- 深色或淺色模式。
- 介面背景圖與背景顯示強度。
- 登入頁標題與說明文字。
- 面板連接埠
PORT。 - 選用的面板綁定 IP。
背景圖片與登入頁文字會在按下「儲存外觀設定」後保存。選擇圖片時只會顯示本機預覽，尚未儲存前可以取消變更。
網路設定變更後需要重新啟動 BlockPilotMC。若主機只有一張網路卡，通常不必指定綁定 IP；使用 0.0.0.0 即可監聽可用介面，再由防火牆限制允許連入的網段。
ADMIN_USERNAME與ADMIN_PASSWORD只用於第一次建立管理員帳號。- 帳號建立完成後，請在面板內修改密碼並妥善保存。
- 修改
.env不會覆蓋已存在的管理員密碼。 - 忘記密碼時，請在專案根目錄執行
npm run reset-admin。
WEB_ORIGINS 用於限制可存取 API 與 WebSocket 的前端來源。請填入實際需要的來源，避免使用萬用字元或與 BlockPilotMC 無關的網站。
同一主機部署前端與 API 時，通常保留下列來源即可：
WEB_ORIGINS=http://localhost:8787,http://127.0.0.1:8787正式對外使用時，建議透過 HTTPS 反向代理或 VPN 存取，不要直接把管理面板暴露到未受信任的公網。
下列資料只屬於執行中的主機，不應加入版本控制、公開 ZIP 或問題截圖：
.env與任何含真實憑證的設定檔。runtime/內的資料庫、登入金鑰、背景圖片、備份與主控台紀錄。Server/內的世界檔、模組、插件與伺服器設定。node_modules/、dist/、日誌、資料庫、備份與暫存檔。- CurseForge 或其他第三方服務的 API Key、Token、Cookie 與請求標頭。
- 主機使用者名稱、私人路徑、內部網域、真實 IP、電子郵件與除錯輸出中的敏感資訊。
專案已透過 .gitignore 排除上述常見檔案，但提交前仍應執行：
git status
npm run check:source確認 Repository 中只包含公開原始碼、範例設定與必要文件。
BlockPilotMC v1.0.4 已暫停 CurseForge API Key 與官方 API 整合規劃。目前沒有 API Key 設定欄位、環境變數或內建共用金鑰，管理員也不需要在 .env 加入 CurseForge 設定。
現階段請使用作者提供的 Server Pack ZIP、Modrinth .mrpack 或公開直接下載網址。CurseForge 公開頁面僅採最佳努力解析；若下載遭網站阻擋，請在瀏覽器下載 Server Pack 後再上傳到面板。
請勿自行把 CurseForge API Key 寫入 .env、前端、GitHub Actions、Dockerfile、Issue、日誌或 Release 包。是否恢復此功能，將在自架式使用方式、平台規則及安全保存方案確認後再評估。
Webhook URL 與 Bot Token 由 API 後端加密保存，不應寫入 .env。完整設定、權限與安全說明請參閱 Discord 整合。