DIT Official Website

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

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

技術架構

層級	技術	用途
前端	Vue 3、Vue Router、Vite	SPA 介面與路由
3D / 文件	Three.js、PDF.js	GLB 機器人與 PDF 預覽
後端	FastAPI、Uvicorn、Pillow	JSON API、媒體檔案與圖片處理
資料	JSON、圖片、影片、PDF、GLB	網站內容與靜態資源
容器	Docker Compose、Nginx	建置、服務管理與 API 反向代理

瀏覽器 :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 Compose

需求

• 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

改變對外 port

WEB_PORT=80 docker compose up -d --build

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

WEB_BIND=192.168.50.20WEB_PORT=80DATABASE_HOST_DIR=/home/dit-web/dit-website-dataDIT_CHATBOT_BASE_URL=http://192.168.50.21:8000DIT_CHATBOT_API_KEY=請填入網站專用的-public-api-keyTUNNEL_TOKEN=請填入-Cloudflare-Tunnel-tokenEDITOR_USERNAME=請設定編輯器帳號EDITOR_PASSWORD=至少-12-字元的獨立密碼EDITOR_SESSION_SECRET=以-openssl-rand-base64-48-產生EDITOR_ALLOWED_NETWORKS=192.168.50.0/24,127.0.0.0/8EDITOR_ALLOWED_HOSTS=192.168.50.20EDITOR_UID=1000EDITOR_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

1. 啟動後端

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。

2. 啟動前端

另開終端：

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 只用於本機檢查，不應作為正式伺服器。

網站路由

路徑	頁面
/	首頁、團隊、教授、贊助商與聯絡資訊
/Eurobot	Eurobot 介紹、當年資料與歷年機器人
/Competition	其他競賽

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

主要 API

方法	路徑	說明
GET	/api/aboutPage/data	團隊介紹
GET	/api/Advisor/data	指導教授
GET	/api/Sponsors	贊助商
GET	/api/Eurobot	最新年度 Eurobot
GET	/api/Eurobot/{year}	指定年度 Eurobot
GET	/api/Eurobot/History	歷年 Eurobot
GET	/api/Eurobot/{year}/file/{filename}	年度圖片、PDF 或 GLB
GET	/api/heroVideo/{platform}	mobile 或 desktop 首頁影片
GET	/api/jsonData/{title}	共用 JSON
GET	/api/PopUpItem/{file}	彈出視窗附件

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

內容與媒體

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

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

Git 不包含的檔案

.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。

常見問題

網站顯示 502

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

3D 模型顯示 404

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 中為唯讀，後端不應直接修改網站內容。