docs: 添加项目说明与生产部署文档
This commit is contained in:
dekun
@@ -0,0 +1,213 @@
|
||||
# openai_node
|
||||
|
||||
本地 **Ollama / OpenAI 兼容** 大模型中转网关：统一鉴权、多节点按模型调度、Web 管理面板与流量统计。
|
||||
|
||||
代码仓库：[https://git.bz121.com/dekun/openai_node.git](https://git.bz121.com/dekun/openai_node.git)
|
||||
|
||||
---
|
||||
|
||||
## 功能概览
|
||||
|
||||
| 模块 | 说明 |
|
||||
|------|------|
|
||||
| **OpenAI 兼容 API** | `POST /v1/chat/completions`，Bearer `sk-...` 鉴权，支持流式响应 |
|
||||
| **多节点调度** | 按请求体中的 `model` 转发到不同机器/端口（`nodes.json`） |
|
||||
| **Web 控制台** | 首页模型分布卡片、流量统计、系统设置、用户中心 |
|
||||
| **访问统计** | 记录客户端 IP、Token 用量、按节点汇总（SQLite） |
|
||||
| **健康检查** | 定时探测各节点 `/v1/models`，首页显示中文状态 |
|
||||
|
||||
---
|
||||
|
||||
## 架构示意
|
||||
|
||||
```
|
||||
客户端 / Cursor / 脚本
|
||||
│
|
||||
▼
|
||||
宝塔 Nginx（443/80）──反代──► VPS :8150（本网关）
|
||||
│ │
|
||||
│ ├─ 鉴权 / 统计 / Web
|
||||
│ │
|
||||
│ ┌────────────┼────────────┐
|
||||
│ ▼ ▼ ▼
|
||||
│ 127.0.0.1:3313 :3314 :3315 …（frp 映射）
|
||||
│ │ │ │
|
||||
│ PC-A Ollama PC-B Ollama PC-C Ollama
|
||||
```
|
||||
|
||||
- **对外只暴露一个域名**，反代到网关 **8150**。
|
||||
- 各家用/办公室电脑通过 **frp** 等内网穿透，把模型端口映射到 VPS 本机 `127.0.0.1:3313` 等。
|
||||
- 网关在 **系统设置** 中维护「端口 ↔ 模型」关系，无需为每台机器单独配公网域名。
|
||||
|
||||
---
|
||||
|
||||
## 环境要求
|
||||
|
||||
- Python **3.10+**
|
||||
- 上游服务：**Ollama**（或其它 OpenAI 兼容 HTTP API）
|
||||
- 生产建议：**PM2** 守护进程；**宝塔** 或 Nginx 做 HTTPS 反代
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 克隆仓库
|
||||
|
||||
```bash
|
||||
git clone https://git.bz121.com/dekun/openai_node.git
|
||||
cd openai_node
|
||||
```
|
||||
|
||||
### 2. 安装依赖
|
||||
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # Windows: .\venv\Scripts\Activate.ps1
|
||||
pip install -r requirements.txt -U
|
||||
```
|
||||
|
||||
### 3. 配置文件
|
||||
|
||||
```bash
|
||||
cp gateway.json.example gateway.json
|
||||
cp nodes.json.example nodes.json
|
||||
```
|
||||
|
||||
编辑 **`gateway.json`**：
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "你的强密码",
|
||||
"api_key": ""
|
||||
}
|
||||
```
|
||||
|
||||
`api_key` 留空时，首次启动会自动生成 `sk-...` 并写回文件。
|
||||
|
||||
编辑 **`nodes.json`**（示例为 3 台节点，主机默认 `127.0.0.1`，端口 `3313–3315`）：
|
||||
|
||||
- `models[].id` 必须与调用 API 时 JSON 里的 **`model` 字段完全一致**（Ollama 模型名）。
|
||||
- `models[].label` 为 Web 卡片上的显示名。
|
||||
|
||||
### 4. 启动
|
||||
|
||||
```bash
|
||||
export JWT_SECRET="请改为长随机字符串"
|
||||
python -m uvicorn main:app --host 0.0.0.0 --port 8150
|
||||
```
|
||||
|
||||
浏览器打开 `http://127.0.0.1:8150`：
|
||||
|
||||
| 路径 | 说明 |
|
||||
|------|------|
|
||||
| `/` | 首页：模型分布卡片 + 使用说明 |
|
||||
| `/login` | 管理员登录 |
|
||||
| `/settings` | 系统设置（节点/端口/模型，需登录） |
|
||||
| `/stats` | 流量统计、IP 列表、Token 账单 |
|
||||
| `/user` | 查看 / 复制 API Key |
|
||||
|
||||
---
|
||||
|
||||
## 调用示例
|
||||
|
||||
将 `https://你的域名` 换为实际地址（或 `http://IP:8150` 调试）：
|
||||
|
||||
```bash
|
||||
curl https://你的域名/v1/chat/completions \
|
||||
-H "Authorization: Bearer sk-xxxx" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "your-model-id-1",
|
||||
"messages": [{"role": "user", "content": "你好"}],
|
||||
"stream": true
|
||||
}'
|
||||
```
|
||||
|
||||
在 Cursor、OpenAI SDK 等客户端中：
|
||||
|
||||
- **Base URL**：`https://你的域名/v1`
|
||||
- **API Key**：`gateway.json` 中的 `api_key` 或用户中心页面复制
|
||||
|
||||
---
|
||||
|
||||
## 配置说明
|
||||
|
||||
### gateway.json
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `username` | Web 登录用户名 |
|
||||
| `password` | Web 登录密码（明文存储，请限制文件权限） |
|
||||
| `api_key` | OpenAI 兼容 API Key，可自动生成 |
|
||||
|
||||
### nodes.json
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `id` | 节点唯一 ID（系统自动生成亦可） |
|
||||
| `name` | 显示名称 |
|
||||
| `host` | 上游主机，frp 场景填 **`127.0.0.1`** |
|
||||
| `port` | 上游端口，如 **3313–3318** |
|
||||
| `enabled` | 是否启用 |
|
||||
| `max_concurrent` | 单节点最大并发请求数（建议 1） |
|
||||
| `models` | `{ "id": "模型ID", "label": "显示名" }` 列表 |
|
||||
|
||||
也可在 Web **系统设置** 中增删改，保存后写入 `nodes.json`。
|
||||
|
||||
### 环境变量
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `JWT_SECRET` | （弱默认值） | **生产必改**，Web 登录 JWT 签名 |
|
||||
| `GATEWAY_PORT` | `8150` | 监听端口 |
|
||||
| `GATEWAY_CONFIG` | `gateway.json` | 账号配置路径 |
|
||||
| `NODES_CONFIG` | `nodes.json` | 节点配置路径 |
|
||||
| `STATS_DB` | `gateway_stats.db` | 统计数据库路径 |
|
||||
| `UPSTREAM_URL` | `http://127.0.0.1:10434` | **未配置 nodes 时** 的单机上流回退地址 |
|
||||
| `APP_ROOT` | 空 | 反代子路径前缀，如 `/wg` |
|
||||
|
||||
---
|
||||
|
||||
## 节点状态（中文）
|
||||
|
||||
| 状态 | 含义 |
|
||||
|------|------|
|
||||
| 空闲 | 在线且可接受新请求 |
|
||||
| 忙碌 | 已达 `max_concurrent` |
|
||||
| 离线 | 健康检查未通过 |
|
||||
| 未启用 | 节点在设置中关闭 |
|
||||
| 异常 | 连接失败并带有错误信息 |
|
||||
|
||||
---
|
||||
|
||||
## 项目文件
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `main.py` | 网关主程序（API + Web 单文件） |
|
||||
| `gateway.json.example` | 账号配置示例 |
|
||||
| `nodes.json.example` | 多节点配置示例 |
|
||||
| `requirements.txt` | Python 依赖 |
|
||||
| `ecosystem.config.cjs` | PM2 配置 |
|
||||
| `DEPLOY.md` | **生产部署文档**（宝塔 + frp + PM2） |
|
||||
|
||||
---
|
||||
|
||||
## 安全提示
|
||||
|
||||
- 勿将 `gateway.json`、`nodes.json`、`gateway_stats.db` 提交到公开仓库。
|
||||
- 生产环境务必修改 **`JWT_SECRET`**，并为 `gateway.json` 设置严格文件权限（如 `chmod 600`）。
|
||||
- 统计与设置接口需 Web 登录；API 调用使用 `sk-` Key，请勿混用。
|
||||
|
||||
---
|
||||
|
||||
## 生产部署
|
||||
|
||||
详见 **[DEPLOY.md](./DEPLOY.md)**（VPS、宝塔反代 8150、frp 多机、PM2）。
|
||||
|
||||
---
|
||||
|
||||
## 许可证
|
||||
|
||||
私有仓库，按团队内部约定使用。
|
||||
Reference in New Issue
Block a user