# 使用網頁版 VS Code Server 來執行 Amazon Q CLI
## 📋 目錄
1. [概述](#概述)
2. [前置需求](#前置需求)
3. [系統相容性檢查](#系統相容性檢查)
4. [Amazon Q CLI 安裝](#amazon-q-cli-安裝)
5. [故障排除](#故障排除)
6. [最佳實務](#最佳實務)
---
## 概述
本指導手冊基於 [AWS 官方文件](https://docs.aws.amazon.com/zh_tw/amazonq/latest/qdeveloper-ug/command-line-installing-ssh-setup-autocomplete.html)，將教您如何在前面部署的 Docker 容器化多用戶 VS Code Server 環境中正確安裝、配置和使用 Amazon Q CLI。
### 🎯 學習目標
完成本指導手冊後，您將能夠：
- ✅ 檢查系統的 glibc 版本並選擇正確的 Amazon Q CLI 版本
- ✅ 在 Web 版 VS Code Server 中正確安裝 Amazon Q CLI
- ✅ 配置 Amazon Q CLI 的認證和設定
- ✅ 在瀏覽器中的 VS Code 終端機使用 Amazon Q CLI
- ✅ 掌握 Amazon Q CLI 的各種實用功能
- ✅ 解決常見的安裝和使用問題
### 🏗️ 架構概覽
```
┌─────────────────────────────────────────────────────────────┐
│ 瀏覽器 (您的電腦) │
│ ┌─────────────────────────────────────────────────────────┤
│ │ VS Code Server Web UI │
│ │ ┌──────────────────┐ ┌──────────────────┐ │
│ │ │ 檔案管理器 │ │ 整合終端機 │ │
│ │ │ │ │ │ │
│ │ │ - 專案檔案 │ │ $ q chat │ │
│ │ │ - 配置檔案 │ │ $ q explain │ │
│ │ │ - 腳本檔案 │ │ $ q transform │ │
│ │ └──────────────────┘ └──────────────────┘ │
│ └─────────────────────────────────────────────────────────┤
└─────────────────────────────────────────────────────────────┘
│
│ HTTPS
▼
┌─────────────────────────────────────────────────────────────┐
│ AWS EC2 Instance (Amazon Linux 2023) │
│ ┌─────────────────────────────────────────────────────────┤
│ │ Docker Container │
│ │ ┌──────────────────────────────────────────────────────┤
│ │ │ Code Server 4.21.1 │
│ │ │ ┌────────────────┐ ┌────────────────┐ │
│ │ │ │ Amazon Q CLI │ │ 開發環境 │ │
│ │ │ │ (正確版本) │ │ │ │
│ │ │ │ │ │ - Python 3.11│ │
│ │ │ │ - Standard │ │ - Node.js 20 │ │
│ │ │ │ - 或 Musl │ │ - Go 1.21 │ │
│ │ │ │ (依 glibc) │ │ - Rust │ │
│ │ │ └────────────────┘ └────────────────┘ │
│ │ └──────────────────────────────────────────────────────┤
│ └─────────────────────────────────────────────────────────┤
└─────────────────────────────────────────────────────────────┘
```
---
## 前置需求
### 🔧 必要條件
在開始之前，請確保您已經完成以下設定：
#### 1. VS Code Server 環境
- ✅ 已部署 Docker 容器化多用戶 VS Code Server
- ✅ 可以透過瀏覽器正常存取 VS Code Server
- ✅ 容器內已安裝基本開發工具和 `unzip` 指令
#### 2. AWS 帳戶與權限
- ✅ 有效的 AWS 帳戶
- ✅ Amazon Q Developer 的存取權限
- ✅ 適當的 IAM 權限設定
#### 3. 網路連線
- ✅ 穩定的網際網路連線
- ✅ 可以存取 AWS 服務的網路環境
### 📋 檢查清單
在開始安裝前，請執行以下檢查：
```bash
# 1. 檢查 VS Code Server 狀態
curl -I http://your-server-ip:8080
# 2. 登入到容器
docker exec -it vscode-apple /bin/bash
# 3. 檢查基本工具
python3 --version
node --version
curl --version
unzip -v
```
---
## 系統相容性檢查
> **📋 適用對象**：本章節主要提供給 **VS Code Server 系統管理員** 參考，用於在部署或維護容器環境時進行系統相容性評估。
根據 AWS 官方文件，Amazon Q CLI 的安裝需要先檢查系統相容性。
### 🔍 支援的系統
Amazon Q CLI 支援以下系統：
- **Fedora** 最新發行版本
- **Ubuntu** 最新發行版本
- **Amazon Linux 2023** 最新發行版本
- **架構**: 64 位元 x86_64 和 ARM aarch64
### 📊 檢查 glibc 版本
**這是最重要的步驟！** 您需要檢查系統的 glibc 版本來決定使用哪個版本的 Amazon Q CLI。
#### 1. 進入 VS Code Server
首先，在瀏覽器中開啟您的 VS Code Server：
```
http://your-server-ip:8080 (apple 用戶)
http://your-server-ip:8081 (orange 用戶)
```
#### 2. 開啟整合終端機
在 VS Code Server 中：
- 按下 `Ctrl + Shift + `` (反引號) 或
- 選擇選單 `Terminal` → `New Terminal`
#### 3. 檢查 glibc 版本
在終端機中執行：
```bash
# 檢查 glibc 版本
ldd --version
```
輸出範例：
```bash
# Amazon Linux 2023 (通常是 2.34+)
ldd (GNU libc) 2.34
Copyright (C) 2021 Free Software Foundation, Inc.
# 或者較舊的系統 (< 2.34)
ldd (GNU libc) 2.28
Copyright (C) 2018 Free Software Foundation, Inc.
```
#### 4. 版本判斷規則
根據檢查結果：
- **glibc 2.34 或更新版本** → 使用 **標準版本**
- **glibc 版本早於 2.34** → 使用 **Musl 版本**
#### 5. 檢查系統架構
```bash
# 檢查系統架構
uname -m
```
可能的輸出：
- `x86_64` → 使用 x86-64 版本
- `aarch64` → 使用 ARM 版本
### 📋 相容性檢查總結
執行以下腳本來自動檢查您的系統：
```bash
#!/bin/bash
echo "=== Amazon Q CLI 系統相容性檢查 ==="
echo
# 檢查作業系統
echo "作業系統資訊:"
cat /etc/os-release | grep -E "(NAME|VERSION)"
echo
# 檢查架構
ARCH=$(uname -m)
echo "系統架構: $ARCH"
# 檢查 glibc 版本
echo "glibc 版本檢查:"
GLIBC_VERSION=$(ldd --version | head -n1 | grep -o '[0-9]\+\.[0-9]\+')
echo "glibc 版本: $GLIBC_VERSION"
# 判斷需要的版本
if [ "$(echo "$GLIBC_VERSION >= 2.34" | bc -l 2>/dev/null)" = "1" ] || [ "$GLIBC_VERSION" \> "2.34" ] || [ "$GLIBC_VERSION" = "2.34" ]; then
VERSION_TYPE="標準版本"
FILE_SUFFIX=""
else
VERSION_TYPE="Musl 版本"
FILE_SUFFIX="-musl"
fi
echo
echo "=== 建議的 Amazon Q CLI 版本 ==="
echo "版本類型: $VERSION_TYPE"
if [ "$ARCH" = "x86_64" ]; then
echo "下載檔案: q-x86_64-linux${FILE_SUFFIX}.zip"
elif [ "$ARCH" = "aarch64" ]; then
echo "下載檔案: q-aarch64-linux${FILE_SUFFIX}.zip"
else
echo "警告: 不支援的架構 $ARCH"
fi
# 檢查必要工具
echo
echo "=== 必要工具檢查 ==="
for tool in curl unzip; do
if command -v $tool >/dev/null 2>&1; then
echo "✓ $tool: 已安裝"
else
echo "✗ $tool: 未安裝"
fi
done
```
將此腳本儲存為 `check-compatibility.sh` 並執行：
```bash
chmod +x check-compatibility.sh
./check-compatibility.sh
```
---
## Amazon Q CLI 安裝
> **👤 適用對象**：本章節適合 **Amazon Q CLI 用戶** 參考，提供完整的安裝和配置流程。
根據 AWS 官方文件，以下是正確的安裝步驟。
### 🔧 步驟 1：安裝必要工具
在開始下載和安裝 Amazon Q CLI 之前，需要確保系統已安裝必要的工具。
#### 檢查必要工具
```bash
# 檢查是否已安裝必要工具
for tool in curl unzip; do
if command -v $tool >/dev/null 2>&1; then
echo "✓ $tool: 已安裝"
else
echo "✗ $tool: 未安裝"
fi
done
```
#### 安裝解壓縮工具
根據您的作業系統選擇適當的安裝指令：
##### Amazon Linux 2023
```bash
# 更新套件列表
sudo dnf update -y
# 安裝 unzip 和 curl (通常已預安裝)
sudo dnf install -y unzip curl
# 驗證安裝
unzip -v
curl --version
```
##### Ubuntu / Debian
```bash
# 更新套件列表
sudo apt-get update
# 安裝 unzip 和 curl
sudo apt-get install -y unzip curl
# 驗證安裝
unzip -v
curl --version
```
##### CentOS / RHEL / Fedora
```bash
# CentOS/RHEL 7/8
sudo yum update -y
sudo yum install -y unzip curl
# 或者 Fedora/CentOS Stream/RHEL 9+
sudo dnf update -y
sudo dnf install -y unzip curl
# 驗證安裝
unzip -v
curl --version
```
##### Alpine Linux
```bash
# 更新套件索引
sudo apk update
# 安裝 unzip 和 curl
sudo apk add unzip curl
# 驗證安裝
unzip -v
curl --version
```
#### 在 Docker 容器中安裝
如果您在 Docker 容器中，可能需要以 root 權限安裝：
```bash
# 檢查當前用戶
whoami
# 如果是 root 用戶，直接安裝
apt-get update && apt-get install -y unzip curl
# 如果是一般用戶，使用 sudo
sudo apt-get update && sudo apt-get install -y unzip curl
```
### 📥 步驟 2：下載安裝檔案
根據前面的相容性檢查結果，選擇適當的下載指令：
#### 標準版本 (glibc 2.34+)
##### Linux x86-64
```bash
curl --proto '=https' --tlsv1.2 -sSf \
"https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip" \
-o "q.zip"
```
##### Linux ARM (aarch64)
```bash
curl --proto '=https' --tlsv1.2 -sSf \
"https://desktop-release.q.us-east-1.amazonaws.com/latest/q-aarch64-linux.zip" \
-o "q.zip"
```
#### Musl 版本 (適用於 glibc < 2.34)
##### Linux x86-64 搭配 musl
```bash
curl --proto '=https' --tlsv1.2 -sSf \
"https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux-musl.zip" \
-o "q.zip"
```
##### Linux ARM (aarch64) 搭配 musl
```bash
curl --proto '=https' --tlsv1.2 -sSf \
"https://desktop-release.q.us-east-1.amazonaws.com/latest/q-aarch64-linux-musl.zip" \
-o "q.zip"
```
### 🔧 步驟 3：安裝 Amazon Q CLI
按照 AWS 官方文件的步驟進行安裝：
#### 1. 解壓縮安裝程式
```bash
# 解壓縮下載的檔案
unzip q.zip
```
您應該會看到類似以下的輸出：
```bash
Archive: q.zip
creating: q/
inflating: q/install.sh
inflating: q/q
inflating: q/LICENSE
inflating: q/README.md
```
#### 2. 執行安裝程式
```bash
# 執行官方安裝腳本
./q/install.sh
```
安裝程式會啟動互動式設定流程，以下是完整的安裝過程：
##### 步驟 1：Shell 配置選擇
```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
? Do you want q to modify your shell config (you will have to manually do this otherwise)? ›
❯ Yes
No
```
**建議選擇 `Yes`**，讓安裝程式自動修改您的 shell 配置檔案。
##### 步驟 2：登入方式選擇
```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
? Select login method ›
Use for Free with Builder ID
❯ Use with Pro license
```
選擇適合您的登入方式：
- **Use for Free with Builder ID**: 免費版本，使用 AWS Builder ID
- **Use with Pro license**: 專業版本，使用企業 SSO 或 AWS 帳戶
##### 步驟 3：輸入 Start URL（如選擇 Pro license）
```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
? Enter Start URL › https://d-9911abacfd.awsapps.com/start
```
輸入您組織的 AWS SSO Start URL，格式通常為：
`https://your-org.awsapps.com/start`
**Enter Start URL ›** 提示時，請輸入您組織的完整 SSO URL。
##### 步驟 4：選擇 AWS 區域
```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9911abacfd.awsapps.com/start
? Enter Region › us-east-1
```
選擇適當的 AWS 區域，Amazon Q CLI 目前支援的區域：
- `us-east-1` (美國東部 - 維吉尼亞北部)
- `eu-central-1` (歐洲 - 法蘭克福)
**Enter Region ›** 提示時，請選擇上述支援的區域之一。
##### 步驟 5：瀏覽器認證
```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9911abacfd.awsapps.com/start
✔ Enter Region · us-east-1
Confirm the following code in the browser
Code: LSRC-XPGB
Open this URL: https://d-9911abacfd.awsapps.com/start/#/device?user_code=LSRC-XPGB
▰▰▰▰▰▰▱ Logging in...
```
**重要步驟**：
1. 複製顯示的 URL 到您本地電腦的瀏覽器
2. 在瀏覽器中輸入顯示的驗證碼（例如：`LSRC-XPGB`）
3. 完成 AWS SSO 登入流程
4. 等待認證完成
##### 步驟 6：安裝完成
```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9911abacfd.awsapps.com/start
✔ Enter Region · us-east-1
Confirm the following code in the browser
Code: LSRC-XPGB
Open this URL: https://d-9911abacfd.awsapps.com/start/#/device?user_code=LSRC-XPGB
Device authorized
Logged in successfully
```
當看到 `Device authorized` 和 `Logged in successfully` 訊息時，表示安裝和認證都已完成。
#### 3. 重新載入環境變數
由於安裝程式已自動修改 shell 配置，需要重新載入環境變數：
```bash
# 重新載入 shell 配置
source ~/.bashrc
# 或者重新開啟終端機
```
#### 4. 驗證安裝和認證
安裝完成後，執行 `q chat` 指令來驗證 Amazon Q CLI 是否成功安裝並可正常使用：
```bash
# 執行 q chat 指令驗證安裝
q chat
```
如果安裝和認證都成功，您將看到 Amazon Q CLI 的歡迎畫面：
```bash
coder@c0a265769ffc:~/workspace$ q chat
⢠⣶⣶⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣤⣶⣿⣿⣿⣶⣦⡀⠀
⠀⠀⠀⣾⡿⢻⣿⡆⠀⠀⠀⢀⣄⡄⢀⣠⣤⣤⡀⢀⣠⣤⣤⡀⠀⠀⢀⣠⣤⣤⣤⣄⠀⠀⢀⣤⣤⣤⣤⣤⣤⡀⠀⠀⣀⣤⣤⣤⣀⠀⠀⠀⢠⣤⡀⣀⣤⣤⣄⡀⠀⠀⠀⠀⠀⠀⢠⣿⣿⠋⠀⠀⠀⠙⣿⣿⡆
⠀⠀⣼⣿⠇⠀⣿⣿⡄⠀⠀⢸⣿⣿⠛⠉⠻⣿⣿⠛⠉⠛⣿⣿⠀⠀⠘⠛⠉⠉⠻⣿⣧⠀⠈⠛⠛⠛⣻⣿⡿⠀⢀⣾⣿⠛⠉⠻⣿⣷⡀⠀⢸⣿⡟⠛⠉⢻⣿⣷⠀⠀⠀⠀⠀⠀⣼⣿⡏⠀⠀⠀⠀⠀⢸⣿⣿
⠀⢰⣿⣿⣤⣤⣼⣿⣷⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⢀⣴⣶⣶⣶⣿⣿⠀⠀⠀⣠⣾⡿⠋⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⡇⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⢹⣿⣇⠀⠀⠀⠀⠀⢸⣿⡿
⢀⣿⣿⠋⠉⠉⠉⢻⣿⣇⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⣿⣿⡀⠀⣠⣿⣿⠀⢀⣴⣿⣋⣀⣀⣀⡀⠘⣿⣿⣄⣀⣠⣿⣿⠃⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⠈⢿⣿⣦⣀⣀⣀⣴⣿⡿⠃
⠚⠛⠋⠀⠀⠀⠀⠘⠛⠛⠀⠘⠛⠛⠀⠀⠀⠛⠛⠀⠀⠀⠛⠛⠀⠀⠙⠻⠿⠟⠋⠛⠛⠀⠘⠛⠛⠛⠛⠛⠛⠃⠀⠈⠛⠿⠿⠿⠛⠁⠀⠀⠘⠛⠃⠀⠀⠘⠛⠛⠀⠀⠀⠀⠀⠀⠀⠀⠙⠛⠿⢿⣿⣿⣋⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⠿⢿⡧
╭─────────────────────────────── Did you know? ────────────────────────────────╮
│ │
│ You can enable custom tools with MCP servers. Learn more with │
│ /help │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
/help all commands • ctrl + j new lines • ctrl + s fuzzy search
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🤖 You are chatting with claude-4-sonnet
>
```
當您看到上述的 Amazon Q 標誌和互動式聊天介面時，表示：
- ✅ **Amazon Q CLI 安裝成功**
- ✅ **認證配置正確**
- ✅ **可以正常使用 Amazon Q 服務**
- ✅ **準備開始與 AI 助手對話**
### 📝 驗證成功指標
如果您看到以下元素，表示安裝驗證成功：
1. **ASCII 藝術標誌**: Amazon Q 的視覺標誌
2. **提示訊息**: "Did you know?" 資訊框
3. **快捷鍵說明**: `/help all commands • ctrl + j new lines • ctrl + s fuzzy search`
4. **模型資訊**: `🤖 You are chatting with claude-4-sonnet`
5. **輸入提示**: `>` 符號等待您的輸入
### 🎯 開始使用
現在您可以開始與 Amazon Q 對話：
```bash
> 你好，Amazon Q！請介紹一下你的功能
> 如何在 Python 中讀取 CSV 檔案？
> 請解釋什麼是 Docker 容器
```
要退出聊天模式，可以使用 `Ctrl + C` 或輸入 `/quit`。
### 📝 安裝注意事項
#### 如果選擇 "Use for Free with Builder ID"
如果您在步驟2選擇了免費版本，安裝流程會略有不同：
```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use for Free with Builder ID
Confirm the following code in the browser
Code: ABCD-EFGH
Open this URL: https://signin.aws.amazon.com/oauth?response_type=device_code&client_id=...
▰▰▰▰▰▰▱ Logging in...
Device authorized
Logged in successfully
```
#### 瀏覽器認證步驟詳解
由於您在容器中運行 Amazon Q CLI，瀏覽器認證需要特別注意：
1. **複製 URL**: 從終端機複製完整的認證 URL
2. **本地瀏覽器**: 在您本地電腦（不是容器內）的瀏覽器中開啟 URL
3. **輸入驗證碼**: 在瀏覽器頁面中輸入終端機顯示的驗證碼
4. **完成登入**: 根據選擇的登入方式完成 AWS SSO 或 Builder ID 登入
5. **等待確認**: 回到終端機等待 "Device authorized" 訊息
#### 常見問題處理
##### 問題：驗證碼過期
```bash
Error: The device code has expired. Please try again.
```
**解決方案**: 重新執行安裝程式，並在驗證碼過期前完成瀏覽器認證。
##### 問題：無法開啟瀏覽器
```bash
Error: Unable to open browser automatically
```
**解決方案**: 手動複製 URL 到瀏覽器，這在容器環境中是正常的。
##### 問題：認證失敗
```bash
Error: Authentication failed
```
**解決方案**:
1. 檢查網路連線
2. 確認 Start URL 正確
3. 驗證 AWS SSO 權限
4. 重新執行安裝程式
---
## 故障排除
### 🔧 常見問題與解決方案
#### 1. 安裝問題
##### 問題：下載失敗
```bash
# 錯誤訊息
curl: (7) Failed to connect to desktop-release.q.us-east-1.amazonaws.com port 443: Connection refused
```
**解決方案**：
```bash
# 檢查網路連線
ping desktop-release.q.us-east-1.amazonaws.com
# 檢查防火牆設定
sudo iptables -L
# 使用替代方式下載
wget "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip"
```
##### 問題：glibc 版本不相容
```bash
# 錯誤訊息
./q: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found
```
**解決方案**：
```bash
# 重新檢查 glibc 版本
ldd --version
# 如果版本 < 2.34，使用 Musl 版本
curl --proto '=https' --tlsv1.2 -sSf \
"https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux-musl.zip" \
-o "q.zip"
# 重新安裝
unzip q.zip
./q/install.sh
```
##### 問題：權限不足
```bash
# 錯誤訊息
Permission denied: ~/.local/bin/q
```
**解決方案**：
```bash
# 檢查目錄權限
ls -la ~/.local/bin/
# 修復權限
chmod +x ~/.local/bin/q
# 或重新安裝到用戶目錄
mkdir -p ~/.local/bin
cp q/q ~/.local/bin/
chmod +x ~/.local/bin/q
```
#### 2. 認證問題
##### 問題：需要重新登入 Amazon Q CLI
當您遇到認證相關問題時，可以使用以下步驟重新登入：
**步驟 1：登出當前會話**
```bash
# 登出 Amazon Q CLI
q logout
```
輸出範例：
```bash
coder@c0a265769ffc:~/workspace$ q logout
You are now logged out
Run q login to log back in to Amazon Q
```
**步驟 2：重新登入流程**
執行登入指令並選擇登入方式：
```bash
# 重新登入 Amazon Q CLI
q login
```
**步驟 2-1：Shell 配置選擇**
```bash
coder@c0a265769ffc:~/workspace$ q login
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
? Select login method ›
Use for Free with Builder ID
❯ Use with Pro license
```
**步驟 2-2：輸入 Start URL**
```bash
coder@c0a265769ffc:~/workspace$ q login
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
? Enter Start URL › https://d-9099abacfd.awsapps.com/start
```
**步驟 2-3：選擇 AWS 區域**
```bash
coder@c0a265769ffc:~/workspace$ q login
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9099abacfd.awsapps.com/start
? Enter Region › us-east-1
```
**步驟 2-4：瀏覽器認證**
```bash
coder@c0a265769ffc:~/workspace$ q login
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9099abacfd.awsapps.com/start
✔ Enter Region · us-east-1
Confirm the following code in the browser
Code: LSRC-XPGB
Open this URL: https://d-9099abacfd.awsapps.com/start/#/device?user_code=LSRC-XPGB
▰▰▰▰▰▰▱ Logging in...
```
**步驟 2-5：完成認證**
```bash
coder@c0a265769ffc:~/workspace$ q login
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9099abacfd.awsapps.com/start
✔ Enter Region · us-east-1
Confirm the following code in the browser
Code: LSRC-XPGB
Open this URL: https://d-9099abacfd.awsapps.com/start/#/device?user_code=LSRC-XPGB
Device authorized
Logged in successfully
```
**重要提醒**：
- 在步驟 2-4 中，需要在本地電腦的瀏覽器中開啟顯示的 URL
- 輸入顯示的驗證碼（例如：LSRC-XPGB）
- 完成 AWS SSO 登入流程
- 等待 "Device authorized" 和 "Logged in successfully" 訊息
#### 3. 功能問題
##### 問題：指令無法執行
```bash
# 錯誤訊息
q: command not found
```
**解決方案**：
```bash
# 檢查 PATH 環境變數
echo $PATH
# 檢查安裝位置
ls -la ~/.local/bin/q
# 重新設定 PATH
export PATH="/home/coder/.local/bin:$PATH"
echo 'export PATH="/home/coder/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
### 🔍 除錯工具
#### 1. 詳細日誌
```bash
# 啟用詳細日誌
export Q_CLI_DEBUG=true
q chat "test message"
# 查看日誌檔案
tail -f ~/.aws/q/logs/q-cli.log
# 設定日誌等級
export Q_CLI_LOG_LEVEL=DEBUG
```
#### 2. 系統診斷腳本
```bash
#!/bin/bash
# q-cli-diagnostic.sh - Amazon Q CLI 診斷腳本
echo "=== Amazon Q CLI 診斷報告 ==="
echo "生成時間: $(date)"
echo
echo "=== 系統資訊 ==="
echo "作業系統: $(cat /etc/os-release | grep PRETTY_NAME | cut -d'"' -f2)"
echo "架構: $(uname -m)"
echo "glibc 版本: $(ldd --version | head -n1)"
echo
echo "=== Amazon Q CLI 狀態 ==="
if command -v q >/dev/null 2>&1; then
echo "✓ Amazon Q CLI: 已安裝"
echo "版本: $(q --version)"
echo "位置: $(which q)"
else
echo "✗ Amazon Q CLI: 未安裝或不在 PATH 中"
fi
echo
echo "=== 環境變數 ==="
echo "PATH: $PATH"
env | grep -E "(AWS|Q_CLI)" || echo "無相關環境變數"
echo
echo "=== 認證狀態 ==="
echo "請使用 'q login' 來檢查和設定認證狀態"
echo
echo "=== 網路連線測試 ==="
if ping -c 1 desktop-release.q.us-east-1.amazonaws.com >/dev/null 2>&1; then
echo "✓ 可以連接到 Amazon Q 服務"
else
echo "✗ 無法連接到 Amazon Q 服務"
fi
echo
echo "=== 檔案權限 ==="
if [ -f ~/.local/bin/q ]; then
ls -la ~/.local/bin/q
else
echo "Amazon Q CLI 執行檔不存在"
fi
if [ -d ~/.aws ]; then
echo "AWS 配置目錄權限:"
ls -la ~/.aws/
else
echo "AWS 配置目錄不存在"
fi
```
將此腳本儲存為 `q-cli-diagnostic.sh` 並執行：
```bash
chmod +x q-cli-diagnostic.sh
./q-cli-diagnostic.sh
```
---
## 最佳實務
### 🎯 使用建議
#### 1. 有效的提問技巧
##### 具體明確的問題
```bash
# ❌ 不好的問題
q chat "我的程式碼有問題"
# ✅ 好的問題
q chat "這個 Python 函數在處理大型列表時記憶體使用過高，如何優化？" --context slow_function.py
```
##### 提供充足的上下文
```bash
# ❌ 缺乏上下文
q chat "如何修復這個錯誤？"
# ✅ 提供完整上下文
q chat "在執行 Django 遷移時出現 'relation already exists' 錯誤，如何解決？" --context error.log
```
#### 2. 定期維護
```bash
# 檢查更新
q --version
# 清理快取
rm -rf ~/.aws/q/cache/
# 重新登入以更新認證
q logout && q login
```
#### 3. 安全性最佳實務
```bash
# 定期重新登入以更新憑證
q logout && q login
# 避免在程式碼中硬編碼憑證
q chat "如何安全地管理應用程式中的 API 金鑰？"
# 使用最小權限原則
# 在 IAM 中只授予必要的 Amazon Q 權限
```
### 📈 效率提升技巧
#### 1. 自動化工作流程
建立自動化腳本：
```bash
#!/bin/bash
# q-workflow.sh - 自動化程式碼審查工作流程
echo "開始自動化程式碼審查..."
# 審查所有 Python 檔案
for file in *.py; do
if [ -f "$file" ]; then
echo "審查 $file..."
q review "$file" > "review_$file.md"
fi
done
# 生成改進建議
q chat "基於這些審查報告，提供整體改進建議" --context review_*.md > improvement_suggestions.md
echo "工作流程完成！檢查 improvement_suggestions.md"
```
#### 2. VS Code Server 整合最佳實務
在 VS Code Server 中建立 `.vscode/settings.json`：
```json
{
"terminal.integrated.defaultProfile.linux": "bash",
"terminal.integrated.profiles.linux": {
"bash": {
"path": "/bin/bash",
"args": ["-l"],
"env": {
"Q_CLI_AUTO_PROMPT": "true"
}
}
},
"terminal.integrated.cwd": "${workspaceFolder}"
}
```
建立 `.vscode/tasks.json`：
```json
{
"version": "2.0.0",
"tasks": [
{
"label": "Q Review Current File",
"type": "shell",
"command": "q",
"args": ["review", "${file}"],
"group": "build",
"presentation": {
"echo": true,
"reveal": "always",
"focus": false,
"panel": "shared"
}
},
{
"label": "Q Explain Current File",
"type": "shell",
"command": "q",
"args": ["explain", "${file}"],
"group": "build"
}
]
}
```
---
## 總結
### 🎯 本指導手冊總結
本指導手冊基於 AWS 官方文件，提供了在 Docker 容器化 VS Code Server 環境中安裝和使用 Amazon Q CLI 的完整指南：
#### ✅ 核心成就
- **正確的版本選擇**: 根據 glibc 版本選擇標準版本或 Musl 版本
- **官方安裝流程**: 遵循 AWS 官方文件的安裝步驟
- **完整的配置指南**: 涵蓋多種認證方式的詳細設定
- **實用的整合技巧**: 在 Web 版 VS Code Server 中的最佳使用方式
#### ✅ 關鍵特色
- **系統相容性檢查**: 自動檢測系統並選擇正確版本
- **詳細的故障排除**: 涵蓋常見問題和解決方案
- **最佳實務指導**: 提升開發效率的實用技巧
### 🚀 使用優勢
#### 在 Web 版 VS Code Server 中使用 Amazon Q CLI 的優勢：
- **隨時隨地存取**: 透過瀏覽器即可使用完整的 AI 助手功能
- **統一開發環境**: 所有團隊成員使用相同的工具和配置
- **容器化隔離**: 每個用戶獨立的開發環境，避免衝突
- **雲端整合**: 與 AWS 服務的無縫整合
### 💡 持續改進建議
1. **定期更新**: 保持 Amazon Q CLI 的最新版本
2. **監控使用**: 定期檢查認證狀態和使用情況
3. **學習新功能**: 關注 Amazon Q CLI 的新功能和改進
4. **分享經驗**: 與團隊分享使用技巧和最佳實務
### 📚 參考資源
- [AWS 官方文件 - Amazon Q CLI 安裝](https://docs.aws.amazon.com/zh_tw/amazonq/latest/qdeveloper-ug/command-line-installing-ssh-setup-autocomplete.html)
- [Amazon Q Developer 使用者指南](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/)
- [AWS CLI 配置指南](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)
---
*最後更新：2025年8月3日*
*作者：James Chan*
*適用於：Amazon Linux 2023, Docker 24.0+, VS Code Server 4.21.1, Amazon Q CLI 最新版*
Sign in with Wallet
Connect another wallet