ExaFree

简体中文

Exa API 代理与管理面板，支持多账号、用户级 API Key、Linux DO OAuth 登录/注册。

• 协议：MIT（见 LICENSE）
• 免责声明与使用限制：见 docs/DISCLAIMER.md
• 本项目基于gemini-business2api魔改而来，感谢大佬！

• Exa API 代理：/search、/answer、/contents、/findSimilar、/research/v1
• MCP 工具入口：/mcp（HTTP）
• 多账号轮询与失败切换
• 管理面板（账号、用户、策略、日志、监控、系统设置）
• 用户系统（会话登录、用户 API Key、角色/限流）
• 升级兑换码（批量生成、导入、导出、一次性使用）
• Linux DO OAuth2 登录/注册
• SQLite / PostgreSQL 持久化

docker pull ghcr.io/chengtx809/exafree:main
docker run --rm -p 7860:7860 -v ./data:/app/data ghcr.io/chengtx809/exafree:main

镜像支持 linux/amd64 与 linux/arm64。 Docker 镜像会在构建阶段自动生成管理面板前端资源，因此宿主机不需要额外安装 Node.js / npm。

访问：

• 管理面板：http://localhost:7860/#/login
• 健康检查：http://localhost:7860/health

默认管理员（首次启动自动创建）：

• 用户名：admin
• 密码：123456

建议首次登录后立即修改密码。

当前仅支持用户 API Key访问业务接口：

• 请求头：Authorization: Bearer <user_api_key>
• 不再支持管理面板配置“全局 API_KEY”直连调用

示例：

curl http://localhost:7860/search \
  -H "Authorization: Bearer your-user-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query":"latest linux do news","numResults":3}'

项目内置 MCP 服务，入口为：/mcp。
可通过 MCP 客户端调用工具（search、contents、findSimilar、answer、research）。

鉴权

• MCP 通过请求头 Authorization: Bearer <user_api_key> 进行鉴权。
• 未提供有效的 Bearer Token 时，MCP 请求将直接返回错误提示。

Codex 配置示例（推荐）

注意：Codex 的 MCP URL 必须使用带斜杠的 .../mcp/，否则可能因重定向丢失鉴权头。

# ~/.codex/config.toml 或 项目目录下 .codex/config.toml
[mcp_servers.exafree]
url = "http://localhost:7860/mcp/"

# 方式 A：直接写死 Header（不需要环境变量）
http_headers = { "Authorization" = "Bearer your-user-api-key" }

# 方式 B：通过环境变量注入（更安全）
# bearer_token_env_var = "EXAFREE_USER_KEY"

改完配置后需要重启 Codex 才会生效。

claude mcp add --transport http exa-pool http://localhost:7860/mcp

重启 Claude Code 以应用 MCP 的配置变更。

在管理员面板 系统设置 -> 基础 -> Linux DO OAuth 登录 中填写：

• linuxdo_oauth_enabled
• linuxdo_client_id
• linuxdo_client_secret
• linuxdo_authorize_url（默认 https://connect.linux.do/oauth2/authorize）
• linuxdo_token_url（默认 https://connect.linux.do/oauth2/token）
• linuxdo_userinfo_url（默认 https://connect.linux.do/api/user）
• linuxdo_redirect_uri（可选，留空自动推导）
• linuxdo_scope（默认 openid profile email）

回调地址填写规则：

• 若手动填写 linuxdo_redirect_uri：使用该值
• 若留空：自动使用 {base_url}/auth/linuxdo/callback
• base_url 为空时，运行时按当前服务地址推导

登录页会在可用时显示“使用 Linux DO OAuth 登录 / 注册登录”按钮。

参考文档：https://wiki.linux.do/Community/LinuxDoConnect

管理员可在“用户管理 -> 用户策略”控制：

• registration_enabled：总注册开关
• password_registration_enabled：账号密码注册开关
• linuxdo_oauth_registration_enabled：Linux DO OAuth 注册开关

说明：

• 关闭总开关后，所有注册方式都不可用
• 关闭密码注册后，/auth/register 会返回 403
• 关闭 OAuth 注册后，已有 OAuth 绑定用户仍可 OAuth 登录，新用户不可通过 OAuth 自动注册

• 设置 DATABASE_URL：使用 PostgreSQL
• 未设置 DATABASE_URL：默认 SQLite（data/data.db）

系统设置页支持：

• 一键导出数据库（下载 .db 文件）
• 一键导入数据库（上传并覆盖旧数据库）

对应接口：

• GET /api/admin/database/export
• POST /api/admin/database/import（multipart/form-data，字段名 file）

注意：导入覆盖不可逆，建议先导出备份。

说明：

• 启用管理面板时，需要 Node.js ^20.19.0 || >=22.12.0
• 本地前端构建产物输出到 frontend/dist
• 若设置 DISABLE_ADMIN_PANEL=1 仅运行 API，可跳过前端构建

git clone https://github.com/chengtx809/exafree.git
cd exafree
cp .env.example .env

# 前端
cd frontend
npm ci
npm run build
cd ..

# 后端
python -m venv .venv
. .venv/bin/activate   # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt
python main.py

如升级到新版后仓库根目录仍残留旧版 static/，那是历史构建产物，可在确认无用后手动删除；源码运行将不再读取该目录。

1. 登录页不显示 Linux DO OAuth 按钮
   原因：linuxdo_oauth_enabled 未开启，或 client_id/client_secret 等未配置完整。

2. OAuth 回调失败
   检查 Linux DO Connect 配置的回调地址是否与系统设置中的实际回调完全一致。

3. 导入数据库失败
   目前浏览器导入仅支持 SQLite .db 文件，且会覆盖当前库。

• 免责声明：docs/DISCLAIMER.md
• 支持文件类型：docs/SUPPORTED_FILE_TYPES.md