opencode-build/fs-backend/docs/前端连接指南.md

前后端连接指南

前端配置方式

1. 环境变量配置（推荐）

前端项目使用 .env 文件配置后端地址：

# OpenCodeUI/.env
VITE_API_BASE_URL=http://localhost:8000

2. 修改位置

前端项目中的 API 地址配置文件：

• 文件路径: OpenCodeUI/src/constants/api.ts
• 配置项: API_BASE_URL

export const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://127.0.0.1:4096'

添加项目创建接口到前端

步骤 1: 创建 API 调用函数

在 OpenCodeUI/src/api/ 目录下创建 project.ts:

// OpenCodeUI/src/api/project.ts

import { getApiBaseUrl, getAuthHeader } from './http'

export interface ProjectCreateRequest {
  project_name: string
}

export interface ProjectCreateResponse {
  success: boolean
  message: string
  project_path: string
}

/**
 * 创建新项目
 * POST /fs/project/create
 */
export async function createProject(
  params: ProjectCreateRequest
): Promise<ProjectCreateResponse> {
  const baseUrl = getApiBaseUrl()
  const url = `${baseUrl}/fs/project/create`

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      ...getAuthHeader(),
    },
    body: JSON.stringify(params),
  })

  if (!response.ok) {
    const error = await response.json().catch(() => ({ detail: '请求失败' }))
    throw new Error(error.detail || response.statusText)
  }

  return response.json()
}

步骤 2: 在 React 组件中使用

// OpenCodeUI/src/components/ProjectCreate.tsx

import React, { useState } from 'react'
import { createProject } from '@/api/project'

export function ProjectCreate() {
  const [projectName, setProjectName] = useState('')
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState('')

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()
    setLoading(true)
    setError('')

    try {
      const result = await createProject({ project_name: projectName })
      alert(result.message)
      setProjectName('')
    } catch (err) {
      setError(err instanceof Error ? err.message : '创建失败')
    } finally {
      setLoading(false)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={projectName}
        onChange={(e) => setProjectName(e.target.value)}
        placeholder="输入项目名称"
      />
      <button type="submit" disabled={loading}>
        {loading ? '创建中...' : '创建项目'}
      </button>
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </form>
  )
}

本地开发联调

1. 启动后端服务

cd OpenCode-backend
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

2. 启动前端开发服务器

cd OpenCodeUI
# 确保 .env 文件中配置了正确的后端地址
echo "VITE_API_BASE_URL=http://localhost:8000" > .env.local
npm install
npm run dev

3. 跨域配置（如需要）

后端已配置 CORS，允许所有来源访问。如需限制，修改：

# OpenCode-backend/app/core/config.py
class Settings(BaseSettings):
    CORS_ORIGINS: List[str] = ["http://localhost:5173", "http://127.0.0.1:5173"]

API 接口列表

接口	方法	地址	描述
创建项目	POST	/fs/project/create	创建新项目目录
健康检查	GET	/	服务状态检查

请求示例

cURL

curl -X POST "http://localhost:8000/fs/project/create" \
  -H "Content-Type: application/json" \
  -d '{"project_name": "my_project"}'

成功响应

{
  "success": true,
  "message": "项目 'my_project' 创建成功",
  "project_path": "/root/workspace/my_project"
}

错误响应

{
  "detail": "项目名称仅允许包含中英文、数字、下划线、横杠"
}

安全说明

1. 路径安全: 后端已锁定所有文件操作在 /root/workspace 目录内
2. 输入校验: 项目名经过正则校验，禁止路径逃逸字符
3. CORS: 生产环境建议配置具体的允许来源