boos/BoosAPI
2
0
Fork 2
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
1 changed files with 161 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+161 -27
View File
@@ -16,9 +16,10 @@
<p align="center">
<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="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 align="center">
@@ -161,26 +162,24 @@ mkdir boosapi && cd boosapi
cat > docker-compose.yml << 'EOF'
services:
boosapi:
image: 1467078763/boosapi:latest
image: ghcr.io/boos/boosapi:latest
ports:
- "4000:4000"
volumes:
- ./data:/app/data
environment:
AUTH_TOKEN: ${AUTH_TOKEN:?AUTH_TOKEN is required}
PROXY_TOKEN: ${PROXY_TOKEN:?PROXY_TOKEN is required}
CHECKIN_CRON: "0 8 * * *"
BALANCE_REFRESH_CRON: "0 * * * *"
PORT: ${PORT:-4000}
DATA_DIR: /app/data
TZ: ${TZ:-Asia/Shanghai}
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: ${UPSTREAM_KEY}
BOOSAPI_SERVER__PORT: "4000"
restart: unless-stopped
EOF
# AUTH_TOKEN = 管理后台登录令牌
# PROXY_TOKEN = 下游客户端调用 /v1/* 的 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
```
@@ -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 |
| 前端框架 | React 18 + Vite |
| 语言 | TypeScript |
| 后端框架 | **Axum 0.8**（Rust） |
| 运行时 | **Tokio**（异步运行时） |
| 数据库 | **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 |
| 数据库 | SQLite / MySQL / PostgreSQL + Drizzle ORM |
| 数据可视化 | VChart |
| 定时任务 | node-cron |
| 容器化 | Docker + Docker Compose |
| 测试 | Vitest |
| 容器化 | Docker + Docker Compose + K3s |
| 构建工具 | Cargo（后端）/ npm（前端静态构建） |
> **运行时零 Node.js 依赖**，Node.js 仅用作前端构建工具。生产环境只需 Rust 编译后的单二进制文件。
---
## 🛠️ 本地开发
```bash
npm install
npm run db:migrate
npm run dev # 前后端热更新
```
### 后端（Rust）
```bash
npm run build # 构建前端 + 后端
npm run build:web # 仅构建前端
npm run build:server # 仅构建后端
npm test # 运行全部测试
npm run db:generate # 生成迁移文件
# 编译并运行
cargo run --release
# 仅检查编译
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
```
---