企业官网建设流程全解析

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

本指南以 gaianet-node 仓库的官方 README（README-fa.md）为核心骨架，完整讲解如何在你自己的 Mac、Linux 或 Windows WSL 机器上安装、初始化、启动、停止并配置一个去中心化的 GaiaNet AI 智能体节点。读完本文，你将掌握gaianetCLI 的完整生命周期操作（install → init → start → stop → config），理解config.json每个关键字段的底层含义，并能基于仓库源码定位每个命令背后真正执行的组件与调用链，实现从"照抄命令"到"按需定制节点"的进阶。

快速开始：四步跑通一个 GaiaNet 节点

如果你只想在最短时间内把一个默认节点跑起来，只需依次执行以下四步：

1. 安装节点软件栈

在 Mac、Linux 或 Windows WSL 终端中执行一行命令，即可安装默认的节点软件栈：

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

安装完成后，请跟随终端提示设置 environment path——提示的命令行会以source开头，用于把 WasmEdge 等运行时加入当前 shell 的 PATH。

注意：Windows 用户必须使用 WSL（Windows Subsystem for Linux）环境运行，仓库脚本 gaianet 中对MINGW32_NT平台会直接提示For Windows users, please run this script in WSL。

2. 初始化节点（下载模型与知识库）

gaianet init

init会依据$HOME/gaianet/config.json中指定的地址，下载 GGUF 格式的对话模型文件、Embedding 模型文件，并在 Qdrant 向量数据库中创建（或从快照恢复）知识库 collection。由于这些文件通常很大，这一步可能需要几分钟。

3. 启动节点

gaianet start

启动成功后，脚本会在控制台打印节点的正式访问地址，格式类似：

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

用浏览器打开这个 URL，即可查看节点信息并直接与节点上的 AI 智能体对话。

4. 停止节点

gaianet stop

安装指南：install.sh 的完整行为解析

除快速开始使用的 Release 安装命令外，仓库还支持从源码仓库直接安装：

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 ... Installation of wasmedge-0.13.5 successful The WasmEdge Runtime wasmedge version 0.13.5 is installed in /home/azureuser/.wasmedge/bin/wasmedge. [+] Installing Qdrant binary... * Download Qdrant binary * Initialize Qdrant directory [+] Downloading the rag-api-server.wasm ... [+] Downloading dashboard ...

从上述日志可以看出，一次安装实际做了四类工作，对应 install.sh 中的版本常量：

此外，install.sh 还支持--reinstall（重装并下载全部依赖）、--upgrade（升级节点）、--backup <File>/--migrate <File>（配置备份与迁移）、--ggmlcuda 11|12（安装指定 CUDA 版本的 GGML 插件）等高级参数，需要时可用./install.sh --help查看完整选项。

安装到自定义目录：--base

默认情况下，节点安装到$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/config命令也都要通过--base指定同一目录（详见下文各节）。在 gaianet 脚本中，默认基目录同样被定义为gaianet_base_dir="$HOME/gaianet"，--base参数会将其覆盖。

初始化节点：gaianet init 详解

默认初始化

gaianet init

成功输出类似：

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

init严格依据$HOME/gaianet/config.json完成四件事（对应 gaianet 中init()函数）：

1. 校验配置：调用check_config_options逐一检查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（对话模型 URL）与embedding（Embedding 模型 URL）并下载 GGUF 文件；若已存在同名文件则复用缓存；本地.gguf路径也被支持。
3. 恢复知识库：当snapshot字段非空时，调用create_collection启动临时 Qdrant 实例、删除旧的defaultcollection、下载快照（支持.tar.gz压缩包或直接快照文件）、通过 Qdrant 的 snapshot 上传接口导入并完成恢复。
4. 准备控制台与域名：下载并执行 registry.wasm（wasmedge --dir .:. registry.wasm）同步 dashboard 配置，并改写gaia-frp/frpc.toml中的subdomain、name、localPort、serverAddr，为公网域名映射做准备。

使用预设配置初始化

你可以使用社区/官方提供的预设配置。例如，下面的命令初始化一个使用 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可查看全部预设配置名。--config参数既支持预设名称，也接受任意config.json的 URL——也就是说，你可以托管自己的配置，让节点初始化为你想要的任意状态。

初始化自定义基目录下的节点

gaianet init --base $HOME/gaianet.alt

启动节点：gaianet start 背后的组件调用链

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

结合 gaianet 脚本中start()函数的实现（输出[1/4]到[4/4]四个进度阶段），gaianet start实际启动了五个协同工作的进程：

1. Chat Server（start_chat_server）：用wasmedge --nn-preload default:GGML:AUTO:<模型文件> llama-api-server.wasm --model-name <chat_name> --ctx-size <chat_ctx_size> --prompt-template <模板> --port <llamaedge_chat_port>启动对话推理服务，默认端口 9068，并自动通过/v1/chat/completions做健康检查（最多重试 3 次）。
2. Embedding Server（start_embedding_server）：以--prompt-template embedding启动 Embedding 推理服务，默认端口 9069，通过/v1/embeddings做健康检查。
3. Qdrant 实例（start_qdrant_instance）：当snapshot非空（即 RAG 模式开启）时启动向量数据库，默认监听 6333 端口，PID 写入qdrant.pid。
4. gaia-frp（公网映射）：当未加--local-only时，启动frpc -c gaia-frp/frpc.toml，把节点通过 GaiaNet 域名反向代理暴露到公网。
5. gaia-nexus（网关）：负责统一入口、健康检查（每 60 秒一次）与 Web UI，并把 Chat/Embedding 两个下游服务注册到自己的/admin/servers/register接口。

启动完成后控制台会输出：

✅ COMPLETED! The GaiaNet node is started at: https://<subdomain>.<domain> 👉 To stop the GaiaNet node, run the command: gaianet stop ❗ You can close this terminal window safely now.

仅本地启动：--local-only

如果只想在本机使用，可以本地模式启动。节点只会通过localhost访问，不会出现在 GaiaNet 域名的任何公网 URL 上：

gaianet start --local-only

本地模式下脚本不再启动 gaia-frp，而是提示The GaiaNet node is started in local mode at: http://localhost:<llamaedge_port>。

启动自定义基目录下的节点

gaianet start --base $HOME/gaianet.alt

停止节点：gaianet stop

gaianet stop

输出：

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

从源码 gaianet 的stop_force()可以看到，停止操作实际会依次pkillQdrant、gaia-nexus、cardea-agentic-search、wasmedge（覆盖 Chat/Embedding 推理进程）以及 frpc，并清理qdrant.pid、chat_server.pid、embedding_server.pid、llama_nexus.pid、cardea_agentic_search_mcp.pid、gaia-frp.pid等 PID 文件。

停止安装在其他基目录的节点：

gaianet stop --base $HOME/gaianet.alt

更新配置：gaianet config 子命令全解

gaianet config用于就地更新$HOME/gaianet/config.json中的关键字段。重要：每次更新配置后，必须重新执行gaianet init，否则新的配置不会生效。

更新对话模型 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

全部选项参考

README 中给出的gaianet config --help输出如下：

$ gaianet config --help Usage: gaianet config [OPTIONS] Options: --chat-url <url> Update the url of chat model. --chat-ctx-size <val> Update the context size of chat model. --embedding-url <url> Update the url of embedding model. --embedding-ctx-size <val> Update the context size of embedding model. --prompt-template <val> Update the prompt template of chat model. --port <val> Update the port of LlamaEdge API Server. --system-prompt <val> Update the system prompt. --rag-prompt <val> Update the rag prompt. --rag-policy <val> Update the rag policy [Possible values: system-message, last-user-message]. --reverse-prompt <val> Update the reverse prompt. --domain <val> Update the domain of GaiaNet node. --snapshot <url> Update the Qdrant snapshot. --qdrant-limit <val> Update the max number of result to return. --qdrant-score-threshold <val> Update the minimal score threshold for the result. --base <path> The base directory of GaiaNet node. --help Show this help message

对照仓库内 CLI 脚本 gaianet 中show_config_help()的实现，当前版本还支持以下扩展选项，可按需使用：

--chat-batch-size <val> 更新对话模型的 batch size。 --chat-ubatch-size <val> 更新对话模型的 ubatch size。 --embedding-batch-size <val> 更新 Embedding 模型的 batch size。 --embedding-ubatch-size <val> 更新 Embedding 模型的 ubatch size。 --chat-port <val> 更新 Chat Server 端口。 --embedding-port <val> 更新 Embedding Server 端口。 --context-window <val> 更新上下文窗口。

各选项与config.json字段的映射关系为：--chat-url → chat、--chat-ctx-size → chat_ctx_size、--chat-port → llamaedge_chat_port、--port → llamaedge_port、--embedding-port → llamaedge_embedding_port、--snapshot → snapshot、--domain → domain、--qdrant-limit → qdrant_limit、--qdrant-score-threshold → qdrant_score_threshold。脚本通过update_config()中的sed就地替换对应键值，因此字段名必须与配置文件严格一致。

config.json 核心字段深度解析

README 反复提到的$HOME/gaianet/config.json是节点的"唯一事实来源"。仓库根目录的 config.json 是一份可直接参考的默认配置（对话模型为 Qwen3-4B，Embedding 模型为 Nomic-embed-text-v1.5）：

{ "address": "", "description": "The default GaiaNet node config with a Llama-3.2-3B-Instruct model.", "domain": "gaia.domains", "llamaedge_chat_port": "9068", "llamaedge_embedding_port": "9069", "llamaedge_port": "8080", "chat": "https://huggingface.co/second-state/Qwen3-4B-GGUF/resolve/main/Qwen3-4B-Q5_K_M.gguf", "chat_name": "Qwen3-4B", "chat_ctx_size": "16384", "chat_batch_size": "128", "chat_ubatch_size": "128", "prompt_template": "qwen3-no-think", "reverse_prompt": "", "system_prompt": "You are a helpful AI assistant. Please answer questions as clearly and concisely as possible.", "embedding": "https://huggingface.co/gaianet/Nomic-embed-text-v1.5-Embedding-GGUF/resolve/main/nomic-embed-text-v1.5.f16.gguf", "embedding_name": "Nomic-embed-text-v1.5", "embedding_ctx_size": "8192", "embedding_batch_size": "8192", "embedding_ubatch_size": "8192", "snapshot": "", "embedding_collection_name": "default", "qdrant_limit": "1", "qdrant_score_threshold": "0.5" }

各字段在运行时（gaianet 脚本）中的实际作用如下：

值得一提的是，chat_name/embedding_name若未配置，脚本会自动从 GGUF 文件名推导模型名（见start_chat_server()/start_embedding_server()中的回退逻辑），因此自定义模型时这两个字段可省。

用测试用例验证节点 API

节点启动后，可借助仓库 tests 目录下的 Hurl 测试脚本快速验证 OpenAI 兼容接口是否按预期工作：

• tests/chat.hurl：验证GET /v1/models（断言模型 id 为Qwen3-4B或Nomic-embed-text-v1.5）、POST /v1/chat/completions（断言模型名为Qwen3-4B且回答包含 "Paris"），并覆盖了"传入错误模型名仍能正常回落"的场景。
• tests/embeddings.hurl：验证 Embedding 接口。
• tests/rag.hurl：带 RAG 上下文的问答测试，请求体与 tests/test.rag.json 配合使用。

例如，本地模式启动后可直接执行：

hurl --test tests/chat.hurl

这也印证了start()中健康检查采用的就是同一套/v1/chat/completions与/v1/embeddings探测逻辑。

其他部署形态：Docker 一键运行

如果你希望跳过手动安装环境依赖，也可以使用官方 Docker 镜像直接运行节点（详见 docker/README.md）。典型命令：

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

镜像内置了 LLM 与 Embedding 模型文件，但知识库快照会在容器每次启动时下载导入（因为知识库更新频繁），宿主机上的qdrant_storage目录负责持久化向量数据。Nvidia CUDA 12 用户可改用cuda12标签并追加--device nvidia.com/gpu=all。需要注意的是，Docker 方式与本文前述--base目录方式二选一即可，两者都是对同一节点配置模型的不同交付形式。

小结

围绕 README-fa.md 的完整脉络，本文不仅覆盖了 install / init / start / stop / config 五类命令的标准用法，还通过 gaianet 脚本、config.json、install.sh 与 tests 逐层拆解了节点背后的组件架构：

• 安装：WasmEdge（推理运行时）+ Qdrant（向量库）+ llama-api-server.wasm（API 服务）+ dashboard（控制台），支持--base自定义目录；
• 初始化：按config.json下载模型、恢复知识库快照、改写 frpc 隧道配置；
• 启动：Chat Server、Embedding Server、Qdrant、gaia-frp、gaia-nexus 五进程协同，本地模式与公网模式自由切换；
• 配置：gaianet config支持 20+ 字段就地更新，改后必须重新init。

现在，你已经具备从零部署、定制并验证一个 GaiaNet 去中心化 AI 智能体节点的完整能力。Enjoy!

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