openJiuwen AgentOS 私有化部署与多智能体编排

企业级 AgentOS 的价值不在于“能跑一个智能体”，而在于把几十上百个智能体统一注册、编排、授权、审计。这篇教程带你把 openJiuwen 的 AgentOS 在一台内网服务器上跑起来，并完成从环境搭建到AI 词典：多智能体编排">多智能体编排、权限管控的完整链路。

> 说明：下文涉及仓库地址、包名、环境变量名、接口路径、端口、配置文件结构等，会随版本变化。请以官方文档与仓库当前版本的 .env.example、docs/ 目录为准。文中用 <...> 表示需要你替换成实际值的内容。

适用场景

这套方案适合两类团队：一是希望把大模型能力私有化落地、数据不出内网的中大型企业的平台/运维团队；二是已经零散地写了几个 Agent 脚本，想让它们从“个人脚本”升级为“可被多个业务线复用、可被审计的服务”的研发团队。部署完成后，你会得到一个统一入口：智能体注册中心 + 编排引擎 + 租户与角色权限 + 运行日志。

环境与前置条件

前置动作：确认能访问官方代码仓库、准备好一个可用的模型服务端点（自建推理服务或统一模型网关均可）、准备一个用于登录后台的管理员初始口令。

分步骤部署

第 1 步：准备主机基础依赖

```bash

sudo apt-get update

sudo apt-get install -y git curl make gcc g++ python3 python3-venv python3-pip

```

安装完成后验证：

```bash

git --version && python3 --version && docker version

```

三条命令都能打印出版本号，说明基础工具链齐了。若 docker version 报权限错误，把当前用户加入 docker 组后重新登录：

```bash

sudo usermod -aG docker $USER

```

第 2 步：获取源码并确认目录结构

```bash

export AGENTOS_HOME=$HOME/agentos

git clone <官方仓库地址> "$AGENTOS_HOME"

cd "$AGENTOS_HOME"

ls -la

```

仓库地址从官方文档或代码托管页获取。进入目录后先看清楚三样东西：.env.example（配置模板）、docker-compose*.yml 或 deploy/ 目录（容器编排文件）、scripts/ 目录（初始化脚本）。这三处的实际名称决定了后面几步怎么写，不要跳过。

第 3 步：创建虚拟环境并安装依赖

```bash

cd "$AGENTOS_HOME"

python3 -m venv .venv

source .venv/bin/activate

pip install -U pip setuptools wheel

pip install -r requirements.txt

```

最后一行如果没有出现 ERROR: 且以 Successfully installed ... 结尾，就算成功。若仓库采用前后端分离结构，前端目录（通常是 web/ 或 frontend/）需要单独走 npm 安装：

```bash

cd web && npm install && npm run build

```

第 4 步：写配置文件

```bash

cp .env.example .env

```

然后用编辑器打开 .env，重点确认这几类配置（变量名以模板为准）：

• 服务监听：HOST=0.0.0.0、PORT=<平台端口>
• 数据库连接串：指向本机或独立数据库实例
• 缓存连接串：指向 Redis 实例
• 模型接入：模型服务的 BASE_URL、API_KEY、默认模型名
• 管理凭据：管理员初始账号与令牌，务必改成强口令

生产环境建议把 .env 权限收紧：chmod 600 .env。

第 5 步：拉起依赖组件

如果仓库自带 Compose 文件，用最容易的方式把数据库、缓存、向量库起起来：

```bash

docker compose -f <compose 文件名> up -d postgres redis

docker compose ps

```

STATUS 一列显示 Up（或 healthy）即正常。首次启动数据库需要十几秒，用日志确认：

```bash

docker compose logs --tail=50 postgres

```

看到 database system is ready to accept connections 就可以继续。

第 6 步：初始化数据库

先看脚本目录里有哪些入口：

```bash

ls scripts/

```

常见的初始化动作是建表 + 写入默认租户与管理员，例如执行迁移与初始化脚本：

```bash

python scripts/<初始化脚本>.py

若仓库使用迁移工具，则按官方文档执行对应 upgrade 命令

```

成功时会输出建表完成、默认管理员创建完成一类的日志。这一步只做一次，重复执行前先确认脚本是否幂等。

第 7 步：启动 AgentOS 服务

容器化方式（推荐用于生产）：

```bash

docker compose -f <compose 文件名> up -d

docker compose ps

docker compose logs -f <平台服务名>

```

源码方式（适合调试）：

```bash

source .venv/bin/activate

bash scripts/<启动脚本>.sh

或按官方文档给出的启动命令

```

看到服务监听端口的日志（如 Uvicorn running on http://0.0.0.0:<port>）即启动成功。建议把平台服务交给 systemd 或 Compose 的 restart: always 托管，避免 SSH 断开后进程消失。

第 8 步：注册第一个智能体

先在后台或通过接口创建一个访问令牌，然后调用注册接口：

```bash

export AGENTOS_TOKEN=<你的令牌>

export AGENTOS_API=http://127.0.0.1:<平台端口>

curl -s -X POST "$AGENTOS_API/api/v1/agents" \

-H "Authorization: Bearer $AGENTOS_TOKEN" \

-H "Content-Type: application/json" \

-d '{

"name": "kb-qa",

"description": "内部知识库问答",

"type": "http",

"endpoint": "http://127.0.0.1:<你的智能体端口>/invoke"

}'

```

接口路径与字段名以官方 API 文档为准。返回体里带上智能体 ID 即注册成功。注册的“智能体”本质上是一个可被调用的服务端点，你的既有脚本只要包一层 HTTP 接口就能接进来。

第 9 步：编排多智能体

编排通常用一份 YAML/JSON 描述节点与依赖关系。以“合同审阅”为例，思路是：抽取 → 条款风险审查 → 知识库比对 → 汇总。

```yaml

name: contract-review

nodes:

• id: extract

type: agent

agent: doc-extractor

• id: risk

type: agent

agent: risk-reviewer

inputs: [extract.output]

• id: check

type: agent

agent: kb-qa

inputs: [risk.output]

• id: summary

type: agent

agent: report-writer

inputs: [check.output]

```

字段名以官方 schema 为准。写得好的编排有三个特征：每个节点职责单一、节点之间只通过明确的输入输出传递数据、失败节点有重试或兜底分支。定义好后用接口或后台导入这份编排：

```bash

curl -s -X POST "$AGENTOS_API/api/v1/workflows" \

-H "Authorization: Bearer $AGENTOS_TOKEN" \

-H "Content-Type: application/json" \

-d @contract-review.yaml

```

第 10 步：把权限收紧

企业落地的分水岭就在这一步。建议按下面的顺序配置：

1. 租户隔离：每个业务线一个租户，智能体、编排、会话记录都挂在租户下，默认互相不可见。

2. 角色划分：至少区分平台管理员（管全局配置与密钥）、租户管理员（管本租户智能体与编排）、普通使用者（只能调用被授权的编排）。

3. 智能体级授权：把智能体显式授权给租户或角色，而不是默认全员可用。

4. 工具与数据权限：智能体能调用的外部工具（数据库查询、文件读取、内网接口）单独授权，避免一个问答机器人顺手把整张表读走。

5. 密钥与配额：给每个租户分配独立的模型调用凭据和调用上限，超限时触发告警而不是直接静默失败。

配置完成后，用一个低权限账号登录，确认它看不到未授权的智能体——这是权限是否真的生效的最直接验证。

验证部署是否成功

按顺序执行，四步都通过即可认为部署完成：

```bash

1. 健康检查

curl -s "$AGENTOS_API/healthz"

2. 智能体列表

curl -s -H "Authorization: Bearer $AGENTOS_TOKEN" \

"$AGENTOS_API/api/v1/agents" | head -c 500

3. 跑一次编排

curl -s -X POST "$AGENTOS_API/api/v1/workflows/contract-review/runs" \

-H "Authorization: Bearer $AGENTOS_TOKEN" \

-H "Content-Type: application/json" \

-d '{"input": "请审阅这份合同的付款条款"}'

4. 查看运行记录

curl -s -H "Authorization: Bearer $AGENTOS_TOKEN" \

"$AGENTOS_API/api/v1/runs?limit=5"

```

预期结果：第 1 步返回形如 {"status":"ok"} 的健康状态；第 2 步的返回里能看到刚注册的 kb-qa；第 3 步返回一个运行 ID；第 4 步能查到这次运行的状态为成功或失败（失败也算链路通了，说明要去看具体节点的错误信息）。另外打开后台页面，用管理员账号登录，能看到租户、智能体、编排、运行记录四个列表都有数据。

常见报错与解决

1. Error: [Errno 98] Address already in use

→ 原因：平台端口或依赖组件端口被其他进程占用，常见于上次异常退出后容器未清理，或同机部署了多个服务。

→ 解决：

```bash

sudo ss -lntp | grep <端口号>

docker compose -f <compose 文件名> down

或修改 .env 中的端口后重新启动

```

2. sqlalchemy.exc.OperationalError: could not connect to server: Connection refused

→ 原因：数据库还没起来，或 .env 里的连接串主机写成了 localhost 但服务实际跑在容器里（容器内的 localhost 指向容器自身）。

→ 解决：

```bash

docker compose ps

docker compose logs --tail=50 postgres

容器化部署时，把连接串主机改为 compose 中的服务名，如 postgres

```

3. pip install 过程中出现 error: command 'gcc' failed

→ 原因：某个依赖包含 C 扩展，但主机缺少编译工具链或对应的开发库。

→ 解决：

```bash

sudo apt-get install -y build-essential python3-dev libpq-dev

pip install -U pip setuptools wheel

pip install -r requirements.txt

内网环境优先配置离线源或私有 PyPI 镜像

```

4. 接口返回 401 Unauthorized 或 403 Forbidden

→ 原因：令牌缺失/过期，或该账号所属角色没有被授权访问这个智能体或编排。

→ 解决：

```bash

先确认请求头带了令牌

curl -s -H "Authorization: Bearer $AGENTOS_TOKEN" "$AGENTOS_API/api/v1/agents"

仍为 403 则进后台检查该角色的智能体授权与租户归属

```

5. 编排运行卡住或超时

→ 原因：下游智能体端点不可达、模型服务响应慢、节点没有设置超时。

→ 解决：

```bash

curl -sS -m 10 http://127.0.0.1:<你的智能体端口>/invoke

docker compose logs --tail=100 <平台服务名>

在编排定义中为每个节点补上 timeout 与 retry 配置

```

后续维护

备份：至少备份三样东西——关系型数据库（如 pg_dump 导出全库）、平台配置文件与 .env、向量库数据目录。写成定时任务，并把备份文件复制到另一台机器；只备份不验证等于没备份，定期做一次恢复演练。

升级：升级前先备份、先读官方 release notes 确认是否有破坏性变更与数据库迁移脚本；顺序是停服务 → 拉新代码/新镜像 → 执行依赖安装与迁移 → 启动 → 跑一遍上面的四步验证。不要在生产环境直接改代码目录，用镜像或独立目录做灰度。

日志：平台日志、依赖组件日志、编排运行日志分开存放，统一用 docker compose logs 或日志采集组件收走，配置轮转避免把磁盘写满。编排运行日志建议保留足够长的周期，合规场景下审计日志需要更久。

监控：暴露的 /metrics 或健康检查端点接入 Prometheus + Grafana，重点盯四个指标：接口错误率、编排运行成功率、单次运行耗时、模型调用配额消耗。对“连续失败”“配额接近上限”“依赖组件掉线”设置告警，落到值班群。

密钥轮换：模型 API Key、平台管理员令牌、租户凭据都要有轮换计划，轮换后同步更新 .env 并重启服务，同时排查是否有硬编码在代码或编排文件里的密钥。