Docker
BAT 留在你的電腦，Agent 在本機 Docker 的 Linux 容器裡執行，專案資料夾掛進容器。適合想把每個專案的環境隔開、隨時可以重建的人。
不用自己建置映像：精靈會拉取一個公開的基底映像（預設 buildpack-deps:bookworm-scm），把 BAT 伺服器套件裝進容器專用的 Docker volume，再用基底映像建立容器。伺服器套件和 WSL、SSH 一樣，從 GitHub 下載或從本機檔案匯入。
開始之前
- Docker Desktop（Windows、macOS）或 Docker Engine（Linux），daemon 已經在執行：在終端機執行
docker info不會出錯。Docker Desktop 要用 Linux 容器。 - 能拉取基底映像：預設映像在 Docker Hub；沒有網路時，請先把映像準備在這台電腦上（見離線使用）。
- 一個要掛進容器的專案資料夾。
容器在 x86-64 或 arm64 的 Docker 上執行，伺服器以 root 身分在容器裡執行。
基底映像
在「建立新容器」時，精靈會讓你確認基底映像，預設是 buildpack-deps:bookworm-scm：Debian 12 的官方映像，內含 git、curl 與 ssh，壓縮後約 130 MiB。
也可以填你自己的開發映像（內部 registry 的映像也可以，例如 registry.example.com/team/dev:1.2），條件是：
- glibc 2.35 以上：Debian 12、Ubuntu 22.04 或更新的映像都可以。Alpine 這類使用 musl 的映像不能用。
- 有
/bin/sh、tar與gzip。
精靈會檢查兩次：拉取映像後先檢查工具與 glibc，裝好伺服器套件後再確認它能在這個映像上執行。不符合時，精靈會在建立任何容器或 volume 之前停下，並提供「修改基底映像」回到前面重填。
進階：使用內含伺服器的 bat-server:latest
BAT 的原始碼仍可用 npm run build:docker-image 建置內含伺服器的 bat-server:latest。在基底映像欄位填入它，精靈會看出映像自己會啟動伺服器，略過安裝，直接用它建立容器。這種容器不能用重跑精靈升級；要升級，請用新版原始碼重新建置映像，再建立新容器。
設定精靈
在側欄底部按 配置，再按 + 更多 ▾，在「容器類」選 新增 Docker 設定檔。
- 偵測目標環境：確認找得到
docker指令，daemon 也在執行。 - 選擇 Docker 容器模式：選 建立新容器（接著確認基底映像）或 沿用既有容器（接著從清單選容器）。差別見兩種模式。
- 選擇工作資料夾：選一個本機資料夾，它會掛到容器的
/workspace/<資料夾名稱>。沿用既有容器時，精靈先列出容器已經掛載的資料夾，確認後直接使用。 - 安裝 BAT 伺服器套件：拉取基底映像（畫面會顯示拉取到第幾層）、檢查映像、取得伺服器套件，裝進容器的 volume。
- 啟動 Docker 容器：挑一個空著的埠、建立或啟動容器，最多等 45 秒讓它的健康檢查通過，再讀取伺服器的權杖。
- 取得 TLS 指紋：記下伺服器憑證的指紋，之後每次連線都會核對。
- 連線測試。
- 寫入連線設定：同一個容器已經有設定時更新它，否則在「配置」裡新增一筆 Docker 設定。
- 完成：列出過程中收集到的警告。
兩種模式
| 項目 | 建立新容器（建議） | 沿用既有容器 |
|---|---|---|
| 容器 | 用基底映像建立新容器，名稱是 bat-server-profile；已有同名容器時加上 -2、-3 | 從清單選：每個容器列出映像、狀態、發佈的埠，以及是不是 BAT 建立的 |
| 伺服器 | 裝在 volume bat-server-<容器名稱>-bundle | BAT 建立的容器可以升級；其他容器的映像要自己內含伺服器（/opt/bat-server） |
| 掛載的資料夾 | 建立容器時掛上 | 沿用容器原本掛載的資料夾；改選別的資料夾只影響路徑轉換，不會改容器 |
| 自動重啟 | 容器設成 unless-stopped，Docker 重啟或電腦重開後自己回來 | 維持容器原本的設定 |
| 適合 | 大多數情況 | 重跑精靈、升級 BAT 建立的容器，或接上你自己管理的容器 |
容器
- 建立新容器（建議）
- 用基底映像建立新容器，名稱是 bat-server-profile；已有同名容器時加上 -2、-3
- 沿用既有容器
- 從清單選：每個容器列出映像、狀態、發佈的埠，以及是不是 BAT 建立的
伺服器
- 建立新容器（建議）
- 裝在 volume bat-server-<容器名稱>-bundle
- 沿用既有容器
- BAT 建立的容器可以升級；其他容器的映像要自己內含伺服器（/opt/bat-server）
掛載的資料夾
- 建立新容器（建議）
- 建立容器時掛上
- 沿用既有容器
- 沿用容器原本掛載的資料夾；改選別的資料夾只影響路徑轉換，不會改容器
自動重啟
- 建立新容器（建議）
- 容器設成 unless-stopped，Docker 重啟或電腦重開後自己回來
- 沿用既有容器
- 維持容器原本的設定
適合
- 建立新容器（建議）
- 大多數情況
- 沿用既有容器
- 重跑精靈、升級 BAT 建立的容器，或接上你自己管理的容器
清單裡不能用的容器會顯示但無法選，並說明原因：容器沒有把 BAT 伺服器的埠（9876/tcp）發佈到本機，或發佈的埠正好是 BAT 自己的伺服器在用的埠。沒有任何可用的容器時，精靈會說明原因，並提供 改用建立新容器。停止中的容器可以選，精靈會啟動它；取消精靈時只會停回它自己啟動的容器。
連接埠、權杖與資料
- 建立新容器：精靈在你的電腦上挑一個沒被占用的埠（從 9877 起），避開 BAT 自己的伺服器用的埠；這個埠只對本機的
127.0.0.1公開，區網上的其他電腦連不到。連線設定記的就是這個埠。 - 沿用既有容器：沿用容器已經公開的埠。容器必須以
-p 127.0.0.1:<埠>:9876公開伺服器埠，BAT 才連得到。 - 權杖：容器裡的伺服器第一次啟動時自己產生權杖，存在容器的資料 volume；精靈等容器就緒後才讀取。權杖不會出現在
docker run的參數或容器的環境變數裡。 - 資料：伺服器套件在 volume
bat-server-<容器名稱>-bundle，憑證與權杖在bat-server-<容器名稱>-data，刪掉容器後兩個 volume 都還在。
離線使用
- 伺服器套件：下載失敗時，第 4 步會顯示「無法下載 BAT 伺服器套件」，按 匯入本機 tarball…，選你從別台電腦下載的
bat-server-linux-x64-v<版號>.tar.gz（arm64 的 Docker 選linux-arm64）與同名的.sha256。步驟見常見問題。 - 基底映像：先在這台電腦上準備好映像（例如
docker load，或從內部 registrydocker pull）。拉取失敗但電腦上已經有這個映像時，精靈會直接使用。
連上之後
- 在「配置」裡開啟這筆 Docker 設定，會開一個新的 BAT 視窗；裡面的終端機與 Agent 都在容器裡執行，專案資料夾在
/workspace/<資料夾名稱>。 - 附加到 Agent 對話的本機檔案，在掛載資料夾裡的會自動換成容器裡的路徑；不在掛載資料夾裡的，送出時會先上傳到容器。
- BAT 不會替你啟動停掉的容器。容器停了，執行
docker start <容器名稱>再連線。
升級與移除
重跑精靈與升級
升級 BAT 之後，對同一個容器再執行一次設定精靈：選 沿用既有容器，再從清單選 BAT 建立的那個容器。
- 容器裡的伺服器已經是這個 BAT 的版本：精靈不安裝、不重新啟動容器，只更新連線設定。
- 版本不同：精靈先問你。選 升級並重新啟動，精靈換上新版伺服器、確認能執行，再重新啟動容器；選 先不升級，就連到容器目前的伺服器。
- 重新啟動容器會結束容器裡所有終端機與 Agent，請先存好工作。
- 容器、掛載的資料夾、權杖與憑證都不變；「配置」裡仍是同一筆設定，不會多出一筆。
- 升級途中取消或失敗，精靈會換回原本的伺服器。
移除
在「配置」裡刪除 Docker 設定，只會刪掉 BAT 這邊的設定，容器不會停。要完整移除：
docker rm -f bat-server-profile
docker volume rm bat-server-bat-server-profile-bundle bat-server-bat-server-profile-data容器名稱不一樣時，換成你的名稱；可以用 docker ps -a 查。基底映像沒有其他容器在用時，也可以 docker rmi buildpack-deps:bookworm-scm。
常見狀況
未偵測到 Docker daemon
啟動 Docker Desktop（Linux 上啟動 Docker 服務），等它就緒後按「我已啟動 Docker，重試」。Docker Desktop 若設成 Windows 容器，請切換成 Linux 容器。
無法拉取基底映像
- 找不到映像：確認名稱與 tag；私有 registry 要先
docker login。 - 已達 Docker Hub 的拉取次數上限：先
docker login、稍候再試，或改用其他 registry 的映像。 - 沒有網路：見離線使用。
基底映像不能用
- **使用 musl（Alpine）**或 glibc 太舊：改用 Debian 12、Ubuntu 22.04 或更新的映像。
- 缺少
/bin/sh、tar或gzip：在你的映像裡加上這些工具，或改用其他映像。 - BAT 伺服器無法在這個映像上執行：詳細資訊裡有錯誤原因，請改用其他基底映像。
出現這些訊息時，精靈還沒有建立任何容器或 volume。
埠已經被占用
精靈顯示「BAT 伺服器埠無法使用」時，表示精靈挑不到空著的埠，或 Docker 無法公開精靈挑好的埠。精靈會移除它剛建立的容器，按 重試 會換一個埠。
沿用既有容器時，公開的埠正好是 BAT 自己的伺服器在用的埠、或沒有公開伺服器埠的容器，會在清單裡顯示為不能選。前者可以到 設定 > 進階 > 遠端存取 把「伺服器 Port」改成別的埠，按「儲存並切換」；改了 BAT 的伺服器埠之後，已經開著的分頁還記著舊的埠，派工、完成通知這類功能要在之後新開的分頁裡才會正常。
等不到容器變成 healthy
看容器的日誌與健康檢查結果：
docker logs bat-server-profile
docker inspect --format '{{json .State.Health}}' bat-server-profile讀不到伺服器權杖
精靈顯示讀不到權杖時，確認容器裡跑的是 BAT 伺服器、而且有正常啟動：看 docker logs <容器名稱>。
容器公開在所有網路介面上
精靈若警告容器的埠公開在主機所有網路介面上，表示那是 BAT 改成只對本機公開之前建立的舊容器；若警告映像建置於網路修正之前，表示那是舊的伺服器映像。精靈不會修改這些容器。改用 建立新容器 建立新的容器，確認不再需要舊容器的資料後再自己刪掉它。
中途取消
按 取消，或在執行中關掉精靈，已完成的步驟會依序復原：這次建立的容器與 volume 會刪掉；升級時換掉的伺服器會換回原本的；原本就有、這次才啟動的容器會停回去；不是這次建立的東西不會動。
指紋不符
回報 Docker 相關問題時，請附上 Docker 版本、基底映像、精靈的錯誤訊息與 BAT 的除錯日誌，見回報與協助測試。更多問題見常見問題。