要求与限制
本页列出开始前需要准备的条件，以及使用中可能碰到的限制。各专题页会重复与该专题相关的条目。
电脑与软件
| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 10 及以上（x64）· macOS 13（Ventura）及以上（Apple 芯片或 Intel）· Linux：Ubuntu 22.04 或 24.04（DEB）、Rocky Linux 或 RHEL 9（RPM）；其他发行版使用 tar.gz 包（x64） |
| 内存 | 最低 8 GB，建议 16 GB |
| 可用磁盘空间 | 源码安装 10 GB，Docker 20 GB。数据目录会随附件、交付物和安装的 Agent 底座增长 |
| Python | 3.12 及以上。Windows 安装时勾选 Add Python to PATH |
| Node.js | 22.19 及以上，含 npm。构建管理端、运行桌面客户端时需要 |
| 网络 | 首次启动需要联网下载依赖，之后的启动会复用 |
| Docker（可选） | Windows、macOS 使用 Docker Desktop 的 Linux 容器模式；Linux 使用 Docker Engine 和 Compose v2 |
部署
- 从源码启动默认只监听
127.0.0.1，用于在一台电脑上试用。--host可以绑定到局域网地址，但仍是 HTTP 加 SQLite；团队使用请用 Docker 或生产部署。 - Docker 把 Hub 映射到
127.0.0.1，不对外开放 PostgreSQL。团队访问需要你自己配置 HTTPS 反向代理，代理要支持 WebSocket 和长时间的流式响应。 - 数据目录必须在源码目录之外，并且是空目录，或由同一个启动器创建过。
- 一个数据目录只对应一个实例。 不要对同一个数据库同时运行两个迁移。
- 多节点 Hub 需要另外设计共享存储和协调机制。随附的启动器只部署单节点。
- 离线安装：首次构建需要联网。离线部署时，先在同平台、能联网的机器上构建好镜像。
模型
- SoduWork 不包含模型密钥，需要配置你有权使用的模型服务。
- 模型服务通过 OpenAI 兼容接口（
/v1）接入，覆盖大多数网关、vLLM、Ollama 和兼容的服务商。其他协议不会自动转换。 - 组织密钥保存在 Hub 上，不会以明文返回。用户可以在客户端里配置个人密钥。
Agent 底座
- Pi 随客户端内置。其他底座在 设置 → Agent 管理 按需安装。
- 有的底座使用 SoduWork 配置的模型；有的（如 Codex、Claude Code）用它们自己的账号登录。
- 支持 Agent Client Protocol（ACP）的程序，可以在
hub-backend/app/agent_catalog.json里增加一条声明，重新构建客户端和 Runner 后接入。底座 ID 以小写字母开头，最长 40 位，只能用小写字母、数字和连字符。 - 使用其他协议的程序需要另外编写适配。
- 不支持远程安装底座。每台电脑或执行机各自安装。
插件
- 包格式：
.soduwork-plugin，即 zip 文件，不超过 10 MB、300 个文件，根目录必须有plugin.json（schemaVersion: 1）。 - 工作流有 1～100 个节点，不能有环。每个节点最多重试 5 次。AI 节点的运行上限为 60～86,400 秒。
- 已发布的版本不可修改，内容变化必须升 SemVer 版本号。
- 发布到组织的插件要先进入隔离区，经过管理员审查。
- Skill 和插件不是安全沙箱，只安装可信来源的。
安全
- 生产环境使用 HTTPS，并为 Hub 设置独立的认证密钥。
- Runner 只接入你信任的 Hub。
local-service.json（源码安装）和deployment.json（Docker）里有签名密钥，要像密码一样保管。- 备份范围要包含数据库和文件存储。
升级与数据
- 升级前停止服务，备份整个数据目录。
- 回退时要同时恢复匹配版本的源码和对应的数据备份。新版本迁移过的数据库，旧版本不能直接使用。
- 两者都有更新时，先升级 Hub，再升级客户端。