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