polymedx-production-部署流程

Application Server + 獨立 MongoDB Server 正式環境部署指南

架構概述

正式環境採分離式架構：MongoDB 獨立運行於 MongoDB Server，Application Server 只運行應用服務群（polymed-system）。

MongoDB Server
└── polymed-mongodb

Application Server
└── polymed-system
    ├── redis
    ├── backend
    ├── frontend
    ├── rmf-api-service
    ├── loki
    └── grafana

**ℹ 說明 polymed-system 不會**啟動本機 MongoDB，而是透過網路連線至獨立 MongoDB Server。此設計便於資源隔離與獨立擴展。

首次初始化（僅 Application Server 第一次部署需要）

在 Application Server 建立完整 PolyMedX workspace：

mkdir polyMedX
cd polyMedX

repo init \
  -u git@ssh.dev.azure.com:v3/pixsee/PolyMedX/polymedx-manifest \
  -b main \
  -m default.xml

repo sync -c -j8

完成後目前目錄即為 polyMedX workspace root。接著執行：

cp production.env.example production.env
cp tams-frontend/.env.example tams-frontend/.env
cp tams-backend-service/.env.example tams-backend-service/.env
cp rmf-api-service/.env.example rmf-api-service/.env

make prod-config
make prod-build
make prod-up

**ℹ 說明 此初始化流程只需要在 Application Server 第一次**部署時執行。MongoDB Server 只需取得並部署 mongodb-deployment 目錄即可。

MongoDB Server 部署

將 mongodb-deployment 整個目錄複製到 MongoDB Server，建議放置於：

sudo mkdir -p /opt/polymedx
sudo chown "$USER" /opt/polymedx
cd /opt/polymedx
# 接著將 mongodb-deployment 目錄放入此處

目錄結構應如下：

/opt/polymedx/mongodb-deployment/
├── docker-compose.yml
├── production.mongodb.env.example
└── mongo-init/

建立正式設定檔：

cd /opt/polymedx/mongodb-deployment
cp production.mongodb.env.example production.mongodb.env
chmod 600 production.mongodb.env

編輯 production.mongodb.env：

# MongoDB Server 的 private IP
MONGO_BIND_ADDRESS=10.10.0.20
MONGO_PORT=27017

DEFAULT_MONGO_DB_NAME=tams

# MongoDB 管理帳號
MONGO_INITDB_ROOT_USERNAME=tams_root
MONGO_INITDB_ROOT_PASSWORD='請替換成強密碼'

# 給 PolyMedX backend 使用的 MongoDB 帳號
MONGO_APP_USERNAME=polymedx_app
MONGO_APP_PASSWORD='請替換成另一組強密碼'

# 初始 API Basic Auth client
INIT_CLIENT_ID=production-client
INIT_CLIENT_SECRET='請替換成強密碼'
INIT_CLIENT_NAME=PolyMedX Production

啟動 MongoDB：

docker compose --env-file production.mongodb.env config -q
docker compose --env-file production.mongodb.env pull
docker compose --env-file production.mongodb.env up -d
docker compose --env-file production.mongodb.env ps

確認 mongodb 顯示 healthy。

若 MongoDB 已經有既有 volume，需補建管理員帳號 admin@tams.com：

docker compose --env-file production.mongodb.env \
  --profile bootstrap run --rm bootstrap-admin

MongoDB Server 防火牆設定

假設網路規劃如下：

Application Server：10.10.0.10
MongoDB Server：    10.10.0.20

只允許 Application Server 連入 MongoDB 27017 埠：

sudo ufw allow from 10.10.0.10 to any port 27017 proto tcp
sudo ufw deny 27017/tcp

**⚠ 注意 **絕對不要將 27017 對公網開放。僅允許受信任的 Application Server IP 存取。

Application Server 準備 PolyMedX

Application Server 需要完整 PolyMedX workspace，結構如下：

polyMedX/
├── Makefile
├── docker-compose.prod.yml
├── tams-backend-service/
├── tams-frontend/
├── rmf-api-service/
└── workspace-config/

進入 workspace 根目錄：

cd /opt/polymedx/polyMedX

建立 root production env：

cp production.env.example production.env
chmod 600 production.env

編輯 production.env：

DEFAULT_MONGO_URI=mongodb://10.10.0.20:27017/tams?authSource=tams
DEFAULT_MONGO_DB_NAME=tams

MONGO_APP_USERNAME=polymedx_app
MONGO_APP_PASSWORD='與 MongoDB Server 相同的密碼'

REDIS_PASSWORD='請替換成強密碼'
RMF_API_KEY='正式 RMF API key'

# 依實際 ROS Bridge 位址調整
ROSBRIDGE_URL=ws://host.docker.internal:9090

**⚠ 注意 **MONGO_APP_USERNAME 與 MONGO_APP_PASSWORD 必須與 MongoDB Server 的設定完全相同。

建立各服務必要的 `.env` 檔案

Base Compose 仍會讀取這兩個檔案，因此首次部署需要建立：

cp tams-backend-service/.env.example tams-backend-service/.env
cp rmf-api-service/.env.example rmf-api-service/.env

chmod 600 tams-backend-service/.env
chmod 600 rmf-api-service/.env

**ℹ 說明 **production 的 MongoDB、Redis、RMF API key 會由 root 的 production.env 覆寫；但仍請檢查各服務 .env 中的 production 相關設定（例如 CSH URL、JWT、ROS Bridge、domain 與 logging path）。

驗證 Application Server 能連線 MongoDB

先測試網路連通：

nc -vz 10.10.0.20 27017

若有安裝 mongosh，可進一步確認帳密：

mongosh \
  "mongodb://polymedx_app@10.10.0.20:27017/tams?authSource=tams" \
  --password

**ℹ 說明 **密碼請以互動式輸入，避免寫入 shell history。

使用 Make 部署 polymed-system

先檢查 production Compose 設定：

make prod-config

確認輸出的服務列表中沒有 mongodb：

docker compose \
  --env-file production.env \
  -f docker-compose.prod.yml \
  config --services

首次部署或程式碼更新時，先建立 images：

make prod-build

啟動服務：

make prod-up

make prod-up 等同於：

docker compose --env-file production.env -f docker-compose.prod.yml up -d

它會啟動 polymed-system 的 Redis、backend、frontend、RMF API、Loki 與 Grafana，但不會啟動 MongoDB。

若想一次 build 並啟動，可使用：

make prod-up-build

上線後檢查

查看服務狀態：

make prod-ps

查看即時日誌：

make prod-logs

只查看 backend 日誌：

docker compose \
  --env-file production.env \
  -f docker-compose.prod.yml \
  logs -f backend

確認 backend 日誌沒有以下錯誤：

MongoServerSelectionError
Authentication failed
ECONNREFUSED

首次管理員登入帳號：

Email:    admin@tams.com
Password: Tams123!

**⚠ 注意 **正式環境上線後請立即修改預設管理員密碼。

日常維運指令

請一律使用 make prod-* 指令，避免誤用開發環境設定。

指令	說明
`make prod-up`	啟動既有 production services
`make prod-ps`	查看服務狀態
`make prod-logs`	查看所有日誌
`make prod-restart`	重啟 production services
`make prod-down`	停止 production services

**⚠ 注意 **請使用 make prod-* 指令，不要在 production 主機使用一般的 make up 或 make down，避免誤套用本機開發設定。

文件整理自 PolyMedX production 部署筆記。部署時請依實際網路環境調整 IP、密碼與金鑰。