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 中只包含公開原始碼、範例設定與必要文件。
CurseForge 已改為官方 Core API 專用。真實 Key 只應存在部署主機的BlockPilot 設定頁：
API Key 不再放在 .env。請由 BlockPilot「設定 → CurseForge 官方 API」儲存；後端會加密保存於本機 SQLite，並以 x-api-key 呼叫 https://api.curseforge.com。一般前端讀取不會取得原始 Key。
可先執行：
Test-CurseForge-API.bat可在「設定 → CurseForge 官方 API」按「測試連線」驗證 Key。完整 API Endpoint / Enum Code 參考 docs/CURSEFORGE_API_REFERENCE.md。
- 真實
.env - CurseForge API Key 的實際值
- 管理員密碼、Token、私人金鑰
runtime/與Server/的執行資料
Webhook URL 與 Bot Token 由 API 後端加密保存，不應寫入 .env。完整設定、權限與安全說明請參閱 Discord 整合。