开发者指南 · 03

开发环境搭建

3.1 后端

bash

# 创建虚拟环境
python -m venv venv
venv\Scripts\activate          # Windows
source venv/bin/activate       # Linux/macOS

# 安装依赖
pip install -r requirements.txt

# 配置环境变量（也可以登录后在 Settings → General 配置 per-admin key）
cp .env.example .env
# 编辑 .env，至少配置 ANTHROPIC_API_KEY 或 OPENAI_API_KEY

# 生成注册码（首次部署，未运行过则需要）
python generate_keys.py

# 启动（开发模式，热重载）
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

API 文档：http://localhost:8000/docs（Swagger UI）。

提示：项目根目录提供跨平台启动器 python launcher.py [--dev]，自动检测旧实例、端口冲突、双进程管理，详见 §13。

3.2 前端

bash

cd frontend
npm install

npm run dev       # Vite dev server → http://localhost:3000（推荐）
npm run build     # 生产构建 → dist/
npm run preview   # 预览生产构建
npm run legacy    # 旧 Express server（从 dist/ 提供静态资源）

Vite 开发代理规则（vite.config.ts）：

路径	目标	说明
`/api/*`	`localhost:8000`	FastAPI 所有 API
`/s/*`	`localhost:8000`	Consumer 聊天页
`/wc/*`	`localhost:8000`	WeChat 中间页
`/media_resources/*`	`localhost:8000`	Logo/图标静态资源

SSE 请求自动设置 Accept: text/event-stream 并禁用代理缓冲。

Vite multi-entry：rollupOptions.input 同时声明 main 和 service-chat 两个入口，分别打包到 dist/index.html 和 dist/service-chat.html。

3.3 一键启动

bash

# Windows
start_local.bat
# Linux/macOS
./start_local.sh
# 都等价于 python launcher.py