Raspberry Pi 5 從安裝到伺服器部署完整教學

從燒錄系統、首次開機、SSH、套件更新，到 Nginx、Ollama、Docker、Docker Compose 與 MariaDB / phpMyAdmin / LAMP 實作。

適合大學課程、實驗課、IoT 專題前導教學，也適合作為學生的課後操作手冊。

Raspberry Pi 5 Ubuntu / Raspberry Pi OS Docker Compose Web 與 AI 服務部署

一、教學目標

理解 Raspberry Pi 5 的系統安裝流程
熟悉 SSH 遠端管理與基本安全設定
學會更新系統與安裝常見套件
學會部署 Nginx、Ollama、Docker
使用 Docker Compose 建立 MariaDB、phpMyAdmin 與 LAMP 環境

二、建議硬體

Raspberry Pi 5 主機板
官方或品質穩定的 USB-C 電源供應器
microSD 卡，建議 32GB 以上
若要長時間跑 Docker / Ollama，建議使用 SSD
散熱片或風扇
網路線或穩定 Wi-Fi

若要安裝 Ollama，建議 RAM 至少 8GB，且盡量使用 SSD，否則體驗會偏慢。

三、系統安裝前準備

1. 下載 Raspberry Pi Imager

Windows / macOS / Ubuntu 均可安裝 Raspberry Pi Imager
也可用 balenaEtcher，但 Raspberry Pi Imager 對初學者更方便

2. 選擇作業系統

系統	適合情境	說明
Raspberry Pi OS	入門教學、一般應用	官方支援最好，硬體相容性高
Ubuntu Server	伺服器課程、Docker、雲端服務	偏文字介面，適合遠端管理與部署
Ubuntu Desktop	需要圖形桌面教學	資源消耗較高，不一定適合長期伺服器用途

如果課程主題是 IoT、伺服器、Docker、網頁部署，我會比較推薦 Ubuntu Server 或 Raspberry Pi OS Lite。

四、燒錄 microSD 與進階設定

開啟 Raspberry Pi Imager
選擇裝置：Raspberry Pi 5
選擇作業系統，例如 Ubuntu Server 24.04 LTS 或 Raspberry Pi OS Lite
選擇儲存裝置：microSD 卡
按設定圖示，先做預設配置

建議先設定的項目

主機名稱，例如 rpi5-iot
建立使用者帳號與密碼
設定 Wi-Fi SSID 與密碼
設定時區為 Asia/Taipei
啟用 SSH

若課程在教室一次配置多台樹莓派，主機名稱不要都一樣，否則區網上會很容易混淆。

五、首次開機後的基本檢查

1. 直接接螢幕與鍵盤

whoami
hostname
pwd
ip a

2. 從另一台電腦 SSH 登入

ssh 使用者名稱@樹莓派IP位址

# 例如
ssh minhuang@192.168.1.120

3. 若不知道 IP 位址

在路由器管理頁面查看 DHCP 清單
或在本機掃描區網

ping rpi5-iot.local

若 mDNS 正常，很多情況可直接用 主機名稱.local 連線。

六、系統更新與常用工具安裝

第一次登入後，幾乎一定要先做更新。

sudo apt update
sudo apt upgrade -y
sudo apt full-upgrade -y
sudo apt autoremove -y
sudo apt autoclean

安裝常用工具

sudo apt install -y \
  git curl wget vim nano htop tree unzip zip \
  net-tools dnsutils ca-certificates gnupg lsb-release \
  software-properties-common apt-transport-https

重新開機

sudo reboot

上課時可順便說明：update 是更新套件清單，upgrade 是升級已安裝套件，兩者功能不同。

七、基本安全與系統設定

1. 變更密碼

passwd

2. 設定時區

timedatectl
sudo timedatectl set-timezone Asia/Taipei

3. 啟用防火牆

sudo apt install -y ufw
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

4. 查看系統資訊

uname -a
cat /etc/os-release
free -h
df -h
vcgencmd measure_temp

八、安裝與測試 Nginx

1. 安裝 Nginx

sudo apt install -y nginx

2. 啟動與開機自動執行

sudo systemctl enable nginx
sudo systemctl start nginx
sudo systemctl status nginx

3. 測試

curl http://localhost

也可直接在瀏覽器輸入樹莓派 IP，例如 http://192.168.1.120。

4. 網頁根目錄

cd /var/www/html
ls -al

5. 測試自訂首頁

echo '<h1>Hello Raspberry Pi 5</h1>' | sudo tee /var/www/html/index.html

6. 常見管理指令

sudo nginx -t
sudo systemctl reload nginx
sudo systemctl restart nginx

九、安裝 Docker

雖然 Ubuntu 套件庫裡也有 docker 套件，但正式部署建議使用 Docker 官方安裝方式。

1. 加入 Docker 官方 GPG key 與來源

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

2. 安裝 Docker 相關套件

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3. 測試 Docker

sudo docker version
sudo docker run hello-world

4. 讓一般使用者可直接使用 docker

sudo usermod -aG docker $USER
newgrp docker

docker ps

加入 docker 群組後，通常重新登入一次 shell 會比較穩定。

十、安裝 Docker Compose 與基本觀念

新版 Docker Compose 多半已整合為 plugin，指令是 docker compose，不是舊版的 docker-compose。

docker compose version

基本流程

建立專案目錄
撰寫 compose.yaml
執行 docker compose up -d
用 docker compose ps 查看狀態
用 docker compose logs -f 查看日誌

十一、用 Docker Compose 建立 MariaDB + phpMyAdmin

1. 建立專案資料夾

mkdir -p ~/docker/mariadb-phpmyadmin
cd ~/docker/mariadb-phpmyadmin

2. 撰寫 compose.yaml

nano compose.yaml

services:
  mariadb:
    image: mariadb:11
    container_name: mariadb
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: root123456
      MYSQL_DATABASE: iotdb
      MYSQL_USER: iotuser
      MYSQL_PASSWORD: iotpass123
    volumes:
      - mariadb_data:/var/lib/mysql
    ports:
      - "3306:3306"

  phpmyadmin:
    image: phpmyadmin:latest
    container_name: phpmyadmin
    restart: unless-stopped
    environment:
      PMA_HOST: mariadb
      PMA_PORT: 3306
      UPLOAD_LIMIT: 256M
    ports:
      - "8080:80"
    depends_on:
      - mariadb

volumes:
  mariadb_data:

3. 啟動服務

docker compose up -d

4. 檢查

docker compose ps
docker compose logs -f

5. 瀏覽器測試

phpMyAdmin：http://樹莓派IP:8080
帳號：root
密碼：root123456

正式環境不要直接使用簡單密碼，課堂示範結束後請改密碼。

十二、用 Docker Compose 建立 Apache + PHP + MariaDB 的 LAMP 環境

1. 建立資料夾

mkdir -p ~/docker/lamp-stack/www
cd ~/docker/lamp-stack

2. 建立首頁測試檔

cat > ~/docker/lamp-stack/www/index.php <<'EOF'
<?php
phpinfo();
?>
EOF

3. 撰寫 compose.yaml

services:
  web:
    image: php:8.2-apache
    container_name: lamp-web
    restart: unless-stopped
    ports:
      - "8081:80"
    volumes:
      - ./www:/var/www/html
    depends_on:
      - db

  db:
    image: mariadb:11
    container_name: lamp-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: root123456
      MYSQL_DATABASE: lampdb
      MYSQL_USER: lampuser
      MYSQL_PASSWORD: lamp123456
    volumes:
      - lamp_db_data:/var/lib/mysql
    ports:
      - "3307:3306"

  phpmyadmin:
    image: phpmyadmin:latest
    container_name: lamp-pma
    restart: unless-stopped
    environment:
      PMA_HOST: db
      PMA_PORT: 3306
    ports:
      - "8082:80"
    depends_on:
      - db

volumes:
  lamp_db_data:

4. 啟動服務

docker compose up -d

5. 測試位置

LAMP 網頁：http://樹莓派IP:8081
phpMyAdmin：http://樹莓派IP:8082

6. 若要支援 mysqli / pdo_mysql

正式教學時可延伸到自製 Dockerfile。

FROM php:8.2-apache
RUN docker-php-ext-install mysqli pdo pdo_mysql

十三、建立更完整的 PHP + Apache 映像檔

1. 建立 Dockerfile

mkdir -p ~/docker/lamp-custom/www
cd ~/docker/lamp-custom
nano Dockerfile

FROM php:8.2-apache
RUN apt-get update && apt-get install -y \
    libpng-dev libjpeg-dev libfreetype6-dev zip unzip
RUN docker-php-ext-install mysqli pdo pdo_mysql
RUN a2enmod rewrite

2. compose.yaml

services:
  web:
    build: .
    container_name: custom-lamp-web
    restart: unless-stopped
    ports:
      - "8083:80"
    volumes:
      - ./www:/var/www/html
    depends_on:
      - db

  db:
    image: mariadb:11
    container_name: custom-lamp-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: root123456
      MYSQL_DATABASE: customdb
      MYSQL_USER: customuser
      MYSQL_PASSWORD: custompass123
    volumes:
      - custom_db_data:/var/lib/mysql

volumes:
  custom_db_data:

3. 啟動

docker compose up -d --build

十四、安裝 Ollama

Ollama 可在本機執行大型語言模型，但 Raspberry Pi 5 的速度與模型大小需審慎選擇。

1. 官方腳本安裝

curl -fsSL https://ollama.com/install.sh | sh

2. 啟動服務

sudo systemctl enable ollama
sudo systemctl start ollama
sudo systemctl status ollama

3. 測試版本

ollama --version

4. 下載模型

ollama pull llama3.2
# 或較小模型
ollama pull qwen2.5:0.5b

5. 執行模型

ollama run llama3.2

6. API 測試

curl http://localhost:11434/api/tags

如果樹莓派 RAM 較小，建議先從體積較小的模型開始，否則容易變慢或記憶體不足。

十五、Nginx 反向代理到 Docker 或 Ollama

這部分很適合當作進階示範，讓學生理解內外網服務映射。

1. 建立站台設定

sudo nano /etc/nginx/sites-available/ollama_proxy

server {
    listen 80;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:11434;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

2. 啟用設定

sudo ln -s /etc/nginx/sites-available/ollama_proxy /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

正式公開前請先做好權限管控，否則任何人都可能存取你的 Ollama API。

十六、常用 Docker 管理指令

指令	用途
`docker ps`	查看執行中的容器
`docker ps -a`	查看所有容器
`docker images`	查看本機映像檔
`docker logs 容器名稱`	查看容器日誌
`docker exec -it 容器名稱 bash`	進入容器互動操作
`docker compose up -d`	背景啟動服務
`docker compose down`	關閉 compose 服務
`docker compose restart`	重啟服務
`docker compose logs -f`	即時查看服務輸出

十七、課堂上很值得補充的除錯技巧

1. 檢查服務是否啟動

systemctl status nginx
systemctl status ollama
docker ps

2. 檢查 Port 是否被占用

sudo ss -tulpn

3. 檢查 Docker Compose 設定

docker compose config

4. 看 Nginx 是否語法正確

sudo nginx -t

5. 看系統資源

htop
free -h
df -h

十八、教學建議流程

先讓學生了解 Raspberry Pi 5 的硬體定位
示範燒錄作業系統與首次開機
示範 SSH 登入與系統更新
示範安裝 Nginx，讓學生看到第一個網站
示範安裝 Docker，讓學生理解容器化觀念
示範 Docker Compose 啟動 MariaDB 與 phpMyAdmin
進一步部署 LAMP
最後再示範 Ollama，讓學生感受本地 AI 推論服務

這個流程非常適合切成 2 到 4 次實作課，每次聚焦一個主題，學生吸收會更完整。

十九、作業或實驗題目建議

自行完成 Raspberry Pi 5 作業系統安裝與 SSH 登入
完成 Nginx 網頁部署，首頁顯示學號與姓名
完成 Docker 安裝並成功執行 hello-world
用 Docker Compose 啟動 MariaDB 與 phpMyAdmin
完成一個可執行 phpinfo() 的 LAMP 環境
進階題：讓 Nginx 反向代理到另一個容器服務

二十、結語

只要完成這份教學內容，學生基本上已經掌握從單板電腦安裝、Linux 伺服器管理、Web 服務部署、容器化與本地 AI 服務的完整入門路徑。

這不只是 Raspberry Pi 教學，也是一條很好的現代 IoT 與邊緣運算課程起點。