DIT Robotics 官方網站，包含團隊介紹、Eurobot 競賽資料、歷年機器人 3D 模型、指導教授、贊助商與聯絡資訊。

• 網站：DIT Official Website
• 部署指南：docs/DEPLOYMENT.md
• 後端說明：backend/README.md
• 資料庫規範：database/README.md

瀏覽器 :8080
  └─ frontend / Nginx
       ├─ /        → Vue 靜態網站
       └─ /api/*  → backend:8000 / FastAPI
                             └─ /app/database

後端不直接對外開放 port，瀏覽器的 API 請求統一經過前端 Nginx。

.
├─ compose.yaml              # 前後端 Docker Compose
├─ backend/
│  ├─ Dockerfile
│  ├─ main.py               # FastAPI 入口
│  ├─ requirements.txt
│  ├─ PyAPI/                # 資料與檔案服務
│  └─ routers/              # API routers
├─ frontend/
│  ├─ Dockerfile            # Node 建置 + Nginx runtime
│  ├─ nginx.conf            # SPA 與 /api 反向代理
│  ├─ package.json
│  └─ src/
│     ├─ components/
│     ├─ composables/
│     ├─ router/
│     └─ views/
├─ database/README.md       # 外部資料的格式規範（內容不進 Git）
└─ docs/DEPLOYMENT.md         # Ubuntu 正式部署指南

• Docker Desktop，或 Linux Docker Engine
• Docker Compose v2（docker compose）
• 完整的外部 database 目錄（JSON、圖片、影片、PDF 與 GLB）

在專案根目錄執行：

docker compose up -d --build

開啟 http://localhost:8080，並可使用下列指令測試：

curl -I http://localhost:8080/
curl -fsS http://localhost:8080/api/Eurobot

WEB_PORT=80 docker compose up -d --build

也可在專案根目錄建立 .env：

WEB_BIND=192.168.50.20
WEB_PORT=80
DATABASE_HOST_DIR=/home/dit-web/dit-website-data
DIT_CHATBOT_BASE_URL=http://192.168.50.21:8000
DIT_CHATBOT_API_KEY=請填入網站專用的-public-api-key
TUNNEL_TOKEN=請填入-Cloudflare-Tunnel-token
EDITOR_USERNAME=請設定編輯器帳號
EDITOR_PASSWORD=至少-12-字元的獨立密碼
EDITOR_SESSION_SECRET=以-openssl-rand-base64-48-產生
EDITOR_ALLOWED_NETWORKS=192.168.50.0/24,127.0.0.0/8
EDITOR_ALLOWED_HOSTS=192.168.50.20
EDITOR_UID=1000
EDITOR_GID=1000

DIT_CHATBOT_API_KEY 只會傳入 Nginx 反向代理，不會編譯進 Vue 前端。請勿將正式 key 提交至 Git，並限制 .env 的讀取權限。

WEB_BIND=192.168.50.20 只會在 Server 的內網介面提供直接連線。Editor 只接受 http://192.168.50.20:<WEB_PORT>/Editor，經 Cloudflare Tunnel 或 web.ditrobotics.com 進入會直接回應 403。

# 查看容器與健康狀態
docker compose ps

# 追蹤日誌
docker compose logs -f
docker compose logs -f frontend
docker compose logs -f backend

# 停止並移除容器與 Compose network
docker compose down

# 重新建置並啟動
docker compose up -d --build

DATABASE_HOST_DIR 是唯一的正式資料來源：它會以唯讀 volume 掛載給公開 API，並以可寫 volume 掛載給 Editor。沒有設定時 Compose 會拒絕啟動。EDITOR_UID / EDITOR_GID 必須與擁有該目錄的帳號一致。

不使用 Docker 時需要：

• Python 3.10 以上
• Node.js 22.18.0 以上，或 24.12.0 以上
• npm
• 開發用 backend/cert.pem 與 backend/key.pem

macOS / Linux：

cd backend
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python main.py

Windows PowerShell：

cd backend
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python main.py

main.py 的直接啟動模式只供本機開發，會讀取 PEM 憑證並啟用 reload。

另開終端：

cd frontend
npm ci
npm run dev

預設網址為 http://localhost:5173。Vite 會將 /api 代理至 https://127.0.0.1:8000。

cd frontend
npm run format
npm run build

建置結果位於 frontend/dist/。npm run preview 只用於本機檢查，不應作為正式伺服器。

Nginx 已設定 SPA fallback，直接重新整理子頁時不會因 Vue Router 而出現 404。

FastAPI 互動式文件位於後端 /docs。Compose 的 Nginx 只對外代理 /api；需要檢視 /docs 時，請在原生開發環境直接開啟後端。

DATABASE_HOST_DIR 指向的外部目錄是網站內容的唯一來源，前端透過 /api/... 取得內容。

• JSON 與實際檔名必須完全一致；Linux 會區分大小寫。
• 每個 Eurobot 年度目錄都需要 main_data.json。
• year 由後端從資料夾名稱產生，不需寫入 JSON。
• 新媒體檔建議使用 ASCII kebab-case 名稱。
• 完整規範請參考 database/README.md。

.gitignore 會忽略：

/database/**
*.pem

因此：

• Git clone 不會取得任何正式內容；部署前必須先準備 DATABASE_HOST_DIR。
• backend/key.pem 與 backend/cert.pem 只供本機開發，不應提交、分享或包入 image。
• Docker Compose 不需要 PEM；正式 HTTPS 應由外層 Nginx、Caddy、Cloudflare 或 load balancer 處理。

將修改推送到 GitHub 後，在伺服器執行：

cd /home/dit-web/Dit_website
git pull --ff-only
docker compose up -d --build
docker compose ps

若只修改已掛載的 JSON 或媒體檔，通常不需重建 image。必要時可重啟後端：

docker compose restart backend

完整的 Ubuntu、網域、HTTPS、Nginx 與備份說明請參考 docs/DEPLOYMENT.md。

docker compose ps
docker compose logs --tail=100 backend

find "$DATABASE_HOST_DIR/Eurobot" -name '*.glb' -type f

確認 GLB 已另外上傳，並且檔名與 main_data.json 中的 glbPath 完全一致。

docker compose up -d --build

程式碼會被包入 image，因此需重新建置。Nginx 對 index.html 設定了 no-cache，含 hash 的 /assets/ 則會長期快取。

docker compose exec backend python -c "import PyAPI.ResourceService as r; print(r.BASE_DIR)"

預期輸出 /app/database。

• 不要將私密金鑰、正式憑證、密碼或 token 提交到 Git。
• 不要把 FastAPI reload 開發模式暴露到公開網路。
• 正式環境應使用 HTTPS，並將 TLS 交由容器外層 reverse proxy 管理。
• database volume 在 Compose 中為唯讀，後端不應直接修改網站內容。