dz-mykolas/searxng-access

# 🔐 SearXNG 访问控制 基于 Token 的访问控制插件，适用于 [SearXNG](https://github.com/searxng/searxng) 支持 API token、权限、配额、浏览器会话以及撤销功能。 ## 🚀 快速开始 ### 1. 启动 ``` mkdir searxng-access && cd searxng-access curl -fsSL \ https://raw.githubusercontent.com/dz-mykolas/searxng-access/main/compose.example.yaml \ -o compose.yaml mkdir core-config docker compose up -d ``` 该镜像已内置 SearXNG，并在全新安装时自动启用访问插件。 示例默认使用 `latest` 标签。为了确保生产环境部署的稳定性和可预测性， 请创建一个本地 `.env` 文件并设置 `SEARXNG_ACCESS_VERSION=0.1.2`。 ### 2. 创建浏览器 token ``` docker compose exec core searxng-access token create \ --label browser --capability search --capability access ``` 打开你的 SearXNG URL 并粘贴生成的 token。该 token 仅显示一次。 ### 3. 创建 API token ``` docker compose exec core searxng-access token create \ --label ai-harness --capability search --limit 1000 --window 3600 ``` ``` curl \ -H 'Authorization: Bearer sxng_REPLACE_ME' \ 'https://search.example.com/search?q=searxng&format=json' ``` 当受限 token 的当前配额窗口耗尽时，将返回带有标准 `Retry-After` header 的 `429 Too Many Requests`。 ## 🌐 配置带自动 HTTPS 的 VPS 对于公网 VPS，请使用 Caddy 示例来代替基础的 Compose 文件。将你的域名 解析到该服务器，并放行入站端口 `80` 和 `443`，然后运行： ``` mkdir searxng-access && cd searxng-access curl -fsSL \ https://raw.githubusercontent.com/dz-mykolas/searxng-access/main/examples/caddy/compose.yaml \ -o compose.yaml curl -fsSL \ https://raw.githubusercontent.com/dz-mykolas/searxng-access/main/examples/caddy/Caddyfile \ -o Caddyfile printf '%s\n' \ 'SEARXNG_HOST=search.example.com' \ 'SEARXNG_ACCESS_VERSION=0.1.2' > .env mkdir core-config docker compose up -d ``` Caddy 会自动获取并续期 HTTPS 证书。仅由 Caddy 暴露主机 端口；SearXNG 仅能在 Compose 网络内部访问。 ## 🛠️ 开发 在 devcontainer 中打开此代码库，或者使用配备了 Python 3.11、`uv`、构建 工具以及 Dockerfile 中指定原生库的 Debian 环境。 ``` make setup make lint test test-integration make run ``` 然后打开 并使用： ``` development-token ``` API 示例： ``` curl \ -H 'Authorization: Bearer development-token' \ http://localhost:8888/config ``` | 路径 | 用途 | | --- | --- | | `.venv/` | 插件工具和单元测试 | | `.searxng/local/py3/` | 指定版本的 SearXNG 和集成测试 | ## 🔑 权限 | 权限 | 访问范围 | | --- | --- | | `search` | 搜索、自动补全、图片和网站图标 (favicons) | | `access` | 偏好设置、信息和浏览器账户路由 | | `admin` | 指标和详细的引擎错误信息 | | `*` | 所有已分类的权限 | 浏览器 token 通常需要 `search` + `access` 权限。仅用于搜索的 API 客户端只需要 `search` 权限。未知的路由在明确分类之前将拒绝访问（失败关闭）。 ## 🎛️ Token 管理 ``` # List tokens docker compose exec core searxng-access token list # 撤销 token 及其浏览器会话 docker compose exec core searxng-access token revoke TOKEN_ID # 查看聚合使用计数器 docker compose exec core searxng-access usage ``` ## ⚙️ 配置 | 变量 | 默认值 | 用途 | | --- | --- | --- | | `SEARXNG_ACCESS_DB` | 镜像内为 `/var/cache/searxng/access.db` | 数据库路径 | | `SEARXNG_ACCESS_SECURE_COOKIE` | `true` | 仅限 HTTPS 的浏览器 cookie | | `SEARXNG_ACCESS_SESSION_IDLE` | `28800` | 空闲超时时间（秒） | | `SEARXNG_ACCESS_SESSION_LIFETIME` | `604800` | 最大会话生命周期 | ## 🛡️ 安全概览 - 原始 token 和会话 ID 绝不存储——仅保存 SHA-256 哈希值。 - 浏览器 cookie 默认为 `HttpOnly`、`SameSite=Lax` 和 `Secure`。 - 撤销 token 同时会使通过该 token 创建的浏览器会话失效。 - 使用量计数器中绝不包含搜索查询内容。 - SQLite 中包含 token、会话、配额窗口和汇总使用量。 - 请勿将 `Authorization` 和 `X-API-Key` 的值保留在代理和调试日志中。 - 部署后，请确认缺失和无效 token 的 API 请求是否均返回 `401`。 ## 📦 容器镜像 版本标签会发布已通过测试的 `linux/amd64` 和 `linux/arm64` 镜像至： ``` ghcr.io/dz-mykolas/searxng-access:0.1.2 ghcr.io/dz-mykolas/searxng-access:latest ``` 发布工作流会运行单元测试和 SearXNG 集成测试，然后发布 SBOM 和来源证明。维护者必须首次将 GHCR 包公开一次， 以便 VPS 用户可以匿名拉取。 ## 📄 许可证 [GNU AGPL-3.0-or-later](LICENSE)

标签：API令牌, SearXNG, Streamlit, 插件, 访问控制, 请求拦截, 逆向工具, 限流配额