lis3456/droid2api

1# Docker 部署指南2 3## 本地 Docker 部署4 5### 1. 准备环境变量6 7创建 `.env` 文件（从 `.env.example` 复制）：8 9```bash10cp .env.example .env11```12 13编辑 `.env` 文件，配置认证方式和管理后台：14 15```env16# ===== API 认证配置（三选一） =====17# 方式1：使用固定API密钥（推荐生产环境）18FACTORY_API_KEY=your_factory_api_key_here19 20# 方式2：使用refresh token自动刷新21DROID_REFRESH_KEY=your_actual_refresh_token_here22 23# ===== 管理后台配置（强烈推荐） =====24ADMIN_ACCESS_KEY=your-secure-admin-password25 26# ===== 服务配置（可选） =====27PORT=300028NODE_ENV=production29```30 31**优先级：FACTORY_API_KEY > DROID_REFRESH_KEY > 客户端authorization**32 33**重要提示**：34- `ADMIN_ACCESS_KEY` 用于保护管理后台，请设置强密码35- `NODE_ENV=production` 启用文件日志到 `logs/` 目录36 37### 2. 使用 Docker Compose 启动38 39```bash40docker-compose up -d41```42 43查看日志：44 45```bash46docker-compose logs -f47```48 49停止服务：50 51```bash52docker-compose down53```54 55### 3. 使用原生 Docker 命令56 57**构建镜像：**58 59```bash60docker build -t droid2api:latest .61```62 63**运行容器：**64 65```bash66# 方式1：使用固定API密钥67docker run -d \68  --name droid2api \69  -p 3000:3000 \70  -e FACTORY_API_KEY="your_factory_api_key_here" \71  droid2api:latest72 73# 方式2：使用refresh token74docker run -d \75  --name droid2api \76  -p 3000:3000 \77  -e DROID_REFRESH_KEY="your_refresh_token_here" \78  droid2api:latest79```80 81**查看日志：**82 83```bash84docker logs -f droid2api85```86 87**停止容器：**88 89```bash90docker stop droid2api91docker rm droid2api92```93 94## 云平台部署95 96### Render.com 部署97 981. 在 Render 创建新的 Web Service992. 连接你的 GitHub 仓库1003. 配置：101   - **Environment**: Docker102   - **Branch**: docker-deploy103   - **Port**: 30001044. 添加环境变量（选择其一）：105   - `FACTORY_API_KEY`: 固定API密钥（推荐）106   - `DROID_REFRESH_KEY`: refresh token1075. 点击 "Create Web Service"108 109### Railway 部署110 1111. 在 Railway 创建新项目1122. 选择 "Deploy from GitHub repo"1133. 选择分支：docker-deploy1144. Railway 会自动检测 Dockerfile1155. 添加环境变量（选择其一）：116   - `FACTORY_API_KEY`: 固定API密钥（推荐）117   - `DROID_REFRESH_KEY`: refresh token1186. 部署完成后会自动分配域名119 120### Fly.io 部署121 1221. 安装 Fly CLI：123   ```bash124   curl -L https://fly.io/install.sh | sh125   ```126 1272. 登录：128   ```bash129   fly auth login130   ```131 1323. 初始化应用（在项目目录）：133   ```bash134   fly launch135   ```136 1374. 设置环境变量（选择其一）：138   ```bash139   # 使用固定API密钥（推荐）140   fly secrets set FACTORY_API_KEY="your_factory_api_key_here"141   142   # 或使用refresh token143   fly secrets set DROID_REFRESH_KEY="your_refresh_token_here"144   ```145 1465. 部署：147   ```bash148   fly deploy149   ```150 151### Google Cloud Run 部署152 1531. 构建并推送镜像：154   ```bash155   gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/droid2api156   ```157 1582. 部署到 Cloud Run：159   ```bash160   # 使用固定API密钥（推荐）161   gcloud run deploy droid2api \162     --image gcr.io/YOUR_PROJECT_ID/droid2api \163     --platform managed \164     --region us-central1 \165     --allow-unauthenticated \166     --set-env-vars FACTORY_API_KEY="your_factory_api_key_here" \167     --port 3000168   169   # 或使用refresh token170   gcloud run deploy droid2api \171     --image gcr.io/YOUR_PROJECT_ID/droid2api \172     --platform managed \173     --region us-central1 \174     --allow-unauthenticated \175     --set-env-vars DROID_REFRESH_KEY="your_refresh_token_here" \176     --port 3000177   ```178 179### AWS ECS 部署180 1811. 创建 ECR 仓库1822. 推送镜像到 ECR1833. 创建 ECS 任务定义1844. 配置环境变量（选择其一）：185   - `FACTORY_API_KEY`（推荐）186   - `DROID_REFRESH_KEY`1875. 创建 ECS 服务188 189## 持久化配置190 191### 密钥池数据持久化192 193密钥池数据存储在 `key_pool.json`，容器重启会丢失。**生产环境强烈推荐挂载数据卷**。194 195### Docker Compose 方式196 197修改 `docker-compose.yml`：198 199```yaml200services:201  droid2api:202    volumes:203      - key-pool-data:/app/key_pool.json      # 密钥池数据204      - logs-data:/app/logs                    # 日志目录205 206volumes:207  key-pool-data:208  logs-data:209```210 211### Docker 命令方式212 213```bash214# 创建数据卷215docker volume create droid2api-keypool216docker volume create droid2api-logs217 218# 使用固定API密钥219docker run -d \220  --name droid2api \221  -p 3000:3000 \222  -e FACTORY_API_KEY="your_factory_api_key_here" \223  -e ADMIN_ACCESS_KEY="your-admin-password" \224  -e NODE_ENV="production" \225  -v droid2api-keypool:/app/key_pool.json \226  -v droid2api-logs:/app/logs \227  droid2api:latest228 229# 或使用refresh token230docker run -d \231  --name droid2api \232  -p 3000:3000 \233  -e DROID_REFRESH_KEY="your_refresh_token_here" \234  -e ADMIN_ACCESS_KEY="your-admin-password" \235  -e NODE_ENV="production" \236  -v droid2api-keypool:/app/key_pool.json \237  -v droid2api-logs:/app/logs \238  droid2api:latest239```240 241## 健康检查242 243容器启动后，可以通过以下端点检查服务状态：244 245```bash246# 检查服务基本状态247curl http://localhost:3000/248 249# 获取可用模型列表250curl http://localhost:3000/v1/models251 252# 检查管理后台（需要ADMIN_ACCESS_KEY）253curl -H "x-admin-key: your-admin-key" http://localhost:3000/admin/stats254```255 256## 管理后台访问257 258### Web界面259 260浏览器访问 `http://localhost:3000/` 或 `http://your-domain.com/`261 262**功能列表**：263- 密钥池统计信息264- 添加/删除/测试密钥265- 批量导入密钥266- 导出密钥列表267- 配置轮询算法268 269### API接口270 271所有管理接口需要在请求头中添加 `x-admin-key`：272 273```bash274# 获取密钥池统计275curl -H "x-admin-key: your-admin-key" http://localhost:3000/admin/stats276 277# 批量测试所有密钥278curl -X POST -H "x-admin-key: your-admin-key" http://localhost:3000/admin/keys/test-all279 280# 导出所有active状态的密钥281curl -H "x-admin-key: your-admin-key" "http://localhost:3000/admin/keys/export?status=active"282```283 284## 环境变量说明285 286| 变量名 | 必需 | 优先级 | 说明 |287|--------|------|--------|------|288| `FACTORY_API_KEY` | 否 | 最高 | 固定API密钥，跳过自动刷新（推荐生产环境） |289| `DROID_REFRESH_KEY` | 否 | 次高 | Factory refresh token，用于自动刷新 API key |290| `ADMIN_ACCESS_KEY` | 强烈推荐 | - | 管理后台访问密钥，保护 `/admin/*` 接口 |291| `NODE_ENV` | 否 | - | 运行环境（development/production），默认 production |292| `PORT` | 否 | - | 服务端口，默认 3000 |293 294**重要提示**：295- `FACTORY_API_KEY` 和 `DROID_REFRESH_KEY` 至少配置一个296- **必须配置 `ADMIN_ACCESS_KEY`** 以保护管理后台安全297- `NODE_ENV=production` 时日志写入 `logs/` 目录，按天轮换298 299## 故障排查300 301### 容器无法启动302 303查看日志：304```bash305docker logs droid2api306```307 308常见问题：309- 缺少认证配置（`FACTORY_API_KEY` 或 `DROID_REFRESH_KEY`）310- API密钥或refresh token 无效或过期311- 端口 3000 已被占用312- `ADMIN_ACCESS_KEY` 未设置或使用默认值（需要更改）313 314### API 请求返回 401315 316**原因**：API密钥或refresh token 过期或无效317 318**解决**：3191. 如果使用 `FACTORY_API_KEY`：检查密钥是否有效3202. 如果使用 `DROID_REFRESH_KEY`：获取新的 refresh token3213. 更新环境变量3224. 重启容器323 324### 容器频繁重启325 326检查健康检查日志和应用日志，可能是：327- 内存不足328- API key 刷新失败329- 配置文件错误330 331## 安全建议332 3331. **不要将 `.env` 文件提交到 Git**3342. **使用 secrets 管理敏感信息**（如 GitHub Secrets、Docker Secrets）3353. **生产环境推荐使用 `FACTORY_API_KEY`**（更稳定，无需刷新）3364. **必须设置强 `ADMIN_ACCESS_KEY`** 保护管理后台3375. **定期更新 API 密钥和 refresh token**3386. **启用 HTTPS**（云平台通常自动提供）3397. **限制管理后台访问来源**（通过防火墙或云平台配置）3408. **定期备份 `key_pool.json`** 密钥池数据3419. **使用数据卷持久化** 密钥池和日志数据342 343## 性能优化344 345### 多阶段构建（可选）346 347```dockerfile348# 构建阶段349FROM node:24-alpine AS builder350WORKDIR /app351COPY package*.json ./352RUN npm ci353 354# 生产阶段355FROM node:24-alpine356WORKDIR /app357COPY --from=builder /app/node_modules ./node_modules358COPY . .359EXPOSE 3000360CMD ["node", "server.js"]361```362 363### 资源限制364 365在 docker-compose.yml 中添加：366 367```yaml368services:369  droid2api:370    deploy:371      resources:372        limits:373          cpus: '1'374          memory: 512M375        reservations:376          cpus: '0.5'377          memory: 256M378```379 380## 监控和日志381 382### 日志系统383 384droid2api 使用智能日志系统：385 386**生产模式（NODE_ENV=production）**：387- 控制台：简洁日志388- 文件：详细日志写入 `logs/droid2api_YYYY-MM-DD.log`389- 自动按天轮换390 391**开发模式（NODE_ENV=development）**：392- 控制台：详细日志393- 文件：不写入394 395### 查看日志396 397**Docker Compose**：398```bash399# 实时查看容器日志400docker-compose logs -f401 402# 查看最近100行403docker-compose logs --tail=100404 405# 查看文件日志（如果挂载了卷）406docker exec droid2api ls /app/logs407docker exec droid2api cat /app/logs/droid2api_2025-10-11.log408```409 410**Docker 命令**：411```bash412# 容器日志413docker logs -f droid2api414 415# 导出日志到文件416docker logs droid2api > droid2api.log 2>&1417 418# 访问容器内部日志文件419docker exec -it droid2api sh420cd logs421ls -lh422```423 424### 集成监控工具425 426可以集成：427- Prometheus + Grafana（指标监控）428- Datadog（全栈监控）429- New Relic（APM性能监控）430- Sentry（错误追踪）431- ELK Stack（日志聚合分析）432