# 🚀 Coder VSCode Template 使用指南

## 📋 功能清單

- ✅ 每個使用者獨立 Workspace
- ✅ GitHub OIDC 登入認證
- ✅ GitHub Copilot 支援
- ✅ code-server 網頁版 VSCode
- ✅ 自動存檔
- ✅ 程式碼 & 設定持久化 (Volume)
- ✅ JetBrains IDE 支援（可選）
- ✅ 資源監控（CPU、RAM、Disk）

---

## 🎯 使用流程

### 第一步：啟動 Coder Server

你的 Docker 環境中已有 `vs-code-server.yml`，執行：

```bash
cd c:\Users\ckliu\Documents\docker_stack\vs-code-server
docker-compose -f vs-code-server.yml up -d
```

檢查 Coder 是否正常運行：
```bash
# 訪問
https://code.karylab.com
```

---

### 第二步：上傳 Template 到 Coder

#### 方法 A：使用 Coder CLI（推薦）

```bash
# 1. 安裝 Coder CLI（如果還沒安裝）
# 參考：https://coder.com/docs/install

# 2. 登入 Coder server
coder login https://code.karylab.com

# 3. 上傳 template
coder templates create \
  -d c:\Users\ckliu\Documents\docker_stack\vs-code-server\template \
  --name vscode
```

#### 方法 B：在 Coder UI 手動上傳

1. 進入 https://code.karylab.com/admin/templates
2. 點擊 "Create template"
3. 上傳整個 `template` 資料夾
4. 設定名稱為 "vscode"
5. 點擊 "Create"

---

### 第三步：使用者建立 Workspace

**以普通使用者身份：**

1. **用 GitHub 登入 Coder**
   ```
   進入 https://code.karylab.com
   → 點擊 "Sign in with GitHub"
   → 授權
   ```

2. **建立新 Workspace**
   ```
   Dashboard → "Create Workspace"
   → Select template: "vscode"
   → Workspace name: "my-first-workspace"
   → 點擊 "Create"
   ```

3. **等待初始化**
   ```
   狀態從 "Provisioning" → "Running"
   (首次約 30-60 秒)
   ```

4. **進入 VSCode**
   ```
   Workspace 啟動後 → 點擊 "code-server"
   → 進入網頁版 VSCode
   ```

---

## 💡 在 VSCode 中使用 GitHub Copilot

### 自動啟用（推薦）

因為你已用 GitHub 登入，Copilot 會自動使用你的 GitHub 身份：

1. 進入 VSCode → Extensions (Ctrl+Shift+X)
2. 搜尋 "GitHub Copilot"
3. 安裝官方 extension（Microsoft 出品）
4. 完成 → Copilot 自動認證

### 手動驗證

打開任何代碼文件，開始輸入：

```python
# 計算兩個數的和

# Copilot 應該會自動完成：
def add(a, b):
    return a + b
```

如果沒有自動完成建議，檢查：
- Extension 是否已安裝
- GitHub 登入是否有效

---

## 📁 你的檔案存放位置

每個 Workspace 的檔案存儲結構：

```
Docker Volume: coder-<user-id>-<workspace-name>
└── /home/coder/
    ├── .config/code-server/       ← VSCode 設定、extension 清單
    ├── .cache/                     ← Copilot 快取、編譯快取
    ├── .local/share/               ← VSCode 歷史、其他數據
    ├── .init_done                  ← 初始化標記（首次啟動時建立）
    └── (你的程式碼檔案)             ← 自動持久化
```

**重要：** 所有檔案都保存在 Docker volume 中，你登出或停止 Workspace 時 **不會遺失**。

---

## 🔄 常見操作

### 重啟 Workspace

```
Dashboard → 選擇你的 Workspace
→ 點擊"..."菜單
→ "Stop"（等 30 秒）
→ "Start"
```

### 刪除 Workspace

```
Dashboard → 選擇你的 Workspace
→ 點擊"..."菜單
→ "Delete"
⚠️ 警告：會永久刪除該 Workspace 的所有檔案！
```

### 查看 Workspace 日誌

```
Dashboard → 選擇你的 Workspace
→ 點擊"Logs"
（可看 startup_script 的執行結果，有錯誤時很有用）
```

### 自訂 Extensions

在 VSCode 的終端執行：

```bash
# 安裝 extension
code-server --install-extension ms-vscode.cpptools
code-server --install-extension ms-python.python
code-server --install-extension rust-lang.rust-analyzer

# 查看已安裝
code-server --list-extensions

# 卸載 extension
code-server --uninstall-extension <extension-id>
```

---

## ⚙️ 進階配置

### 如果要自動安裝特定 Extensions

編輯 `main.tf` 中的 `startup_script` 部分：

```hcl
startup_script = <<-EOT
  set -e

  # 初始化使用者目錄
  if [ ! -f ~/.init_done ]; then
    cp -rT /etc/skel ~
    touch ~/.init_done
  fi

  # 確保必要目錄存在
  mkdir -p ~/.config ~/.cache ~/.local/share

  # 自動安裝 extensions
  code-server --install-extension github.copilot
  code-server --install-extension ms-vscode.cpptools
  code-server --install-extension ms-python.python
EOT
```

然後重新上傳 template：

```bash
coder templates create \
  -d c:\Users\ckliu\Documents\docker_stack\vs-code-server\template \
  --name vscode
```

### 傳入 GitHub Token（可選）

如果要顯式指定 GitHub token，建立 Workspace 時傳入：

```bash
coder create my-workspace \
  --parameter github_token="ghp_xxxxxxxxxxxxxxxxxxxx"
```

---

## 🐛 常見問題

### Q1：Copilot 無法工作

**症狀：** 沒有自動完成建議，或顯示"Not Authorized"

**解決步驟：**
1. 檢查是否已安裝 GitHub Copilot extension
2. 在 VSCode 中按 `Ctrl+Shift+P` → 搜尋 "Copilot"
3. 選擇 "GitHub Copilot: Sign In"
4. 如果彈出授權窗口，點擊授權
5. 重新開啟代碼文件

### Q2：Workspace 啟動失敗

**症狀：** 狀態停留在 "Provisioning" 或顯示紅色錯誤

**診斷步驟：**
```
Dashboard → 選擇 Workspace
→ 點擊 "Logs" 分頁
→ 查看錯誤信息
```

常見原因：
- Docker 資源不足
- Coder server 無法連接到 provisioner
- startup_script 有語法錯誤

**解決方案：**
- 檢查 Docker 磁碟空間
- 重啟 Coder server：`docker-compose restart`
- 檢查 `main.tf` 語法

### Q3：無法保存檔案

**症狀：** 編輯後 Ctrl+S 無反應，或重啟後檔案遺失

**檢查步驟：**
1. VSCode 左下角應有自動存檔指示
2. Settings → 搜尋 "Auto Save" → 確認已啟用
3. 檢查磁碟空間是否充足
4. 查看 code-server 是否正常運行

### Q4：如何備份 Workspace 的檔案？

因為使用 Docker volume，備份方式：

```bash
# 1. 進入 Docker 容器
docker exec -it coder /bin/sh

# 2. 備份 volume（替換 <volume-name>）
docker run --rm -v <volume-name>:/data \
  -v /backup:/backup \
  alpine tar czf /backup/workspace-backup.tar.gz -C /data .

# 3. 檔案會存在 /backup 目錄
```

---

## 📊 資源監控

在 VSCode 右側 "Workspace" 菜單中，可看到：
- **CPU Usage** - 目前 CPU 使用率
- **RAM Usage** - 目前 RAM 使用量
- **Home Disk** - home 目錄磁碟使用量
- **CPU Usage (Host)** - 宿主機 CPU
- **Memory Usage (Host)** - 宿主機 RAM

如果 RAM 接近上限，可以：
- 關閉不必要的 extensions
- 重啟 Workspace
- 聯繫管理員增加資源

---

## 🔐 安全性

- ✅ 所有通訊都通過 HTTPS（由 Nginx 處理）
- ✅ GitHub OIDC 認證保護
- ✅ 每個使用者的 workspace 完全隔離
- ✅ 敏感信息（GitHub token）以環境變數形式傳遞，不儲存

---

## 📞 需要幫助？

1. **查看 Logs** → Dashboard → Workspace → Logs
2. **Coder 官方文檔** → https://coder.com/docs
3. **code-server 文檔** → https://github.com/coder/code-server
4. **聯繫管理員** → 提供 Workspace 名稱和錯誤信息

---

## 📝 版本資訊

- **Coder** v2.0+
- **code-server** module ~> 1.0
- **jetbrains** module ~> 1.1
- **Terraform** 0.13+

上次更新：2025-11-17