Docker 部署
Mindwtr 正式支援使用 Docker 執行:
- mindwtr-app:由 Nginx 提供服務的桌面網頁版/PWA 組建。
- mindwtr-cloud:輕量同步伺服器及任務自動化 REST API。
兩者都提供 Docker image,並可使用 Docker Compose 輕鬆編排。
快速開始(Docker Compose)
您不需要 clone 儲存庫。官方映像已發佈到 GHCR,compose.yaml 會自動為您拉取。
下載 compose 檔案:
bashcurl -LO https://raw.githubusercontent.com/dongdongbh/Mindwtr/main/docker/compose.yaml在旁邊建立
.env檔案(Docker Compose 會自動讀取):dotenvMINDWTR_CLOUD_AUTH_TOKENS=your_token_here MINDWTR_CLOUD_CORS_ORIGIN=http://localhost:5173MINDWTR_CLOUD_CORS_ORIGIN必須與您在瀏覽器中開啟 PWA 的位址完全一致,包含協定與連接埠。http://localhost:5173只有在瀏覽器執行於 Docker 主機上時才有效,從其他裝置存取時請填寫主機位址,例如http://192.168.1.20:5173。只能設定一個來源。拉取並啟動服務:
bashdocker compose pull docker compose up -d存取服務:
- PWA(網頁版):在瀏覽器中開啟
http://localhost:5173。 - Cloud 存活檢查:開啟
http://localhost:8787/health。 - Cloud 儲存就緒檢查:開啟
http://localhost:8787/ready。 - 供本機測試的自行託管 URL:
http://localhost:8787 - REST API Base URL:
http://localhost:8787/v1
- PWA(網頁版):在瀏覽器中開啟
/health 只表示 Cloud 伺服器能夠回應 HTTP 要求。/ready 還會檢查所設定的資料目錄是否可寫入,因此想確認伺服器能否真正儲存資料時應查看這個位址。Compose 使用映像內建的健康狀態檢查:目前映像檢查 /ready,舊版映像檢查 /health。
若您想從原始碼組建映像,請 clone 儲存庫並在其根目錄執行 docker compose -f docker/compose.yaml up --build -d。請參閱下方的手動組建。
此預設 compose 檔案只使用 HTTP,適合本機/私人測試。Mindwtr 桌面版及行動版用戶端只會對已辨識為本機/私人目標的位址接受 HTTP,例如 localhost、127.0.0.1、10.x.x.x、172.16.x.x 至 172.31.x.x、192.168.x.x、loopback/private IPv6 位址、*.local 及 *.home.arpa。
從 v1.3.8 起,Docker 網頁應用程式的瀏覽器政策允許透過 HTTP 連線到同一主機名稱或 IPv4 位址上的其他連接埠。例如,開啟 http://192.168.1.20:5173,將自架 URL 設為 http://192.168.1.20:8787,並設定 MINDWTR_CLOUD_CORS_ORIGIN=http://192.168.1.20:5173。兩個 URL 必須使用相同位址:即使開啟允許不安全連接(HTTP),瀏覽器政策仍會阻擋其他區域網路 HTTP 主機。雲端位於其他主機時,請使用 HTTPS。
公用 URL、自訂 DNS 名稱、VPN hostname、Tailscale、ZeroTier,或任何未辨識為本機/私人的名稱,都請使用 HTTPS,或在應用程式的同步設定中開啟允許不安全連接(HTTP),以透過明文 HTTP 接受該主機名稱。開啟後資料會以未加密方式傳輸,請只在信任的網路上使用。在 iOS 上,此開關無法解除 Apple 本身的規則:即使開啟開關,iOS 仍會阻擋以明文 HTTP 連到完整網域名稱(例如 Tailscale 的 *.ts.net 名稱)。在 iPhone 和 iPad 上請對這類名稱使用 HTTPS;使用 Tailscale 時,tailscale serve 可為伺服器提供 HTTPS 位址。
使用 Caddy 設定 HTTPS
若要供公用桌面版或行動版同步使用,請使用 Caddy 支援的 compose 檔案:
cp docker/.env.https.example docker/.env.https.local編輯 docker/.env.https.local:
MINDWTR_CLOUD_DOMAIN=mindwtr.example.com
MINDWTR_CLOUD_AUTH_TOKENS=your_long_random_token
MINDWTR_CLOUD_CORS_ORIGIN=https://mindwtr.example.com
MINDWTR_CADDYFILE=Caddyfile.https啟動 stack:
docker compose --env-file docker/.env.https.local -f docker/compose.https.yaml up -d檢查伺服器:
curl https://mindwtr.example.com/health
curl https://mindwtr.example.com/ready在 Mindwtr 的設定 -> 同步 -> 自行託管中,將自行託管 URL 設為:
https://mindwtr.example.comMindwtr 會自動附加 /v1/data。
公用 HTTPS
當 MINDWTR_CLOUD_DOMAIN 是指向此 Docker 主機的公用 DNS 名稱時,請使用 Caddyfile.https。Port 80 及 443 必須能夠存取,才能自動簽發憑證。Caddy 會取得並續期憑證,再將要求反向代理至 mindwtr-cloud。
僅限 LAN 的 HTTPS
若 hostname 只在家用網路內解析,請使用 Caddyfile.local-https:
MINDWTR_CLOUD_DOMAIN=mindwtr.home.arpa
MINDWTR_CLOUD_CORS_ORIGIN=https://mindwtr.home.arpa
MINDWTR_CADDYFILE=Caddyfile.local-https這會使用 Caddy 的內部憑證授權單位。每台用戶端裝置都必須信任 Caddy 的本機根憑證,Mindwtr 才會接受 HTTPS 連線。Mindwtr 1.2.0 及更新版本會在 Android 上信任使用者安裝的憑證授權單位;iPhone 和 iPad 還需要安裝根憑證並明確啟用完全信任。若 hostname 可從公用網路存取,公用 Let's Encrypt 憑證仍是最簡單的選擇。
僅限 LAN 的 stack 啟動後,請匯出 Caddy 的本機根憑證:
docker compose --env-file docker/.env.https.local -f docker/compose.https.yaml cp caddy:/data/caddy/pki/authorities/local/root.crt ./mindwtr-caddy-root.crt在會同步至此 hostname 的每台裝置上,將該憑證安裝為受信任的根憑證。
組態
同步 Token
雲端伺服器需要 token 進行驗證。你必須在環境變數中設定。
在 docker/compose.yaml 中(或透過環境變數)設定:
MINDWTR_CLOUD_AUTH_TOKENS=your_token_here為維持向後相容,目前仍接受 MINDWTR_CLOUD_TOKEN,但已棄用。
若要使用以檔案為基礎的 Docker secret,請從 .env 檔案中移除 MINDWTR_CLOUD_AUTH_TOKENS,將 token 存放在只有擁有者可讀取的主機檔案中,並以 docker/compose.secrets.yaml 疊加檔啟動 Compose。MINDWTR_CLOUD_AUTH_TOKENS_FILE_HOST 必須是主機上的絕對路徑:
printf '%s\n' 'replace_with_a_token_at_least_20_characters_long' > /absolute/path/mindwtr-cloud-tokens
chmod 600 /absolute/path/mindwtr-cloud-tokens
MINDWTR_CLOUD_AUTH_TOKENS_FILE_HOST=/absolute/path/mindwtr-cloud-tokens \
docker compose -f docker/compose.yaml -f docker/compose.secrets.yaml up -d疊加檔會將該檔案以唯讀方式掛載到 /run/secrets/mindwtr_cloud_tokens,並自動設定 MINDWTR_CLOUD_AUTH_TOKENS_FILE,因此 token 內容不會進入產生的 Compose 環境。請讓主機檔案維持 0600 權限。若直接寫入的設定與可讀取的 token 檔案都未提供有效 token,伺服器仍會拒絕啟動。
同一個疊加檔也適用於 Caddy HTTPS 組合。請從 docker/.env.https.local 中移除直接寫入的 token,然後執行:
MINDWTR_CLOUD_AUTH_TOKENS_FILE_HOST=/absolute/path/mindwtr-cloud-tokens \
docker compose --env-file docker/.env.https.local \
-f docker/compose.https.yaml -f docker/compose.secrets.yaml up -d產生 Token: 可使用以下命令產生高強度隨機 token:
cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 50 | head -n 1用戶端組態
若要將 Mindwtr 用戶端(桌面版或行動版)連接至這個自行託管雲端:
- 前往設定 → 同步。
- 選擇自行託管(或 Cloud)。
- 將自行託管 URL 設為伺服器的 base endpoint:Mindwtr 會自動將
http://localhost:8787/v1/data附加至此 URL。 - 輸入在
MINDWTR_CLOUD_AUTH_TOKENS中設定的相同 token。
若是私人 LAN HTTP,請使用 http://192.168.1.20:8787 等本機/私人位址。公用 URL 請使用上述 Caddy HTTPS 設定。
預置網頁應用程式的同步設定
新瀏覽器開啟 PWA 時,可以讓雲端 URL 已經填好,使用者只需輸入權杖:
- 同一網域(推薦): 當應用程式與雲端 API 共用一個網域(Caddy HTTPS 方案即如此)時,網頁應用程式會自動在自身來源上偵測雲端,無需任何設定。
- 不同網域: 在
mindwtr-app容器上設定MINDWTR_DEFAULT_CLOUD_URL為雲端的公開 URL,適用於 Kubernetes 等應用程式與 API 部署在不同主機的情境。
該值只用於預填設定表單。它絕不會覆蓋瀏覽器中已設定的 URL,在使用者以權杖儲存之前同步保持關閉。
限制誰可以開啟託管的網頁應用程式
瀏覽器版本將任務資料保存在每個瀏覽器的本機儲存空間中。Mindwtr 沒有自己的登入畫面;雲端 API 在 /v1/* 上使用 bearer 權杖。若要限制對託管頁面的存取,請在代理上啟用 HTTP Basic Auth。將 /v1/*、/health、/ready 與 /sw.js 排除在外,讓原生用戶端、健康檢查與 Service Worker 更新正常運作。使用 Caddy 時,以 caddy hash-password 產生雜湊,然後使用:
example.com {
@ui not path /v1/* /health /ready /sw.js
basic_auth @ui {
alice <bcrypt hash>
}
@cloud path /v1/* /health /ready
handle @cloud {
reverse_proxy mindwtr-cloud:8787
}
handle {
reverse_proxy mindwtr-app:5173
}
}保持 /sw.js 可公開存取,並將其代理至 mindwtr-app;下文支援的僅限連線模式需要這個 URL 傳回 Worker 指令碼,而不是 404。使用 nginx 時,在 location / 中啟用 auth_basic,在 location = /sw.js 中停用它並將該路徑代理至應用程式;讓 /v1/、/health 與 /ready 不經過代理驗證,並將它們轉送至雲端伺服器。
依上文所述保持 MINDWTR_CLOUD_AUTH_TOKENS 與 MINDWTR_CLOUD_CORS_ORIGIN 的設定。代理驗證控制頁面下載;它不會鎖定已下載至瀏覽器中的任務資料,包括已安裝的 PWA。
Basic Auth 後的僅限連線模式
在 Firefox 中,既有的 Service Worker 可能導致瀏覽器重新啟動後傳回 401,卻不顯示 Basic Auth 登入提示。對於支援此選項的 Docker 映像,在隨附的 compose.yaml 旁邊的 .env 中加入以下設定,然後執行 docker compose up -d 重新建立 mindwtr-app:
MINDWTR_PWA_ENABLED=false預設值為 true,保留正常的 PWA 行為。設為 false 後,應用程式會在同一個 /sw.js URL 提供一個不攔截請求的空 Worker。它會啟用,但不會強制重新載入頁面或刪除儲存資料。瀏覽器中的任務資料庫會保留,但應用程式介面將無法離線載入;開啟應用程式需要網路連線。
既有的 Worker 應會自動更新,但可能需要一些時間。若要立即恢復,請在瀏覽器開發人員工具中僅取消註冊此網站的 Mindwtr Service Worker,關閉該網站的所有 Mindwtr 分頁與已安裝 PWA 的視窗,然後重新開啟。不要清除網站資料:這可能會刪除本機儲存的任務。
對於不支援此選項的舊映像,一位回報者測試過一種 Caddy 暫時解法:允許公開存取 /sw.js,但讓它傳回 404,然後執行相同的手動取消註冊、關閉與重新開啟步驟。這是針對這些映像的已回報暫時解法;使用支援的選項時,應讓應用程式正常提供 /sw.js。
Dropbox 同步與 Docker PWA
Docker mindwtr-app image 提供瀏覽器/PWA 組建。此 runtime 無法使用原生 Dropbox OAuth 同步,因為 Dropbox 連線是由原生桌面版及行動版應用程式實作。透過 .env、env_file、compose runtime environment 或 Docker build argument 加入 VITE_DROPBOX_APP_KEY 或 DROPBOX_APP_KEY,都不會在 Docker 中啟用 Dropbox。
Docker 託管的同步請使用隨附的自行託管雲端伺服器或 WebDAV。若自行託管端點位於 Authelia 或其他互動式 SSO proxy 後方,請設定 proxy,讓 Mindwtr 的同步/API 路徑直接使用 Mindwtr 的 bearer token;行動版無法在 /v1/data 前方完成 Authelia 瀏覽器登入。
Docker PWA 中的提醒
任務提醒以及開始、到期與檢視日期提醒在瀏覽器版本中同樣會觸發,形式為網頁通知。請為網站授予通知權限(設定 → 通知),並保持一個 Mindwtr 分頁開啟:瀏覽器版本沒有背景服務,因此只有在分頁執行時才會送達提醒。位於背景的分頁其計時器會被節流,提醒可能最多遲到一分鐘;在所有分頁都關閉時到點的提醒會被跳過,而不會稍後補送。若需要在瀏覽器關閉後仍然可靠的提醒,請使用桌面或行動應用程式。
任務自動化 API
同一個 mindwtr-cloud 容器也會公開供任務自動化使用的 REST API。它採用與同步相同的 base URL 及 bearer token。
常用端點:
GET /v1/data及PUT /v1/data:同步GET /v1/tasks及POST /v1/tasks:列出及建立任務GET /v1/projects:專案GET /v1/search?query=...:搜尋任務及專案
範例:
curl -X POST http://localhost:8787/v1/tasks \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{"input":"Review PR @work /due:tomorrow"}'CORS Origin(正式環境)
雲端伺服器的 CORS 預設為 http://localhost:5173。正式環境請設定:
MINDWTR_CLOUD_CORS_ORIGIN=https://your-app-domain.example資料持久化
為了在容器重新啟動時妥善保護雲端資料,請為資料目錄掛載 volume。
在你的 compose.yaml 中:
volumes:
- ./data:/app/cloud_data手動組建
若不使用 Compose,而想自行組建 image:
組建 PWA:
docker build -f docker/app/Dockerfile -t mindwtr-app .組建 Cloud Server:
docker build -f docker/cloud/Dockerfile -t mindwtr-cloud .GitHub Actions 與 GHCR
專案包含 GitHub Actions workflow,會自動組建 image 並推送至 GitHub Container Registry(GHCR)。
官方 Image:
ghcr.io/dongdongbh/mindwtr-app:latestghcr.io/dongdongbh/mindwtr-cloud:latest
預發行組建可使用浮動的 beta tag;它永遠指向最新發行版本(release candidate 或 stable)。也可使用特定版本,例如 ghcr.io/dongdongbh/mindwtr-app:1.2.0-rc.1。latest 永遠維持在 stable。其他平台請參閱加入測試版管道。
docker/compose.yaml 檔案預設已設定使用這些 image,因此無須在本機組建,也能輕鬆拉取最新版本。
技術注意事項
- PWA 服務:網頁版使用用戶端渲染。Nginx 容器已設定
try_files,將所有要求重新導向至index.html,避免重新整理頁面時出現 404 錯誤。 - Base Image:組建使用 Bun(固定為 v1.3),並包含
better-sqlite3所需的 C++20 flags。