Blade 全家桶离线部署指南

生成时间：2026-06-28 | 来源机器：bladedev ()

一、部署包概览

部署包 box-deploy.tar.gz（约 192MB）包含以下组件的完整配置和运行时数据：

组件	镜像	端口	作用
blade-oauth	`registry.cn-beijing.aliyuncs.com/bladeai/blade-oauth:v0.4.2`	19000	统一认证中心（OAuth / 证书校验）
gitea	`docker.gitea.com/gitea:1.26.2`	30030	Git 服务（技能仓库存储）
skill-registry	`registry.cn-beijing.aliyuncs.com/bladeai/skill-registry:v0.4.1`	8010	能力中心（技能管理）
blade-os	`registry.cn-beijing.aliyuncs.com/bladeai/blade-os:v0.2.35`	80	操作系统（Web 桌面入口）
blade-agent	`registry.cn-beijing.aliyuncs.com/bladeai/blade-agent:v0.5.28`	8020	智能助手（对话 + 软件工厂）
blade-sandbox	`registry.cn-beijing.aliyuncs.com/bladeai/blade-sandbox:v0.0.19`	动态	代码沙箱（blade-agent 运行时按需创建）

二、前置条件

Linux 系统（推荐 Ubuntu 22.04 / 24.04）
Docker Engine 24+，支持 docker compose（v2）
root 权限
端口 80, 8010, 8020, 19000, 30030 未被占用
已将 6 个镜像传入离线环境并 docker load 完毕

三、镜像离线导入

在有网络的机器上拉取并导出：

# 拉取全部镜像
docker pull registry.cn-beijing.aliyuncs.com/bladeai/blade-os:v0.2.35
docker pull registry.cn-beijing.aliyuncs.com/bladeai/blade-agent:v0.5.28
docker pull registry.cn-beijing.aliyuncs.com/bladeai/blade-sandbox:v0.0.19
docker pull registry.cn-beijing.aliyuncs.com/bladeai/skill-registry:v0.4.1
docker pull registry.cn-beijing.aliyuncs.com/bladeai/blade-oauth:v0.4.2
docker pull docker.gitea.com/gitea:1.26.2

# 打包为单个 tar（约 3-5 GB）
docker save \
  registry.cn-beijing.aliyuncs.com/bladeai/blade-os:v0.2.35 \
  registry.cn-beijing.aliyuncs.com/bladeai/blade-agent:v0.5.28 \
  registry.cn-beijing.aliyuncs.com/bladeai/blade-sandbox:v0.0.19 \
  registry.cn-beijing.aliyuncs.com/bladeai/skill-registry:v0.4.1 \
  registry.cn-beijing.aliyuncs.com/bladeai/blade-oauth:v0.4.2 \
  docker.gitea.com/gitea:1.26.2 \
  -o blade-images.tar

在离线目标机器上导入：

docker load -i blade-images.tar

四、部署步骤

步骤 1：解压部署包

mkdir -p /opt/box-deploy
tar xzf box-deploy.tar.gz --strip-components=1 -C /opt/box-deploy/

步骤 2：运行初始化脚本

脚本会自动替换所有配置文件中的 IP 地址，并配置大模型参数。

# 基本用法（仅指定 IP，LLM 用默认值）
sudo bash /opt/box-deploy/setup.sh 192.168.x.x

# 完整用法（同时配置 LLM）
sudo bash /opt/box-deploy/setup.sh 192.168.x.x \
  http://192.168.x.x:8000/v1 \
  sk-your-api-key \
  qwen2.5-72b

参数说明：

第 1 个参数（必填）：本机 IP，所有服务的访问地址
第 2 个参数（可选）：大模型 API 地址（OpenAI 兼容格式），默认 http://<本机IP>:30000/v1
第 3 个参数（可选）：大模型 API Key，默认 EMPTY
第 4 个参数（可选）：大模型 Model ID，默认 z-ai/glm-5.2

步骤 3：启动全部服务

sudo bash /opt/box-deploy/start-all.sh

或手动按顺序启动（必须按此顺序，因为存在依赖关系）：

# 1. 认证中心（其他服务都依赖它验签）
cd /opt/box-deploy/system/blade-oauth && docker compose up -d

# 2. Git 服务（skill-registry 依赖它存技能）
cd /opt/box-deploy/gitea && docker compose up -d

# 3. 能力中心
cd /opt/box-deploy/agent/skill_registry && docker compose up -d

# 4. 操作系统（Web 桌面）
cd /opt/box-deploy/agent/blade-os && docker compose up -d

# 5. 智能助手
cd /opt/box-deploy/agent/blade && docker compose up -d

步骤 4：验证

# 查看所有容器状态
docker ps --format 'table {{.Names}}\t{{.Status}}'

# 逐个检查健康状态
curl -s http://localhost:19000/health    # blade-oauth
curl -s http://localhost:30030/api/healthz  # gitea
curl -s http://localhost:8010/api/health  # skill-registry
curl -s http://localhost:80/health        # blade-os
curl -s http://localhost:8020/api/health  # blade-agent

全部返回正常后，浏览器访问 http://<本机IP> 即可进入 Blade OS 桌面。

五、压缩包中的修改记录

以下是相对于源机器 (bladedev ) 上 /opt/box-deploy/ 的变更：

变更类型	说明
删除数据	`agent/blade/workspace/.sessions.db` 中的 `llm_payloads` 表已清空并 VACUUM。原因：该表存储了所有 LLM 调用的完整 request/response（2820 条，共 735MB），是运行时日志，不影响部署。清除后数据库从 704MB 缩小到 2.7MB。其余表（sessions, memories, agent_board 等）均保留。
排除目录	所有 `node_modules/` 目录已排除（主要在 workspace 的会话产物中，约 520MB）。 agent 运行时会自动 `npm install` 重建。
新增文件	`setup.sh` — 初始化脚本，替换 IP + 配置 LLM `start-all.sh` — 一键启动全部服务 `stop-all.sh` — 一键停止全部服务

setup.sh 会修改的文件

setup.sh 运行时会用目标机器 IP 替换以下文件中的：

文件	涉及的配置项
`agent/blade/docker-compose.yaml`	BLADE_OS_PATH, BASE_URL, API_KEY, MODEL_ID
`agent/blade-os/docker-compose.yaml`	GRAFANA_PUBLIC_URL
`agent/blade-os/.env`	FRONTEND_BASE_URL, CORS_ALLOW_ORIGINS
`agent/blade-os/agentos/discovery.json`	llm.baseURL, mirrors.npm, mirrors.pip
`agent/blade-os/agentos/agentos.yaml`	llm.baseURL, mirrors.npm, mirrors.pip
`gitea/docker-compose.yaml`	GITEA__server__DOMAIN, GITEA__server__ROOT_URL
`system/blade-oauth/docker-compose.yaml`	--issuer URL

六、目录结构说明

/opt/box-deploy/
├── setup.sh              # 初始化脚本（新增）
├── start-all.sh          # 一键启动（新增）
├── stop-all.sh           # 一键停止（新增）
├── system/
│   └── blade-oauth/      # 统一认证
│       ├── docker-compose.yaml
│       └── data/          # SQLite 数据 + bootstrap token
├── gitea/
│   ├── docker-compose.yaml
│   └── data/              # Git 仓库 + Gitea 数据库
├── agent/
│   ├── blade-os/          # 操作系统
│   │   ├── docker-compose.yaml
│   │   ├── .env
│   │   ├── oauth_config.yaml
│   │   ├── app_configs.yaml   # 桌面应用清单
│   │   └── agentos/           # discovery + LLM 配置
│   ├── blade/             # 智能助手
│   │   ├── docker-compose.yaml
│   │   ├── oauth_config.yaml
│   │   ├── example_sessions/  # 展示用例（6 个 zip）
│   │   ├── frontend_config/
│   │   └── workspace/         # 会话运行时数据（含 .sessions.db）
│   └── skill_registry/    # 能力中心
│       ├── docker-compose.yaml
│       ├── oauth_config.yaml
│       ├── data/              # 预装技能
│       └── bh-data/           # 用户态持久化
├── host_vars/             # Ansible 主机变量（仅参考）
└── obs/                   # 可观测性配置（当前为空）

七、常见问题

Q: 服务启动后页面打不开？

检查防火墙是否放行了 80, 8010, 8020, 19000, 30030 端口。Ubuntu 上：ufw allow 80,8010,8020,19000,30030/tcp

Q: blade-agent 启动了但对话没有回复？

检查 LLM 配置。docker logs blade-agent 看是否有模型连接错误。需要在离线环境中自行部署一个 OpenAI 兼容的 LLM 服务（如 vLLM），然后在 setup.sh 中指定地址。

Q: skill-registry 启动失败？

skill-registry 依赖 gitea。确保 gitea 已经启动且健康：curl http://localhost:30030/api/healthz。另外检查 /opt/box-deploy/agent/skill_registry/gitea_admin_token 文件是否存在。

Q: 需要更换 IP 怎么办？

停止所有服务后重新运行 setup.sh，传入新 IP。注意：脚本中硬编码了原始 IP 作为查找目标，如果已经替换过一次，需要手动用 sed 替换或重新解压。

Q: discovery.json 里的 npm/pip 镜像源指向哪里？

默认指向 http://<本机IP>:30020（Nexus 私源）。如果离线环境没有 Nexus，需要自行修改或搭建。sandbox 里的 pip/npm 源由 blade-agent compose 中的 SANDBOX_PIP_INDEX_URL 和 SANDBOX_NPM_CONFIG_REGISTRY 控制，当前指向公网镜像（清华 / npmmirror），离线环境需改为内网源。

八、端口清单

端口	服务	协议	说明
80	blade-os	HTTP	Web 桌面入口，用户主访问地址
8010	skill-registry	HTTP	能力中心 API + 前端
8020	blade-agent	HTTP	智能助手 API + 前端
19000	blade-oauth	HTTP	OAuth 认证 + 证书校验 + 用户控制台
30030	gitea	HTTP	Git 服务（内部使用，一般不对外暴露）