docs: update README tech stack and dev guide for Rust backend

- Rewrote 技术栈 section (Axum/Tokio/SQLx/TokenRouter)
- Rewrote 本地开发 section (cargo run + npm build)
- Added 项目结构 section describing Rust backend layout
- Added 环境变量 reference (BOOSAPI_*__* naming)
- Updated Docker Compose examples for Rust config vars
- Removed all Node.js runtime/TypeScript refs from backend docs
This commit is contained in:
boos
2026-05-18 09:37:04 +08:00
parent 0eb7c32585
commit b89b71a95f
+161 -27
View File
@@ -16,9 +16,10 @@
<p align="center"> <p align="center">
<img alt="Rust" src="https://img.shields.io/badge/Rust-1.85%2B-000000?logo=rust&style=flat"> <img alt="Rust" src="https://img.shields.io/badge/Rust-1.85%2B-000000?logo=rust&style=flat">
<img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&style=flat"> <img alt="SQLx" src="https://img.shields.io/badge/SQLx-0.8-3E6E93?style=flat">
<img alt="License" src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat"> <img alt="License" src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat">
<img alt="React" src="https://img.shields.io/badge/React-19-61DAFB?logo=react&style=flat"> <img alt="React" src="https://img.shields.io/badge/React-19-61DAFB?logo=react&style=flat">
<img alt="Axum" src="https://img.shields.io/badge/Axum-0.8-3182F6?style=flat">
</p> </p>
<p align="center"> <p align="center">
@@ -161,26 +162,24 @@ mkdir boosapi && cd boosapi
cat > docker-compose.yml << 'EOF' cat > docker-compose.yml << 'EOF'
services: services:
boosapi: boosapi:
image: 1467078763/boosapi:latest image: ghcr.io/boos/boosapi:latest
ports: ports:
- "4000:4000" - "4000:4000"
volumes: volumes:
- ./data:/app/data - ./data:/app/data
environment: environment:
AUTH_TOKEN: ${AUTH_TOKEN:?AUTH_TOKEN is required} BOOSAPI_AUTH__AUTH_TOKEN: ${AUTH_TOKEN?required}
PROXY_TOKEN: ${PROXY_TOKEN:?PROXY_TOKEN is required} BOOSAPI_AUTH__PROXY_TOKEN: ${PROXY_TOKEN?required}
CHECKIN_CRON: "0 8 * * *" BOOSAPI_UPSTREAM_BASE: https://api.boos.lat/v1
BALANCE_REFRESH_CRON: "0 * * * *" BOOSAPI_UPSTREAM_KEY: ${UPSTREAM_KEY}
PORT: ${PORT:-4000} BOOSAPI_SERVER__PORT: "4000"
DATA_DIR: /app/data
TZ: ${TZ:-Asia/Shanghai}
restart: unless-stopped restart: unless-stopped
EOF EOF
# AUTH_TOKEN = 管理后台登录令牌 # AUTH_TOKEN = 管理后台登录令牌
# PROXY_TOKEN = 下游客户端调用 /v1/* 的 Token # PROXY_TOKEN = 下游客户端调用 /v1/* 的 Token
export AUTH_TOKEN=your-admin-token export AUTH_TOKEN=your-admin-token
export PROXY_TOKEN=your-proxy-sk-token export PROXY_TOKEN=sk-your-proxy-token
docker compose up -d docker compose up -d
``` ```
@@ -191,36 +190,171 @@ docker compose up -d
--- ---
## 📁 项目结构
```
.
├── Cargo.toml # Rust 项目定义
├── config.toml # 默认配置文件
├── Dockerfile # 多阶段构建
├── docker/
│ └── docker-compose.yml
├── src/
│ ├── main.rs # 入口
│ ├── lib.rs # 库入口
│ ├── config.rs # 配置加载(环境变量 + config.toml)
│ ├── error.rs # 统一错误处理
│ ├── db/ # 数据库模型与查询
│ ├── routes/
│ │ ├── mod.rs # 路由组装 + 静态文件 serve
│ │ ├── comfyui_agent.rs # ComfyUI 视频助手 SSE 聊天
│ │ ├── comfyui/ # ComfyUI 代理(prompt/history/view)
│ │ ├── proxy/ # OpenAI 兼容代理入口
│ │ ├── auth.rs # 用户注册/登录 JWT
│ │ ├── checkin.rs # 自动签到
│ │ └── ...
│ ├── proxy/ # 代理引擎核心
│ │ ├── conductor/ # Proxy Conductor(故障转移)
│ │ ├── token_router/ # Token 路由引擎
│ │ └── executors/ # 执行器(chat/image/embedding)
│ ├── transformers/ # 协议转换
│ │ ├── openai/ # OpenAI Compatible
│ │ ├── anthropic/ # Claude Messages
│ │ └── gemini/ # Gemini GenerateContent
│ └── services/ # 后台服务
│ ├── cron/ # 定时任务
│ ├── billing/ # 计费逻辑
│ └── notification/ # 通知推送
├── migrations/ # SQLite 迁移
├── src/web/ # 前端源码(React 19 + Vite)
│ ├── pages/
│ │ ├── ComfyUIAgent.tsx # 视频助手聊天界面
│ │ └── ...
│ └── components/
└── dist/web/ # 前端构建产物(由 Rust serve)
```
## 🔧 环境变量
所有配置通过环境变量覆盖,命名规则:`BOOSAPI_<SECTION>__<KEY>`(双下划线分隔层级):
```bash
# 服务
BOOSAPI_SERVER__HOST=0.0.0.0
BOOSAPI_SERVER__PORT=4000
BOOSAPI_SERVER__LOG_LEVEL=info
# 认证
BOOSAPI_AUTH__AUTH_TOKEN=your-admin-token
BOOSAPI_AUTH__PROXY_TOKEN=sk-your-proxy-token
BOOSAPI_AUTH__JWT_SECRET=your-jwt-secret
# 数据库
BOOSAPI_DB__URL=sqlite:data/boosapi.db?mode=rwc
# 上游 API(ComfyUI Agent 使用)
BOOSAPI_UPSTREAM_BASE=https://api.boos.lat/v1
BOOSAPI_UPSTREAM_KEY=sk-your-key
# 前端静态目录(默认 dist/web)
BOOSAPI_WEB_DIR=dist/web
```
## 🏗️ 技术栈 ## 🏗️ 技术栈
| 层 | 技术 | | 层 | 技术 |
|----|------| |----|------|
| 后端框架 | Fastify | | 后端框架 | **Axum 0.8**(Rust) |
| 前端框架 | React 18 + Vite | | 运行时 | **Tokio**(异步运行时) |
| 语言 | TypeScript | | 数据库 | **SQLite** + **SQLx**(编译期 SQL 检查) |
| 并行计算 | **Rayon**(CPU 密集任务) |
| 认证鉴权 | **JWT** + API Key 双模式 |
| 代理引擎 | 自定义 Token Router + Proxy Conductor |
| 协议转换 | OpenAI / Claude / Gemini 全兼容 |
| ComfyUI Agent | SSE 流式 + gpt-image-2 + TTS 自动生成 |
| 前端框架 | React 19 + Vite(仅构建工具) |
| 样式 | Tailwind CSS v4 | | 样式 | Tailwind CSS v4 |
| 数据库 | SQLite / MySQL / PostgreSQL + Drizzle ORM |
| 数据可视化 | VChart | | 数据可视化 | VChart |
| 定时任务 | node-cron | | 容器化 | Docker + Docker Compose + K3s |
| 容器化 | Docker + Docker Compose | | 构建工具 | Cargo(后端)/ npm(前端静态构建) |
| 测试 | Vitest |
> **运行时零 Node.js 依赖**,Node.js 仅用作前端构建工具。生产环境只需 Rust 编译后的单二进制文件。
--- ---
## 🛠️ 本地开发 ## 🛠️ 本地开发
```bash ### 后端(Rust)
npm install
npm run db:migrate
npm run dev # 前后端热更新
```
```bash ```bash
npm run build # 构建前端 + 后端 # 编译并运行
npm run build:web # 仅构建前端 cargo run --release
npm run build:server # 仅构建后端
npm test # 运行全部测试 # 仅检查编译
npm run db:generate # 生成迁移文件 cargo check
# 运行测试
cargo test
# 环境变量配置
export BOOSAPI_SERVER__HOST=0.0.0.0
export BOOSAPI_SERVER__PORT=4000
export BOOSAPI_AUTH__AUTH_TOKEN=your-admin-token
export BOOSAPI_AUTH__PROXY_TOKEN=sk-your-proxy-token
export BOOSAPI_UPSTREAM_BASE=https://api.boos.lat/v1
export BOOSAPI_UPSTREAM_KEY=sk-boos4721
```
### 前端(React SPA)
前端使用 Vite 构建,产物由 Rust 后端静态 serve:
```bash
# 安装依赖(首次)
npm install
# 开发模式(热更新,需要 Node.js)
cd src/web && npx vite --host 0.0.0.0
# 构建生产版本
npm run build
# 输出到 dist/web/,Rust 后端自动 serve
```
> 生产环境不需要 Node.js 进程。`npm run build` 后,Rust 后端直接 serve 静态文件。
> 前端 API 请求通过 Vite 代理(开发)或同域访问(生产)指向 `localhost:4000`。
### Docker 部署
```bash
# 构建
docker build -t boosapi .
# 运行
docker run -d \
-p 4000:4000 \
-e BOOSAPI_AUTH__AUTH_TOKEN=your-admin-token \
-e BOOSAPI_AUTH__PROXY_TOKEN=sk-your-proxy-token \
-v $(pwd)/data:/app/data \
boosapi
```
### Docker Compose
```yaml
services:
boosapi:
build: .
ports:
- "4000:4000"
volumes:
- ./data:/app/data
environment:
BOOSAPI_AUTH__AUTH_TOKEN: ${AUTH_TOKEN?required}
BOOSAPI_AUTH__PROXY_TOKEN: ${PROXY_TOKEN?required}
BOOSAPI_UPSTREAM_BASE: https://api.boos.lat/v1
BOOSAPI_UPSTREAM_KEY: sk-your-upstream-key
restart: unless-stopped
``` ```
--- ---