Skip to content

DEV_NOTES.md

Latest commit

 

History

History
218 lines (167 loc) · 6.51 KB

DEV_NOTES.md

File metadata and controls

218 lines (167 loc) · 6.51 KB
Raw

Mini-OpenClaw 开发踩坑记录

最后更新：2026-02-27

问题 1：前端无法绑定端口（EACCES: permission denied）

现象

Error: listen EACCES: permission denied :::5173
Error: listen EACCES: permission denied :::8080

根本原因

vite.config.ts 中使用了 IPv6 host 配置：host: "::"

Windows 上 IPv6 绑定权限比 IPv4 更严格，某些端口范围在 IPv6 下会直接被拒绝访问。

解决方案

将 vite.config.ts 中的 host 改为 IPv4：

// frontend/vite.config.ts
server: {
  host: "localhost",  // 或 "127.0.0.1"，不要用 "::"
  port: 5173,
}

问题 2：后端无法绑定端口（WinError 10013）

现象

ERROR: [WinError 10013] 以一种访问权限不允许的方式做了一个访问套接字的尝试。

某些端口（8000、8002、8888）报错，换其他端口（如 9000）可以。

根本原因 1：Hyper-V / WSL2 端口保留

Windows 的 Hyper-V 和 WSL2 会保留一系列端口段，普通进程无法绑定这些端口。

查看保留范围：

netsh int ipv4 show excludedportrange protocol=tcp

典型保留范围示例：

起始端口 结束端口 受影响的常用端口
7997 8096 8000, 8002, 8080
8819 8918 8888

根本原因 2：Clash Verge Tun 模式

Tun 模式会安装虚拟网卡并接管所有网络流量，导致非管理员权限的进程无法 bind() 任何 TCP socket。

解决方案

方案 A：换端口（推荐） 使用不在保留范围内的端口，如 9000：

# 启动命令
python -m uvicorn backend.app:app --reload --port 9000

方案 B：关闭 Clash Verge Tun 模式 关闭 Tun 模式（保留系统代理即可），然后重试启动。

方案 C：以管理员身份运行 管理员权限下可以绑定被 Hyper-V 保留的端口。

排查方法

# 检查是否有代理/VPN进程
Get-Process | Where-Object {$_.Name -match "clash|v2ray|proxifier|fiddler|wireguard|vpn"}

# 验证端口是否被占用（WinError 10013 ≠ 端口占用）
netstat -ano | findstr ":8000"

# 验证端口排除范围（Hyper-V会保留一段端口）
netsh int ipv4 show excludedportrange protocol=tcp

# 直接测试socket是否能绑定
python -c "import socket; s=socket.socket(); s.bind(('127.0.0.1',9000)); print('OK'); s.close()"

注意：WinError 10013 ≠ 端口被占用（10048 才是端口被占用）。10013 是权限拒绝。

问题 3：CORS 预检请求（OPTIONS）返回 400 / 405

现象

INFO: 127.0.0.1:xxxx - "OPTIONS /api/chat HTTP/1.1" 400 Bad Request
INFO: 127.0.0.1:xxxx - "OPTIONS /api/chat HTTP/1.1" 405 Method Not Allowed

前后端服务都起来了，但前端发请求时浏览器先发 CORS preflight，被后端拒绝。

根本原因

  1. Origin 不匹配：127.0.0.1:5173 和 localhost:5173 在 CORS 中被视为不同的 origin
  2. OPTIONS 方法未处理：FastAPI 的 CORSMiddleware 默认应该处理 OPTIONS，但有时需要显式配置

解决方案（三步）

步骤 1：vite.config.ts 使用 localhost

// frontend/vite.config.ts
server: {
  host: "localhost",  // 统一用 localhost
  port: 5173,
}

步骤 2：后端 CORS 白名单完整配置

# backend/app.py
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:3000",
        "http://localhost:5173",
        "http://127.0.0.1:5173",   # 兜底
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
    expose_headers=["*"],
)

步骤 3：显式添加 OPTIONS 处理器（兜底）

# backend/app.py
from starlette.responses import Response

@app.options("/api/chat")
@app.options("/api/sessions")
@app.options("/api/files")
def options_handler():
    return Response(status_code=200, headers={
        "Access-Control-Allow-Origin": "http://localhost:5173",
        "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
        "Access-Control-Allow-Headers": "*",
        "Access-Control-Allow-Credentials": "true",
    })

排查方法

  1. 浏览器 DevTools → Network → 找 OPTIONS 请求 → 看 Origin 请求头是什么
  2. 和后端 allow_origins 做精确对比（含协议、主机名、端口）
  3. 127.0.0.1 ≠ localhost，两者都要加，或统一用其中一个

环境与启动说明

启动命令

# ========================================
# 终端 1：启动后端（在项目根目录执行）
# ========================================
cd F:\vibe_coding_study\mini-openclaw
conda activate langgraph
python -m uvicorn backend.app:app --reload --port 9000

# 后端启动成功后显示：
# INFO: Uvicorn running on http://127.0.0.1:9000
# 访问 Swagger UI: http://localhost:9000/docs

# ========================================
# 终端 2：启动前端（在 frontend 目录执行）
# ========================================
cd F:\vibe_coding_study\mini-openclaw\frontend
npm run dev

# 前端启动成功后显示：
# ➜  Local:   http://localhost:5173/

访问地址

服务 地址 说明
前端应用 http://localhost:5173 主界面
后端 API http://localhost:9000 FastAPI 服务
Swagger 文档 http://localhost:9000/docs API 调试界面

端口配置汇总

服务 当前端口 说明
后端 FastAPI 9000 原定 8002，因 Windows Hyper-V 保留范围改用 9000
前端 Vite 5173 默认端口

关键配置文件

文件 作用 当前值
backend/app.py CORS 配置、API 端点 允许 localhost:5173 和 127.0.0.1:5173
frontend/vite.config.ts Vite server 配置 host: "localhost", port: 5173
frontend/src/api.ts 前端 API 地址 API_BASE = 'http://localhost:9000'
backend/.env LLM 配置 API Key、模型名等

修改端口时的检查清单

如果需要更换端口，请确保修改以下三处并保持一致：

  1. 后端启动命令：--port XXXX
  2. 前端 api.ts：API_BASE = 'http://localhost:XXXX'
  3. 后端 CORS 白名单：添加新端口的 origin（如果不是标准端口）

IDE Lint 误报说明

backend/app.py 中 Pyre2 报 Cannot find import of fastapi 等错误——这是 IDE 没有配置 conda langgraph 环境路径导致的，不影响实际运行。

解决方法：VSCode 中 Ctrl+Shift+P → Python: Select Interpreter → 选择 langgraph conda 环境。