内容
# Axon
版本：7.1.5
Axon 是一个自我托管的 RAG 堆栈，用于爬取、抓取、摄入、嵌入、搜索和查询索引内容。生产版本优先使用 Docker Compose：一台 Axon 服务器容器、Qdrant、Hugging Face TEI，配备 `Qwen/Qwen3-Embedding-0.6B`，以及用于重 JS 页面的 Chrome。
## 当前运行时与未来源管道
本 README 文档当前生产运行时。干净的管道统一目标在 [`docs/pipeline-unification/`](docs/pipeline-unification/README.md) 和 [GitHub 问题 #298](https://github.com/jmagar/axon/issues/298) 中跟踪。该目标将源获取/索引移动到 `axon <source>`，通过共享的 `SourceRequest` DTO 路由 CLI/MCP/REST，并删除旧的公共别名，而不是保留向后兼容性。
## 生产合约
支持的生产运行时：
- 仅限 Docker Compose。
- 仅限 Qdrant 用于向量存储。
- 仅限 Hugging Face TEI 用于嵌入。
- 生产嵌入模型为 `Qwen/Qwen3-Embedding-0.6B`。
- Gemini CLI 是默认的 LLM 合成路径；当配置为 `AXON_LLM_BACKEND=openai-compat` 时，支持 OpenAI 兼容的端点，如 llama.cpp。
- 网络搜索/研究使用自我托管的 SearXNG 实例（`AXON_SEARXNG_URL`）进行配置，否则默认为 Tavily（`TAVILY_API_KEY`）。
- 本地 NVIDIA RTX 4070 目标，配备 NVIDIA 容器工具包。
- CLI 和 MCP 在进程内运行所有操作；仅当需要 HTTP API 访问时，部署 `axon serve` 容器。
- 一个共享的配置中心：`~/.axon/.env`、`~/.axon/config.toml`、`~/.axon/jobs.db`、`~/.axon/output`、`~/.axon/logs`、`~/.axon/artifacts`、`~/.axon/screenshots` 和 `~/.axon/tei`。Qdrant 存储位于运行 Qdrant 的主机上；默认情况下，dookie 指向 tootie。
不支持的生产路径：
- systemd 部署 Axon 二进制文件。
- Postgres、Redis、RabbitMQ、AMQP 或外部工作器服务。
- OpenAI 兼容的首次运行 LLM 配置。手动配置 `AXON_LLM_BACKEND=openai-compat` 以使用 llama.cpp 或另一个 OpenAI 兼容的 `/v1/chat/completions` 端点。
- Neo4j 或图检索。
- 多个竞争的 `.env` 或 `config.toml` 位置。
## 安装
### Linux
前提条件：
- Linux x86_64。
- Docker 和 Docker Compose。
- NVIDIA 驱动程序、`nvidia-smi` 和 NVIDIA 容器工具包。
- Gemini CLI 已安装并已身份验证，除非使用配置的 OpenAI 兼容端点进行 LLM 合成。
- `curl`、`sha256sum` 和 `install`。
一键安装程序：
```bash
curl -fsSL https://raw.githubusercontent.com/jmagar/axon/main/install.sh | sh
```
安装程序验证发布校验和，将 `axon` 二进制文件安装到 `~/.local/bin`，然后将设置委托给 `axon setup`。
有用的安装程序控件：
```bash
AXON_INSTALL_DRY_RUN=1 ./install.sh
AXON_INSTALL_PREFIX=/opt/axon ./install.sh
AXON_VERSION=vX.Y.Z ./install.sh # 固定特定版本；默认为最新版本
AXON_INSTALL_SKIP_SETUP=1 ./install.sh
```
### Windows
前提条件：
- Windows x86_64（PowerShell 5.1+ 或 PowerShell Core）。
- 带有 WSL 2 后端（适用于完整堆栈）的 Docker Desktop。
- NVIDIA 驱动程序和 NVIDIA 容器工具包（用于 GPU 加速）。
- Gemini CLI 已安装并已身份验证，或配置了 OpenAI 兼容端点用于 LLM 合成。
一键安装程序（PowerShell）：
```powershell
irm https://raw.githubusercontent.com/jmagar/axon/main/install.ps1 | iex
```
安装程序验证发布校验和，将 `axon.exe` 安装到 `%USERPROFILE%\.local\bin`，将其添加到用户路径，然后将设置委托给 `axon setup`。
有用的安装程序控件：
```powershell
$env:AXON_INSTALL_DRY_RUN='1'; irm .../install.ps1 | iex
$env:AXON_INSTALL_PREFIX='C:\tools\axon'; irm .../install.ps1 | iex
$env:AXON_VERSION='vX.Y.Z'; irm .../install.ps1 | iex # 固定版本
$env:AXON_INSTALL_SKIP_SETUP='1'; irm .../install.ps1 | iex
```
Claude Code 插件安装：
```bash
claude plugin install <path-to-this-repo>
```
该插件不附带二进制文件。首先通过 `install.sh` 安装 `axon`，然后安装插件。其 `SessionStart` 钩子运行 `scripts/plugin-setup.sh`，该脚本将 `CLAUDE_PLUGIN_OPTION_*` 设置同步到进程环境变量，并委托给 `axon setup plugin-hook`。该子命令**仅为探测，不会部署**：它检查 `/readyz`，如果堆栈正常，则静默退出，如果堆栈不正常，则打印一行 `run /axon-deploy` 建议。当堆栈不正常时，`ConfigChange` 运行相同的脚本，因此更新的插件设置立即生效。配置是通过 `/axon-deploy` 斜杠命令（或 `axon setup` / `axon compose up`）进行的。不会创建 systemd 单元。
## 设置流程
`axon setup` 是便捷的启动路径。它是幂等的，可以安全地重新运行。它：
1. 创建或刷新 `~/.axon`。
2. 创建或保留 `~/.axon/config.toml`。
3. 创建或保留 `~/.axon/.env`，仅填充缺失的运行时值并保留机密。
4. 在 `~/.axon/compose` 下写入 Docker Compose 资产。
5. 在请求时检查 Docker、Docker Compose、`nvidia-smi`、Gemini CLI 身份验证和 OAuth 配置。
6. 拉取并启动 Compose 堆栈。
7. 等待 Qdrant、TEI、Chrome 和 Axon 服务器的健康状态。
聚焦命令：
```bash
axon setup # init + compose up + preflight
axon setup init # create ~/.axon, config.toml, .env, and compose assets
axon preflight # check prerequisites, auth config, and service readiness
axon compose up # pull/start services, then follow logs until Ctrl-C
axon compose down # stop services
axon compose restart # restart services
axon compose rebuild # rebuild the Axon image and start services
axon smoke # TEI prewarm + crawl/ask proof
axon setup plugin-hook # probe-only SessionStart path (never deploys; advises /axon-deploy when down)
axon setup targets # list SSH aliases discovered from ~/.ssh/config (informational)
```
对于本地 bearer-token 操作，不需要手动环境值。`setup init` 默认设置为环回 MCP HTTP，写入 `AXON_AUTH_MODE=bearer`，并生成 `AXON_HTTP_TOKEN`。可选功能需要凭证：默认 LLM 功能下的 Gemini 身份验证、`AXON_LLM_BACKEND=openai-compat` 加 `AXON_OPENAI_BASE_URL` 和 `AXON_SYNTHESIS_OPENAI_MODEL` 用于 OpenAI 兼容的合成、`TAVILY_API_KEY` 用于搜索/研究、`GITHUB_TOKEN` 用于更高速率的 GitHub 摄入，以及 `REDDIT_CLIENT_ID` 加 `REDDIT_CLIENT_SECRET` 用于 Reddit 摄入。OAuth 模式还需要 `AXON_PUBLIC_URL`、`AXON_GOOGLE_CLIENT_ID`、`AXON_GOOGLE_CLIENT_SECRET` 和 `AXON_AUTH_ADMIN_EMAIL`。
热路径设置目标在 2 分钟内完成（前提是图像和模型权重已缓存）。冷启动拉取图像和模型权重可能需要更长时间；目标硬件时序仍需针对发布的工件进行测量。
## 本地索引
使用 `axon embed /path` 将本地文件注册到后台本地代码索引监视器。现有本地文件和目录输入默认情况下开始监视；使用 `axon embed /path --watch` 将监视器附加到前台，或使用 `axon embed /path --no-watch` 进行一次性本地嵌入，写入向量后退出。
SourceLedger 目前在与 Axon 作业相同的 SQLite 运行时 DB 中跟踪爬取刷新和可变 Git 摄入源的生成和清理状态。
已删除的 `code-search-watch` 命令现在作为墓碑退出；使用 `embed` 进行本地 Git 检出/工作区代码索引。监视器使用现有的 `axon-code-index` 生命周期表。
## Docker 堆栈
生产 Compose 文件启动：
| 服务 | 目的 | 主机绑定 |
| --- | --- | --- |
| `axon` | HTTP 服务器、Web 面板、MCP HTTP、动作 API、进程内工作器 | `127.0.0.1:8001` |
| `axon-qdrant` | 向量存储，可选本地服务；生产默认指向 tootie | `127.0.0.1:53333`、`127.0.0.1:53334` |
| `axon-tei` | 通过 TEI 的 Qwen3 嵌入 | `127.0.0.1:52000` |
| `axon-chrome` | 浏览器渲染和 CDP 代理 | `127.0.0.1:6000`、`127.0.0.1:9222`、`127.0.0.1:9223` |
手动启动：
```bash
docker compose --env-file ~/.axon/.env -f ~/.axon/compose/docker-compose.yaml up -d
```
检查：
```bash
docker compose --env-file ~/.axon/.env -f ~/.axon/compose/docker-compose.yaml ps
axon preflight
axon doctor
```
停止：
```bash
docker compose --env-file ~/.axon/.env -f ~/.axon/compose/docker-compose.yaml down
```
开发堆栈：
```bash
cargo build --bin axon
docker compose --env-file .env.example -f docker-compose.yaml build axon
docker compose --env-file ~/.axon/.env -f docker-compose.yaml up -d axon
```
开发堆栈使用生产基础设施定义，但运行 `axon` 从绑定挂载的本地调试二进制文件下 `target/debug`，位于较新的 `axon:dev-runtime` 镜像中。
## 配置
Axon 有两个配置层：
| 文件 | 目的 |
| --- | --- |
| `~/.axon/.env` | URL、机密、身份验证、Docker 插值、运行时启动值 |
| `~/.axon/config.toml` | 非机密调优和行为 |
优先级：
```text
CLI 标志 > 环境变量 > ~/.axon/config.toml > 内置默认值
```
保留在 `.env` 中：
- URL：`QDRANT_URL`、`TEI_URL`、`AXON_CHROME_REMOTE_URL`、`AXON_SEARXNG_URL`。
- 机密：`AXON_HTTP_TOKEN`、`TAVILY_API_KEY`、`GITHUB_TOKEN`、`GITLAB_TOKEN`、`GITEA_TOKEN`、Reddit 凭证、OAuth 凭证、`HF_TOKEN`。
- Docker/运行时启动：`AXON_HOME`、`AXON_DATA_DIR`、`AXON_IMAGE`、`AXON_HTTP_PUBLISH`、`TEI_HTTP_PORT`、GPU 设备值。
- 需要时 LLM 运行时指针：`AXON_HEADLESS_GEMINI_CMD`、`AXON_HEADLESS_GEMINI_HOME`、`AXON_LLM_BACKEND`、`AXON_OPENAI_BASE_URL`、`AXON_SYNTHESIS_OPENAI_MODEL`（旧别名：`AXON_OPENAI_MODEL`），以及可选的 `AXON_OPENAI_API_KEY`。
放入 `config.toml` 中：
- 集合/搜索/询问调优。
- 工作器和作业限制。
- TEI 客户端调优。
- Qdrant 批处理大小。
- 不作为进程启动问题的日志行为。
- UI/输出行为。
`~/.axon/.env` 在配置中心下永远不会通过符号链接加载。
## 首次运行
设置后：
```bash
axon doctor
axon crawl https://example.com --wait true
axon ask "我们爬取了什么？"
```
CLI 和 MCP 命令始终在进程内针对 Qdrant 和 TEI 运行。`axon serve` 通过 HTTP (`/v1/*`、MCP-over-HTTP) 为想要 API 访问已部署实例的客户端公开相同的操作。
## 值得注意的功能
- **混合搜索**。新的 Qdrant 集合使用命名 `dense` + `bm42` 稀疏向量进行查询，并使用 Reciprocal Rank Fusion（RRF）进行查询。旧的无名集合回落到仅密集的余弦搜索。通过 `config.toml` 中的 `[search]` 部分进行调优；运行 `axon migrate --from <old> --to <new>` 将旧的无名集合复制到新的命名模式集合中，然后将 `AXON_COLLECTION` 指向它。
- **标准化源规划**。爬取清单、抓取结果、摄入源、本地文件和内存记录在 chunking 之前标准化为 `SourceDocument`。源文档规划器是唯一选择 markdown/plain-text/file chunking 并发出 `PreparedDoc` 值用于 TEI/Qdrant 的层。文件起源（`GitFile`、`LocalFile`）在支持的语言中获取 tree-sitter-aware 代码块，以及 `code_*`、`symbol_*`、`chunk_locator`、`source_range` 和 `chunk_content_kind` 元数据；不支持的代码回落到散文块并使用回落元数据。
- **垂直提取器**。`scrape`（以及 `scrape` MCP/REST 操作）自动路由已知 URL 到结构化站点提取器（GitHub、PyPI、npm、crates.io、Reddit、YouTube 等）而不是通用 HTML→markdown。垂直有效负载保持 `extractor_name` 和有界结构化数据，通过与通用抓取相同的源文档规划器使用。禁用 `AXON_ENABLE_VERTICALS=false` 或 `[verticals]` 配置部分。
- **新鲜度计划**。CLI 可以使用 `--fresh <Nd>` 在 `scrape`、`crawl`、`embed` 和 `ingest` 上创建循环调度。 `axon serve`/`axon mcp` 从 SQLite 运行调度器，重放通过正常服务/作业路径的安全版本快照。仅限 v1`。在 CLI 中使用 `axon fresh list`、`axon fresh run-now <id>` 和 `axon fresh history <id>`。
- **Web 面板**。`axon serve` 在绑定地址（默认为 `http://127.0.0.1:8001`）上托管一个 Aurora 样式的控制面板，带有首次运行设置流程、配置/堆栈检查和命令运行器，以及 `/v1/*` REST 接口和 OpenAPI 文档，位于 `/docs`。
## CLI 映射
核心：
- `scrape <url>...`
- `crawl <url>...`
- `map <url>`
- `extract <url>...`
- `embed [input]`
- `query <text>`
- `retrieve <url>`
- `ask <question>`
- `summarize <url>...`
- `evaluate <question>`
- `diff <url-a> <url-b>` - 显示两个 URL 之间的变化（内容/元数据/链接）
- `brand <url>` - 提取品牌身份：颜色、字体、徽标、favicon
发现和摄入：
- `search <query>` - 通过 SearXNG（或 Tavily）的网络搜索，自动排队爬取作业
- `research <query>` - 使用 LLM 合成多源网络研究
- `suggest [focus]`
- `endpoints <url>` - 从页面 HTML 和 JavaScript 包中发现 API 端点
- `ingest <target>` - GitHub、GitLab、Gitea/Forgejo、通用 Git、Reddit 或 YouTube
- `sessions` - 索引 AI 会话导出（Claude、Codex、Gemini）
操作：
- `setup`
- `update` - 安装最新的 GitHub Release 二进制文件并同步本地容器
- `doctor`
- `debug`
- `serve`
- `mcp`
- `status`
- `monitor jobs` - 流式传输作业生命周期事件（start/complete/fail/cancel）
- `fresh` - 列出、运行和检查 CLI 创建的 Freshness 调度
- `sources`
- `domains`
- `stats`
- `watch`
- `refresh [filter]` - 重新爬取/重新摄入以前索引的来源（完整文档刷新）
- `dedupe`
- `migrate`
- `screenshot`
- `train` - 收集人类偏好投票以评估 RAG 候选
- `config`
- `completions`
使用命令特定的帮助：
```bash
axon --help
axon setup --help
axon crawl --help
axon mcp --help
```
图标志不是生产 CLI、MCP 或 `/v1/ask` 请求契约的一部分。
## MCP 和身份验证
Axon 公开一个名为 `axon` 的 MCP 工具；动作由 `action` 和可选的 `subaction` 路由。
示例：
```json
{ "action": "doctor" }
{ "action": "scrape", "url": "https://example.com" }
{ "action": "ask", "query": "setup 如何工作？" }
{ "action": "summarize", "url": "https://example.com" }
{ "action": "crawl", "subaction": "status", "job_id": "<uuid>" }
```
HTTP 身份验证模式：
- 使用 `AXON_HTTP_TOKEN` 进行静态 bearer-token 身份验证。
- 使用 `AXON_AUTH_MODE=oauth` 进行 OAuth/lab-auth。
`/mcp` 和 `/v1/*` REST 路由（例如 `/v1/ask`、`/v1/scrape`、`/v1/query`）共享相同的身份验证策略。无令牌 HTTP 仅适用于环回开发绑定。
## 开发
构建：
```bash
cargo build --bin axon
cargo build --release --bin axon
```
测试和 lint：
```bash
cargo fmt --all -- --check
cargo check --workspace --all-targets --features test-helpers
cargo clippy --workspace --all-targets --features test-helpers -- -D warnings
cargo test --workspace --features test-helpers
```
常见聚焦检查：
```bash
cargo test --test cli_help_contract -- --nocapture
cargo test parse_setup -- --nocapture
cargo test load_dotenv -- --nocapture
python3 scripts/generate_mcp_schema_doc.py --check
docker compose --env-file .env.example -f docker-compose.yaml config --quiet
```
模块布局策略：
- 不要添加 `mod.rs`。
- Rust 模块根位于 `foo.rs`。
- 子模块位于 `foo/bar.rs`。
## 版本门控
生产版本发布前需要：
- CI fmt/check/clippy/test。
- MCP 模式文档同步。
- CLI 帮助合同测试。
- Docker Compose 配置验证。
- Docker 镜像构建和 GHCR 发布工作流。
- Compose 烟雾测试工作流。
- 自托管 RTX 4070 烟雾测试 Qwen3 TEI 冷/热设置时序。
`cargo machete` 应在安装后运行；它不包含在此仓库中。
## 故障排除
快速检查：
```bash
axon preflight
axon doctor
docker compose --env-file ~/.axon/.env -f ~/.axon/compose/docker-compose.yaml ps
docker compose --env-file ~/.axon/.env -f ~/.axon/compose/docker-compose.yaml logs --tail=100 axon axon-tei axon-qdrant axon-chrome
```
重要路径：
- `~/.axon/.env`
- `~/.axon/config.toml`
- `~/.axon/jobs.db`
- `~/.axon/logs`
- `~/.axon/artifacts`
- `~/.axon/output`
- `~/.axon/tei`
- `~/.axon/qdrant` 在运行 Qdrant 的主机上，通常是 tootie
常见故障：
- Docker 丢失：安装 Docker 和 Docker Compose，然后重新运行 `axon setup`。
- GPU 不可用：验证 `nvidia-smi` 和 NVIDIA 容器工具包。
- Gemini 未认证：运行 Gemini CLI 登录 Axon 外部，然后重新运行设置，
或配置 `AXON_LLM_BACKEND=openai-compat` 以使用 OpenAI 兼容的端点。
- TEI 在首次启动时缓慢：冷路径的模型下载/缓存预热。
- 身份验证失败：确保 Claude/插件配置使用的令牌与 `~/.axon/.env` 中的 `AXON_HTTP_TOKEN` 相同。
## 相关文件
- `install.sh` - 验证的一键安装程序启动器。
- `docker-compose.prod.yaml` - 生产 Compose 堆栈。
- `docker-compose.yaml` - 本地开发堆栈。
- `.env.example` - 生产环境模板。
- `config.example.toml` - 非机密调优模板。
- `plugins/axon/.claude-plugin/plugin.json` - Claude 插件清单。
- `scripts/plugin-setup.sh` - 插件钩子委托给共享设置。
- `docs/reference/mcp/tool-schema.md` - 生成的 MCP 线协议。
- `docs/` - 完整文档树：指南、`reference/actions/`、架构和操作。
## 相关服务器
- [soma](https://github.com/jmagar/soma) - 提供商支持的 MCP 服务器的 RMCP 运行时。
- [unifi-rmcp](https://github.com/jmagar/unifi-rmcp) - UniFi 控制器 REST API 桥接器。
- [tailscale-rmcp](https://github.com/jmagar/tailscale-rmcp) - Tailscale 设备、用户和 tailnet 操作的 API 桥接器。
- [unraid-rmcp](https://github.com/jmagar/unraid-rmcp) - Unraid GraphQL 桥接器，用于 NAS 和服务器管理。
- [apprise-rmcp](https://github.com/jmagar/apprise-rmcp) - Apprise 通知扇出桥接器，用于多个交付后端。
- [gotify-rmcp](https://github.com/jmagar/gotify-rmcp) - Gotify 发送通知的桥接器，用于发送、消息、应用程序和客户端。
- [arcane-rmcp](https://github.com/jmagar/arcane-rmcp) - Arcane Docker 管理桥接器，用于容器和相关资源。
- [yarr](https://github.com/jmagar/yarr) - 媒体堆栈桥接器，用于 Sonarr、Radarr、Prowlarr、Plex 等服务。
- [ytdl-rmcp](https://github.com/jmagar/ytdl-rmcp) - 媒体下载和元数据工作流服务器。
- [synapse-rmcp](https://github.com/jmagar/synapse-rmcp) - 本地 Synapse 工作流服务器，用于侦察和通量操作。
- [cortex](https://github.com/jmagar/cortex) - Syslog 和家庭实验室日志聚合 MCP 服务器。
- [labby](https://github.com/jmagar/labby) - 家庭实验室控制平面和 MCP 网关项目。
- [lumen](https://github.com/jmagar/lumen) - 本地语义代码搜索 MCP 服务器。
## 许可
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器