Skip to content

智能体电脑 + 网站应用(UserApp)部署指南 ​

可以在多个不同的服务器部署智能体电脑 + 用户应用服务,通过配置实现分布式智能体沙箱与用户应用(开发/构建/发布/运行)能力。

本服务是智能体电脑的超集:沙箱/远程桌面/文件上传能力完全一致,额外支持 网站应用(UserApp) 业务——用户在平台上开发应用(前端/后端多项目 workspace),构建打包后以 app-runtime 统一多语言运行时镜像(Node/Python/Java/Go)发布运行,支持闲置自动回收与流量唤醒。

环境要求:每台服务器需要安装 Docker 和 Docker Compose 环境,参考 Docker环境安装。建议最低配置:内存 ≥ 16GB,硬盘 ≥ 200GB(首次部署镜像约 40GB,另需预留沙箱/用户应用数据空间)。

⚠️ 与智能体电脑部署互斥:本服务与 智能体电脑 端口完全相同(9086/9088/9099/60001),一台服务器只能安装其中一套。已部署智能体电脑的服务器请先卸载,或修改端口后再部署本服务。

一、快速部署 ​

一键自动部署[推荐] ​

执行以下命令即可完成一键部署,Linux和macOS均可使用,如果Linux没有docker环境,会尝试自动安装,而macOS需要手动安装docker环境,如果执行不成功,请参考手动部署。

在准备保存部署数据的目录中执行一条命令,即可下载脚本并安装服务。

下载 docker-userapp-computer.zip 部署包,使用 nuwax 镜像,部署目录为当前目录下的 nuwax_userapp_computer_deploy/:

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

macOS 或未安装 wget 时,可以使用 curl:

bash
bash <(curl -fsSL https://nuwa-packages.oss-rg-china-mainland.aliyuncs.com/script/prod/userapp_computer_deploy.sh) install

也可以先下载脚本再执行,将脚本保留在上述同一目录,便于后续管理:

bash
curl -fsSL https://nuwa-packages.oss-rg-china-mainland.aliyuncs.com/script/prod/userapp_computer_deploy.sh -o userapp_computer_deploy.sh
bash userapp_computer_deploy.sh install

脚本常用管理命令(在脚本所在目录执行):

bash
bash userapp_computer_deploy.sh status      # 查看服务状态
bash userapp_computer_deploy.sh logs        # 查看服务日志
bash userapp_computer_deploy.sh upgrade     # 升级镜像(保留全部数据)
bash userapp_computer_deploy.sh key         # 查看当前 API Key
bash userapp_computer_deploy.sh uninstall   # 卸载(删除全部服务与数据)

API Key:服务默认开启 API 鉴权,安装时自动生成随机 Key(安装完成信息中会打印,或用 key 命令随时查看)。平台接入时需要在沙箱配置中一并填写该 Key,所有业务请求必须携带 x-api-key 请求头。

测试环境(beta)部署方式见文末 六、测试环境部署。

手动部署 ​

1. 创建工作目录 ​

bash
mkdir nuwax_userapp_computer_deploy
cd nuwax_userapp_computer_deploy

2.下载安装文件 ​

bash
wget https://nuwa-packages.oss-rg-china-mainland.aliyuncs.com/script/deploy_zip/docker-userapp-computer.zip

3.解压文件 ​

bash
unzip docker-userapp-computer.zip

如果解压失败,请检查系统是否安装了unzip,可以根据自己系统,选择对应安装命令,安装解压工具:

bash
yum install unzip
bash
dnf install unzip
bash
apt install unzip

4. 进入解压目录 ​

bash
cd docker-userapp-computer

5. 启动服务 ​

bash
docker compose up -d

首次启动会拉取以下镜像(阿里云公开镜像仓库,无需账号密码),耐心等待:

  • rcoder:主服务(编排器)
  • rcoder-computer-agent-runner:沙箱容器 + UserApp 开发容器
  • app-runtime:UserApp 发布后的应用运行时(体积较大)

6. 验证服务 ​

查看容器状态

bash
docker compose ps

查看服务日志(可选)

bash
docker compose logs -f

健康检查

bash
curl http://localhost:9086/health

服务启动后,会占用以下端口:

  • 9086:主程序服务地址
  • 9088:远程桌面服务地址(同时也是已发布用户应用的访问入口)
  • 60001:文件上传服务地址
  • 9099:项目子应用入口(nginx)

确保防火墙已开放上述端口。

7. 配置沙箱服务 ​

服务部署完成后,需要在女娲智能体OS平台中配置沙箱服务。

💡 下一步:详细的沙箱配置操作说明,请参考 沙箱配置手册

配置路径:系统管理 → 系统配置 → 站点智能体设置 → 智能体沙箱配置


二、服务管理 ​

常用命令 ​

bash
# 查看服务状态
docker compose ps

# 查看服务日志
docker compose logs -f [service_name]

# 停止服务
docker compose down

# 启动服务
docker compose up -d

# 重启服务
docker compose restart

查看单个服务日志 ​

bash
# 查看主程序日志
docker compose logs -f rcoder

三、升级更新 ​

方式一:全量重新部署(推荐) ​

适合大版本升级或遇到问题时使用。

bash
# 1. 停止服务
docker compose down

# 2. 备份配置与用户数据(重要!)
# 备份配置到当前目录,避免重新解压时被覆盖
sudo cp -r docker-userapp-computer/config config.backup
# 备份三个用户数据目录(数据文件由容器以 root 写入,普通用户复制会因权限不完整而失败,需 sudo)
sudo cp -r docker-userapp-computer/computer-project-workspace workspace.backup
sudo cp -r docker-userapp-computer/userapp-workspace userapp.backup
sudo cp -r docker-userapp-computer/app-workspace app.backup

# 3. 下载最新部署文件并解压
wget https://nuwa-packages.oss-rg-china-mainland.aliyuncs.com/script/deploy_zip/docker-userapp-computer.zip
unzip -o docker-userapp-computer.zip

# 4. 恢复配置与数据目录(一般无需执行)
# 仅当需要保留原配置或原数据时,才取消下面命令的注释
# cp -r config.backup/* docker-userapp-computer/config/
# cp -r workspace.backup docker-userapp-computer/computer-project-workspace
# cp -r userapp.backup docker-userapp-computer/userapp-workspace
# cp -r app.backup docker-userapp-computer/app-workspace

# 5. 拉取最新镜像并启动服务
cd docker-userapp-computer
docker compose pull
docker compose up -d

重要提示:升级时务必保留以下三个目录,它们存储全部用户数据:

  • docker-userapp-computer/computer-project-workspace:沙箱电脑用户工作区
  • docker-userapp-computer/userapp-workspace:用户应用的开发工作区与发布数据(代码、数据库、日志)
  • docker-userapp-computer/app-workspace:用户应用持久存储根

方式二:镜像更新 ​

适合小版本更新,日常发版推荐。

bash
# 进入部署目录
cd docker-userapp-computer

# 拉取最新镜像
docker compose pull

# 停止服务
docker compose down

# 重启服务
docker compose up -d

镜像更新方式会同时更新 app-runtime 运行时镜像(用户应用发布时使用同版本镜像)。

四、高级配置 ​

本章节介绍服务器端的详细配置选项,包括容器清理、资源限制、UserApp 闲置回收等。这些配置可以根据实际需求调整,优化服务器资源使用。

配置文件位置:docker-userapp-computer/config/rcoder/config.yml

4.1 容器清理配置 ​

为了优化服务器资源使用,系统提供了自动容器清理功能。当用户容器闲置超过指定时间后,系统会自动清理,释放内存和 CPU 资源。

配置示例 ​

yaml
cleanup_config:
  # 是否启用自动清理(推荐开启)
  enabled: true

  # 容器闲置超时时间(秒)
  # 默认 600 秒(10分钟),用户容器闲置超过此时间后会被自动清理
  idle_timeout_seconds: 600

  # 清理检查间隔(秒)
  # 默认 300 秒(5分钟),系统每隔此时间检查一次闲置容器
  cleanup_interval_seconds: 300

  # Docker 容器停止超时时间(秒)
  # 默认 30 秒,容器停止超过此时间会强制终止
  docker_stop_timeout_seconds: 30

  # 容器最小保护时间(秒)
  # 默认 300 秒(5分钟),新创建的容器在此时间内不会被清理
  container_protection_seconds: 300

参数说明 ​

参数默认值说明推荐配置
enabledtrue是否启用自动清理建议开启,优化资源使用
idle_timeout_seconds600闲置超时时间(秒)根据业务需求调整,频繁使用可延长至 1800(30分钟)
cleanup_interval_seconds300清理检查间隔(秒)推荐 300-600,过短会增加系统负载
docker_stop_timeout_seconds30容器停止超时(秒)一般不需要修改
container_protection_seconds300容器保护时间(秒)推荐至少 300,避免误清理

详细说明参考:智能体电脑部署指南 → 4.1 容器清理配置

4.2 用户容器资源配置 ​

用户可以根据服务器性能和业务需求,调整每个沙箱容器的资源限制。

配置示例 ​

yaml
docker_config:
  multi_image_config:
    services:
      computer-agent-runner:
        environment:
          # Agent 闲置超时时间(秒),默认 3600 秒(1小时)
          RCODER_AGENT_IDLE_TIMEOUT_SECS: "3600"

        # 资源限制配置(每个沙箱容器的资源上限)
        resource_limits:
          memory_limit: 4294967296  # 内存限制:4GB
          cpu_limit: 2.0            # CPU 限制:2核
          swap_limit: 8589934592    # Swap 限制:8GB

说明:镜像配置(image、arm64_image、amd64_image 等)由系统管理,已预配置好,无需修改。

详细参数说明与分场景配置建议(标准/高性能/节约资源)参考:智能体电脑部署指南 → 4.2 用户容器资源配置

4.3 UserApp 专属配置 ​

4.3.1 用户应用闲置自动回收 ​

已发布的用户应用闲置超过阈值后自动休眠(保留全部数据,仅停止容器释放资源),有真实访问流量时自动唤醒。适合免费用户/低频应用较多的场景。

yaml
userapp_recycle:
  # 是否启用闲置回收(默认 true)
  enabled: true

  # 闲置阈值(秒),默认 432000(5天),应用闲置超过此时间后休眠
  idle_timeout_seconds: 432000

  # 回收扫描间隔(秒),默认 3600(1小时)
  scan_interval_seconds: 3600

  # 流量唤醒等待上限(秒),默认 60
  # 唤醒期间请求挂起等待,超时返回 503 + Retry-After
  wake_timeout_seconds: 60

  # 新建应用最小保护期(秒),默认 300,保护期内不会被回收
  protection_seconds: 300
参数默认值说明
enabledtrue总开关;关闭后应用永不休眠(常驻运行,占用资源)
idle_timeout_seconds432000闲置阈值,默认 5 天;付费/常驻场景可调大或关闭总开关
scan_interval_seconds3600回收扫描间隔
wake_timeout_seconds60访问唤醒等待上限,超时返回 503
protection_seconds300新建应用保护期

场景建议:

  • 资源紧张(服务器要跑很多应用):保持默认,或调低 idle_timeout_seconds 至 86400(1天)
  • 体验优先(应用响应要快):调大 wake_timeout_seconds 至 120,减少 503 概率
  • 常驻运行(应用不允许休眠):enabled: false

4.3.2 UserApp 开发容器资源配置 ​

用户应用的开发容器(builder)资源限制,位置:docker_config.multi_image_config.services.user-app-builder:

yaml
docker_config:
  multi_image_config:
    services:
      user-app-builder:
        # ... image / environment 等配置由系统管理,无需修改 ...
        resource_limits:
          memory_limit: 4294967296  # 内存限制:4GB
          cpu_limit: 2.0            # CPU 限制:2核
          swap_limit: 8589934592    # Swap 限制:8GB

说明:开发容器在用户开发期间常驻,构建(编译前端/后端)也在此容器内进行。用户应用构建慢或卡死时,可适当调大内存与 CPU。

4.3.3 UserApp 运行时镜像配置 ​

发布后的应用使用 app-runtime 镜像运行,镜像地址在 docker-compose.yml 环境变量中配置:

yaml
    environment:
      # 默认用户应用运行时镜像(阿里云公开镜像仓库,无需凭证)
      - RCODER_RUNTIME_IMAGE_DIGEST=${RCODER_RUNTIME_IMAGE_DIGEST:-nuwax-docker-images-registry.cn-hangzhou.cr.aliyuncs.com/nuwax/app-runtime:latest}

一般无需修改。仅内网镜像场景需要覆盖:设置环境变量 RCODER_RUNTIME_IMAGE_DIGEST 指向内网镜像地址后 docker compose up -d 重启。

注意:运行应用时不会自动拉取镜像,镜像由部署/升级时的预拉取服务(app-runtime-image-pre-pull)准备。若曾手动清理镜像导致发布报错,在部署目录执行 docker compose pull 重新拉取。

4.3.4 API Key 鉴权(默认开启) ​

服务默认启用 API Key 鉴权:所有业务 HTTP 请求必须携带 x-api-key 请求头(健康检查 /health 等系统端点豁免)。

  • 一键脚本部署:安装时自动生成随机 Key 并写入 config/rcoder/config.yml,安装完成信息会打印;随时查看:
bash
bash userapp_computer_deploy.sh key
  • 手动部署:必须自行设置,config.yml 中 api_key_auth.api_key 留空时服务会启动失败(明确的 fail-fast 报错)。生成方式:
bash
echo "sk-$(openssl rand -hex 16)"
  • 指定 Key:安装前设置环境变量 RCODER_API_KEY=sk-xxx,脚本会使用该值而不是随机生成;已在 config 中自定义的 Key 不会被升级覆盖。
  • 修改 Key:编辑 config.yml 后需重启(docker compose restart rcoder)。
  • 平台接入:在女娲智能体OS平台的智能体沙箱配置中填写该 Key(沙箱/智能体调用已支持携带)。⚠️ 平台的用户应用管理与文件调用面暂未携带该 Key(平台版本待补):如果平台侧这些请求会直接到达本服务,请先保持 enabled: false 或联系平台侧确认版本支持后再开启。

4.4 老版本 Linux 系统兼容配置(可选) ​

适用场景:大多数用户无需配置此项。仅当服务器 Linux 内核版本较老(如 CentOS 7、openEuler 22 等)时才需要开启。

老内核兼容涉及两个层面的容器,与智能体电脑部署的处理方式一致:

  1. 主服务容器(rcoder 等):在 docker-compose.yml 的 rcoder 服务下添加 security_opt: - seccomp:unconfined;
  2. 动态创建的用户容器(沙箱 computer-agent-runner / UserApp 开发 user-app-builder):在 config.yml 对应服务下添加 security 块。

详细配置方法参考:智能体电脑部署指南 → 4.3 老版本 Linux 系统兼容配置(可选)(其中 computer-agent-runner 的配置方式对 user-app-builder 同样适用)

4.5 配置修改后的重启方法 ​

方式一:配置文件修改后重启(推荐) ​

修改 docker-userapp-computer/config/rcoder/config.yml 后:

bash
# 进入部署目录
cd docker-userapp-computer

# 重启 rcoder 服务以应用新配置
docker compose restart rcoder

# 查看日志确认配置已生效
docker compose logs -f rcoder

方式二:环境变量修改后重启 ​

修改 docker-compose.yml 中的环境变量后:

bash
# 停止服务
docker compose down

# 重新启动(会读取新的环境变量)
docker compose up -d

配置热更新说明 ​

以下配置需要重启服务才能生效:

  • 容器清理配置 (cleanup_config)
  • 用户容器资源配置 (resource_limits)
  • UserApp 闲置回收配置 (userapp_recycle)
  • API Key 鉴权配置 (api_key_auth,修改后 docker compose restart rcoder)
  • 老版本 Linux 安全参数 (security)
  • 端口配置 (port)
  • 项目目录配置 (projects_dir)

注意:

  • 修改资源配置后,只对新创建的容器生效,已存在的容器不受影响
  • UserApp 闲置回收配置重启后,已休眠的应用按新阈值参与下次扫描

五、故障排查 ​

1. 容器启动失败 ​

bash
# 查看容器状态
docker compose ps

# 查看详细日志
docker compose logs

# 检查端口占用
netstat -tlnp | grep -E '9086|9088|9099|60001'

2. 无法访问服务 ​

  • 检查防火墙设置,确保端口已开放
  • 确认服务器 IP 地址配置正确
  • 验证 Docker 服务是否正常运行

3. 数据丢失 ​

检查三个用户数据目录是否完整:computer-project-workspace(沙箱)、userapp-workspace(用户应用开发与发布数据)、app-workspace(用户应用持久存储)。升级前务必备份。

4. 性能问题 ​

根据服务器实际配置调整 memory_limit、cpu_limit 和 swap_limit 参数(详见 4.2 用户容器资源配置)。

更多性能优化,虚拟电脑并发上不去或会话超时卡死问题参考解决方案

5. 容器频繁被清理 ​

现象:用户容器经常被自动清理,影响使用体验。

解决方案:调整 cleanup_config.idle_timeout_seconds(延长至 1800 即 30 分钟)后重启 rcoder。

详细配置说明请参考:4.1 容器清理配置

6. 容器资源不足 ​

现象:容器频繁重启或性能差。

解决方案:

bash
# 1. 查看容器资源使用情况
docker stats

# 2. 调整资源限制配置(编辑 config.yml 中对应服务的 resource_limits)

详细配置说明请参考:4.2 用户容器资源配置

7. 查看配置是否生效 ​

bash
# 查看当前生效的配置
docker compose exec rcoder cat /app/config.yml

# 查看环境变量配置
docker compose exec rcoder env | grep RCODER

# 查看服务启动日志中的配置信息
docker compose logs rcoder | grep -E "配置|Config|最终配置"

8. 智能体连接超时或 EPERM 权限错误(老版本 Linux 系统) ​

现象:前端调用智能体后长时间转圈、最终超时;rcoder 日志报 EPERM: operation not permitted 或 ACP 连接子容器超时;常见于 CentOS 7、openEuler 22 等老版本内核的服务器。

解决方案:参考 4.4 老版本 Linux 系统兼容配置(可选)。

9. 发布用户应用失败:镜像不存在或创建容器失败 ​

现象:发布应用时报错,日志提到 No such image / create_container 失败。

原因:运行应用不自动拉取镜像,本地缺少 app-runtime 镜像(常见于手动清理过镜像)。

解决方案:

bash
# 进入部署目录,重新拉取镜像
cd docker-userapp-computer
docker compose pull

10. 用户应用开发容器创建失败:userapp-workspace 锚点错误 ​

现象:创建应用开发环境失败,日志提到 host path resolve failed / userapp-workspace 锚点。

原因:rcoder 容器通过 docker.sock 反解宿主路径,依赖 compose 中的 ./userapp-workspace:/app/userapp-workspace 挂载。

解决方案:确认 docker-compose.yml 中该挂载存在且未被注释,然后重启:

bash
docker compose restart rcoder

11. 访问已发布应用返回 503 ​

现象:访问应用(9088 端口)返回 503 + Retry-After。

原因:应用被闲置回收休眠,正在唤醒中(正常行为,默认等待上限 60 秒)。

解决方案:等待片刻重试即可。频繁遇到时可调大 userapp_recycle.wake_timeout_seconds 或关闭 userapp_recycle.enabled(详见 4.3.1 用户应用闲置自动回收)。

12. 启动初期日志显示 nuwax-file-server 健康检查失败 ​

现象:服务启动后一两分钟内,日志出现 Nuwax File Server health check failed 并自动重启 2-3 次。

原因:TS 文件服务(60001 端口)冷启动比守护脚本的健康检查窗口慢,属已知现象,随后会自动恢复。

解决方案:无需处理。以 docker compose ps 中 rcoder 容器显示 healthy、60001 端口正常监听为准;若超过 5 分钟仍未恢复,再排查磁盘 IO 与镜像完整性。


六、测试环境部署 ​

适用对象:内部/运维人员的发布前验证,普通用户无需阅读本章。

测试环境与生产环境端口完全相同(9086/9088/9099/60001),同一台服务器只能部署其中一套。

测试环境通过 DEPLOY_ENV=test 选择测试包(下载 docker-userapp-computer-test.zip,使用 nuwax-test 镜像),部署目录为当前目录下的 nuwax_userapp_computer_test_deploy/。

注意:平台客户端的 NUWAX_CLI_ENV=test 不会替 UserApp 脚本切换环境,必须显式设置 DEPLOY_ENV=test。

一键部署 ​

bash
# wget
DEPLOY_ENV=test bash <(wget -qO- https://nuwa-packages.oss-rg-china-mainland.aliyuncs.com/script/prod/userapp_computer_deploy.sh) install

# curl(macOS 或未安装 wget)
DEPLOY_ENV=test bash <(curl -fsSL https://nuwa-packages.oss-rg-china-mainland.aliyuncs.com/script/prod/userapp_computer_deploy.sh) install

也可以先下载脚本再执行:

bash
curl -fsSL https://nuwa-packages.oss-rg-china-mainland.aliyuncs.com/script/prod/userapp_computer_deploy.sh -o userapp_computer_deploy.sh
DEPLOY_ENV=test bash userapp_computer_deploy.sh install

服务管理 ​

测试环境执行管理命令时,同样需要加上 DEPLOY_ENV=test:

bash
DEPLOY_ENV=test bash userapp_computer_deploy.sh status      # 查看服务状态
DEPLOY_ENV=test bash userapp_computer_deploy.sh logs        # 查看服务日志
DEPLOY_ENV=test bash userapp_computer_deploy.sh upgrade     # 升级镜像(保留全部数据)
DEPLOY_ENV=test bash userapp_computer_deploy.sh key         # 查看当前 API Key
DEPLOY_ENV=test bash userapp_computer_deploy.sh uninstall   # 卸载(删除全部服务与数据)

其余配置项(容器清理、资源限制、UserApp 闲置回收、API Key 鉴权等)与生产环境完全一致,参考 四、高级配置。