如何在信创环境中安装JiuwenSwarm

我的提供的安装主机的操作系统是：银河麒麟高级服务器操作系统V11 版本号：V11(2503)，内核：Linux 6.6.0-32.18.v2505.ky11.x86_64。

1. 安装 Git（最新版本）

直接安装

bash 复制代码

sudo yum install git

或者，由于系统源中的 Git 版本可能较旧，且你需要最新版本，推荐使用源码编译安装的方式。这不仅能获得最新版，也不会破坏系统原有的环境。

bash 复制代码

# 1. 安装编译 Git 所需的依赖包
sudo yum install -y curl-devel expat-devel gettext-devel openssl-devel zlib-devel gcc perl-ExtUtils-MakeMaker

# 2. 下载最新的 Git 源码（以 2.45.1 为例）
cd /usr/local/src
sudo wget https://mirrors.edge.kernel.org/pub/software/scm/git/git-2.45.1.tar.gz

# 3. 解压并编译安装
sudo tar -zxvf git-2.45.1.tar.gz
cd git-2.45.1
sudo make prefix=/usr/local all
sudo make prefix=/usr/local install

# 4. 将 Git 添加到环境变量
echo 'export PATH=$PATH:/usr/local/git/bin' >> ~/.bashrc
source ~/.bashrc

# 5. 验证安装
git --version

2. 安装 Node.js（18.x 或更高版本）

bash 复制代码

# 1. 下载并安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 2. 重新加载环境变量使其生效
source ~/.bashrc

# 3. 验证 nvm 是否安装成功
command -v nvm

# 4. 使用 nvm 安装 Node.js 18.x (LTS版本)
nvm install 18

# 5. 设置默认版本并验证
nvm alias default 18
node -v
npm -v

3. 安装 Python 3.11（配合 venv 方案）

直接安装：

bash 复制代码

sudo yum install python

或者，由于系统源可能不提供 3.11 版本，我们继续采用源码编译安装。在麒麟 V11 中，需要确保安装了完整的编译依赖链。

bash 复制代码

# 1. 安装编译 Python 所需的依赖
sudo yum install -y gcc gcc-c++ make openssl-devel bzip2-devel libffi-devel zlib-devel readline-devel sqlite-devel wget

# 2. 下载 Python 3.11.9 源码
cd /usr/local/src
sudo wget https://www.python.org/ftp/python/3.11.9/Python-3.11.9.tgz

# 3. 解压并进入目录
sudo tar -xzf Python-3.11.9.tgz
cd Python-3.11.9

# 4. 配置编译路径（安装到独立目录，避免冲突）
sudo ./configure --prefix=/usr/local/python311 --enable-optimizations

# 5. 编译并安装（关键：使用 altinstall 防止覆盖系统默认的 python3）
sudo make -j$(nproc)
sudo make altinstall

# 6. 配置软链接（方便后续使用）
sudo ln -s /usr/local/python311/bin/python3.11 /usr/bin/python3.11
sudo ln -s /usr/local/python311/bin/pip3.11 /usr/bin/pip3.11

验证安装：

bash 复制代码

python3.11 --version  # 应输出 Python 3.11.9(直接安装的可能不是这个版本号)
pip3.11 --version     # 应显示 pip 关联 python 3.11

4. 为 JiuwenSwarm 创建虚拟环境并安装

基础环境就绪后，你可以直接为 JiuwenSwarm 创建虚拟环境：

bash 复制代码

# 1. 使用 python3.11 创建虚拟环境
python3.11 -m venv jiuwenswarm_env

# 2. 激活环境
source jiuwenswarm_env/bin/activate

# 3. 安装 JiuwenSwarm
此时环境内的 python 和 pip 已经自动绑定为 3.11，直接安装 JiuwenSwarm

## 方式一：默认安装
pip install jiuwenswarm

## 方式二：使用国内镜像源（推荐）
# 清华源
pip install jiuwenswarm -i https://pypi.tuna.tsinghua.edu.cn/simple

# 阿里源
pip install jiuwenswarm -i https://mirrors.aliyun.com/pypi/simple/

$notice$ A new release of pip is available: 23.3.1 -> 26.1.2

$notice$ To update, run: pip install --upgrade pip

(jiuwenswarm_env) $root@openJiuwen \~$ # pip --version

pip 23.3.1 from /root/jiuwenswarm_env/lib64/python3.11/site-packages/pip (python 3.11)

(jiuwenswarm_env) $root@openJiuwen \~$ # pip install --upgrade pip

Requirement already satisfied: pip in ./jiuwenswarm_env/lib64/python3.11/site-packages (23.3.1)

Collecting pip

Downloading pip-26.1.2-py3-none-any.whl.metadata (4.6 kB)

Downloading pip-26.1.2-py3-none-any.whl (1.8 MB)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.8/1.8 MB 2.8 MB/s eta 0:00:00

Installing collected packages: pip

Attempting uninstall: pip

Found existing installation: pip 23.3.1

Uninstalling pip-23.3.1:

Successfully uninstalled pip-23.3.1

Successfully installed pip-26.1.2

(jiuwenswarm_env) $root@openJiuwen \~$ # pip --version

pip 26.1.2 from /root/jiuwenswarm_env/lib64/python3.11/site-packages/pip (python 3.11)

(jiuwenswarm_env) $root@openJiuwen \~$ #

5. 初始化JiuwenSwarm

bash 复制代码

# 初始化 JiuwenSwarm（首次启动）
jiuwenswarm-init

(jiuwenswarm_env) $root@openJiuwen \~$ # jiuwenswarm-init

$jiuwenswarm-init$ Initializing default workspace

$jiuwenswarm-init$ Workspace: /root/.jiuwenswarm

$jiuwenswarm-init$ 增量初始化：只添加缺失文件，不覆盖已有文件 / Incremental init: only adds missing files, preserves existing

$jiuwenswarm-init$ 此操作不可撤销 / This action cannot be undone.

$jiuwenswarm-init$ Do you want to continue? (yes/no): yes

$jiuwenswarm-init$ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

$jiuwenswarm-init$ 请选择默认语言 / Choose your default language

$jiuwenswarm-init$ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

$jiuwenswarm-init$ $1$ 中文（简体）

$jiuwenswarm-init$ → config: preferred_language: zh

$jiuwenswarm-init$ ────────────────────────────────────────────

$jiuwenswarm-init$ $2$ English

$jiuwenswarm-init$ → config: preferred_language: en

$jiuwenswarm-init$ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

$jiuwenswarm-init$ 须明确选择：1 / 2 / zh / en（无默认语言）

$jiuwenswarm-init$ 取消：no / n / q / cancel / 取消

$jiuwenswarm-init$ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

$jiuwenswarm-init$ 请输入选项 (1, 2, zh, en) 或 no 取消: 1

$jiuwenswarm-init$ 将使用语言 / Language: zh

$jiuwenswarm-init$ 初始化完成，文件变更如下：/ Init complete, file changes:

新增文件 / New files: 11

/root/.jiuwenswarm/agent/workspace/USER.md
/root/.jiuwenswarm/agent/workspace/agent-data.json
/root/.jiuwenswarm/config/.env
/root/.jiuwenswarm/config/builtin_rules.yaml
/root/.jiuwenswarm/config/config.yaml
/root/.jiuwenswarm/agent/workspace/AGENT.md
/root/.jiuwenswarm/agent/workspace/HEARTBEAT.md
/root/.jiuwenswarm/agent/workspace/IDENTITY.md
/root/.jiuwenswarm/agent/workspace/SOUL.md
/root/.jiuwenswarm/agent/workspace/memory/MEMORY.md

...等 1 个 / ...and 1 more

$jiuwenswarm-init$ initialized: /root/.jiuwenswarm

(jiuwenswarm_env) $root@openJiuwen \~$ #

6. 启动JiuwenSwarm

bash 复制代码

# 启动 JiuwenSwarm
jiuwenswarm-start

首次启动后，系统会自动创建配置目录 ~/.jiuwenswarm/。

7. 启动后验证

启动成功后，请按以下步骤验证安装是否正确：

打开 Web 端：在浏览器中访问 http://localhost:5173

进入配置页面：点击左侧导航栏「配置信息」

完成模型配置：参考配置信息完成模型 API 配置

验证安装成功：

Web 页面可正常访问

完成模型配置后可进行一次基础对话

7. 编写本地启动脚本

在实际的生产或长期运行环境中，每次启动都需要手动输入"激活环境 -> 启动服务"两步操作，略显繁琐。你可以参考官方的工程化实践，编写一个本地的启动脚本，把虚拟环境和启动命令绑定在一起。

例如，在桌面创建一个 start.sh 脚本：在脚本中写入如下内容：

bash 复制代码

#!/bin/bash
# 启动 jiuwenswarm 服务

echo "正在启动 jiuwenswarm..."
echo "----------------------------------------"

# 激活虚拟环境
source ~/jiuwenswarm_env/bin/activate

# 启动服务
jiuwenswarm-start

# 如果服务退出，暂停一下让用户看到输出
echo "----------------------------------------"
echo "服务已停止，按任意键关闭此窗口..."
read -n 1

或者直接使用下面的命令来创建脚本：

bash 复制代码

cat << 'EOF' > ~/Desktop/start.sh
#!/usr/bin/env bash

# 1. 从用户主目录开始，自动查找名为 jiuwenswarm_env (下划线) 的虚拟环境
VENV_DIR=$(find ~ -maxdepth 2 -type d -name "jiuwenswarm_env" -print -quit 2>/dev/null)

# 2. 检查是否找到了该目录
if [ -z "$VENV_DIR" ]; then
    echo "❌ 错误：未在系统中找到名为 'jiuwenswarm_env' 的虚拟环境！"
    exit 1
fi

# 3. 检查激活文件是否存在
ACTIVATE_SCRIPT="$VENV_DIR/bin/activate"
if [ ! -f "$ACTIVATE_SCRIPT" ]; then
    echo "❌ 错误：找到了虚拟环境目录，但缺少激活文件：$ACTIVATE_SCRIPT"
    exit 1
fi

echo "✅ 正在激活虚拟环境：$VENV_DIR"
source "$ACTIVATE_SCRIPT"

# 4. 启动 JiuwenSwarm 服务
exec jiuwenswarm-start "$@"
EOF

# 赋予执行权限
chmod +x ~/Desktop/start.sh

'EOF' 的单引号非常重要：它告诉 Shell 不要解析脚本内容中的特殊字符（如 ROOTDIR、ROOT_DIR、ROOTDIR、@
等）。如果不加单引号，Shell 会在写入文件时尝试计算这些变量的值，导致脚本内容被破坏。
> start.sh：表示将内容写入当前目录下的 start.sh 文件。如果文件已存在，会被覆盖；如果想追加内容，可以使用 >>。
赋予执行权限：写入完成后，脚本默认是没有执行权限的，你需要运行以下命令赋予权限：

bash 复制代码

chmod +x start.sh

脚本中：exec jiuwenswarm-start "@"换成jiuwenswarm−start有什么区别？这是一个非常专业且切中要害的问题！在Shell脚本中，execjiuwenswarm−start"@"换成 jiuwenswarm-start 有什么区别？这是一个非常专业且切中要害的问题！在 Shell 脚本中，exec jiuwenswarm-start "@"换成jiuwenswarm−start有什么区别？这是一个非常专业且切中要害的问题！在Shell脚本中，execjiuwenswarm−start"@" 和直接写 jiuwenswarm-start 有着本质的区别。它们的核心差异体现在进程替换和参数传递两个方面：

exec 的作用（进程替换）
不使用 exec：Shell 会创建一个新的子进程来运行 jiuwenswarm-start。当前的 start.sh 脚本进程会一直等待，直到 jiuwenswarm-start 运行结束。
使用 exec：Shell 不会创建新进程，而是直接用 jiuwenswarm-start 这个程序替换掉当前的 start.sh 进程。start.sh 脚本在启动该命令后，自身的生命周期就结束了。
💡 为什么推荐用 exec？
对于启动后台服务或守护进程来说，使用 exec 可以节省一个不必要的 Shell 进程。同时，当你在终端按下 Ctrl+C 发送中断信号时，信号会直接发送给 jiuwenswarm-start 进程，而不是被中间的 Shell 脚本拦截，这使得服务的停止和信号管理更加干净、直接。
"@"的作用（参数透传）不带"@" 的作用（参数透传）不带 "@"的作用（参数透传）不带"@"：无论你在运行启动脚本时带了什么参数，jiuwenswarm-start 都不会接收到任何参数。
带 "@"：它代表"将启动脚本接收到的所有参数，原封不动地传递给jiuwenswarm−start"。并且加上双引号"@"：它代表"将启动脚本接收到的所有参数，原封不动地传递给 jiuwenswarm-start"。并且加上双引号 "@"：它代表"将启动脚本接收到的所有参数，原封不动地传递给jiuwenswarm−start"。并且加上双引号"@" 可以确保即使参数中包含空格，也能被正确识别为独立的参数。
💡 举个例子：
假设 jiuwenswarm-start 支持自定义配置文件参数 --config my.conf。
如果你写的是 exec jiuwenswarm-start "@"，当你运行./start.sh−−configmy.conf时，−−configmy.conf会完美传递给底层程序。如果你只写了jiuwenswarm−start，这个参数就会在脚本这一层丢失。总结execjiuwenswarm−start"@"，当你运行 ./start.sh --config my.conf 时，--config my.conf 会完美传递给底层程序。如果你只写了 jiuwenswarm-start，这个参数就会在脚本这一层丢失。总结 exec jiuwenswarm-start "@"，当你运行./start.sh−−configmy.conf时，−−configmy.conf会完美传递给底层程序。如果你只写了jiuwenswarm−start，这个参数就会在脚本这一层丢失。总结execjiuwenswarm−start"@" 是一种非常标准且专业的工程化写法。它既保证了服务启动时进程树的干净，又保留了未来为启动命令扩展参数的灵活性。
如果你确定 JiuwenSwarm 永远不需要任何额外的启动参数，且不在乎多占用一个 Shell 进程，那么直接写 jiuwenswarm-start 也能跑起来，但加上 exec ... "$@" 绝对是更严谨、更优雅的做法。
参考资料：
https://gitcode.com/openJiuwen/jiuwenswarm/blob/develop/docs/zh/安装指南.md