Docker Compose

使用官方控制器映像檔、搭配 TimescaleDB 的 PostgreSQL 與自動遷移功能安裝 Netstamp。

若要自行託管 Netstamp，建議先從程式碼儲存庫提供的標準 Compose 部署開始。它會執行三個服務：

服務用途
postgresPostgreSQL 16、TimescaleDB，以及保存資料的 named volume
migrate使用相同 Netstamp 映像檔版本執行一次性的資料庫遷移
netstamp控制器、內嵌 React 應用程式、API，以及 Linux 探測器安裝資源

下載並設定

bash
mkdir -p /opt/netstamp
cd /opt/netstamp
curl -fsSLO https://raw.githubusercontent.com/yorukot/netstamp/main/deployments/docker/compose.yaml
curl -fsSLO https://raw.githubusercontent.com/yorukot/netstamp/main/deployments/docker/example.env
cp example.env .env
chmod 600 .env

產生五組彼此獨立的密鑰：

bash
openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 32

將不同的隨機值分別填入 .env 下列欄位：

dotenv
DATABASE_PASSWORD=<random value>
LOG_PSEUDONYM_KEY=<random value>
SYSTEM_SETTINGS_ENCRYPTION_KEY=<random value>
AUTH_SESSION_HASH_KEY=<random value>
AUTH_API_TOKEN_HASH_KEY=<random value>

重新啟動或升級時必須沿用這些值。變更 hash key 會讓對應憑證失效；變更系統設定加密金鑰，則可能導致已儲存的 SMTP 憑證無法解密。

啟動服務

bash
docker compose pull
docker compose up -d
docker compose ps
docker compose logs migrate

正常狀態如下：

  • postgres 顯示 healthy；
  • migrate 以狀態碼 0 結束；
  • netstamp 持續執行；
  • 設定的連接埠可回應 /healthz 與 /api/v1/healthz。
bash
curl --fail http://127.0.0.1:3000/healthz
curl --fail http://127.0.0.1:3000/api/v1/healthz

選擇映像檔與版本

預設值如下：

dotenv
NETSTAMP_IMAGE=yorukot/netstamp
NETSTAMP_VERSION=latest
TIMESCALEDB_IMAGE=timescale/timescaledb:latest-pg16
NETSTAMP_PORT=3000

latest 適合試用。正式或受控環境應將 NETSTAMP_VERSION 與 TIMESCALEDB_IMAGE 固定在已測試、不可變動的 release tag 或 digest。遷移與應用程式服務必須使用相同的 Netstamp 版本。

持久化資料

資料庫存放在 Compose 中邏輯名稱為 netstamp-postgres 的 volume；Docker 通常會在實際名稱前加上 Compose project name。移除 container 不會刪除 volume。除非確定要銷毀所有專案、使用者、探測器、結果、事件與設定，否則不要執行 docker compose down -v。

列出並檢查 volume：

bash
docker volume ls --filter name=netstamp-postgres
docker compose exec postgres psql -U netstamp -d netstamp -c 'select now();'

建置自訂映像檔

發布的映像檔包含控制器、遷移工具、網頁應用程式，以及 amd64/arm64 探測器執行檔。若要從 checkout 建置相同映像檔：

bash
docker build -f deployments/docker/Dockerfile -t netstamp:local .
NETSTAMP_IMAGE=netstamp NETSTAMP_VERSION=local docker compose up -d

前端的 VITE_NETSTAMP_* 功能旗標會在建置時寫入。製作自訂映像檔時，請透過 Docker 建置參數修改；在已建置完成的容器中新增執行階段環境變數，不會改變前端內容。

接下來

將服務公開到網際網路之前，請完成正式環境部署中的所有項目。