---
# System prepended metadata

title: Docker 容器化多用戶 VS Code Server 部署指導手冊

---

# Docker 容器化多用戶 VS Code Server 部署指導手冊

## 📋 目錄

1. [概述](#概述)
2. [系統需求](#系統需求)
3. [準備工作](#準備工作)
4. [Docker 環境安裝](#docker-環境安裝)
5. [容器化部署](#容器化部署)
6. [配置管理](#配置管理)
7. [用戶管理](#用戶管理)
8. [監控與維護](#監控與維護)
9. [故障排除](#故障排除)
10. [安全性考量](#安全性考量)
11. [Amazon Q CLI 自動化部署](#amazon-q-cli-自動化部署)

---

## 概述

本指導手冊將引導您完成 Docker 容器化多用戶 VS Code Server 的完整部署過程。相比傳統的 systemd 服務管理方式，Docker 容器化提供了以下優勢：

### 🐳 容器化優勢

- **完全隔離**: 每個用戶運行在獨立的容器中
- **資源管理**: 可設定 CPU 和記憶體限制
- **易於擴展**: 快速添加或移除用戶
- **統一管理**: 使用 Docker Compose 統一管理所有服務
- **可移植性**: 可輕鬆遷移到其他主機
- **自動恢復**: 容器異常時自動重啟

### 🏗️ 架構概覽

```
┌─────────────────────────────────────────────────────────────┐
│                    AWS EC2 Instance                        │
│  ┌─────────────────────────────────────────────────────────┤
│  │                Docker Engine                            │
│  │  ┌──────────────────┐    ┌──────────────────┐          │
│  │  │  vscode-apple    │    │  vscode-orange   │          │
│  │  │  Container       │    │  Container       │          │
│  │  │  Port: 8080      │    │  Port: 8081      │          │
│  │  │  User: apple     │    │  User: orange    │          │
│  │  └──────────────────┘    └──────────────────┘          │
│  │           │                        │                   │
│  │  ┌──────────────────────────────────────────────────┐  │
│  │  │            Docker Network                        │  │
│  │  │         vscode-network                           │  │
│  │  └──────────────────────────────────────────────────┘  │
│  └─────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────────┤
│  │                Host File System                         │
│  │  ./data/apple/    ./data/orange/                       │
│  │  ├── workspace/   ├── workspace/                       │
│  │  ├── config/      ├── config/                          │
│  │  └── local/       └── local/                           │
│  └─────────────────────────────────────────────────────────┤
└─────────────────────────────────────────────────────────────┘
```

---

## 系統需求

### 🖥️ 硬體需求

- **CPU**: 最少 2 vCPU (建議 4 vCPU 以上)
- **記憶體**: 最少 4GB RAM (建議 8GB 以上)
- **儲存空間**: 最少 20GB 可用空間
- **網路**: 穩定的網際網路連線

### 🐧 軟體需求

- **作業系統**: Amazon Linux 2023 或 Ubuntu 22.04+
- **Docker**: 版本 24.0 以上
- **Docker Compose**: 版本 2.20 以上
- **SSH**: 用於遠端管理

### ☁️ AWS 資源需求

- **EC2 實例**: t3.medium 或更高規格
- **安全群組**: 開放端口 22, 8080, 8081
- **SSH 金鑰對**: 用於安全連線

---

## 準備工作

### 1. 創建 EC2 實例

```bash
# 使用 AWS CLI 創建 Amazon Linux 2023 實例
aws ec2 run-instances \
    --image-id ami-0230bd60aa48260c6 \
    --count 1 \
    --instance-type t3.medium \
    --key-name your-key-name \
    --security-group-ids sg-xxxxxxxxx \
    --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=Docker-VSCode-Server-AL2023}]'
```

### 2. 配置安全群組

```bash
# 創建安全群組
aws ec2 create-security-group \
    --group-name docker-vscode-sg \
    --description "Security group for Docker VS Code Server"

# 添加規則
aws ec2 authorize-security-group-ingress \
    --group-id sg-xxxxxxxxx \
    --protocol tcp \
    --port 22 \
    --cidr 0.0.0.0/0

aws ec2 authorize-security-group-ingress \
    --group-id sg-xxxxxxxxx \
    --protocol tcp \
    --port 8080 \
    --cidr 0.0.0.0/0

aws ec2 authorize-security-group-ingress \
    --group-id sg-xxxxxxxxx \
    --protocol tcp \
    --port 8081 \
    --cidr 0.0.0.0/0
```

### 3. 連線到實例

```bash
# SSH 連線
ssh -i your-key.pem ec2-user@your-instance-ip
```

---

## Docker 環境安裝

### 1. 系統更新

```bash
# Amazon Linux 2023
sudo dnf update -y

# Ubuntu 22.04+
sudo apt update && sudo apt upgrade -y
```

### 2. 安裝 Docker

### 2. 安裝 Docker

#### Amazon Linux 2023

```bash
# 安裝 Docker
sudo dnf install -y docker

# 啟動 Docker 服務
sudo systemctl start docker
sudo systemctl enable docker

# 將用戶添加到 docker 群組
sudo usermod -a -G docker ec2-user

# 重新登入以應用群組變更
newgrp docker

# 驗證安裝
docker --version
```

#### Ubuntu 22.04+

```bash
# 安裝必要套件
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# 添加 Docker GPG 金鑰
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加 Docker 儲存庫
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安裝 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 啟動 Docker 服務
sudo systemctl start docker
sudo systemctl enable docker

# 將用戶添加到 docker 群組
sudo usermod -a -G docker $USER

# 驗證安裝
docker --version
```

### 3. 安裝 Docker Compose

#### 方法 1: 使用 Docker Compose Plugin (推薦)

```bash
# Amazon Linux 2023 - Docker Compose Plugin 通常已包含在 Docker 安裝中
# 驗證安裝
docker compose version

# 如果未安裝，手動安裝
sudo dnf install -y docker-compose-plugin
```

#### 方法 2: 獨立安裝 Docker Compose

```bash
# 下載最新版本的 Docker Compose
DOCKER_COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep 'tag_name' | cut -d\" -f4)
sudo curl -L "https://github.com/docker/compose/releases/download/${DOCKER_COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 設定執行權限
sudo chmod +x /usr/local/bin/docker-compose

# 建立符號連結
sudo ln -sf /usr/local/bin/docker-compose /usr/bin/docker-compose

# 驗證安裝
docker-compose --version
```

#### 使用建議

```bash
# 推薦使用 docker compose (plugin 版本)
docker compose up -d

# 而不是 docker-compose (獨立版本)
docker-compose up -d
```

---

## 容器化部署

### 1. 創建項目目錄結構

```bash
# 創建主目錄
mkdir -p ~/vscode-docker
cd ~/vscode-docker

# 創建子目錄
mkdir -p scripts data/{apple,orange}/{workspace,config,local}
```

### 2. 創建 Dockerfile

```bash
cat > Dockerfile << 'EOF'
FROM codercom/code-server:4.21.1

USER root

# 更新套件列表並安裝基礎工具
RUN apt-get update && apt-get install -y \
    git \
    curl \
    wget \
    nano \
    vim \
    htop \
    net-tools \
    sudo \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# 安裝 Python 3.11 和相關工具
RUN apt-get update && apt-get install -y \
    python3.11 \
    python3.11-pip \
    python3.11-venv \
    python3.11-dev \
    && ln -sf /usr/bin/python3.11 /usr/bin/python3 \
    && ln -sf /usr/bin/python3.11 /usr/bin/python \
    && rm -rf /var/lib/apt/lists/*

# 安裝 Node.js 20 LTS
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs

# 安裝常用的全域 npm 套件
RUN npm install -g \
    typescript \
    ts-node \
    nodemon \
    pm2 \
    @angular/cli \
    create-react-app \
    vue-cli

# 安裝 Go 1.21
RUN wget https://go.dev/dl/go1.21.6.linux-amd64.tar.gz \
    && tar -C /usr/local -xzf go1.21.6.linux-amd64.tar.gz \
    && rm go1.21.6.linux-amd64.tar.gz

# 安裝 Rust
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

# 設定環境變數
ENV PATH="/usr/local/go/bin:/home/coder/.cargo/bin:${PATH}"
ENV GOPATH="/home/coder/go"
ENV GOROOT="/usr/local/go"

# 建立用戶腳本
COPY scripts/entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh

# 設定工作目錄
WORKDIR /home/coder

# 暴露端口
EXPOSE 8080

# 健康檢查
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8080 || exit 1

# 使用自定義入口點
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
EOF
```

### 3. 創建入口點腳本

```bash
cat > scripts/entrypoint.sh << 'EOF'
#!/bin/bash

# 設定預設值
USER_NAME=${USER_NAME:-coder}
USER_PASSWORD=${USER_PASSWORD:-password}
WORKSPACE_DIR=${WORKSPACE_DIR:-/home/coder/workspace}

# 建立工作目錄
mkdir -p "$WORKSPACE_DIR"

# 建立配置目錄
mkdir -p /home/coder/.config/code-server

# 建立配置檔案
cat > /home/coder/.config/code-server/config.yaml << CONFIG_EOF
bind-addr: 0.0.0.0:8080
auth: password
password: $USER_PASSWORD
cert: false
disable-telemetry: true
disable-update-check: true
disable-getting-started-override: true
CONFIG_EOF

# 設定 Git 全域配置
sudo -u coder git config --global user.name "$USER_NAME"
sudo -u coder git config --global user.email "$USER_NAME@example.com"
sudo -u coder git config --global init.defaultBranch main

# 設定 Python 虛擬環境
sudo -u coder python3 -m venv "$WORKSPACE_DIR/.venv"

# 建立常用目錄
sudo -u coder mkdir -p "$WORKSPACE_DIR"/{projects,scripts,docs,temp}

# 設定權限
chown -R coder:coder /home/coder
chmod 600 /home/coder/.config/code-server/config.yaml

# 建立歡迎檔案
cat > "$WORKSPACE_DIR/README.md" << WELCOME_EOF
# 歡迎使用 $USER_NAME 的 Docker VS Code Server！

## 🐳 容器化環境特色

### 📋 基本資訊
- **用戶名稱**: $USER_NAME
- **工作目錄**: $WORKSPACE_DIR
- **密碼**: $USER_PASSWORD
- **Code Server 版本**: $(code-server --version | head -n1)

### 🛠️ 預安裝開發環境

#### Python 3.11
- **版本**: $(python3 --version)
- **虛擬環境**: $WORKSPACE_DIR/.venv
- **啟動虛擬環境**: \`source .venv/bin/activate\`

#### Node.js 20 LTS
- **版本**: $(node --version)
- **npm 版本**: $(npm --version)
- **全域套件**: TypeScript, Angular CLI, React CLI, Vue CLI

#### Go 1.21
- **版本**: $(go version)
- **GOPATH**: $GOPATH
- **GOROOT**: $GOROOT

#### Rust
- **版本**: $(rustc --version 2>/dev/null || echo "正在初始化...")
- **Cargo**: $(cargo --version 2>/dev/null || echo "正在初始化...")

### 📁 目錄結構
- \`projects/\` - 您的專案檔案
- \`scripts/\` - 實用腳本
- \`docs/\` - 文件和筆記
- \`temp/\` - 臨時檔案

### 🚀 快速開始

#### Python 開發
\`\`\`bash
# 啟動虛擬環境
source .venv/bin/activate

# 安裝套件
pip install requests flask django

# 創建新專案
mkdir projects/my-python-app
cd projects/my-python-app
\`\`\`

#### Node.js 開發
\`\`\`bash
# 創建 React 應用
cd projects
npx create-react-app my-react-app

# 創建 Angular 應用
ng new my-angular-app

# 創建 Vue 應用
vue create my-vue-app
\`\`\`

#### Go 開發
\`\`\`bash
# 初始化 Go 模組
cd projects
mkdir my-go-app && cd my-go-app
go mod init my-go-app
\`\`\`

#### Rust 開發
\`\`\`bash
# 創建新的 Rust 專案
cd projects
cargo new my-rust-app
cd my-rust-app
cargo run
\`\`\`

### 🔧 實用指令

\`\`\`bash
# 檢查系統資源
htop

# 檢查網路狀態
netstat -tlnp

# Git 操作
git status
git add .
git commit -m "Initial commit"

# 檢查已安裝的套件
pip list                # Python 套件
npm list -g --depth=0   # 全域 npm 套件
go list -m all          # Go 模組
cargo --list            # Rust 工具
\`\`\`

### 📚 學習資源
- [VS Code 官方文件](https://code.visualstudio.com/docs)
- [Python 官方教學](https://docs.python.org/3/tutorial/)
- [Node.js 官方文件](https://nodejs.org/en/docs/)
- [Go 官方教學](https://tour.golang.org/)
- [Rust 官方書籍](https://doc.rust-lang.org/book/)

祝您開發愉快！ 🐳✨
WELCOME_EOF

# 建立實用腳本
cat > "$WORKSPACE_DIR/scripts/setup-python-project.sh" << SCRIPT_EOF
#!/bin/bash
# Python 專案快速設定腳本

PROJECT_NAME=\$1
if [ -z "\$PROJECT_NAME" ]; then
    echo "使用方法: \$0 <專案名稱>"
    exit 1
fi

cd "$WORKSPACE_DIR/projects"
mkdir -p "\$PROJECT_NAME"
cd "\$PROJECT_NAME"

# 創建虛擬環境
python3 -m venv venv
source venv/bin/activate

# 創建基本檔案
cat > requirements.txt << REQ_EOF
requests>=2.31.0
flask>=2.3.0
pytest>=7.4.0
black>=23.0.0
flake8>=6.0.0
REQ_EOF

cat > main.py << MAIN_EOF
#!/usr/bin/env python3
"""
$PROJECT_NAME - 主程式
"""

def main():
    print("Hello, $PROJECT_NAME!")

if __name__ == "__main__":
    main()
MAIN_EOF

cat > README.md << README_EOF
# \$PROJECT_NAME

## 安裝依賴
\`\`\`bash
source venv/bin/activate
pip install -r requirements.txt
\`\`\`

## 執行
\`\`\`bash
python main.py
\`\`\`
README_EOF

# 安裝依賴
pip install -r requirements.txt

echo "Python 專案 '\$PROJECT_NAME' 已建立完成！"
echo "位置: $WORKSPACE_DIR/projects/\$PROJECT_NAME"
SCRIPT_EOF

chmod +x "$WORKSPACE_DIR/scripts/setup-python-project.sh"

# 設定最終權限
chown -R coder:coder "$WORKSPACE_DIR"

# 切換到 coder 用戶並啟動 code-server
exec sudo -u coder code-server --config /home/coder/.config/code-server/config.yaml "$WORKSPACE_DIR"
EOF
```

### 4. 創建 Docker Compose 配置

```bash
cat > docker-compose.yml << 'EOF'
# Docker Compose 版本 (可選，新版本會自動檢測)
name: vscode-multi-user

services:
  vscode-apple:
    build: 
      context: .
      dockerfile: Dockerfile
    container_name: vscode-apple
    hostname: vscode-apple
    ports:
      - "8080:8080"
    environment:
      - USER_NAME=apple
      - USER_PASSWORD=appleCode2024!
      - WORKSPACE_DIR=/home/coder/workspace
    volumes:
      - ./data/apple/workspace:/home/coder/workspace
      - ./data/apple/config:/home/coder/.config
      - ./data/apple/local:/home/coder/.local
    restart: unless-stopped
    networks:
      - vscode-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETGID
      - SETUID

  vscode-orange:
    build: 
      context: .
      dockerfile: Dockerfile
    container_name: vscode-orange
    hostname: vscode-orange
    ports:
      - "8081:8080"
    environment:
      - USER_NAME=orange
      - USER_PASSWORD=orangeCode2024!
      - WORKSPACE_DIR=/home/coder/workspace
    volumes:
      - ./data/orange/workspace:/home/coder/workspace
      - ./data/orange/config:/home/coder/.config
      - ./data/orange/local:/home/coder/.local
    restart: unless-stopped
    networks:
      - vscode-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETGID
      - SETUID

networks:
  vscode-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16
    driver_opts:
      com.docker.network.bridge.name: vscode-br0

# 可選：定義 volumes 用於資料持久化
volumes:
  apple_workspace:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./data/apple/workspace
  orange_workspace:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./data/orange/workspace
EOF
```

### 5. 建立和啟動容器

```bash
# 建立 Docker 映像（使用 BuildKit 加速建立）
DOCKER_BUILDKIT=1 docker compose build --no-cache

# 啟動容器（背景執行）
docker compose up -d

# 檢查容器狀態
docker compose ps

# 查看容器日誌
docker compose logs -f

# 檢查健康狀態
docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"
```

### 6. 驗證部署

```bash
# 檢查容器是否正常運行
docker compose ps

# 測試網路連通性
curl -I http://localhost:8080
curl -I http://localhost:8081

# 檢查容器資源使用
docker stats --no-stream

# 檢查容器健康狀態
docker inspect --format='{{.State.Health.Status}}' vscode-apple
docker inspect --format='{{.State.Health.Status}}' vscode-orange
```

---

## 配置管理

### 1. 容器配置

每個容器都有獨立的配置，可以通過環境變數進行自定義：

```yaml
environment:
  - USER_NAME=username          # 用戶名稱
  - USER_PASSWORD=password      # 登入密碼
  - WORKSPACE_DIR=/path         # 工作目錄路徑
```

### 2. 資料持久化

容器資料通過 Docker volumes 持久化到主機：

```bash
# 資料目錄結構
./data/
├── apple/
│   ├── workspace/    # 用戶工作檔案
│   ├── config/       # VS Code 配置
│   └── local/        # 本地資料
└── orange/
    ├── workspace/
    ├── config/
    └── local/
```

### 3. 網路配置

容器使用自定義網路進行通訊：

```bash
# 檢查網路
docker network ls
docker network inspect vscode-docker_vscode-network
```

---

## 用戶管理

### 1. 添加新用戶

創建新用戶容器的步驟：

```bash
# 1. 創建用戶資料目錄
mkdir -p ./data/newuser/{workspace,config,local}

# 2. 在 docker-compose.yml 中添加新服務
cat >> docker-compose.yml << 'EOF'

  vscode-newuser:
    build: .
    container_name: vscode-newuser
    ports:
      - "8082:8080"
    environment:
      - USER_NAME=newuser
      - USER_PASSWORD=newuserCode2024!
      - WORKSPACE_DIR=/home/coder/workspace
    volumes:
      - ./data/newuser/workspace:/home/coder/workspace
      - ./data/newuser/config:/home/coder/.config
      - ./data/newuser/local:/home/coder/.local
    restart: unless-stopped
    networks:
      - vscode-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080"]
      interval: 30s
      timeout: 10s
      retries: 3
EOF

# 3. 重新部署
docker-compose up -d
```

### 2. 移除用戶

```bash
# 1. 停止並移除容器
docker-compose stop vscode-username
docker-compose rm vscode-username

# 2. 從 docker-compose.yml 中移除服務定義

# 3. 備份並移除用戶資料（可選）
tar -czf username-backup-$(date +%Y%m%d).tar.gz ./data/username/
rm -rf ./data/username/
```

### 3. 用戶管理腳本

創建自動化用戶管理腳本：

```bash
cat > manage-users.sh << 'EOF'
#!/bin/bash

# 用戶管理腳本

show_usage() {
    echo "用戶管理腳本"
    echo
    echo "使用方法:"
    echo "  $0 add <用戶名> <密碼> [端口]     - 添加新用戶"
    echo "  $0 remove <用戶名>              - 移除用戶"
    echo "  $0 list                         - 列出所有用戶"
    echo "  $0 reset-password <用戶名> <新密碼> - 重設密碼"
}

add_user() {
    local username=$1
    local password=$2
    local port=${3:-8082}
    
    if [ -z "$username" ] || [ -z "$password" ]; then
        echo "錯誤: 用戶名和密碼不能為空"
        return 1
    fi
    
    # 檢查用戶是否已存在
    if [ -d "./data/$username" ]; then
        echo "錯誤: 用戶 $username 已存在"
        return 1
    fi
    
    # 創建用戶資料目錄
    mkdir -p "./data/$username"/{workspace,config,local}
    
    # 添加到 docker-compose.yml
    cat >> docker-compose.yml << USER_EOF

  vscode-$username:
    build: .
    container_name: vscode-$username
    ports:
      - "$port:8080"
    environment:
      - USER_NAME=$username
      - USER_PASSWORD=$password
      - WORKSPACE_DIR=/home/coder/workspace
    volumes:
      - ./data/$username/workspace:/home/coder/workspace
      - ./data/$username/config:/home/coder/.config
      - ./data/$username/local:/home/coder/.local
    restart: unless-stopped
    networks:
      - vscode-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080"]
      interval: 30s
      timeout: 10s
      retries: 3
USER_EOF
    
    # 重新部署
    docker-compose up -d
    
    echo "用戶 $username 已成功添加"
    echo "存取 URL: http://$(curl -s http://169.254.169.254/latest/meta-data/public-ipv4):$port"
    echo "密碼: $password"
}

remove_user() {
    local username=$1
    
    if [ -z "$username" ]; then
        echo "錯誤: 請指定用戶名"
        return 1
    fi
    
    # 停止並移除容器
    docker-compose stop "vscode-$username" 2>/dev/null
    docker-compose rm -f "vscode-$username" 2>/dev/null
    
    # 備份用戶資料
    if [ -d "./data/$username" ]; then
        tar -czf "${username}-backup-$(date +%Y%m%d_%H%M%S).tar.gz" "./data/$username/"
        rm -rf "./data/$username/"
        echo "用戶 $username 已移除，資料已備份"
    else
        echo "用戶 $username 不存在"
    fi
}

list_users() {
    echo "=== 現有用戶列表 ==="
    for dir in ./data/*/; do
        if [ -d "$dir" ]; then
            username=$(basename "$dir")
            echo "- $username"
        fi
    done
}

case $1 in
    add)
        add_user "$2" "$3" "$4"
        ;;
    remove)
        remove_user "$2"
        ;;
    list)
        list_users
        ;;
    *)
        show_usage
        exit 1
        ;;
esac
EOF

chmod +x manage-users.sh
```

---

## 監控與維護

### 1. 容器管理腳本

創建完整的容器管理腳本：

```bash
cat > docker-manage.sh << 'EOF'
#!/bin/bash

# Docker VS Code Server 管理腳本 (Amazon Linux 2023 版本)

# 顏色定義
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

log_info() {
    echo -e "${BLUE}[INFO]${NC} $1"
}

log_success() {
    echo -e "${GREEN}[SUCCESS]${NC} $1"
}

log_warning() {
    echo -e "${YELLOW}[WARNING]${NC} $1"
}

log_error() {
    echo -e "${RED}[ERROR]${NC} $1"
}

show_usage() {
    echo "Docker VS Code Server 管理腳本 (Amazon Linux 2023)"
    echo
    echo "使用方法:"
    echo "  $0 start                  - 啟動所有容器"
    echo "  $0 stop                   - 停止所有容器"
    echo "  $0 restart                - 重啟所有容器"
    echo "  $0 status                 - 檢查容器狀態"
    echo "  $0 logs [用戶名]          - 查看日誌"
    echo "  $0 shell [用戶名]         - 進入容器 shell"
    echo "  $0 backup                 - 備份用戶資料"
    echo "  $0 update                 - 更新容器映像"
    echo "  $0 cleanup                - 清理未使用的資源"
    echo "  $0 health                 - 檢查容器健康狀態"
    echo "  $0 rebuild                - 重建容器映像"
}

start_containers() {
    log_info "啟動 VS Code Server 容器..."
    docker compose up -d
    if [ $? -eq 0 ]; then
        log_success "容器啟動完成！"
        show_status
    else
        log_error "容器啟動失敗！"
        return 1
    fi
}

stop_containers() {
    log_info "停止 VS Code Server 容器..."
    docker compose down
    if [ $? -eq 0 ]; then
        log_success "容器已停止！"
    else
        log_error "容器停止失敗！"
        return 1
    fi
}

restart_containers() {
    log_info "重啟 VS Code Server 容器..."
    docker compose restart
    if [ $? -eq 0 ]; then
        log_success "容器重啟完成！"
        show_status
    else
        log_error "容器重啟失敗！"
        return 1
    fi
}

show_status() {
    echo "=== VS Code Server 容器狀態 ==="
    echo
    docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"
    echo
    echo "=== 容器資源使用 ==="
    docker stats --no-stream --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}"
    echo
    echo "=== 存取資訊 ==="
    local public_ip=$(curl -s http://169.254.169.254/latest/meta-data/public-ipv4 2>/dev/null || echo 'localhost')
    
    # 檢查每個服務的端口
    for service in $(docker compose config --services); do
        local container_name=$(docker compose ps -q $service)
        if [ -n "$container_name" ]; then
            local port=$(docker port $container_name 8080/tcp 2>/dev/null | cut -d: -f2)
            if [ -n "$port" ]; then
                echo "$service 用戶: http://$public_ip:$port"
            fi
        fi
    done
}

show_logs() {
    local user=$1
    if [ -z "$user" ]; then
        log_info "顯示所有容器日誌..."
        docker compose logs -f --tail=50
    else
        log_info "顯示用戶 $user 的日誌..."
        docker compose logs -f --tail=50 "vscode-$user"
    fi
}

enter_shell() {
    local user=$1
    if [ -z "$user" ]; then
        log_error "請指定用戶名 (apple 或 orange)"
        return 1
    fi
    
    log_info "進入用戶 $user 的容器..."
    docker exec -it "vscode-$user" /bin/bash
}

backup_data() {
    local backup_dir="./backup/$(date +%Y%m%d_%H%M%S)"
    log_info "備份用戶資料到 $backup_dir..."
    
    mkdir -p "$backup_dir"
    cp -r ./data/* "$backup_dir/" 2>/dev/null || true
    tar -czf "${backup_dir}.tar.gz" -C ./backup "$(basename $backup_dir)"
    rm -rf "$backup_dir"
    
    log_success "備份完成: ${backup_dir}.tar.gz"
}

update_containers() {
    log_info "更新容器映像..."
    docker compose pull
    docker compose up -d --build
    log_success "容器更新完成！"
}

cleanup_resources() {
    log_info "清理未使用的 Docker 資源..."
    docker system prune -f
    docker volume prune -f
    docker network prune -f
    log_success "清理完成！"
}

check_health() {
    log_info "檢查容器健康狀態..."
    echo
    for service in $(docker compose config --services); do
        local container_name="vscode-$service"
        if docker ps --format "{{.Names}}" | grep -q "^$container_name$"; then
            local health=$(docker inspect --format='{{.State.Health.Status}}' $container_name 2>/dev/null || echo "no-healthcheck")
            case $health in
                "healthy")
                    log_success "$service: 健康 ✓"
                    ;;
                "unhealthy")
                    log_error "$service: 不健康 ✗"
                    ;;
                "starting")
                    log_warning "$service: 啟動中 ⏳"
                    ;;
                *)
                    log_warning "$service: 無健康檢查"
                    ;;
            esac
        else
            log_error "$service: 容器未運行"
        fi
    done
}

rebuild_containers() {
    log_info "重建容器映像..."
    docker compose down
    docker compose build --no-cache
    docker compose up -d
    log_success "容器重建完成！"
}

# 檢查 Docker Compose 是否可用
if ! command -v docker &> /dev/null; then
    log_error "Docker 未安裝或不在 PATH 中"
    exit 1
fi

if ! docker compose version &> /dev/null; then
    log_error "Docker Compose 未安裝或不可用"
    exit 1
fi

case $1 in
    start)
        start_containers
        ;;
    stop)
        stop_containers
        ;;
    restart)
        restart_containers
        ;;
    status)
        show_status
        ;;
    logs)
        show_logs "$2"
        ;;
    shell)
        enter_shell "$2"
        ;;
    backup)
        backup_data
        ;;
    update)
        update_containers
        ;;
    cleanup)
        cleanup_resources
        ;;
    health)
        check_health
        ;;
    rebuild)
        rebuild_containers
        ;;
    *)
        show_usage
        exit 1
        ;;
esac
EOF

chmod +x docker-manage.sh
```

### 2. 健康檢查

```bash
# 檢查容器健康狀態
docker-compose ps

# 檢查特定容器的健康狀態
docker inspect --format='{{.State.Health.Status}}' vscode-apple

# 查看健康檢查日誌
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' vscode-apple
```

### 3. 日誌管理

```bash
# 查看容器日誌
docker-compose logs -f vscode-apple

# 限制日誌行數
docker-compose logs --tail=100 vscode-apple

# 查看所有容器日誌
docker-compose logs -f
```

### 4. 資源監控

```bash
# 即時監控容器資源使用
docker stats

# 檢查磁碟使用
docker system df

# 檢查網路狀態
docker network ls
```

---

## 故障排除

### 1. 常見問題

#### 容器無法啟動

```bash
# 檢查容器狀態
docker-compose ps

# 查看容器日誌
docker-compose logs vscode-username

# 檢查 Docker 服務狀態
sudo systemctl status docker

# 重啟 Docker 服務
sudo systemctl restart docker
```

#### 無法存取 Web 介面

```bash
# 檢查端口是否開放
netstat -tlnp | grep 8080

# 檢查防火牆設定
sudo iptables -L

# 檢查安全群組設定
aws ec2 describe-security-groups --group-ids sg-xxxxxxxxx
```

#### 容器記憶體不足

```bash
# 檢查系統記憶體
free -h

# 檢查容器記憶體使用
docker stats --no-stream

# 設定記憶體限制
# 在 docker-compose.yml 中添加：
# deploy:
#   resources:
#     limits:
#       memory: 1G
```

### 2. 除錯指令

```bash
# 進入容器進行除錯
docker exec -it vscode-username /bin/bash

# 檢查容器內部網路
docker exec vscode-username netstat -tlnp

# 檢查容器內部程序
docker exec vscode-username ps aux

# 檢查容器檔案系統
docker exec vscode-username df -h
```

### 3. 效能調優

```bash
# 設定容器資源限制
cat >> docker-compose.yml << 'EOF'
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M
EOF

# 調整 Docker daemon 設定
sudo tee /etc/docker/daemon.json << 'EOF'
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

sudo systemctl restart docker
```

---

## 安全性考量

### 1. 網路安全

```bash
# 限制存取來源 IP
# 在安全群組中設定特定 IP 範圍
aws ec2 authorize-security-group-ingress \
    --group-id sg-xxxxxxxxx \
    --protocol tcp \
    --port 8080 \
    --cidr 192.168.1.0/24
```

### 2. 容器安全

```bash
# 使用非 root 用戶運行容器
# 在 Dockerfile 中：
USER coder

# 限制容器權限
# 在 docker-compose.yml 中：
security_opt:
  - no-new-privileges:true
read_only: true
tmpfs:
  - /tmp
  - /var/tmp
```

### 3. 資料加密

```bash
# 使用 HTTPS（需要 SSL 憑證）
# 在容器中配置 SSL
# 或使用反向代理（如 Nginx）
```

### 4. 定期更新

```bash
# 定期更新基礎映像
docker pull codercom/code-server:latest

# 重建容器
docker-compose build --no-cache
docker-compose up -d
```

---

## Amazon Q CLI 自動化部署

### 🤖 使用 Amazon Q CLI 快速部署

Amazon Q CLI 可以大幅簡化 Docker 容器化多用戶 VS Code Server 的部署過程。以下是一些實用的 prompt 技巧和自動化工作流程。

### 📝 Prompt 技巧與範例

#### 1. 基礎部署 Prompt

```
我需要在 AWS EC2 上部署一個 Docker 容器化的多用戶 VS Code Server 環境。請幫我：

1. 創建一個 t3.medium EC2 實例（Amazon Linux 2023）
2. 配置安全群組，開放端口 22, 8080, 8081
3. 安裝最新版本的 Docker 和 Docker Compose
4. 創建兩個用戶的 VS Code Server 容器：
   - apple 用戶：端口 8080，密碼 appleCode2024!
   - orange 用戶：端口 8081，密碼 orangeCode2024!
5. 提供完整的 Dockerfile 和 docker-compose.yml 配置
6. 包含以下開發環境：
   - Python 3.11 + pip + venv
   - Node.js 20 LTS + npm
   - Go 1.21
   - Rust 最新版
   - 常用開發工具
7. 包含容器管理腳本和健康檢查

請提供詳細的步驟和所有必要的配置檔案，確保相容 Amazon Linux 2023。
```

#### 2. 進階配置 Prompt

```
基於現有的 Docker 容器化 VS Code Server 環境，請幫我：

1. 添加健康檢查和自動重啟機制
2. 設定容器資源限制（CPU: 1核心, 記憶體: 1GB）
3. 配置日誌輪轉和監控
4. 創建用戶管理腳本，支援動態添加/移除用戶
5. 實作資料備份和恢復機制
6. 添加 SSL/HTTPS 支援
7. 設定防火牆和安全性最佳實務

請提供完整的配置和腳本。
```

#### 3. 故障排除 Prompt

```
我的 Docker 容器化 VS Code Server 遇到以下問題：

[描述具體問題，例如：]
- 容器無法啟動，顯示 "port already in use" 錯誤
- 無法透過瀏覽器存取 VS Code 介面
- 容器記憶體使用過高
- 用戶資料沒有正確持久化

請幫我診斷問題並提供解決方案，包括：
1. 問題診斷步驟
2. 具體的修復指令
3. 預防措施
4. 監控和警報設定
```

#### 4. 擴展功能 Prompt

```
請幫我擴展現有的 Docker VS Code Server 環境：

1. 添加 Nginx 反向代理，支援域名存取
2. 整合 Let's Encrypt 自動 SSL 憑證
3. 設定用戶認證系統（LDAP 或 OAuth）
4. 添加檔案共享功能
5. 整合 Git 伺服器
6. 設定自動備份到 S3
7. 添加監控儀表板（Grafana + Prometheus）

請提供完整的架構設計和實作步驟。
```

### 🚀 自動化部署工作流程

#### 完整部署 Prompt 範本

```
# Docker 容器化多用戶 VS Code Server 自動化部署 (Amazon Linux 2023)

請幫我創建一個完整的自動化部署解決方案，包含以下需求：

## 基礎設施需求
- AWS EC2 實例：t3.medium，Amazon Linux 2023 (最新 AMI)
- 安全群組：開放 SSH(22), HTTP(80), HTTPS(443), VS Code(8080-8090)
- 彈性 IP：固定公共 IP 地址
- EBS 儲存：30GB gp3，用於資料持久化和開發環境

## 容器化需求
- Docker Engine：最新穩定版 (24.0+)
- Docker Compose：v2.20+ (使用 plugin 版本)
- 基礎映像：codercom/code-server:4.21.1
- BuildKit：啟用以加速映像建立

## 開發環境需求
- Python 3.11 + pip + venv + 常用套件
- Node.js 20 LTS + npm + TypeScript + 前端框架 CLI
- Go 1.21 + 模組支援
- Rust 最新版 + Cargo
- Git + 全域配置
- 建置工具和實用程式

## 多用戶配置
- 支援動態用戶管理
- 每用戶獨立容器和資料目錄
- 自定義密碼和端口分配
- 資料持久化和備份
- 資源限制 (CPU: 2核心, 記憶體: 2GB)

## 管理功能
- 容器生命週期管理腳本 (使用 docker compose)
- 健康檢查和自動重啟
- 日誌管理和監控
- 資源使用監控
- 自動備份機制
- 用戶管理自動化

## 安全性
- 最小權限原則
- 容器安全配置 (no-new-privileges, cap-drop)
- 網路隔離
- 資料加密
- 存取控制

## 相容性要求
- 確保所有指令相容 Amazon Linux 2023
- 使用 dnf 套件管理器
- 支援最新的 Docker Compose 語法
- 包含錯誤處理和相容性檢查

請提供：
1. 完整的部署腳本 (相容 Amazon Linux 2023)
2. 所有配置檔案 (使用最新語法)
3. 管理和維護腳本
4. 故障排除指南
5. 最佳實務建議
6. 效能調優建議

格式要求：
- 提供可執行的 bash 腳本
- 包含詳細註解
- 錯誤處理和驗證
- 使用者友善的輸出訊息
- 支援 Amazon Linux 2023 特有功能
```

### 🔧 實用的 Q CLI 指令範例

#### 快速部署指令

```bash
# 使用 Q CLI 生成部署腳本
q chat "生成一個 Docker 容器化 VS Code Server 的完整部署腳本，包含 EC2 創建、Docker 安裝、容器配置和用戶管理功能"

# 生成故障排除指南
q chat "為 Docker 容器化 VS Code Server 創建一個完整的故障排除指南，包含常見問題和解決方案"

# 生成監控腳本
q chat "創建一個 Docker 容器監控腳本，包含資源使用、健康檢查和警報功能"
```

#### 互動式部署

```bash
# 啟動互動式部署會話
q chat -a

# 然後輸入：
"我要部署 Docker 容器化的多用戶 VS Code Server，請引導我完成整個過程，一步一步詢問我的需求並提供相應的配置"
```

### 📊 部署後驗證 Prompt

```
部署完成後，請幫我創建一個完整的驗證和測試腳本，包含：

1. 基礎設施驗證
   - EC2 實例狀態檢查
   - 安全群組規則驗證
   - 網路連通性測試

2. Docker 環境驗證
   - Docker 服務狀態
   - 容器運行狀態
   - 映像和網路配置

3. 應用程式驗證
   - VS Code Server 可存取性
   - 用戶認證測試
   - 檔案系統權限檢查

4. 效能測試
   - 資源使用監控
   - 回應時間測試
   - 並發用戶測試

5. 安全性檢查
   - 端口掃描
   - 權限審計
   - 日誌檢查

請提供自動化測試腳本和預期結果。
```

### 🎯 最佳實務 Prompt

```
基於 Docker 容器化多用戶 VS Code Server 的部署經驗，請提供：

1. 生產環境最佳實務
   - 高可用性配置
   - 負載平衡
   - 災難恢復

2. 安全性強化
   - 容器安全掃描
   - 網路分段
   - 存取控制

3. 效能優化
   - 資源調優
   - 快取策略
   - 監控指標

4. 維護和更新
   - 自動更新策略
   - 備份和恢復
   - 版本管理

5. 成本優化
   - 資源右調
   - 自動縮放
   - 成本監控

請提供具體的實作建議和配置範例。
```

### 💡 進階應用場景

#### 1. CI/CD 整合

```
請幫我設計一個 CI/CD 流水線，自動化 Docker 容器化 VS Code Server 的部署和更新：

1. 使用 GitHub Actions 或 AWS CodePipeline
2. 自動化測試和部署
3. 藍綠部署策略
4. 回滾機制
5. 通知和監控整合
```

#### 2. 多環境管理

```
請設計一個多環境（開發、測試、生產）的 Docker VS Code Server 管理方案：

1. 環境隔離策略
2. 配置管理
3. 資料同步
4. 存取控制
5. 監控和日誌分離
```

#### 3. 企業級部署

```
請設計一個企業級的 Docker 容器化 VS Code Server 解決方案：

1. 多租戶架構
2. 企業認證整合（AD/LDAP）
3. 資源配額管理
4. 審計和合規
5. 高可用性和災難恢復
```

### 🔄 持續改進 Prompt

```
基於現有的 Docker 容器化 VS Code Server 部署，請幫我：

1. 分析當前架構的優缺點
2. 識別改進機會
3. 提供升級建議
4. 設計遷移計劃
5. 評估風險和影響

請提供詳細的分析報告和行動計劃。
```

---

## 📚 總結

本指導手冊提供了完整的 Docker 容器化多用戶 VS Code Server 部署方案，針對 **Amazon Linux 2023** 進行了最佳化，包含：

### ✅ 主要特色

- **🐳 完全容器化**: 每個用戶運行在獨立的 Docker 容器中
- **🚀 現代化技術棧**: 
  - Amazon Linux 2023 (最新穩定版)
  - Docker 24.0+ with BuildKit
  - Docker Compose v2.20+ (Plugin 版本)
  - Code Server 4.21.1
- **🛠️ 豐富的開發環境**:
  - Python 3.11 + 虛擬環境
  - Node.js 20 LTS + 現代前端工具
  - Go 1.21 + 模組支援
  - Rust 最新版 + Cargo
- **📊 易於管理**: 使用 Docker Compose 統一管理所有服務
- **🔄 高度可擴展**: 支援動態添加和移除用戶
- **💾 資料持久化**: 用戶資料安全儲存在主機檔案系統
- **🔧 自動化管理**: 提供完整的管理和監控腳本
- **🛡️ 安全隔離**: 容器級別的安全隔離和資源限制
- **💪 效能優化**: 資源限制、健康檢查、自動重啟

### 🆕 Amazon Linux 2023 優勢

- **📦 現代套件管理**: 使用 `dnf` 替代 `yum`，更快的依賴解析
- **🔒 增強安全性**: 最新的安全補丁和強化配置
- **⚡ 效能提升**: 優化的核心和更好的容器支援
- **🔄 長期支援**: 5年的安全更新和維護
- **🐳 原生 Docker 支援**: 更好的容器化效能和穩定性

### 🚀 Amazon Q CLI 優勢

透過 Amazon Q CLI，您可以：

- **🗣️ 快速部署**: 使用自然語言描述需求，自動生成配置
- **🔍 智能故障排除**: 描述問題，獲得精確的解決方案
- **🔄 持續優化**: 根據使用情況不斷改進架構
- **📚 最佳實務**: 獲得業界最佳實務建議
- **🤖 自動化腳本**: 生成各種管理和維護腳本
- **🆕 技術更新**: 自動獲得最新技術棧的建議

### 📈 相比傳統方案的改進

#### vs SystemD 方式
- ✅ 更好的隔離性和安全性
- ✅ 統一的管理介面
- ✅ 自動重啟和健康檢查
- ✅ 資源使用監控
- ✅ 易於擴展和遷移

#### vs Amazon Linux 2
- ✅ 更現代的套件管理 (dnf vs yum)
- ✅ 更好的容器支援
- ✅ 增強的安全性
- ✅ 更長的支援週期
- ✅ 更好的效能

### 📈 後續發展

- **🔧 整合更多開發工具**: Docker, Kubernetes, Terraform
- **🏢 實作企業級認證**: LDAP, OAuth, SAML
- **📊 添加更多監控功能**: Prometheus, Grafana, ELK Stack
- **🌐 支援更多程式語言**: Java, .NET, PHP, Ruby
- **🚀 整合 CI/CD 流水線**: GitHub Actions, GitLab CI, Jenkins
- **☁️ 雲端原生功能**: EKS 部署, Fargate 支援

### 💡 最佳實務建議

1. **🔄 定期更新**: 保持基礎映像和套件的最新版本
2. **📊 監控資源**: 定期檢查容器資源使用情況
3. **💾 備份策略**: 實施自動化備份和災難恢復
4. **🛡️ 安全審計**: 定期檢查安全配置和存取權限
5. **📈 效能調優**: 根據使用情況調整資源限制
6. **📚 文件維護**: 保持部署文件和程序的更新

透過本指導手冊和 Amazon Q CLI 的結合使用，您可以在 Amazon Linux 2023 上快速建立一個強大、安全、可擴展的現代化多用戶開發環境！

---

*最後更新：2025年8月*  
*版本：2.0 (Amazon Linux 2023 版)*  
*技術棧：Amazon Linux 2023, Docker 24.0+, Docker Compose v2.20+, Code Server 4.21.1*
