安装部署

借助于官方提供的 nuwax-cli 命令工具，来快速本地部署服务。视频教程(抖音)视频教程(B站)

⚠️ 重要提示：本部署文档仅部署智能体平台核心服务。部分功能需要额外部署对应的组件服务：
技能管理、通用型智能体 → 智能体电脑部署指南
文档解析（PDF / Word / Excel 等转 Markdown） → 文档解析服务部署
语音转写 / 语音合成 → 语音转写服务部署

🚀 快速开始

环境准备

系统要求

平台的硬件需求要根据实际并发量来决定，建议最低配置（1-2人长期使用）要求如下：

系统要求： Ubuntu24.04LTS或以上版本，macOS 10.15+（Windows 10/11后续支持）
配置要求： 4核CPU、16G内存、200G或以上硬盘
环境要求： docker、docker compose V2 环境 docker安装指南
增量配置： 每多一个并发，需增量配置2核CPU、4G内存、50G硬盘，如：需要增加10人并发，需增量配置 20核CPU、40G内存、500G硬盘

支持的平台

Linux: x86_64, ARM64
- Ubuntu 22.04 LTS（推荐）
- 推荐使用阿里云镜像
macOS: Intel, Apple Silicon (M1/M2), Universal
- macOS 10.15 (Catalina) 及以上版本
- 安装docker推荐使用OrbStack（个人免费，性能更佳）
- 确保 OrbStack 或 Docker Desktop 已启动
- 首次运行可能需要允许未知开发者：系统偏好设置 → 安全性与隐私

部署

目前支持以下部署方式：一键自动部署、手动部署和离网部署（离线部署），可根据网络环境和实际情况选择部署方式。

一键自动部署[推荐]

执行以下命令即可完成一键部署，Linux和macOS均可使用，区别在于Linux将docker安装也包含在内，macOS需要先安装docker，如果执行不成功，请参考手动部署。

bash

bash <(wget -qO- https://nuwa-packages.oss-rg-china-mainland.aliyuncs.com/script/nuwax_deploy.sh)

手动部署

客户端下载

客户端仅作为运维工具，不包含平台软件包

nuwax-cli-linux-amd64.tar.gz
nuwax-cli-linux-arm64.tar.gz
nuwax-cli-macos-universal.tar.gz（amd64&arm64）

执行命令完成部署

安装时，当前用户需要有 Docker 权限，验证方式docker ps，查看是否有权限问题，碰到权限问题，可以使用 sudo 权限运行。

Linux / macOS

1. 创建工作目录

bash

 mkdir nuwax_deploy
 cd nuwax_deploy

2. 下载客户端运维工具（根据系统执行下载命令）

X86下载命令

bash

wget https://nuwa-packages.oss-rg-china-mainland.aliyuncs.com/nuwax-cli/v1.0.130/nuwax-cli-linux-amd64.tar.gz

ARM下载命令

bash

wget https://nuwa-packages.oss-rg-china-mainland.aliyuncs.com/nuwax-cli/v1.0.130/nuwax-cli-linux-arm64.tar.gz

macOS下载命令

bash

wget https://nuwa-packages.oss-rg-china-mainland.aliyuncs.com/nuwax-cli/v1.0.130/nuwax-cli-macos-universal.tar.gz

3. 将下载的客户端文件解压到工作目录

X86解压命令

bash

tar -xzf nuwax-cli-linux-amd64.tar.gz

ARM解压命令

bash

tar -xzf nuwax-cli-linux-arm64.tar.gz

macOS解压命令

bash

tar -xzf nuwax-cli-macos-universal.tar.gz

4. 添加执行权限

bash

chmod +x nuwax-cli

5. 初始化

bash

./nuwax-cli init

6. 部署

bash

./nuwax-cli auto-upgrade-deploy run

正常情况下，执行完命令后，服务就已经部署好了。如需指定 project name，或者访问端口(默认80)，可以使用以下命令：./nuwax-cli auto-upgrade-deploy run --port 8091 -p nuwax

7. 更新 建议定期升级下命令行工具自身,再对应工作目录下执行命令:

bash

./nuwax-cli check-update install

离网部署（离线部署）

适用于目标服务器无法访问互联网的场景（如内网环境、涉密网络等）。离网部署需要在一台有网络的机器上提前准备好部署包，然后通过 U 盘、光盘等方式将部署包传输到目标服务器上进行部署。

前提条件

目标服务器已安装 Docker 和 Docker Compose V2（参考 Docker环境安装）
已在目标服务器上完成 nuwax-cli 客户端的下载、解压和初始化（参考手动部署中的步骤 1~5）
已在有网络的机器上下载好对应版本的服务部署包（.zip 或 .tar.gz 格式）

获取离线部署包： 在有网络的机器上下载完整服务包，详细步骤见下方。

步骤一：在有网络的机器上下载部署包

1. 准备 nuwax-cli 客户端

在有网络的机器上，按照手动部署中的步骤 1~5，完成 nuwax-cli 的下载、解压和初始化。

2. 下载完整服务包

bash

./nuwax-cli upgrade download

下载完成后，部署包会保存在工作目录下的缓存目录中。目录结构如下：

./cacheDuckData/download/
  └── {版本号}/              # 例如 0.0.74
      └── full/
          ├── docker-x86_64.zip        # x86_64 架构部署包
          └── docker-x86_64.zip.hash   # 校验文件

ARM 架构的机器下载的文件名为 docker-aarch64.zip，目录结构相同：

./cacheDuckData/download/
  └── 0.0.74/
      └── full/
          ├── docker-aarch64.zip
          └── docker-aarch64.zip.hash

3. 确认部署包文件

bash

# 查看下载好的部署包（以 x86_64 为例）
ls -lh ./cacheDuckData/download/0.0.74/full/docker-x86_64.zip

提示： 部署包文件名格式为 docker-{架构}.{格式}，版本号体现在目录路径中而非文件名中。下载完成后只需将 .zip 或 .tar.gz 文件拷贝出来即可，.hash 校验文件无需一起传输。

操作步骤

1. 将部署包传输到目标服务器

将下载好的服务部署包（如 docker-x86_64.zip）通过 U 盘、SCP 或其他方式拷贝到目标服务器的工作目录下（即 nuwax-cli 所在目录）。

2. 执行离线部署命令

bash

./nuwax-cli auto-upgrade-deploy offline-deploy \
  --archive ./docker-x86_64.zip \
  --version 0.0.74

参数说明：

参数	必填	说明
`--archive`	是	本地部署包文件路径（支持 `.zip` 或 `.tar.gz` 格式）
`--version`	是	目标部署版本号
`--port`	否	前端服务端口，默认 80
`--config`	否	自定义 docker-compose 配置文件路径
`-p, --project`	否	指定 Docker Compose 项目名称

3. 指定端口部署（可选）

如需指定访问端口或项目名称：

bash

./nuwax-cli auto-upgrade-deploy offline-deploy \
  --archive ./docker-x86_64.zip \
  --version 0.0.74 \
  --port 8091 \
  -p nuwax

离网升级

如果已部署过旧版本，需要升级到新版本，操作步骤相同：将新版本的部署包传输到目标服务器，然后执行 offline-deploy 命令即可。命令会自动完成以下操作：

停止当前运行的服务
备份现有 docker/ 目录（用户数据目录如 data、upload 等会自动保留）
解压新版本部署包
更新配置并重新启动服务

bash

# 示例：从 0.0.74 升级到 0.0.75
./nuwax-cli auto-upgrade-deploy offline-deploy \
  --archive ./docker-x86_64.zip \
  --version 0.0.75

注意： 离线部署不会联网检查版本或下载文件，也不会执行数据库 SQL 差异升级。如果版本升级涉及数据库结构变更，请确认部署包中已包含对应的 SQL 初始化脚本。

访问服务

部署完成后，在浏览器访问：http://localhost或者公网IP地址，即可访问服务。

使用默认管理员账号登录：admin@nuwax.com 密码：123456

注：如果80端口被占用，可以成功部署，但访问页面会有问题，可以部署指定端口，比如：

bash

 ./nuwax-cli auto-upgrade-deploy run --port 8091

重要配置

登录后请及时修改：

1. 智能体客户端端口配置【重要】

如果需要支持你的用户使用智能体客户端，请将 6443端口 开放能被客户端访问：

该端口用于智能体客户端与平台的通信
确保防火墙规则已放行此端口
如果使用云服务器，请在安全组中添加6443端口的入站规则
检查端口是否开放：netstat -tlnp | grep 6443

注意：如果不开放此端口，用户将无法使用智能体客户端连接到平台。

2. 管理员密码

首次登录后请立即修改默认管理员密码，确保系统安全。

3. 站点信息配置

配置站点的基本信息，包括站点名称、Logo、描述等。

alt text

4. 邮件服务配置

配置邮件服务，用于用户登录注册时收取验证码。

alt text

智能体电脑部署【可选】

智能体电脑为可选部署项，部署后可在智能体平台创建通用型智能体。

详细部署文档请参考：智能体电脑部署指南

部署故障排查

如果自动部署失败，可以再尝试一次执行自动部署执行：

初始化配置 同一个工作目录下，只需执行一次初始化，如果重复执行了也没关系，不用担心重复初始化导致问题，除非你增加参数: --force 强制重新初始化，会进行覆盖初始化动作。
bash
```
./nuwax-cli init
```
自动部署 会自动检测下载最新的应用服务，然后升级应用服务进行部署。
bash
```
./nuwax-cli  auto-upgrade-deploy run
```
重启服务的话
bash
```
./nuwax-cli docker-service restart
```

常用管理命令

服务管理

启动服务：./nuwax-cli docker-service start
停止服务：./nuwax-cli docker-service stop
重启服务：./nuwax-cli docker-service restart
检查状态：./nuwax-cli docker-service status

备份管理

备份服务，需要停止Docker应用服务器，建议业务低谷时，操作备份。

停止服务命令

bash

./nuwax-cli docker-service stop

一键备份
- 手动执行一次备份：
bash
```
./nuwax-cli auto-backup run
```
- 列出所有备份：
bash
```
./nuwax-cli list-backups
```
- 从备份恢复：
bash
```
./nuwax-cli rollback [BACKUP_ID]
```

升级管理

应用服务升级，使用命令./nuwax-cli auto-upgrade-deploy run 会自动检测下载新版本，自动部署。

如果之前下载过应用服务，但认为下载的文件有损坏，可以强制使用重新下载。

upgrade 命令不会自动安装,用于检查有无最新版本应用文件使用，和下载应用服务文件。

强制重新下载：
bash
```
./nuwax-cli upgrade --force
```

注：如果之前的数据不想要了，全新部署，可以删除工作目录下的: docker 文件夹，然后执行 ./nuwax-cli auto-upgrade-deploy run 命令自动部署。

一次升级完整命令如下: 1.检查运维客户端是否有新版本并更新

shell

./nuwax-cli check-update install

2.更新应用服务

shell

./nuwax-cli auto-upgrade-deploy run

数据库表结构升级

升级到新版本时，MySQL 的库表结构由 auto-upgrade-deploy run 自动完成，一般不需要人工干预。原理是 Live Diff：命令不比对"你上次装的是哪个版本"，而是先只启动 MySQL 服务，读取线上每张表的真实结构（SHOW CREATE TABLE），与部署包内的目标结构模板逐表、逐列、逐索引比对，算出增量 DDL 后再执行。

因此从任意老版本升级都走同一条路径：线上缺的表会自动建、缺的列会自动加、列定义变化会自动改。如果某个库在线上根本不存在（早期版本没建过这个库），差异会自然退化成"建库 + 全量建表"，自动补齐。

自动生成的差异 SQL 去哪里看

所有产物都在执行 nuwax-cli 的那个工作目录下（不是 docker/ 里面）：

文件	内容
`temp_sql/upgrade_diff.sql`	本次生成的差异 SQL（执行过程中）
`temp_sql/diff_sql_executed_<时间戳>.sql`	差异已执行成功，原地改名留档
`temp_sql/diff_sql_failed_<时间戳>.sql`	执行失败，排障从这份文件开始看
`temp_sql/diff_sql_no_exec_<时间戳>.sql`	本次没有可自动执行的语句，只含需要人工处理的警告
`temp_sql/<库名>_old.sql`	迁移前的线上真实结构快照（`SHOW CREATE TABLE` 原文）
`temp_sql/<库名>_new.sql`	本次使用的目标结构模板（从部署包复制）
`history_sql/temp_sql_<时间戳>/`	下一轮部署开始时，整个 `temp_sql/` 目录被搬到这里归档

每次部署开始时都会把上一次的 temp_sql/ 挪进 history_sql/，所以历次升级的差异都能追溯。命令日志里也会打印差异文件的完整保存路径。

为什么删除类变更不会自动执行

这是有意的安全设计：新版本里删掉的表、删掉的列、删掉的主键/索引，CLI 只输出警告注释，绝不自动生成 DROP 语句。同理，ENGINE / CHARSET / COLLATE 变更也只给提示，不自动生成 CONVERT TO。会自动执行的只有新增和修改：CREATE TABLE、ADD COLUMN、MODIFY COLUMN、ADD KEY / UNIQUE / FULLTEXT / SPATIAL / PRIMARY KEY。

带来的两个后果，运维时要心里有数：

升级后发现旧字段、旧表还在，是正常现象，不是升级失败。确认业务和代码确实不再依赖它们后，再手工清理。
反过来说，升级不会因为新版本删了字段而丢数据。

需要人工处理时怎么办

方式一：直接按差异文件里的提示手工执行（推荐，最省事）

打开最近一次的 temp_sql/diff_sql_no_exec_*.sql（或 diff_sql_failed_*.sql），里面形如：

sql

-- ⚠️  Warning: Column `old_name` in table `t_user` was removed in the new version.
-- To delete it, run manually: ALTER TABLE `t_user` DROP COLUMN `old_name`;

run manually 后面的语句就是待人工执行的 SQL。逐条确认、先在测试库验证，再上生产。

方式二：用 diff-sql 重新生成差异（需要对比任意两个版本、或在测试环境预演时）

bash

# 1) 准备"旧结构"文件
#    优先用命令已经留档的快照，口径和自动升级完全一致：
cp temp_sql/agent_platform_old.sql /tmp/old.sql
#    或者从正在运行的库里现场导出（库名换成你自己的）：
docker compose -f docker/docker-compose.yml --env-file docker/.env exec -T mysql \
  sh -c 'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" \
         --no-data --skip-comments --databases agent_platform' > /tmp/old.sql

# 2) 准备"新结构"文件：用部署包内的结构模板
#    平台库 docker/config/init_mysql.sql，IM 库 docker/config/init_mysql_im.sql；
#    也可以直接复用留档的 temp_sql/<库名>_new.sql。
#    包内库名与文件的对应关系以 docker/config/mysql-schema-manifest.json 为准。

# 3) 生成差异 SQL
./nuwax-cli diff-sql /tmp/old.sql docker/config/init_mysql.sql \
  --old-version 0.0.74 --new-version 0.0.75 \
  --output manual_diff.sql

# 4) 人工审阅 manual_diff.sql（先备份！先在测试库执行！）

# 5) 手工执行：注意必须显式指定数据库
docker compose -f docker/docker-compose.yml --env-file docker/.env exec -T mysql \
  mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -D agent_platform < manual_diff.sql

使用 diff-sql 时注意三点：

它是纯文件比对，不连接数据库，也不会自己找库；
输出里不包含 USE、CREATE DATABASE 和授权语句，执行时必须指定目标库；
一次只处理一个库，多库要逐库分别跑。

另外，解析失败的建表语句只会记一条警告日志然后跳过，不会报错中断。审阅时顺手核对一下日志末尾打印的表数量是否符合预期，避免差异被漏算。

常见问题

现象	原因与处理
升级后旧字段、旧表还在	设计如此，删除类变更不自动生成 `DROP`。见上文"为什么删除类变更不会自动执行"，确认后手工清理
日志报 `Database upgrade failed`	终端错误信息会指出失败在第几条语句（形如 `failed at statement N after M successful`）；对应的完整脚本已改名留档在 `temp_sql/diff_sql_failed_<时间戳>.sql`，从那条语句往后就是没执行的部分。DDL 不支持整批回滚，失败即停。修复后重跑 `auto-upgrade-deploy run` 即可——差异会按数据库当前状态重算，语句都是幂等的，不会重复执行已成功的部分
日志报"无数据库结构差异"但确实该改表	检查部署包内 `docker/config/mysql-schema-manifest.json` 与结构模板是否齐全；`temp_sql/<库名>_new.sql` 就是本次实际使用的目标结构，和它对比一下
差异文件找不到了	去 `history_sql/temp_sql_<时间戳>/` 按时间找上一轮的归档
离线部署后表结构没变	正常。`offline-deploy` 不执行数据库 SQL 差异升级，见离网升级的注意说明

操作数据库前请先备份：./nuwax-cli auto-backup run（需先停止服务，建议在业务低谷执行）。手工执行差异 SQL 前，务必先在测试环境验证一遍。

常见问题

1. 服务启动失败

检查 Docker 是否正常运行
使用 ./nuwax-cli status 查看详细状态
检查端口是否被占用

2. 无法访问服务

确认服务已正常启动可以输入 docker ps命令查看，或者 ./nuwax-cli ducker 查看，或者带界面的桌面应用来查看容器启动情况。
检查防火墙设置
确认端口配置正确

3. 权限问题 - Permission denied

Linux（Ubuntu 22.04 LTS）: 确保用户在 docker 组中
macOS: 允许未知开发者运行，确保OrbStack或Docker Desktop已启动

典型错误如下: 出现关键字"Permission denied"

使用 sudo 来执行命令，重新执行一键部署命令 sudo ./nuwax-cli auto-upgrade-deploy run

4. 配置文件问题

如果手动修改过配置文件，可以尝试重新初始化配置

使用 ./nuwax-cli init --force 重新初始化
检查 config.toml 文件是否存在

5. 如果发现启动后，页面无法正常打开，查看docker容器 frontend, backend 有无启动，没有可以手动启动下试试

执行命令: ./nuwax-cli ducker ，启动容器管理界面，通过界面来查看容器启动状态

如果：frontend, backend 容器，没启动，通过 ducker 界面提示，选中容器，然后按r(run) 启动容器

然后在浏览器打开 "http://localhost" 查看是否正常访问。

ducker命令界面

6. 解压失败,错误:Directory not empty(os error 39)

先完全停止掉docker服务(如果有部分之前的docker应用，已经启动的话，执行命令 ./nuwax-cli docker-service stop停止), 然后手动删掉工作目录下的 docker 目录。然后重新执行 ./nuwax-cli auto-upgrade-deploy run 命令自动部署。

操作步骤：

先完全停止掉docker服务，如果确认本地没有残余启动的docker应用，可忽略不执行。

shell


./nuwax-cli docker-service stop

重新执行一键部署命令

shell

./nuwax-cli auto-upgrade-deploy run

7. 进入界面，但界面提示系统异常

启动成功，但界面提示系统异常，可以看后台系统日志，工作目录下的： ./docker/logs/agent/app.log ，可以查看具体错误信息。有时某个容器成功启动了，但可能会意外出现错误，比如redis容器出现无法写数据到磁盘的错误信息： "MISCONF Redis is configured to save RDB snapshots, but it's currently unable to persist to disk."

直接重新启动下服务，这种错误就解决了，可以正常使用服务了。重启服务（推荐）

shell

./nuwax-cli docker-service restart

或者

停止服务

shell

./nuwax-cli docker-service stop

启动服务

shell

./nuwax-cli docker-service start

8. 下载失败:error decoding response body

下载失败，这种一般是网络原因，直接重试下载就行了，会断点续传文件继续下载。(如果是在部署的时候失败的话,会自动重新下载)

shell


./nuwax-cli auto-upgrade-deploy run

9. libssl.so.1.1 缺失 - 仅影响旧版客户端

错误信息：

./nuwax-cli: error while loading shared libraries: libssl.so.1.1: cannot open shared object file: No such file or directory

原因： 早期版本的 nuwax-cli 编译时依赖系统的 OpenSSL 1.1 共享库，而 Ubuntu 24.04 及以上版本默认只带 OpenSSL 3.x，不再提供 libssl.so.1.1。

当前版本已不再有这个问题：客户端的 TLS 栈已换成内置的 rustls，不再链接系统 OpenSSL。所以首选做法是换用新版客户端，而不是往系统里装旧版 libssl：

如果这台机器上的 nuwax-cli 还能正常执行命令，直接升级自身即可：
bash
```
./nuwax-cli check-update install
```
如果二进制完全跑不起来（就是报上面这个错），按手动部署重新下载当前版本的客户端，替换掉旧文件后重试。

兜底方案（仅在完全离网、拿不到新版客户端时使用）：从 Ubuntu 20.04 仓库安装 libssl1.1，它可与系统自带的 OpenSSL 3.x 共存，不影响其他组件。装完请尽快换回新版客户端，不要长期依赖这个旧库。

x86_64 架构：

bash

wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.24_amd64.deb
sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2.24_amd64.deb

ARM64 架构：

bash

wget http://ports.ubuntu.com/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.24_arm64.deb
sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2.24_arm64.deb

验证：

bash

./nuwax-cli --version

参考命令

全局选项

nuwax-cli支持以下全局选项：

选项	说明	默认值
`-c, --config <CONFIG>`	指定配置文件路径	`config.toml`
`-v, --verbose`	详细输出（日志级别降为 debug），排障时建议带上	-
`-h, --help`	显示帮助信息	-
`-V, --version`	显示版本信息	-

命令输出与日志固定为英文，便于统一排障和提交工单时粘贴原文。

主要命令

获取帮助

使用 -h 参数查看任何命令的帮助信息：

bash

./nuwax-cli -h                    # 查看主要命令
./nuwax-cli docker-service -h    # 查看Docker服务命令
./nuwax-cli upgrade -h           # 查看升级命令

日志查看

bash

./nuwax-cli status              # 查看服务状态
./nuwax-cli docker-service status  # 查看详细Docker状态

系统管理命令

status - 显示服务状态和版本信息

bash

./nuwax-cli status

init - 首次使用时初始化客户端，创建配置文件和数据库

bash

./nuwax-cli init [OPTIONS]

--force: 如果配置文件已存在，强制覆盖

api-info - 显示当前API配置信息

bash

./nuwax-cli api-info

device-info - 查看本机设备指纹（用于许可证绑定）

bash

./nuwax-cli device-info [OPTIONS]

--json: 以 JSON 格式输出，便于脚本处理
--apply: 采集指纹并写入 docker/.env（该文件不存在时会直接报错，需先完成初始化部署）
--refresh: 忽略已冻结的指纹，按当前硬件重新绑定（更换服务器/虚拟化环境后使用）

更新管理

check-update - 检查客户端更新

bash

./nuwax-cli check-update <COMMAND>

子命令：

check: 检查最新版本信息
install [OPTIONS]: 安装指定版本或最新版本
- --version <VERSION>: 指定版本号（如不指定则安装最新版本）
- --force: 强制重新安装（即使当前已是最新版本）

upgrade - 检查并下载Docker服务部署包

bash

./nuwax-cli upgrade [OPTIONS]
./nuwax-cli upgrade <COMMAND>

直接跟在 upgrade 后使用时：

--force: 强制重新下载（用于文件损坏时），下载完整服务包
--check: 只检查是否有可用的升级版本，不执行下载

子命令：

download: 下载最新服务部署包到本地缓存目录
check [--force]: 检查可用的升级版本

该命令只检查和下载，不会自动安装部署；要完成部署请使用 auto-upgrade-deploy run。下载的历史版本可用 cache clean-downloads 清理。

部署管理

auto-upgrade-deploy - 自动升级部署

bash

./nuwax-cli auto-upgrade-deploy <COMMAND>

子命令：

run [OPTIONS]: 立即执行自动升级部署
- --port <PORT>: 指定frontend服务的端口号，对应docker-compose.yml中的FRONTEND_HOST_PORT变量（默认: 80端口）
- --config <PATH>: 自定义 docker-compose 配置文件路径（默认: docker/docker-compose.yml）
- --project <PROJECT_NAME>: 可简写"-p",指定Docker compose项目名，对应docker-compose.yml中的project_name变量（默认: docker）
- 部署过程会自动完成 MySQL 库表结构升级，差异脚本的查看与人工处理见数据库表结构升级
offline-deploy [OPTIONS]: 离线部署，从本地部署包进行全量升级部署（适用于无法联网的环境）
- --archive <PATH>: 本地部署包文件路径（支持 .zip 或 .tar.gz 格式）
- --version <VERSION>: 目标部署版本号
- --port <PORT>: 指定前端服务端口（默认: 80端口）
- --config <PATH>: 自定义 docker-compose 配置文件路径
- -p, --project <PROJECT_NAME>: 指定 Docker Compose 项目名称
status: 显示当前自动升级配置

Docker服务管理

docker-service - Docker服务相关命令

bash

./nuwax-cli docker-service <COMMAND>

子命令：

start: 启动Docker服务， -p 指定 project name，默认为“docker”
stop: 停止Docker服务
restart: 重启Docker服务， -p 指定 project name，默认为“docker”
status: 检查服务状态
restart-container <CONTAINER_NAME>: 重启指定容器
load-images: 加载Docker镜像
setup-tags: 设置镜像标签
arch-info: 显示架构信息
list-images: 列出Docker镜像（使用ducker）
check-mount-dirs: 检查并按 docker-compose.yml 创建所需的挂载目录（Windows + Podman 等不会自动建目录的环境排障用）

ducker - 一个用于管理Docker容器的终端应用

ducker命令界面

bash

./nuwax-cli ducker

备份管理

auto-backup - 一键备份（推荐）

bash

./nuwax-cli auto-backup <COMMAND>

子命令：

status: 显示当前备份配置
run: 立即执行一次备份

list-backups - 列出所有备份

bash

./nuwax-cli list-backups

rollback - 从备份恢复

bash

./nuwax-cli rollback [OPTIONS] [BACKUP_ID]

[BACKUP_ID]: 备份ID（可选，不提供时将显示交互式选择界面）
--force: 强制覆盖
--rollback-data: 同时回滚数据文件（默认不启用，即只恢复程序文件、保留现有数据）
--list-json: 输出JSON格式的备份列表（用于GUI集成）

缓存管理

cache - 缓存管理

bash

./nuwax-cli cache <COMMAND>

子命令：

clear: 清理所有缓存文件
status: 显示缓存使用情况
clean-downloads [OPTIONS]: 清理下载缓存（保留最新版本）
- --keep <KEEP>: 保留的版本数量 [default: 3]

开发工具

diff-sql - 对比两个SQL文件并生成差异SQL

库表结构升级通常由 auto-upgrade-deploy run 自动完成，不需要手工调用本命令。只有在需要人工处理结构变更（例如新版本删了字段、改了索引定义、改了字符集）时才用它，完整流程见数据库表结构升级。

bash

./nuwax-cli diff-sql [OPTIONS] <OLD_SQL> <NEW_SQL>

<OLD_SQL>: 旧版本SQL文件路径
<NEW_SQL>: 新版本SQL文件路径
--old-version <OLD_VERSION>: 旧版本号，用于生成差异描述
--new-version <NEW_VERSION>: 新版本号，用于生成差异描述
--output <OUTPUT>: 差异SQL输出文件名 [default: upgrade_diff.sql]

常用命令组合

完整部署流程

bash

# 1. 初始化
./nuwax-cli init

# 2. 一键部署
./nuwax-cli auto-upgrade-deploy run

# 3. 检查状态
./nuwax-cli status

手动部署流程

bash

# 1. 初始化
./nuwax-cli init

# 2. 下载服务文件
./nuwax-cli upgrade

# 3. 启动服务
./nuwax-cli docker-service start

# 4. 检查状态
./nuwax-cli status

离网部署流程

bash

# 1. 在有网络的机器上下载完整部署包
./nuwax-cli upgrade download

# 2. 将部署包和 nuwax-cli 客户端传输到目标服务器（U盘/SCP等）

# 3. 在目标服务器上初始化
./nuwax-cli init

# 4. 执行离线部署（部署包在 cacheDuckData/download/{版本号}/full/ 目录下）
./nuwax-cli auto-upgrade-deploy offline-deploy \
  --archive ./docker-x86_64.zip \
  --version 0.0.74

# 5. 检查状态
./nuwax-cli status

备份与恢复（推荐使用一键备份）

bash

# 推荐：查看备份状态
./nuwax-cli auto-backup status

# 推荐：手动执行一次备份（自动停服 → 备份 → 重启服务）
./nuwax-cli auto-backup run

# 查看备份列表 ，第一列是 BACKUP_ID 
./nuwax-cli list-backups

# 从备份恢复，看自己需要恢复的时间版本，然后输入第一列的 BACKUP_ID
./nuwax-cli rollback [BACKUP_ID]

一键备份设置（推荐）

一键备份数据(./docker/data,./docker/app 这2个核心数据目录)。

重要提示： 备份的时候，必须完全停止服务，备份完毕后，会自动重新启动服务，大约需要几分钟。

bash


# 手动执行一次备份
./nuwax-cli auto-backup run

命令行工具的更新管理(Beta)

升级命令行工具，等后续完善升级流程。

bash

# 检查更新
./nuwax-cli check-update check

# 安装最新版本
./nuwax-cli check-update install

# 强制重新安装
./nuwax-cli check-update install --force

日志级别

使用-v或--verbose参数可以获得更详细的输出信息，用于调试和故障排除。

退出码

退出码	说明
`0`	成功
`1`	失败。配置错误、网络错误、文件系统错误、Docker 错误等所有失败都归为此码

失败的具体原因不通过退出码区分，请查看命令输出与日志；排障时加上 -v 获取更详细的日志。

Docker环境安装

补充说明： 本章节为Docker环境安装的详细步骤，仅供需要安装Docker的用户参考。如果您已经有Docker环境，可以跳过此章节。

重要说明

Docker和Docker Compose是运行本服务的核心依赖，必须正确安装。以下提供了各主流操作系统的详细安装步骤。

安装前注意事项：

确保有足够的磁盘空间（至少200GB可用空间）
Linux推荐使用Ubuntu 24.04.3 LTS
安装过程中可能需要重启系统
中国大陆用户建议配置镜像加速器

Linux安装Docker推荐方案：一键安装配置脚本

社区一键安装配置 Docker 脚本

该脚本支持 13 种 Linux 发行版，包括国产操作系统（openEuler、Anolis OS、OpenCloudOS、Alinux、Kylin Linux），一键安装 docker、docker-compose 并自动配置轩辕镜像加速源。

shell

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

脚本特性与优势

✅ 支持 13 种主流发行版：openEuler (欧拉)、OpenCloudOS、Anolis OS (龙蜥)、Alinux (阿里云)、Kylin Linux (银河麒麟)、Fedora、Rocky Linux、AlmaLinux、Ubuntu、Debian、CentOS、RHEL、Oracle Linux

✅ 国产操作系统完整支持：深度适配国产操作系统（openEuler、Anolis OS、OpenCloudOS、Alinux、Kylin Linux），支持版本自动识别和最优配置

✅ 多镜像源智能切换：内置阿里云、腾讯云、华为云、中科大、清华等 6+ 国内镜像源，自动检测并选择最快源

✅ 老版本系统特殊处理：支持 Ubuntu 16.04、Debian 9/10 等已过期系统，自动配置兼容的安装方案

✅ 双重安装保障：包管理器安装失败时自动切换到二进制安装，确保安装成功率

✅ macOS/Windows 友好提示：自动检测 macOS 和 Windows 系统，提供适合的 Docker Desktop 安装指引

Alibaba Cloud Linux 3

参考社区安装文档：

查看安装社区版Docker（docker-ce）章节来安装。 https://developer.aliyun.com/article/1328603

Ubuntu 22.04 LTS

可以参考docker官方安装文档（安装 Docker和安装 Docker Compose），也可以直接使用下面的命令尝试安装。

1. 更新软件包索引

bash

sudo apt update

2. 安装必要的软件包

bash

sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

3. 添加Docker官方GPG密钥

bash

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

4. 设置稳定版仓库

bash

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

5. 安装Docker Engine

bash

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

6. 启动Docker服务

bash

sudo systemctl start docker
sudo systemctl enable docker

7. 将用户添加到docker组

bash

sudo usermod -aG docker $USER

8. 验证安装

bash

# 需要重新登录或运行以下命令
newgrp docker
docker --version
docker compose version

macOS

可以参考docker官方安装文档（在 Mac 内安装 Docker 桌面端），也可以直接使用下面的命令尝试安装。

方法一：使用OrbStack（推荐）

OrbStack是一个轻量级的Docker替代方案，个人使用免费，性能更好，资源占用更少。

访问 OrbStack官网
下载并安装OrbStack
启动OrbStack后，自动支持docker和docker compose命令
验证安装：
bash
```
docker --version
docker compose version
```

方法二：使用Docker Desktop

访问 Docker Desktop官网
下载适合你Mac的版本（Intel或Apple Silicon）
双击安装包进行安装
启动Docker Desktop
验证安装：
bash
```
docker --version
docker compose version
```

方法三：使用Homebrew安装OrbStack

bash

# 安装Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装OrbStack
brew install orbstack

# 启动OrbStack
open /Applications/OrbStack.app

Docker镜像加速（可选）

中国大陆用户建议配置镜像加速器

Linux系统：

bash

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

macOS/Windows：

OrbStack (macOS推荐)：

打开OrbStack
进入Settings
选择Docker

在Registry Mirrors中添加：

https://docker.mirrors.ustc.edu.cn
https://hub-mirror.c.163.com
https://mirror.baidubce.com

点击保存并重启

Docker Desktop：

打开Docker Desktop
进入Settings/Preferences
选择Docker Engine

在配置中添加：

json

{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}

点击Apply & Restart

验证Docker安装

运行以下命令验证Docker是否正确安装：

bash

# 检查Docker版本
docker --version

# 检查Docker Compose版本
docker compose version

# 运行hello-world测试
docker run hello-world

# 检查Docker服务状态
docker info

如果所有命令都能正常运行，说明Docker环境已经安装成功。

Docker安装常见问题

Q1: 提示 "permission denied" 错误

A: 用户没有Docker权限，需要将用户添加到docker组：
sudo usermod -aG docker $USER
然后重新登录或执行：newgrp docker

Q2: Docker服务启动失败

A: 先定位原因，不要直接删数据：
   - 查看系统日志：sudo journalctl -u docker.service -n 100
   - 查看磁盘空间：df -h /var/lib/docker（空间不足是最常见原因）
   - 检查配置文件是否语法错误：cat /etc/docker/daemon.json
   确认是残留资源占用时，只清理悬空对象：docker system prune
   ⚠️ 切勿执行 `sudo rm -rf /var/lib/docker`：这会删除全部镜像、容器和数据卷，
      包括平台 MySQL 的数据卷，等同于把已部署的业务数据全部清空。
      确需重装 Docker 时，先按 [备份管理](#备份管理) 做好平台数据备份。

Q3: 网络连接问题

A: 检查防火墙设置：
   - Ubuntu: sudo ufw status
   - 临时关闭防火墙测试：sudo ufw disable

Q4: 磁盘空间不足

A: 清理Docker数据：
   - 清理未使用的镜像：docker system prune
   - 清理所有数据：docker system prune -a
   - 查看磁盘使用：docker system df

Q5: 容器无法启动

A: 检查容器日志：
   - 查看容器状态：docker ps -a
   - 查看容器日志：docker logs <container_name>
   - 检查端口占用：netstat -tlnp | grep :80

安装部署 ​

🚀 快速开始 ​

环境准备 ​

系统要求 ​

支持的平台 ​

部署 ​

一键自动部署[推荐] ​

手动部署 ​

客户端下载 ​

执行命令完成部署 ​

Linux / macOS ​

离网部署（离线部署） ​

前提条件 ​

步骤一：在有网络的机器上下载部署包 ​

操作步骤 ​

离网升级 ​

访问服务 ​

重要配置 ​

1. 智能体客户端端口配置【重要】 ​

2. 管理员密码 ​

3. 站点信息配置 ​

4. 邮件服务配置 ​

智能体电脑部署【可选】 ​

部署故障排查 ​

常用管理命令 ​

服务管理 ​

备份管理 ​

升级管理 ​

数据库表结构升级 ​

自动生成的差异 SQL 去哪里看 ​

为什么删除类变更不会自动执行 ​

需要人工处理时怎么办 ​

常见问题 ​

常见问题 ​

1. 服务启动失败 ​

2. 无法访问服务 ​

3. 权限问题 - Permission denied ​

4. 配置文件问题 ​

5. 如果发现启动后，页面无法正常打开，查看docker容器 frontend, backend 有无启动，没有可以手动启动下试试 ​

6. 解压失败,错误:Directory not empty(os error 39) ​

7. 进入界面，但界面提示系统异常 ​

8. 下载失败:error decoding response body ​

9. libssl.so.1.1 缺失 - 仅影响旧版客户端 ​

参考命令 ​

全局选项 ​

主要命令 ​

获取帮助 ​

日志查看 ​

系统管理命令 ​

更新管理 ​

部署管理 ​

Docker服务管理 ​

备份管理 ​

缓存管理 ​

开发工具 ​

常用命令组合 ​

完整部署流程 ​

手动部署流程 ​

离网部署流程 ​

备份与恢复（推荐使用一键备份） ​

一键备份设置（推荐） ​

命令行工具的更新管理(Beta) ​

日志级别 ​

退出码 ​

Docker环境安装 ​

重要说明 ​

Linux安装Docker推荐方案：一键安装配置脚本 ​

脚本特性与优势 ​

Alibaba Cloud Linux 3 ​

Ubuntu 22.04 LTS ​

macOS ​

方法一：使用OrbStack（推荐） ​

方法二：使用Docker Desktop ​

方法三：使用Homebrew安装OrbStack ​

Docker镜像加速（可选） ​

验证Docker安装 ​

Docker安装常见问题 ​

安装部署

🚀 快速开始

环境准备

系统要求

支持的平台

部署

一键自动部署[推荐]

手动部署

客户端下载

执行命令完成部署

Linux / macOS

离网部署（离线部署）

前提条件

步骤一：在有网络的机器上下载部署包

操作步骤

离网升级

访问服务

重要配置

1. 智能体客户端端口配置【重要】

2. 管理员密码

3. 站点信息配置

4. 邮件服务配置

智能体电脑部署【可选】

部署故障排查

常用管理命令

服务管理

备份管理

升级管理

数据库表结构升级

自动生成的差异 SQL 去哪里看

为什么删除类变更不会自动执行

需要人工处理时怎么办

常见问题

常见问题

1. 服务启动失败

2. 无法访问服务

3. 权限问题 - Permission denied

4. 配置文件问题

5. 如果发现启动后，页面无法正常打开，查看docker容器 frontend, backend 有无启动，没有可以手动启动下试试

6. 解压失败,错误:Directory not empty(os error 39)

7. 进入界面，但界面提示系统异常

8. 下载失败:error decoding response body

9. libssl.so.1.1 缺失 - 仅影响旧版客户端

参考命令

全局选项

主要命令

获取帮助

日志查看

系统管理命令

更新管理

部署管理

Docker服务管理

备份管理

缓存管理

开发工具

常用命令组合

完整部署流程

手动部署流程

离网部署流程

备份与恢复（推荐使用一键备份）

一键备份设置（推荐）

命令行工具的更新管理(Beta)

日志级别

退出码

Docker环境安装

重要说明

Linux安装Docker推荐方案：一键安装配置脚本

脚本特性与优势

Alibaba Cloud Linux 3

Ubuntu 22.04 LTS

macOS

方法一：使用OrbStack（推荐）

方法二：使用Docker Desktop

方法三：使用Homebrew安装OrbStack

Docker镜像加速（可选）

验证Docker安装

Docker安装常见问题