关于设置 Claude Code 的完整演练 - 从 Docker 安装到 API 使用。这个开源项目允许你通过 Amazon Q Developer 账户使用 Claude AI,为官方 API 提供了一个经济实惠的替代方案。 --- ## 目录 - [安装 Docker](#安装-docker) - [Windows 10/11](#1-windows-1011) - [macOS](#2-macos-intel--apple-silicon) - [Ubuntu / Debian](#3-ubuntu--debian) - [CentOS / RHEL / Fedora](#4-centos--rhel--fedora) - [Arch Linux](#5-arch-linux) - [验证安装](#6-验证安装) - [配置](#配置) - [运行 Docker](#运行-docker) - [打开项目](#打开项目) - [添加你的第一个账户](#添加你的第一个账户) - [API 使用](#api-使用) - [故障排除](#故障排除) --- Claude Code 是一个开源项目,使用 Amazon Q Developer 账户提供 Claude API 访问。它非常适合想要将 Claude 功能集成到他们的应用程序中而无需支付官方 API 费用的开发者。 # 安装 Docker ## **1. Windows 10/11** ### **使用 Docker Desktop(推荐)** 1. 访问 Docker 官方下载页面: 2. 下载 **Docker Desktop for Windows**。 3. 运行安装程序: - 提示时启用 **WSL 2**。 - 如果需要,重新启动。 4. 启动 Docker Desktop → 确认它显示"Docker is running"。 **要求:** - Windows 10/11 64 位 - 启用 WSL 2 - 在 BIOS 中启用硬件虚拟化 --- ## **2. macOS (Intel & Apple Silicon)** ### **使用 Docker Desktop** 1. 下载适用于 macOS 的 Docker Desktop: 2. 选择正确的版本: - Intel Mac - Apple Silicon (M1/M2/M3/M4) 3. 打开 `.dmg` → 将 Docker 拖到应用程序。 4. 启动 Docker Desktop → 允许权限。 **要求:** - 推荐 macOS 12+ - 管理员权限 --- ## **3. Ubuntu / Debian** ### **安装 Docker Engine (仅 CLI)** ### **步骤 1 — 删除旧版本** ```bash sudo apt remove docker docker-engine docker.io containerd runc ``` ### **步骤 2 — 添加 Docker 官方仓库** ```bash sudo apt update sudo apt install ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \ https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \ | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null ``` ### **步骤 3 — 安装 Docker** ```bash sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin ``` ### **步骤 4 — (可选) 无需 sudo 运行 Docker** ```bash sudo usermod -aG docker $USER ``` > **注意:** 注销并重新登录以使其生效。 --- ## **4. CentOS / RHEL / Fedora** ### 安装 Docker Engine ### 删除旧版本 ```bash sudo yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine ``` ### 添加仓库 ```bash sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo ``` ### 安装 ```bash sudo yum install docker-ce docker-ce-cli containerd.io docker-compose-plugin sudo systemctl enable --now docker ``` --- ## **5. Arch Linux** ### **使用 pacman** ```bash sudo pacman -S docker docker-compose sudo systemctl enable --now docker ``` --- ## **6. 验证安装** 运行: ```bash docker --version docker compose version docker run hello-world ``` 你应该看到版本信息和确认 Docker 正在工作的消息。 --- # 配置在运行 Claude Code 之前,你需要创建一个配置文件。 ## **1. 创建环境文件** `.env` 文件存储你的配置设置。保持此文件安全,永远不要将其提交到版本控制！在项目根目录中创建一个 `.env` 文件: ## **2. 配置环境变量** 使用你喜欢的设置编辑 `.env` 文件: ```bash # API 密钥(逗号分隔,留空用于开发模式) # 当为空时,任何 API 密钥都可以工作(用于本地测试) API_KEYS="" # Web 控制台的管理员密码(请更改此密码!) ADMIN_PASSWORD="your-secure-password" # 自动禁用账户之前的最大错误计数 MAX_ERROR_COUNT=100 # HTTP 代理(可选,用于企业网络) HTTP_PROXY="" # 启用 Web 控制台(默认: true) ENABLE_CONSOLE="true" # 用于重定向的前端 URL FRONTEND_URL="http://localhost:3000" # 服务器端口 PORT=8000 # 数据库 URL(留空用于 SQLite - 大多数用户推荐) # PostgreSQL: DATABASE_URL="postgresql://user:password@host:5432/dbname" # MySQL: DATABASE_URL="mysql://user:password@host:3306/dbname" DATABASE_URL="" ``` ### 配置选项说明 | 变量 | 描述 | 默认值 | | ----------------- | ----------------------------------------------- | ------------------------- | | `API_KEYS` | 逗号分隔的允许的 API 密钥列表。留空以开放访问。 | `""` | | `ADMIN_PASSWORD` | 访问管理仪表板的密码 | `"admin"` | | `MAX_ERROR_COUNT` | 连续出现此数量错误后账户自动禁用 | `100` | | `HTTP_PROXY` | 出站请求的 HTTP 代理 URL | `""` | | `ENABLE_CONSOLE` | 启用/禁用 Web 控制台 | `"true"` | | `FRONTEND_URL` | 前端托管的 URL | `"http://localhost:3000"` | | `PORT` | 后端服务器端口 | `8000` | | `DATABASE_URL` | 数据库连接字符串(空 = SQLite) | `""` | --- # 运行 Docker ## **1. 克隆仓库** ## **2. 启动 Docker 容器** 导航到你的项目目录并运行: 这将: - 构建后端(FastAPI)和前端(Next.js)镜像 - 以分离模式启动两个容器 - 为 SQLite 数据库创建持久数据卷 **注意:** 首次运行可能需要几分钟来构建镜像。 ## **3. 检查容器状态** 验证你的容器正在运行: 你应该看到类似的输出: 8000/tcp claude-code-frontend-1 claude-code-frontend Up 2 minutes 0.0.0.0:3000->3000/tcp`} /> ## **4. 查看容器日志** 监控容器的输出: ```bash # 查看所有日志 docker compose logs -f # 仅查看后端日志 docker compose logs -f backend # 仅查看前端日志 docker compose logs -f frontend ``` ## **5. 停止容器** 需要停止容器时: ```bash docker compose down ``` ## **6. 重启容器** 进行更改后重启: ```bash docker compose restart ``` 或者重新构建并重启: ```bash docker compose up -d --build ``` ## **7. 更新到最新版本** ```bash git pull origin main docker compose up -d --build ``` --- # 打开项目 ## **1. 访问 Web 界面** 容器运行后,打开浏览器并导航到: | 界面 | URL | 描述 | | -------------- | -------------------------------------------------------------- | ------------------- | | **前端(推荐)** | [http://localhost:3000](http://localhost:3000) | 现代 Next.js 仪表板 | | **后端 API** | [http://localhost:8000](http://localhost:8000) | 基本界面和 API 端点 | | **健康检查** | [http://localhost:8000/healthz](http://localhost:8000/healthz) | 容器健康状态 | ## **2. 登录仪表板** 1. 打开 [http://localhost:3000](http://localhost:3000) 2. 输入你的管理员密码(默认: `admin`,或你在 `.env` 中设置的密码) 3. 点击 **Login** ## **3. 仪表板概述** 登录后,你将看到带有以下选项卡的主仪表板: | 选项卡 | 描述 | | -------------- | ---------------------------------------------- | | **Accounts** | 管理 Amazon Q 账户 - 添加、启用/禁用、刷新令牌 | | **URL Login** | 通过 URL 添加账户的替代方法 | | **Chat Test** | 内置聊天界面以测试你的 Claude API 设置 | | **API Tokens** | 创建和管理用于编程访问的 API 令牌 | | **Usage** | 监控令牌使用情况、查看分析和使用模式 | --- # 添加你的第一个账户 ## **方法 1: 设备授权(推荐)** 1. 转到 **Accounts** 选项卡 2. 点击 **Add Account** 3. 将出现设备授权代码 4. 点击授权链接或访问: 5. 输入代码并授权 6. 返回仪表板 - 你的账户将自动添加 ## **方法 2: URL 登录** 1. 转到 **URL Login** 选项卡 2. 按照说明获取登录 URL 3. 粘贴 URL 并提交 4. 你的账户将被添加 ## **验证账户状态** 添加账户后: - 检查状态是否显示 **Enabled** - 账户应显示有效的令牌到期时间 - 使用 **Chat Test** 选项卡验证连接是否正常 --- # API 使用配置账户后,你可以将 Claude Code 用作 Claude API 替代品。 ## **Python (使用 Anthropic SDK)** ```python from anthropic import Anthropic client = Anthropic( base_url="http://localhost:8000", api_key="your-api-key" # 如果 API_KEYS 为空,任何密钥都可以工作 ) message = client.messages.create( model="claude-sonnet-4", max_tokens=1024, messages=[ {"role": "user", "content": "你好! 你好吗?"} ] ) print(message.content[0].text) ``` ```python with client.messages.stream( model="claude-sonnet-4", max_tokens=1024, messages=[{"role": "user", "content": "写一首关于编码的短诗"}] ) as stream: for text in stream.text_stream: print(text, end="", flush=True) ``` ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ baseURL: 'http://localhost:8000', apiKey: 'your-api-key', }); const message = await client.messages.create({ model: 'claude-sonnet-4', max_tokens: 1024, messages: [{ role: 'user', content: '你好!' }], }); console.log(message.content[0].text); ``` ```bash curl -X POST http://localhost:8000/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: your-api-key" \ -d '{ "model": "claude-sonnet-4", "max_tokens": 1024, "messages": [ {"role": "user", "content": "你好!"} ] }' ``` ## **可用的 API 端点** | 端点 | 方法 | 描述 | | --------------------------- | ---- | --------------------------------- | | `/v1/messages` | POST | Claude Messages API(流式和非流式) | | `/v1/messages/count_tokens` | POST | 令牌计数端点 | | `/api/status` | GET | 系统状态检查 | | `/healthz` | GET | 健康检查端点 | --- # 故障排除 ## **常见问题** ### 容器无法启动 ```bash # 检查日志错误 docker compose logs # 确保端口未被占用 lsof -i :3000 lsof -i :8000 # 尝试重建 docker compose down docker compose up -d --build ``` ### 权限被拒绝错误 ```bash # 确保 Docker 可以访问项目文件 sudo chown -R $USER:$USER . # Linux: 将用户添加到 docker 组 sudo usermod -aG docker $USER # 然后注销并重新登录 ``` ### 数据库错误 ```bash # 重置数据库 rm -rf data/data.sqlite3 docker compose restart backend ``` ### 账户授权失败 1. 确保你的互联网连接正常 2. 检查设备授权 URL 是否可访问 3. 尝试使用 URL 登录方法 4. 检查后端日志: `docker compose logs -f backend` ### 前端无法连接到后端 1. 确保两个容器都在运行: `docker compose ps` 2. 检查后端是否健康: `curl http://localhost:8000/healthz` 3. 查看前端日志: `docker compose logs -f frontend` ### API 返回 401 Unauthorized 1. 检查 `.env` 中的 `API_KEYS` 设置 2. 如果设置了 `API_KEYS`,确保你使用的是允许的密钥之一 3. 如果为空,任何 API 密钥都应该可以工作 ### 高内存使用 ```bash # 检查容器资源使用情况 docker stats # 重启容器以释放内存 docker compose restart ``` ## **获取帮助** 如果你遇到此处未涵盖的问题: 1. 检查 GitHub Issues: 2. 搜索类似问题 3. 创建新问题并提供: - 你的操作系统 - Docker 版本 (`docker --version`) - 日志中的错误消息 - 重现步骤 --- # 高级配置 ## **使用外部数据库** ### PostgreSQL ```bash # .env DATABASE_URL="postgresql://username:password@localhost:5432/claude_code" ``` ### MySQL ```bash # .env DATABASE_URL="mysql://username:password@localhost:3306/claude_code" ``` ## **在反向代理后运行 (Nginx)** ```nginx server { listen 80; server_name your-domain.com; location / { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; } location /v1/ { proxy_pass http://localhost:8000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 300s; proxy_buffering off; # 对于流式重要 } location /api/ { proxy_pass http://localhost:8000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } ``` ## **自定义 Docker Compose 覆盖** 创建一个 `docker-compose.override.yml` 用于本地自定义: ```yaml services: backend: environment: - DEBUG=true ports: - '8080:8000' # 使用不同端口 frontend: ports: - '3001:3000' # 使用不同端口 ``` --- # 本地开发(无 Docker) 对于无 Docker 的开发: ## **后端** ```bash # 安装 Python 依赖项 pip install -e . # 运行并自动重新加载 uvicorn src.main:app --reload --host 0.0.0.0 --port 8000 ``` ## **前端** ```bash cd frontend # 安装依赖项 npm install # 运行开发服务器 npm run dev ``` --- # 快速参考 | 任务 | 命令 | | -------- | ------------------------------------------ | | 启动容器 | `docker compose up -d` | | 停止容器 | `docker compose down` | | 查看日志 | `docker compose logs -f` | | 重启 | `docker compose restart` | | 重建 | `docker compose up -d --build` | | 检查状态 | `docker compose ps` | | 更新 | `git pull && docker compose up -d --build` | | URL | 目的 | | ----------------------------- | ----------------- | | http://localhost:3000 | 前端仪表板 | | http://localhost:8000 | 后端 API | | http://localhost:8000/healthz | 健康检查 | | http://localhost:8000/docs | API 文档(Swagger) | --- ## 结论你现在拥有一个完全功能的本地运行的 Claude Code 安装。你可以: - 添加多个 Amazon Q 账户以实现负载均衡 - 将其用作官方 Claude API 的即插即用替代品 - 通过 Web 仪表板监控使用情况 - 通过添加更多后端容器进行水平扩展

开源 Docker FastAPI Next.js

### 有用的资源 **Docker Hub 仓库:** ### 关于作者 --- _本指南基于 Claude Code,一个开源项目。始终检查官方仓库以获取最新更新和文档。_

评论

发表评论