# 从零到第一个工作流：10 分钟上手 ChengOS（新手向完整教程）

这篇教程带你从一台空白的 Linux 服务器出发，一路走到**跑通第一个 AI 工作流**。全程大约 10 分钟，产出的东西虽小但真实可用：一个接收文本、交给大模型处理、展示结果的工作流。

> 完整文档见 [安装指南](/docs/install-chengos) 和 [你的第一个工作流](/docs/quickstart-first-workflow)。本帖是新手视角的串联版，补充了文档里没写的实操细节。

## 第 0 分钟：你需要什么

- 一台 64 位 Linux 主机
- 一个 LLM 的 API Key（OpenAI / Claude / DeepSeek / Ollama 本地模型都行）

**硬件要求（实测数据）：**

| 配置 | 规格 | 说明 |
|---|---|---|
| **标配** | 2 核 CPU / 4 GB 内存 / 10 GB 磁盘 | 推荐配置，Docker 模式也够用 |
| **低配** | 1 核 CPU / 1 GB 内存 | 二进制模式正常运行 |
| **极限** | 1 核 CPU / **512 MB** 内存 | 也能流畅运行——前提是安装**二进制版本**，且主机上没有 Docker 等其他高内存程序 |

内存占用实测：

- **二进制（Native）模式**：ChengOS 自身全部组件内存占用 **150 MB 以内**，加上系统占用整体在 **300 MB 以内**
- **Docker 模式**：因镜像额外占用，整体内存占用在 **600 MB 以内**

ChengOS 有两种部署模式：

| 模式 | 依赖 | 适合 |
|---|---|---|
| **Native（原生）** | 仅需发布包，数据库以普通用户进程运行 | 试用、单机、无 root 权限的主机、小内存 VPS |
| **Docker** | Docker Engine + Compose 插件 | 生产环境、可复现部署 |

新手推荐 **Native 模式**——不需要 root，不需要拉镜像，最轻量，512 MB 的小机器也能跑。

## 第 1 分钟：安装

**新手推荐：交互式安装**，一行命令进入安装引导：

```bash
curl -fsSL https://chengos.dev/chengos.sh | bash
```

执行后会进入**交互式双语菜单**：

```
===========================================
       ChengOS 统一管理与部署工具
===========================================
  1) 安装/初始化模块 (Install/Init)
  2) 启动服务 (Start)
  3) 停止服务 (Stop)
  4) 重启服务 (Restart)
  5) 更新模块 (Update)
  6) 单独安装 CLI (Install CLI Only)
  7) 查看服务状态 (Status)
  8) 安装系统命令 (Install Command Shortcuts)
  9) 卸载/停用模块 (Uninstall)
  10) 切换语言 (Switch Language)
  11) 退出 (Exit)
  12) 重置登录用户名/密码 (Reset Credentials)
  13) 回滚到上一个版本 (Rollback)
===========================================
请选择操作 [1-12]:
```

选 `1` 进入安装引导，按提示选好模式和模块，装完再选 `2` 启动、`7` 查看状态即可——安装、更新、回滚、重置密码、卸载全在这一个菜单里，不习惯命令行参数的用户全程不用查文档。

如果你偏好脚本化/CI 部署，也可以用参数直通模式，进入 `deploy/` 目录执行：

```bash
./chengos.sh install --mode native --db-install-mode managed-process --with api,ui,app,cli
./chengos.sh start
./chengos.sh status
```

三个参数解释一下（理解了以后能按需裁剪）：

- `--mode native`：直接在主机上跑 API 二进制和静态资源，不经过 Docker
- `--db-install-mode managed-process`：PostgreSQL、Valkey、Qdrant 以**普通用户进程**方式跑在安装目录里，**全程无需 sudo**（另一种 `system-service` 模式走 apt + systemd，需要 root）
- `--with api,ui,app,cli`：选择要装的模块，只要编辑器的话 `--with api,ui` 就够了

## 第 2 分钟：验证安装

```bash
curl http://127.0.0.1:3000/health   # API 健康检查
./chengos.sh status                # 进程、端口、日志
```

启动成功后，四个服务在监听：

| 服务 | 端口 | 用途 |
|---|---|---|
| API 后端 | `3000` | REST API + WebSocket |
| 主界面 | `8080` | 可视化工作流编辑器 |
| 聊天应用 | `5055` | 聊天客户端 / 移动端 H5 |
| PostgreSQL | `5432` | 主数据存储 |

浏览器打开 `http://<你的主机>:8080`。全新数据库没有任何用户，会进入**首次运行设置**——在这里创建的账号就是管理员。

> ⚠️ 如果起不来，先看 `deploy/logs/`。启动失败十有八九是数据库连接问题或端口被占用。

## 第 3–8 分钟：搭第一个工作流

### 先认识四个词

- **workflow（工作流）**：一张有向图，是保存、版本化、运行、发布的单位
- **node（节点）**：一个步骤，声明了带类型的输入输出。节点用 `分类/名称` 寻址，如 `io/input_text`、`ai/llm`
- **edge（连线）**：连接上游输出端口和下游输入端口，连线决定执行顺序
- **execution（执行）**：一次运行，有自己的状态机（pending → running → completed / failed / cancelled）和可回看的执行轨迹

### Step 1：拖入输入节点

在左侧节点面板找到 `io/input_text`，**拖到画布上**。选中它，右侧属性面板里给字段起个名字，比如 `user_input`，再填一个默认值方便测试。

### Step 2：拖入模型节点

拖一个 `ai/llm` 到输入节点右边。选中后在属性面板配置：选供应商和模型，写提示词。**引用上游文本用变量引用**，不要手抄字面量——这才是把两个步骤真正连起来的东西：

```
请用一句话总结以下内容：

{{user_input}}
```

> 🔑 还没配模型供应商的话，先去设置里配一个。凭证存在加密保险库里，节点里只有引用，**真实密钥由服务端在请求时注入，LLM 全程接触不到**。

### Step 3：连线

从 `io/input_text` 右侧的输出端口拖到 `ai/llm` 左侧的输入端口。连线是**类型检查**的——如果连不上，说明两个端口类型不兼容，编辑器在帮你提前拦截运行时才会暴露的错误。

### Step 4：加预览节点

拖入 `utils/preview`，把 `ai/llm` 的输出连过去。预览节点专门用来在开发时看中间值，是理解一个节点到底输出什么的最快方式。

你的图现在是：**`io/input_text` → `ai/llm` → `utils/preview`**

### Step 5：保存并运行

`Ctrl+S` 保存（首次会要求命名，工作流存在 PostgreSQL 里，不依赖浏览器）。然后点运行——执行视图通过 WebSocket **实时流式推送事件**，你能看到节点按顺序点亮，而不是干等最终结果。

如果某个节点失败，点它：执行详情会显示该节点的错误**和它实际收到的输入**，基本一眼定位。最常见的首次运行失败是模型配置——凭证缺失或模型名写错。

## 第 9–10 分钟：从模板继续

跑通之后，别急着从零造轮子——每个新工作区都自带一组内置模板，**读一个能跑的工作流比搭一个玩具工作流学得更快**：

| 模板 | 演示什么 |
|---|---|
| `no-memory-chat` | 最小聊天工作流：输入直达模型，无历史 |
| `memory-chat` | 会话记忆：加载历史、窗口化、持久化回复 |
| `tools-user` | 带文件操作工具的 ReAct 智能体，沙箱内自主运行 |
| `http-tools` | 给模型 HTTP 工具，让它自己调外部 API |
| `main-chat` | 意图路由：条件路由分发到三个子工作流 |
| `scheduled-task` | 用自然语言管理定时任务 |
| `skills-run` | 发现并运行已安装的 Skill |

## 下一步

- [把工作流发布成应用](/docs/app-publish-workflow)——给它一个别人能访问的 URL
- [REST API 概览](/docs/api-rest-overview)——用代码调用同一个工作流
- [环境变量参考](/docs/config-env-reference)——开启智能体记忆和向量检索

---

**打卡时间：** 跑通第一个工作流的同学，回帖晒一下你的三节点图和模型输出吧！遇到卡壳的地方也直接问，我们看到就回。