基于Ubuntu部署SoduWork：企业级 AI 原生协同平台实战全流程

江湖有缘2026-11-15 8:40

基于Ubuntu系统部署SoduWork开源企业级 AI 原生协同平台实战全流程

  • 前言
  • 一、SoduWork介绍
    • [1.1 SoduWork简介](#1.1 SoduWork简介)
    • [1.2 SoduWork主要特点](#1.2 SoduWork主要特点)
    • [1.3 SoduWork核心思想](#1.3 SoduWork核心思想)
    • [1.4 注意事项](#1.4 注意事项)
  • 二、实践环境规划
    • [2.1 部署环境信息](#2.1 部署环境信息)
    • [2.2 本次实践介绍](#2.2 本次实践介绍)
  • 三、环境准备工作
    • [3.1 安装基本依赖](#3.1 安装基本依赖)
    • [3.2 编译安装Python3.12](#3.2 编译安装Python3.12)
    • [3.3 安装 Node.js](#3.3 安装 Node.js)
    • [3.4 配置相关镜像源（重要）](#3.4 配置相关镜像源（重要）)
    • [3.4 安装图形化界面](#3.4 安装图形化界面)
  • 四、部署SoduWork控制台
    • [4.1 拉取项目](#4.1 拉取项目)
    • [4.2 启动控制台](#4.2 启动控制台)
    • [4.3 打开控制台](#4.3 打开控制台)
    • [4.4 设置系统语言中文](#4.4 设置系统语言中文)
    • [4.5 配置大模型服务](#4.5 配置大模型服务)
  • 五、桌面客户端配置工作
    • [5.1 登录桌面客户端配置](#5.1 登录桌面客户端配置)
    • [5.2 测试对话](#5.2 测试对话)
    • [5.3 SoduWork工作台监控](#5.3 SoduWork工作台监控)
  • 六、单桌面客户端体验
    • [6.1 下载客户端](#6.1 下载客户端)
    • [6.2 安装桌面客户端](#6.2 安装桌面客户端)
    • [6.3 注册账号](#6.3 注册账号)
    • [6.4 配置大模型](#6.4 配置大模型)
    • [6.5. 测试文档能力](#6.5. 测试文档能力)
    • [6.6 测试代码能力](#6.6 测试代码能力)
  • 七、遇到的问题与解决
  • 八、总结

前言

作为一名初次接触 SoduWork 的新人，我最初对"AI 原生协同平台"这个概念其实并没有太具体的想象，只当是又一个套着 AI 外壳的协作工具。真正上手之后才发现，它把模型调度、代理执行和团队协作串成了一条完整的链路，从安装到跑通第一个任务，整个过程比预想的要顺畅不少。本文完整记录了我在 Ubuntu 主机上从零部署 SoduWork 的全过程，包括环境准备、控制台启动、模型配置以及文档与代码能力的实测体验。希望这份偏"新人视角"的实战记录，能帮同样想尝鲜的朋友少踩几个坑，更快地把平台跑起来。

一、SoduWork介绍

1.1 SoduWork简介

SoduWork 是一个开源的企业级 AI 原生（AI-native）协同平台，定位是"面向团队及其代理的 AI 原生引擎"。它把分散的工具与业务经验汇聚成团队共同的工作能力，连接人、AI 与企业系统，支持多框架、多代理、自托管。

1.2 SoduWork主要特点

能力 说明
双 AI 交叉验证 一个代理负责执行（如 Pick Pi），另一个用不同模型审核（如 OpenCode），按验收标准评估；审核不通过则连同原因退回
向同事的代理提交请求 人提交请求 → AI 编写验收标准 → 分配给自己或同事 → 对方代理完成并审核 → 人工确认；全程可见谁做了什么
把个人专长变成团队资产 与 AI 成功完成任务后，可将聊天记录保存为"插件"，经审核后团队共享并持续贡献改进，权限按需授予

1.3 SoduWork核心思想

  • 🔀 智能调度：为每一步任务选择合适的代理与模型，对话中途可切换；常规步骤用廉价或本地模型，关键节点用强模型；长任务可发到自己的云端运行器。
  • 🛡️ 内置治理：由组织决定 AI 能做什么、在哪做；插件分享前需审核、可撤销；具备角色、用量、成本与审计日志。
  • ✅ 自托管 + 已验证的交付：先定验收标准，"完成"以请求者签字确认为准；每个请求都带验收标准，由独立 AI 审核，最终由人做决定。

1.4 注意事项

  1. 仍在公开测试阶段，官方建议先试用反馈，投入生产环境前做好评估。
  2. 落地建议：从一项边界清晰的工作开始，让可验证的成果逐步走进日常，避免一次性全面铺开。
  3. 治理与安全：代理会实际执行操作，敏感权限需谨慎授权；自托管虽可控性更强，但审计、成本、角色配置需提前规划。

二、实践环境规划

2.1 部署环境信息

本次实践在一台局域网内的自托管主机上完成部署，硬件与基础环境（系统、内核、运行时版本及网络地址）如下表所示，各项版本均满足 SoduWork 自托管的最低要求：

  • 基础环境（自托管主机）
类别 项目 值
系统 操作系统 Ubuntu 22.04.1 LTS (Jammy Jellyfish)
系统 内核版本 5.15.0-203-generic
主机 hostname jeven
主机 角色定位 服务器（局域网自托管）
网络 局域网地址 192.168.3.251
运行时 Python 3.12.16
运行时 Node.js v22.23.5
桌面客户端 SoduWork 1.13.13

2.2 本次实践介绍

  1. 实践内容：以 Ubuntu主机为底座，完整走一遍 SoduWork（开源企业级 AI 原生协同平台）的自托管部署流程，涵盖环境准备、服务启动、各项配置与基础功能验证，形成可复现的实战记录。
  2. 版本状态：SoduWork 目前仍处于公开测试阶段，官方建议先试用并反馈，投入生产环境前需做好充分评估。
  3. 环境说明：本次实践基于个人测试环境完成，不涉及生产数据，生产环境部署前请自行完成安全性与稳定性评估。
  4. 模型准备：平台本身不自带大模型能力，需自备兼容 OpenAI 协议的大模型 API 进行测试，官方赠送额度有限，跑长周期任务建议提前配置自己的 API Key。

三、环境准备工作

本章节在 Ubuntu 24.04 主机（192.168.3.251）上完成基础依赖、Python 与 Node.js 的安装与验证，为后续 SoduWork 自托管部署做好准本次实践涉及 root 与自建用户 jeven 两个账号：环境准备阶段以 root 身份执行，后续步骤则切换至 jeven 用户完成。

3.1 安装基本依赖

先更新软件包索引并安装基础工具链。build-essential 是 Debian/Ubuntu 系的元软件包，包含 gcc、g++、make、libc6-dev、dpkg-dev 等编译 C/C++ 所必需的核心工具，是后续从源码编译软件、安装 npm 原生依赖的基础。

  1. 更新包索引
bash 复制代码 
apt update
  1. 安装基础工具与编译链
bash 复制代码 
apt install -y curl git build-essential ca-certificates \
  pkg-config zlib1g-dev libssl-dev libffi-dev libsqlite3-dev \
  libreadline-dev libbz2-dev xz-utils wget
  1. 验证编译环境
bash 复制代码 
gcc --version
g++ --version
make --version

说明：若 apt install build-essential 报 unmet dependencies（如 libc6-dev 依赖冲突），可先执行 apt --fix-broken install 修复依赖链后重试。国内服务器建议先替换为阿里云/清华镜像源以加速下载。

3.2 编译安装Python3.12

  1. 在阿里云镜像站下载Python-3.12.6.tgz安装包：
bash 复制代码 
wget https://mirrors.aliyun.com/python-release/source/Python-3.12.6.tgz
bash 复制代码 
tar -xzf Python-3.12.6.tgz && cd Python-3.12.6
  1. 执行以下步骤，进行编译安装：
bash 复制代码 
./configure --prefix=/usr/local/python3.12 --with-ensurepip=install && make -j$(nproc) && make altinstall
  1. 配置环境变量：
bash 复制代码 
cat > /etc/profile.d/python312.sh <<'EOF'
export PATH="/usr/local/python3.12/bin:${PATH}"
EOF
source /etc/profile
  1. 配置软链接：
bash 复制代码 
ln -sf /usr/local/python3.12/bin/python3.12 /usr/local/bin/python3
ln -sf /usr/local/python3.12/bin/pip3.12 /usr/local/bin/pip3
  1. 检查python版本，可以看到已经成功安装3.12版本。
bash 复制代码 
root@jeven:~/Python-3.12.6# python3 --version
Python 3.12.6
root@jeven:~/Python-3.12.6# pip3 --version
pip 24.2 from /usr/local/python3.12/lib/python3.12/site-packages/pip (python 3.12)

说明：切勿删除系统自带的 python3，否则可能破坏 apt 等系统工具。

3.3 安装 Node.js

SoduWork平台需要依赖 Node.js ≥ 22，因此需通过 NodeSource 官方源安装 v22。

  1. 下载node-v22.23.5的二进制包：
bash 复制代码 
wget https://nodejs.org/dist/v22.23.5/node-v22.23.5-linux-x64.tar.xz
  1. 解压到当前目录：
bash 复制代码 
tar -xvJf node-v22.23.5-linux-x64.tar.xz
  1. 配置环境变量：
bash 复制代码 
cat > /etc/profile.d/node.sh <<'EOF'
export PATH="/root/node-v22.23.5-linux-x64/bin:${PATH}"
EOF
source /etc/profile
  1. 验证版本，可以看到输出：v22.23.5。
bash 复制代码 
node -v  
npm -v

说明：

  1. 验证命令为 node -v（小写），node -V 会报 bad option 错误。
  2. 若需在单机管理多个 Node 版本，可改用 nvm 方案：curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash，随后 source ~/.bashrc 并执行 nvm install 22。
  3. 国内环境建议切换 npm 镜像源加速依赖下载：npm config set registry https://registry.npmmirror.com。

3.4 配置相关镜像源（重要）

  1. 配置 pip 使用清华镜像，防止因国内网络问题，下载相关依赖失败导致启动SoduWork失败。

执行以下命令，配置pip国内镜像源。

bash 复制代码 
mkdir -p ~/.pip
cat > ~/.pip/pip.conf << 'EOF'
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
timeout = 120
EOF

若此前未配置国内镜像源，导致依赖下载失败，可先清理环境：删除旧的虚拟环境，使下次启动时重新创建，并清理 pip 缓存，执行以下命令即可。

bash 复制代码 
rm -rf ~/.local/share/soduwork/source-service/venv
pip cache purge 2>/dev/null || true
  1. 配置npm国内镜像源
bash 复制代码 
npm config set registry https://registry.npmmirror.com

如果之前没有配置国内镜像源，导致项目启动失败。可以执行以下命令，删除前端依赖缓存，换完源后清理再重来。

bash 复制代码 
rm -rf ~/.local/share/soduwork/source-service/node_modules
rm -rf ~/.local/share/soduwork/source-service/management-ui/node_modules
  1. 设置 Electron 镜像源：启动SoduWor时候，Electron 安装包默认从 GitHub Releases 下载，国内网络基本连不上，会导致一直卡住启动失败。
  • 设置 Electron 下载镜像为国内源
bash 复制代码 
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
export ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
  • 写入配置文件，永久生效
bash 复制代码 
cat >> ~/.bashrc << 'EOF'
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
export ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
EOF
bash 复制代码 
source ~/.bashrc
  • 如果清理残留后重新运行：
bash 复制代码 
rm -rf ~/.cache/electron
rm -rf ~/.local/share/soduwork/source-service/desktop

3.4 安装图形化界面

我们以root权限执行以下命令，在ubuntu-server下安装图形化桌面环境。

bash 复制代码 
apt install -y  kde-plasma-desktop sddm
systemctl set-default graphical.target
reboot

安装重启后，默认我们使用jeven用户登录，进入桌面环境。

四、部署SoduWork控制台

4.1 拉取项目

执行以下命令，下载SoduWork项目。

bash 复制代码 
git clone https://github.com/mdiri-ai/SoduWork

进入项目，查看项目内容。

bash 复制代码 
jeven@jeven:~$ cd SoduWork/
jeven@jeven:~/SoduWork$ ls
client              DCO.txt      hub-frontend  ops              SECURITY.md  start.command          start.py     tools
CODE_OF_CONDUCT.md  docs         LICENSE       README.md        skills       start-desktop.cmd      start.sh
CONTRIBUTING.md     hub-backend  NOTICE.md     README.zh-CN.md  start.cmd    start-desktop.command  third-party

4.2 启动控制台

在 Ubuntu 命令行终端中执行以下命令，即可启动 SoduWork 控制台。首次启动需联网下载依赖，耗时可能长达数分钟；已完成的步骤会被自动复用，请勿重复启动。启动过程中会提示设置管理员密码，按提示设置即可。这里的IP地址填写自己服务器IP，可以在局域网内访问该SoduWork控制台。

bash 复制代码 
python3 start.py  --host 192.168.3.251  --desktop
  • 其余系统启动方式（可选）：启动命令速查（按系统区分）
系统 启动命令 备注与说明
macOS / Linux sh start.sh --desktop 通过 sh 解释器执行启动脚本；若脚本无执行权限，先执行 chmod +x start.sh；--desktop 表示以桌面（客户端）模式启动
Windows PowerShell .\start.cmd --desktop 必须带 .\ 前缀，否则 PowerShell 不会在当前目录查找脚本，会报「无法将 start.cmd 识别为 cmdlet」
Windows 命令提示符（CMD） start.cmd --desktop CMD 默认在当前目录查找，无需 .\ 前缀，直接执行即可

说明：三种写法本质是同一个启动脚本，差异仅来自不同 Shell 的路径解析规则；--desktop 参数用于指定桌面模式，若需无界面/服务模式运行，可查阅官方文档替换为对应参数。

4.3 打开控制台

首次运行会自动安装依赖，在本机同时启动 Hub、管理端和桌面客户端。这里由Ubuntu桌面浏览器异常，我们在ubuntu访问桌面客户端，在本机Windows访问web管理控制台。登录桌面客户端，使用我们之前启动SoduWork时候设置的账号密码。

在局域网内，访问【http://192.168.3.251:18989】，注意将IP改为自己服务器IP地址。点击右上角 「Enter admin console」 进入管理控制台，输入之前设置的账号密码即可登录。

4.4 设置系统语言中文

在左下角的账号设置中，在语言设置选项下，设置系统语言为简体中文。

4.5 配置大模型服务

在SoduWork左侧菜单栏中，能力配置---模型目录下，已经内置有很多各厂家大模型，直接配置key就可以了。也可以重新接入，点击【接一个服务】，这里使用CSDN提供的大模型服务。

模型配置说明：

  • 标识：自定义，这里就填CSDN;
  • 名字：自定义即可；
  • 接口协议：OpenAI兼容；
  • 接口地址：https://ai.csdn.net/api/model/coding/v1 ，这里根据模型服务商提供的API说明来填写；
  • API Key： 自行在模型服务商商处获取；

填写完毕后保存即可。

在此页面找到我们刚才配置的模型服务，添加模型为glm-5.3-flash，模型用途为对话模型，保存即可。

同样的方法，我们也添加华为云Maas大模型服务。

五、桌面客户端配置工作

5.1 登录桌面客户端配置

桌面客户端的账号密码使用的是SoduWork控制台一样的账号密码，就是我们在启动SoduWork时候设置的。

5.2 测试对话

可以看到SoduWork客户端中对话页面，模型已经自动识别我们刚才设置的大模型了。

我们进行简单对话，"请介绍下你自己"，

5.3 SoduWork工作台监控

进入 SoduWork 管理后台的"运行监控"页面，查看单 Hub 控制面的整体运行状态。通过顶部指标卡确认服务健康度（请求健康 99.9%+、P95 ≤ 100 ms）、正在运行的工作流数量、执行能力（可接活 Runner 1/3）及待人审任务数。在"运行拓扑"区域核对 Hub 节点（hub-primary）是否处于"已就绪"状态，并检查各执行节点与底座的负载及在线/离线情况。同时通过右侧"交付运行态"和"服务请求"面板，确认工作流、AI 会话、环境发布的执行情况，以及近 30 分钟的请求量、服务错误数与接口响应耗时，判断系统是否运行正常。

进入管理后台"用量与成本"页面，查看 AI 运行的资源消耗与成本情况。通过顶部筛选器可按统计周期、成员、工作场景及 Agent 维度进行数据过滤。核心指标卡展示 Token 总用量（近 30 天 1.6 万）、已知模型成本、活跃成员数及 AI 活跃时长。下方图表呈现每日消耗趋势、场景分布（对话场景占比 100%）、成员用量明细，以及 Agent 与模型的调用组合（如 Pi 底座调用 DeepSeek-V4.1-Flash），便于核对消耗来源与异常峰值，为成本管控提供数据支撑。

六、单桌面客户端体验

6.1 下载客户端

在SoduWork官网也可直接下载桌面客户端：https://soduwork.mdiri.com/

6.2 安装桌面客户端

在Windows系统下，直接双击点击下载的安装包即可。

6.3 注册账号

安装完毕后，需要在线使用邮箱注册一个账号，登录即可使用。

6.4 配置大模型

这里配置华为云MaaS平台的大模型服务，按照官网API接入文档即可快速填写配置，也可参考上述SoduWork控制工作台的模型配置步骤与方法。

6.5. 测试文档能力

绑定工作区文件夹，自行设置即可。模型选择刚才设置的DeepSeek-V4.1-Flash-1017和默认Pi执行底座。

在此文件夹内，我们存放测试文档 SoduWork文档能力测试样本.docx ，进行如下测试：

按顺序发这 6 条，每条发完看结果再发下一条：

序号 指令 通过标准
T1 列出当前目录下的所有文件 能看到那个 docx 文件名
T2 读取文档，概括主要内容，不超过100字 提到"文档能力测试""三类测试元素"
T3 提取文档中所有表格，转成 CSV 保存 目录里出现新 csv 文件
T4 把文档里的销售数据表提取出来，计算总金额 算出5210.50
T5 找出文档中的项目编号和校验码 答出 PRJ-ALPHA-9527 和 CHK-8842
T6 把文档转换成 Markdown 格式保存 目录里出现 .md 文件，标题层级正确

T1/T2问题，正常读取名称，进行准确概括文档的主要内容。

T3 指令要求提取文档中的全部表格并转换为 CSV 保存。SoduWork 正常执行该操作，耗时约 8 秒，并在当前目录下生成了对应的 CSV 文件。

T4 指令要求从文档中提取销售数据表并计算总金额。SoduWork 顺利完成了该计算，得出总金额为 5210.50。

可以看到T5问题中，SoduWork准确答出 PRJ-ALPHA-9527 和 `CHK-8842。

生成 Markdown 文档后，SoduWork 不仅会在当前目录下生成对应的 .md 文件，还会在客户端中直接打开实时预览，效果相当不错。

6.6 测试代码能力

我们让SoduWork帮我们生成一个软件公司静态官网，要求简单美观大气。

七、遇到的问题与解决

  1. 依赖下载卡住：Python、Node 依赖默认走境外源，国内网络下载慢且易失败，导致启动 SoduWork 工作台时长时间卡住，需提前配置阿里云等国内镜像源。

  2. 桌面客户端启动失败 ：Electron 二进制包默认从 GitHub 下载，国内访问受限会卡在 postinstall 阶段，需通过 ELECTRON_MIRROR 环境变量指定国内镜像后再安装。

  3. 源码编译后无法启动：Python 编译安装完成后若 SoduWork 仍启动失败，可改用 uv 直接安装该版本并切换至 uv 环境运行，绕过编译依赖问题。

  4. 桌面环境缺失：SoduWork 桌面客户端依赖图形环境，需提前在 Ubuntu 中安装并配置好桌面环境，确保能正常访问和渲染界面。

八、总结

回顾这次从零部署 SoduWork 的完整过程，从基础依赖、Python 与 Node.js 环境搭建，到控制台启动、模型接入和客户端体验，整体链路虽然环节不少，但每一步都有清晰的指引，新人按图索骥基本能顺利跑通。实测下来，它在文档解析、表格提取、数据计算和 Markdown 转换等任务上表现稳定，双 AI 交叉验证的机制也让结果更让人放心。当然，国内网络下的镜像源配置、Electron 下载和图形化环境这几处仍是绕不开的门槛，提前准备好能省下大量等待时间。SoduWork 作为一款仍处于公开测试阶段的开源平台，已经展现出相当完整的可用性，值得作为团队 AI 协作的候选方案持续关注和试用。
⭐ 本测评涉及的开源项目：SoduWork

本文所有功能体验均来自开源项目 mdiri-ai/SoduWork ，源码完整公开在 GitHub，欢迎随时查看与上手试用。

如果这篇文章对你有一点帮助，恳请你花 1 秒钟点亮一个 Star ⭐ 或 Fork 🍴 ------ 你的每一次关注，都是开源作者持续迭代的最大动力！

📎 项目地址 ：https://github.com/mdiri-ai/SoduWork　🚀 Issues / PR：等你一起共建

相关推荐
lucas_AI13 分钟前
Claude Code 的「项目经理」上班了：协调器主动汇报，并行 AI 工人不等你催
人工智能
zhaoshuzhaoshu36 分钟前
NPU（神经网络处理单元）详细解析
人工智能
在所不辞兄36 分钟前
为什么在新能源汽车电驱与热管理开发中，AI驱动的数字孪生和数据驱动仿真正在部分替代对物理台架与实车标定的依赖？
人工智能·深度学习·神经网络·算法·机器学习
阿Q说代码38 分钟前
SoduWork 上手体验：把 Codex、Claude Code 等 AI Agent 放进一个工作平台
ai·agent·soduwork
Flynn Liang1 小时前
LLM 应用安全：Prompt 注入、越权与输入输出护栏
java·人工智能·大模型·langchain4j·llm 安全·prompt 注入·guardrail
吴佳浩5 小时前
《拆解全球最火 AI 开源项目》第一季 · REA
人工智能
AllData公司负责人9 小时前
AI大模型数据开发底座系列说明书，AllData集成Chat2DB开源项目建设AI 数据库分析底座，涵盖AI 洞察/对话SQL/智能视图！
数据库·人工智能·sql·开源·ai 洞察·对话sql
无奈笑天下9 小时前
银河麒麟上nproc命令教程详解
linux·运维·服务器
泯泷10 小时前
让 Agent 分清“马上办、等一等、顺手办”
人工智能·llm·agent
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02几个好用的ip纯净度检测网站03历年考研数学一、数学二、数学三真题试卷及答案PDF04微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新05GitHub 镜像站点06如何新建文件夹？ 电脑新建文件夹的4种方法07蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接08昇腾910B系列芯片完全指南：四款型号对比、服务器选型与大模型部署实战09苹果iPA游戏软件资源下载网站10Dify：一站式AI应用开发平台全解析与Windows部署指南