Skip to content

DEPLOY.md

Latest commit

 

History

History
375 lines (268 loc) · 9.53 KB

DEPLOY.md

File metadata and controls

375 lines (268 loc) · 9.53 KB

AskOnce 部署指南 / Deployment Guide

更新日期 / Updated: 2026-03-07 状态 / Status: 已测试通过 / Tested and Passed

目录 / Table of Contents

  1. 环境准备 / Environment Preparation
  2. 快速部署 / Quick Deployment
  3. 详细步骤 / Detailed Steps
  4. 验证测试 / Verification Tests
  5. 常见问题 / Common Issues
  6. 启动命令汇总 / Startup Commands Summary

1. 环境准备 / Environment Preparation

1.1 基础要求 / Basic Requirements

要求 / Requirement 版本 / Version 说明 / Description
Node.js >= 18.0.0 运行前端和后端 / Run frontend and backend
npm >= 9.0.0 包管理器 / Package manager
Git 任意版本 / Any version 代码版本控制 / Version control

1.2 检查环境 / Check Environment

# 检查 Node.js 版本 / Check Node.js version
node --version
# 输出示例 / Example output: v22.22.0

# 检查 npm 版本 / Check npm version
npm --version
# 输出示例 / Example output: 10.9.4

2. 快速部署 / Quick Deployment

2.1 一键部署脚本 / One-click Deployment Script

# 1. 克隆项目 / Clone project
git clone https://github.com/linuxhsj/askonce.git
cd askonce

# 2. 创建配置文件 / Create config file
cp .env.example .env
# 然后编辑 .env 填入你的 API Key / Then edit .env to add your API Key

# 3. 安装依赖并启动 / Install dependencies and start
cd frontend && npm install && cd ..
cd backend/node && npm install

# 4. 启动服务 / Start services
# 终端1: 后端 / Terminal 1: Backend
cd backend/node && npm run dev

# 终端2: 前端 / Terminal 2: Frontend
cd frontend && npm run dev

# 5. 访问 / Access
# 前端 / Frontend: http://localhost:3000
# 后端 / Backend: http://localhost:8000

3. 详细步骤 / Detailed Steps

3.1 克隆项目 / Clone Project

git clone https://github.com/linuxhsj/askonce.git
cd askonce

3.2 配置 API Key / Configure API Key

# 1. 复制环境变量模板 / Copy environment template
cp .env.example .env

# 2. 编辑配置文件 / Edit config file
nano .env
# 或 / or
vim .env

填入以下内容（至少选择一种 API）/ Fill in the following (at least one API required):

# DeepSeek (推荐，性价比高 / Recommended, cost-effective)
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx

# OpenAI (GPT 系列 / GPT series)
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

# Anthropic (Claude 系列 / Claude series)
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx

# OpenRouter (可访问多种模型 / Access multiple models)
OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxxxxxx

# 服务配置 / Service Configuration
PORT=8000
MAX_CONCURRENT=10
DEFAULT_TIMEOUT=60000

3.3 安装前端依赖 / Install Frontend Dependencies

cd frontend
npm install

3.4 安装后端依赖 / Install Backend Dependencies

cd ../backend/node
npm install

3.5 启动后端服务 / Start Backend Service

# 在终端1中执行 / Execute in Terminal 1
cd backend/node
npm run dev

成功启动后输出 / Output after successful startup:

╔═══════════════════════════════════════════════════════════╗
║   AskOnce API Server                                      ║
║   Server running at: http://localhost:8000                ║
║   WebSocket at: ws://localhost:8000/ws                   ║
╚═══════════════════════════════════════════════════════════╝

3.6 启动前端服务 / Start Frontend Service

# 在终端2中执行 / Execute in Terminal 2
cd frontend
npm run dev

成功启动后输出 / Output after successful startup:

VITE v5.x.x  ready in xxx ms

➜  Local:   http://localhost:3000/
➜  Network: use --host to expose

4. 验证测试 / Verification Tests

4.1 测试后端健康检查 / Test Backend Health Check

curl http://localhost:8000/api/health

预期输出 / Expected output:

{"status":"healthy","timestamp":"2026-03-07T12:00:00.000Z"}

4.2 测试模型列表 / Test Model List

curl http://localhost:8000/api/models

预期输出 / Expected output: 返回支持的模型列表 / Returns list of supported models

4.3 测试单模型查询 / Test Single Model Query

curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{"prompt": "你好", "model_ids": ["deepseek-v3"]}'

预期输出 / Expected output:

{
  "request_id": "req_xxxx",
  "status": "completed",
  "results": [{
    "model_id": "deepseek-v3",
    "status": "completed",
    "content": "你好，我是DeepSeek...",
    "tokens_used": 20,
    "duration": 1500
  }]
}

4.4 测试多模型查询 / Test Multi-model Query

curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{"prompt": "什么是AI？", "model_ids": ["deepseek-v3", "deepseek-r1"]}'

4.5 访问前端界面 / Access Frontend Interface

打开浏览器访问 / Open browser and visit: http://localhost:3000

5. 常见问题 / Common Issues

5.1 端口被占用 / Port Already in Use

问题 / Issue: 启动时提示端口被占用 / Port is occupied on startup

解决 / Solution:

# 查找占用端口的进程 / Find process using port
lsof -i :3000
lsof -i :8000

# 杀掉占用进程 / Kill the process
kill -9 <PID>

# 或者使用其他端口启动 / Or use another port
cd frontend && npm run dev -- --port 3001

5.2 API 认证失败 / API Authentication Failed

问题 / Issue: 返回 401 Authentication Fails 错误 / Returns 401 error

解决 / Solution:

  1. 检查 .env 文件中的 API Key 是否正确 / Check if API Key in .env is correct
  2. 确保 API Key 没有过期 / Ensure API Key hasn't expired
  3. 重新启动后端服务让配置生效 / Restart backend to apply configuration
# 重启后端 / Restart backend
pkill -f "tsx"
cd backend/node && npm run dev

5.3 前端无法连接后端 / Frontend Cannot Connect to Backend

问题 / Issue: 前端页面加载但无法发送请求 / Frontend loads but cannot send requests

解决 / Solution:

  1. 检查后端是否正常运行 / Check if backend is running: curl http://localhost:8000/api/health
  2. 检查 vite.config.ts 中的代理配置是否正确 / Check proxy configuration in vite.config.ts
  3. 清除浏览器缓存 / Clear browser cache

5.4 模块未找到 / Module Not Found

问题 / Issue: npm install 报错找不到模块 / npm install reports module not found

解决 / Solution:

# 清除缓存重新安装 / Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

6. 启动命令汇总 / Startup Commands Summary

6.1 日常启动 / Daily Startup

# ==========================================
# 终端1: 启动后端 / Terminal 1: Start Backend
# ==========================================
cd askonce/backend/node
npm run dev

# 后端地址 / Backend URL: http://localhost:8000

# ==========================================
# 终端2: 启动前端 / Terminal 2: Start Frontend
# ==========================================
cd askonce/frontend
npm run dev

# 前端地址 / Frontend URL: http://localhost:3000

6.2 Docker 部署 / Docker Deployment

# 1. 配置环境变量 / Configure environment variables
cp .env.example .env
nano .env  # 填入 API Key / Add API Key

# 2. 启动所有服务 / Start all services
docker-compose up -d

# 3. 访问 / Access
# 前端 / Frontend: http://localhost:3000
# 后端 / Backend: http://localhost:8000
# SearXNG: http://localhost:8888 (可选 / Optional)

6.3 停止服务 / Stop Services

# 停止所有服务 / Stop all services
pkill -f "tsx"
pkill -f "vite"

# 或在 Docker 中 / Or in Docker
docker-compose down

支持的模型 / Supported Models

DeepSeek (推荐 / Recommended)

模型 ID / Model ID 名称 / Name API Key
deepseek-v3 DeepSeek V3 DEEPSEEK_API_KEY
deepseek-r1 DeepSeek R1 DEEPSEEK_API_KEY

OpenAI

模型 ID / Model ID 名称 / Name API Key
gpt-4o GPT-4o OPENAI_API_KEY
o1 o1 OPENAI_API_KEY

Anthropic

模型 ID / Model ID 名称 / Name API Key
claude-sonnet-4 Claude Sonnet 4 ANTHROPIC_API_KEY
claude-opus-4 Claude Opus 4 ANTHROPIC_API_KEY

OpenRouter

模型 ID / Model ID 名称 / Name API Key
google/gemini-1.5-pro Gemini 1.5 Pro OPENROUTER_API_KEY
x-ai/grok-2 Grok 2 OPENROUTER_API_KEY
meta-llama/llama-3.1-70b-instruct Llama 3.1 70B OPENROUTER_API_KEY

相关文档 / Related Documents

文档版本 / Document Version: v1.1 创建日期 / Created: 2026-03-07 作者 / Author: SeekSage