Spaces:
Sleeping
Sleeping
| title: Notion API 轻量级客户端 | |
| emoji: 📝 | |
| colorFrom: indigo | |
| colorTo: blue | |
| sdk: docker | |
| app_port: 7860 | |
| # Notion API 轻量级客户端 (Hugging Face Space) | |
| 这个项目提供了一个轻量级的 Notion API 客户端，可以作为 Web 服务部署在 Hugging Face Spaces 上。它兼容 OpenAI API 格式，让你可以将 Notion AI 作为后端集成到各种应用中。 | |
| ## 🚀 在 Hugging Face Spaces 上部署 | |
| 1. **创建 Space**: 在 Hugging Face 上创建一个新的 Space。 | |
| 2. **选择 Docker SDK**: 在 "Choose an SDK" 步骤中，选择 "Docker"。 | |
| 3. **上传文件**: 将此项目的所有文件（包括 `Dockerfile`）上传到你的 Space Git 仓库中。 | |
| 4. **设置 Secrets**: 这是最重要的一步。你的 Notion 凭证和其他配置需要作为 Secrets 添加到 Space 中。进入你的 Space "Settings" 页面，找到 "Repository secrets" 部分，然后点击 "New secret" 添加以下变量： | |
| * **必需**: | |
| * `NOTION_COOKIE`: 你的 Notion Cookie。你可以通过浏览器开发者工具获取。 | |
| * **可选**: | |
| * `NOTION_SPACE_ID`: 你的 Notion Space ID。 | |
| * `NOTION_ACTIVE_USER_HEADER`: 你的 Notion 用户 ID。 | |
| * `PROXY_URL`: 如果你需要通过代理访问 Notion，请设置此项 (例如 `http://user:pass@host:port`)。 | |
| * `PROXY_AUTH_TOKEN`: 如果你的代理需要单独的认证令牌，请设置此项。 | |
| * `COOKIE_FILE`: 如果你使用文件管理多个 Cookie，请设置为文件名 (例如 `cookies.txt`)。请确保该文件也已上传到仓库中。 | |
| **注意**: `PORT` 环境变量由 Hugging Face 自动处理，你无需设置。 | |
| 5. **等待部署**: 添加完 Secrets 后，Hugging Face 会自动构建 Docker 镜像并部署你的应用。你可以在 "Logs" 标签页查看部署进度和应用日志。部署成功后，你的 API 端点即可使用。 | |
| ## 📖 API 使用说明 | |
| 服务启动后，你可以通过你的 Space URL 访问 API。 | |
| **基础 URL**: `https://<your-space-name>.hf.space` | |
| ### API 端点 | |
| - `GET /v1/models` - 获取可用模型列表 (主要是为了兼容 OpenAI 客户端) | |
| - `POST /v1/chat/completions` - 核心的聊天完成端点 | |
| - `GET /health` - 健康检查端点 | |
| ### 示例: 使用 cURL 调用 | |
| ```bash | |
| curl -X POST https://<your-space-name>.hf.space/v1/chat/completions \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "model": "openai-gpt-4.1", | |
| "messages": [ | |
| {"role": "user", "content": "你好，请介绍一下你自己"} | |
| ], | |
| "stream": true | |
| }' | |
| ``` | |
| *请将 `<your-space-name>` 替换为你的 Space 名称。* | |
| ## 🍪 Cookie 管理 | |
| 为了提高服务的稳定性，你可以提供多个 Notion Cookie。 | |
| ### 通过文件管理 Cookie | |
| 1. 在项目根目录创建一个 `cookies.txt` 或 `cookies.json` 文件。 | |
| 2. 将文件上传到你的 Space 仓库。 | |
| 3. 在 Space Secrets 中设置 `COOKIE_FILE` 为你的文件名 (例如 `cookies.txt`)。 | |
| 系统启动时会自动从该文件加载Cookie。 | |
| **`cookies.txt` 示例:** (每行一个Cookie) | |
| ``` | |
| cookie1_string_here | |
| cookie2_string_here | |
| ``` | |
| **`cookies.json` 示例:** | |
| ```json | |
| { | |
| "cookies": [ | |
| "cookie1_string_here", | |
| "cookie2_string_here" | |
| ] | |
| } | |
| ``` | |
| ### Cookie 轮询机制 | |
| 系统会自动轮询使用所有有效的Cookie。当一个Cookie失效时（例如返回401错误），会自动切换到下一个有效的Cookie，确保服务不中断。 | |
| --- | |
| ## 本地开发参考 | |
| 以下信息用于在本地计算机上运行和开发。 | |
| ### 依赖项 | |
| ```bash | |
| npm install | |
| ``` | |
| ### 环境变量 | |
| 创建 `.env` 文件，设置以下环境变量： | |
| ``` | |
| NOTION_COOKIE=your_notion_cookie_here | |
| NOTION_SPACE_ID=optional_space_id | |
| NOTION_ACTIVE_USER_HEADER=optional_user_id | |
| PROXY_URL=optional_proxy_url | |
| PROXY_AUTH_TOKEN=your_auth_token | |
| PORT=7860 | |
| ``` | |
| ### 启动服务 | |
| ```bash | |
| npm start | |
| ``` | |
| ### Cookie 管理命令行工具 | |
| 项目提供了一个命令行工具来方便地管理 `cookies.json` 文件。 | |
| ```bash | |
| # 运行命令行工具 | |
| npm run cookie | |
| # 支持的命令 | |
| help, list, add, validate, remove, save, load, exit | |
| ``` |