docker_stack/vs-code-server/template

🚀 Coder VSCode Template 使用指南

📋 功能清單

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

---

🎯 使用流程

第一步：啟動 Coder Server

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

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

檢查 Coder 是否正常運行：

# 訪問
https://code.karylab.com

---

第二步：上傳 Template 到 Coder

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

# 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 啟動後 → 在 Dashboard 中應看到 "code" 應用
   → 點擊進入網頁版 VSCode
   

---

💡 在 VSCode 中使用 GitHub Copilot

自動啟用（推薦）

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

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

手動驗證

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

# 計算兩個數的和

# 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 的終端執行：

# 安裝 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 部分：

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：

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

傳入 GitHub Token（可選）

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

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，備份方式：

# 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