企业官网建设流程全解析

• AI 应用
• 大模型
• CLI
• RAG

本指南以 README-ru.md 为骨架，系统讲解如何在 Mac、Linux 或 Windows WSL 上安装、初始化、启动与停止一个属于自己的 GaiaNet 去中心化 AI 智能体节点，并详解gaianet config的每一个配置参数。读完本文，你将掌握从零部署一个带 RAG 知识库的 LLM 推理服务节点的完整链路，并理解节点启动时 WasmEdge、Qdrant、gaia-frp、gaia-nexus 等组件的协作方式与底层原理。

GaiaNet 节点是什么：一个可运行的软件栈

GaiaNet 节点本质上是一套预打包的分布式 AI 服务软件栈：它用WasmEdge 运行时加载 GGUF 格式的大语言模型与 embedding 模型，用Qdrant作为向量数据库承载知识库，用gaia-frp（frpc）做内网穿透以便对外提供官方域名，用gaia-nexus充当统一网关。安装脚本会把这些组件一次性装配到$HOME/gaianet目录下。

以本仓库默认配置 config.json 为例，一个节点包含两类模型与三类端口：

仓库根目录的 install.sh 中定义了当前安装器版本0.6.0，并锁定各组件版本：WasmEdge0.14.1（GGML 插件b6399）、Qdrantv1.14.1、LlamaEdge API Server0.27.0、gaia-nexus0.8.2、dashboardv3.1。这些版本号以硬编码方式出现在安装脚本顶部，属于本次安装的明确事实，可作排障依据。

快速开始：三行命令拉起你的第一个节点

安装默认节点软件栈只需一行命令，支持 Mac、Linux 与 Windows WSL：

curl -sSfL 'https://github.com/GaiaNet-AI/gaianet-node/releases/latest/download/install.sh' | bash

安装完成后请按屏幕提示设置PATH环境变量，随后的命令应以source开头，例如source ~/.bashrc（zsh 为source ~/.zshrc），使gaianetCLI 在当前的 shell 会话中可用。

初始化节点。它会下载 config.json 中指定的模型文件与向量数据库快照。由于文件体积较大，该过程可能需要几分钟：

gaianet init

启动节点：

gaianet start

启动成功后，控制台会打印节点的官方地址，形如：

... ... https://0xf63939431ee11267f4855a166e11cc44d24960c0.us.gaianet.network

在浏览器中打开该 URL，即可查看节点信息并与节点上的 AI 智能体对话。

停止节点：

gaianet stop

从 gaianet 脚本的实现看，stop会通过pkill依次清理qdrant、gaia-nexus、cardea-agentic-search、wasmedge与frpc五个进程，并删除对应的.pid文件，保证节点可以干净地重启。

安装指南：install.sh 的完整执行流程

标准安装与示例输出

与快速开始不同，安装指南中的命令直接从仓库获取安装脚本：

curl -sSfL 'https://raw.githubusercontent.com/GaiaNet-AI/gaianet-node/main/install.sh' | bash

安装过程的典型输出如下：

[+] Downloading default config file ... [+] Downloading nodeid.json ... [+] Installing WasmEdge with wasi-nn_ggml plugin ... Info: Detected Linux-x86_64 Info: WasmEdge Installation at /home/azureuser/.wasmedge Info: Fetching WasmEdge-0.13.5 /tmp/wasmedge.2884467 ~/gaianet ######################################################################## 100.0% ~/gaianet Info: Fetching WasmEdge-GGML-Plugin Info: Detected CUDA version: /tmp/wasmedge.2884467 ~/gaianet ######################################################################## 100.0% ~/gaianet Installation of wasmedge-0.13.5 successful WasmEdge binaries accessible The WasmEdge Runtime wasmedge version 0.13.5 is installed in /home/azureuser/.wasmedge/bin/wasmedge. [+] Installing Qdrant binary... * Download Qdrant binary ################################################################################################## 100.0% * Initialize Qdrant directory [+] Downloading the rag-api-server.wasm ... ################################################################################################## 100.0% [+] Downloading dashboard ... ################################################################################################## 100.0%

对照 install.sh 源码，上述输出背后是一整套分步装配流程，每一步都有明确职责：

1. 安装gaianetCLI 工具：下载 CLI 二进制到$base/bin/gaianet并赋予执行权限；
2. 下载默认config.json：若本地已有缓存则复用（输出Use the cached config file）；
3. 安装 WasmEdge 与 wasi-nn_ggml 插件：通过 WasmEdge 官方安装脚本完成，Linux 下若检测到 NVIDIA GPU 会额外提示安装nvidia-smi；
4. 安装 Qdrant 二进制并初始化目录：按架构下载静态编译二进制（Linux 为x86_64-unknown-linux-musl或aarch64-unknown-linux-musl），并将 Qdrant 源码包的config/拷入qdrant/config/，同时把config.yaml中的telemetry_disabled改为true以关闭遥测；
5. 下载 LlamaEdge API Server（llama-api-server.wasm）与 cardea-agentic-search MCP server；
6. 安装 gaia-nexus：下载二进制与mcp_config.toml并放置到基础目录；
7. 下载 dashboard（web 界面）到$base/dashboard；
8. 下载registry.wasm：用于后续生成节点 ID；
9. 生成节点 ID：运行wasmedge --dir .:. registry.wasm，产出nodeid.json（含地址address、密钥文件keystore与password）；
10. 安装 gaia-frp（frpc）：下载frpc二进制到bin/，下载frpc.toml，并根据config.json中的address与domain回填subdomain、serverAddr、name、deviceId等字段。

安装脚本还支持--upgrade升级模式：升级前会先把config.json、nodeid.json、keystore 文件、frpc.toml、deviceid.txt备份到$base/backup/，升级完成后自动恢复；--reinstall则会清空整个基础目录后重装。

安装到自定义目录

默认安装到$HOME/gaianet，也可以指定其他目录：

curl -sSfL 'https://raw.githubusercontent.com/GaiaNet-AI/gaianet-node/main/install.sh' | bash -s -- --base $HOME/gaianet.alt

--base参数会同步决定后续init、start、stop时 CLI 操作的目录，三者的--base取值必须一致。

install.sh 其他实用选项

从 install.sh 的print_usage可见，安装器还提供以下选项：

初始化节点：下载模型与导入知识库

gaianet init

初始化过程的典型输出如下：

[+] Downloading Llama-2-7b-chat-hf-Q5_K_M.gguf ... ############################################################################################################################## 100.0%############################################################################################################################## 100.0% [+] Downloading all-MiniLM-L6-v2-ggml-model-f16.gguf ... ############################################################################################################################## 100.0%############################################################################################################################## 100.0% [+] Creating 'default' collection in the Qdrant instance ... * Start a Qdrant instance ... * Remove the existed 'default' Qdrant collection ... * Download Qdrant collection snapshot ... ############################################################################################################################## 100.0%############################################################################################################################## 100.0% * Import the Qdrant collection snapshot ... * Recovery is done successfully

对照 gaianet 脚本的init()函数，其内部逻辑分为四步：

1. 校验配置（check_config_options）：依次确认config.json中存在address、chat、prompt_template、chat_ctx_size、system_prompt、embedding、embedding_ctx_size、snapshot、embedding_collection_name、qdrant_limit、qdrant_score_threshold、domain、llamaedge_port、llamaedge_chat_port、llamaedge_embedding_port等字段，缺失任一字段都会立即报错退出；
2. 下载模型：根据chat字段下载聊天 GGUF 模型，根据embedding字段下载 embedding GGUF 模型；已下载过的文件会提示Using the cached直接复用。字段既支持 http(s) URL，也支持本地.gguf文件路径；
3. 导入知识库快照：若snapshot非空，则先启动临时 Qdrant 实例（监听6333），删除同名旧 collection，下载 snapshot（支持 URL 或本地文件，.tar.gz会自动解包成default.snapshot），再通过 Qdrant 的/collections/{name}/snapshots/upload接口导入；
4. 准备 dashboard 与 frpc 配置：运行wasmedge --dir .:. registry.wasm把配置同步到 dashboard；随后将frpc.toml中的subdomain、name、localPort、serverAddr用config.json的address、domain、llamaedge_port字段回填。

使用预置配置或自定义配置

init命令依据$HOME/gaianet/config.json初始化节点。可以使用现成的预置配置，例如下面的命令初始化一个以 llama-3 8B 为对话模型、以伦敦旅行指南为知识库的节点：

gaianet init --config https://raw.githubusercontent.com/GaiaNet-AI/node-configs/main/llama-3-8b-instruct_london/config.json

查看预置配置列表可执行gaianet init --help。从 gaianet 脚本的show_init_help看，预置名称包括default、paris_guide、mua、gaia等。此外，--config也接受任意自定义config.json的 URL——例如gaianet_docs这类社区配置，或你自己托管的一份配置，节点会下载并据此初始化到你想要的状态。

如果节点安装在替代目录，则需显式指定基础目录：

gaianet init --base $HOME/gaianet.alt

启动节点：四大组件的一次性编排

gaianet start

启动过程的典型输出如下：

[+] Starting Qdrant instance ... Qdrant instance started with pid: 39762 [+] Starting LlamaEdge API Server ... Run the following command to start the LlamaEdge API Server: wasmedge --dir .:./dashboard --nn-preload default:GGML:AUTO:Llama-2-7b-chat-hf-Q5_K_M.gguf --nn-preload embedding:GGML:AUTO:all-MiniLM-L6-v2-ggml-model-f16.gguf rag-api-server.wasm --model-name Llama-2-7b-chat-hf-Q5_K_M,all-MiniLM-L6-v2-ggml-model-f16 --ctx-size 4096,384 --prompt-template llama-2-chat --qdrant-collection-name default --web-ui ./ --socket-addr 0.0.0.0:8080 --log-prompts --log-stat --rag-prompt "Use the following pieces of context to answer the user's question.\nIf you don't know the answer, just say that you don't know, don't try to make up an answer.\n----------------\n" LlamaEdge API Server started with pid: 39796

上面这条wasmedge命令非常关键，它揭示了 RAG 推理链路的完整形态：--nn-preload同时加载聊天模型与 embedding 模型，--ctx-size 4096,384分别为两者指定上下文长度，--prompt-template llama-2-chat指定聊天提示词模板，--qdrant-collection-name default指定检索使用的向量集合，--rag-prompt给出检索增强生成的系统提示词（要求模型依据上下文作答、不确定时明确说不知道）。

需要说明的是：当前仓库的 gaianet 脚本已经演进为更细粒度的四步编排（start()函数），启动日志也会相应打印[1/4] ... [4/4]进度：

• [1/4]校验配置：复用check_config_options，并运行registry.wasm把config.json同步到 dashboard；
• [2/4]启动下游服务：先启动 chat server（llama-api-server.wasm，端口9068），再启动 embedding server（端口9069），两者启动后都会用 curl 向/v1/chat/completions、/v1/embeddings发探测请求做健康检查，失败会自动重试最多 3 次；若snapshot非空（RAG 模式），还会启动 Qdrant 实例与 cardea-agentic-search MCP server；
• [3/4]启动 gaia-frp：frpc -c $base/gaia-frp/frpc.toml建立到 GaiaNet 域名的内网隧道；
• [4/4]启动 gaia-nexus 并注册服务：gaia-nexus 作为统一网关暴露llamaedge_port（默认8080），随后通过POST /admin/servers/register把 chat server 与 embedding server 注册到网关。

仅本机使用（local-only）

可以仅在本机启动节点，此时节点只通过localhost访问，不会出现在任何 GaiaNet 公网域名上：

gaianet start --local-only

本地模式下启动完成后会打印http://localhost:8080（端口取自llamaedge_port）。从 gaianet 脚本看，start还支持--force-rag（即使snapshot为空也强制启动 RAG 服务）与--wait <val>（等待 gaia-nexus 就绪的秒数，默认 30）。

从替代目录启动节点：

gaianet start --base $HOME/gaianet.alt

停止节点

gaianet stop

典型输出：

[+] Stopping WasmEdge, Qdrant and frpc ...

停止替代目录中的节点：

gaianet stop --base $HOME/gaianet.alt

另外，gaianet 脚本还提供一个gaianet info子命令，可随时查看节点的Node ID（来自config.json的address）与Device ID（来自gaia-frp/frpc.toml的metadatas.deviceId）。

更新配置：gaianet config 全参数详解

使用gaianet config子命令可以更新 config.json 中的关键字段。修改配置后必须重新执行gaianet init，新配置才会真正生效（因为init会按新模型 URL 下载模型、按新 snapshot 重建向量集合，并重写 frpc 隧道配置）。

更新聊天模型的 URL：

gaianet config --chat-url "https://huggingface.co/second-state/Llama-2-13B-Chat-GGUF/resolve/main/Llama-2-13b-chat-hf-Q5_K_M.gguf"

更新聊天模型的上下文大小：

gaianet config --chat-ctx-size 5120

gaianet config的全部选项如下（摘自 README，其中选项的中文注解为对照 gaianet 脚本show_config_help的说明）：

$ gaianet config --help Usage: gaianet config [OPTIONS] Options: --chat-url <url> 更新聊天模型的 URL。 --chat-ctx-size <val> 更新聊天模型的上下文大小。 --embedding-url <url> 更新 embedding 模型的 URL。 --embedding-ctx-size <val> 更新 embedding 模型的上下文大小。 --prompt-template <val> 更新聊天模型的提示词模板。 --port <val> 更新 LlamaEdge API Server 的端口。 --system-prompt <val> 更新系统提示词。 --rag-prompt <val> 更新 RAG 提示词。 --rag-policy <val> 更新 RAG 策略 [可选值：system-message, last-user-message]。 --reverse-prompt <val> 更新反向提示词。 --domain <val> 更新 GaiaNet 节点的域名。 --snapshot <url> 更新 Qdrant 快照。 --qdrant-limit <val> 更新检索返回结果的最大条数。 --qdrant-score-threshold <val> 更新结果的最小评分阈值。 --base <path> GaiaNet 节点的基础目录。 --help 显示此帮助信息。

结合 gaianet 脚本的show_config_help，实际可用的选项比 README 列出的更全，还包含以下进阶参数：

config子命令内部通过update_config()函数以sed原位改写config.json中对应字段的值，并逐项打印旧值（Old url/Old size）与新值（New url/New size），便于确认改动结果。

深入 config.json：每个字段的含义与默认值

仓库根目录的 config.json 是默认配置的真实样例，字段含义如下：

这些字段与 gaianet 脚本中start_chat_server()、start_embedding_server()、start_cardea_agentic_search_mcp_server()等函数的解析逻辑一一对应：脚本用awk从config.json提取字段值，拼装成wasmedge启动命令与 MCP server 参数，因此任何字段的改动都会直接影响运行时的模型加载、上下文长度、批处理与检索行为。

验证与补充：测试用例与 Docker 部署

用测试用例验证节点 API

仓库的 tests/chat.hurl 是一份可直接运行的 API 冒烟测试（Hurl 格式），覆盖了节点启动后的核心能力：

• GET /v1/models：断言返回的模型 ID 匹配Qwen3-4B或Nomic-embed-text-v1.5；
• POST /v1/chat/completions：提问"法国的首都是哪里？"，断言model为Qwen3-4B且回答包含Paris；
• 错误模型名容错：即使请求体中的model写错（如Qwen3-4B-Instruct-invalid），网关仍会按正确模型作答。

同样地，tests/embeddings.hurl 与 tests/rag.hurl（配合 tests/test.rag.json）分别覆盖 embedding 接口与 RAG 检索问答场景，可作为节点部署完成后验证服务可用性的现成脚本。

Docker 部署方式

除裸机安装外，仓库还提供 docker/README.md 与Dockerfile（含Dockerfile.cuda11、Dockerfile.cuda12）。默认容器使用 CPU 计算，适合 LLM 在 8GB 内存以上机器运行；NVIDIA GPU 场景需安装 NVIDIA Container Toolkit，并把镜像标签换为cuda12或cuda11、加上--device nvidia.com/gpu=all标志。典型的启动命令：

docker run --name gaianet \ -p 8080:8080 \ -v $(pwd)/qdrant_storage:/root/gaianet/qdrant/storage:z \ gaianet/phi-3-mini-instruct-4k_paris:latest

容器内部即通过 docker/run.sh 依次执行gaianet init与gaianet start。需要注意：镜像内置 LLM 与 embedding 模型，但知识库快照（向量数据）在节点启动时才下载导入，因此用宿主机目录挂载qdrant_storage持久化向量库内容；每次docker start重启都会重新初始化知识库。容器内的配置修改可执行docker exec -it gaianet /root/gaianet/bin/gaianet config --chat-ctx-size 8192，修改后重启容器生效。若想更换节点 ID，则把新的nodeid.json与其对应的 keystore 文件用docker cp拷入容器后重启即可。

小结：一次部署，长期可维护

从本指南可以看出，GaiaNet 节点的日常运维是一条清晰的主线：

1. 安装：install.sh一键装配 CLI、WasmEdge、Qdrant、frpc、gaia-nexus 与 dashboard，--base支持多节点并存，--upgrade/--backup/--migrate支持平滑升级与迁移；
2. 初始化：gaianet init按config.json下载模型、导入知识库快照，--config支持预置或自定义配置，是实现"每个节点一个专属智能体"的入口；
3. 启停：gaianet start编排 chat/embedding 推理服务、Qdrant、frpc 与 gaia-nexus，--local-only提供纯本机模式，gaianet stop干净回收全部进程；
4. 持续调优：gaianet config覆盖模型 URL、上下文大小、batch/ubatch、提示词、端口、Qdrant 检索参数等全部关键字段，改完记得重新init。

掌握这条链路后，你不仅能运行默认节点，还能把任意开源 GGUF 模型与任意知识库快照组合成自己的 RAG 智能体服务，并通过公网域名分享给他人使用。

• AI 应用
• 大模型
• CLI
• RAG